Diffing & Auditing
Relevant source files
The following files were used as context for generating this wiki page:
- packages/cli/src/commands/diff.ts
- packages/cli/src/commands/update.ts
- workers/kdco-registry/files/skill/code-review/SKILL.md
- workers/kdco-registry/files/agent/reviewer.md
- workers/kdco-registry/files/plugin/workspace-plugin.ts
- workers/kdco-registry/files/skill/plan-review/SKILL.md
- packages/cli/tests/diff.test.ts
Diffing and Auditing in OCX represent a multi-layered approach to ensuring code integrity, security, and adherence to project-specific philosophies. This system encompasses technical comparisons between local files and upstream registries, as well as qualitative audits performed by specialized agents. The primary goal is to maintain high-quality, secure, and predictable code across the workspace.
At a technical level, the CLI provides tools to detect structural and content changes in installed components. Simultaneously, the agent-based auditing system applies rigorous review methodologies—such as the "4 Review Layers" and the "5 Laws of Elegant Defense"—to evaluate both implementation plans and final code changes.
Sources: packages/cli/src/commands/diff.ts, workers/kdco-registry/files/skill/code-review/SKILL.md:12-25, workers/kdco-registry/files/agent/reviewer.md:12-22
Technical Diffing
The technical diffing system is primarily managed through the diff and update commands within the OCX CLI. It allows users to compare the state of locally installed components against their original versions in the registry.
Core Comparison Logic
The CLI utilizes ocx.lock and ocx.jsonc to identify installed components and their respective registries. The diff command performs a line-by-line comparison between local content and the upstream content fetched from the registry using a patch creation utility.
The diagram above illustrates the sequence of operations when a user initiates a diff command to compare local component state with a remote registry.
Sources: packages/cli/src/commands/diff.ts:41-118, packages/cli/tests/diff.test.ts:25-50
Technical Diff Features
| Feature | Description | File Source |
|---|---|---|
| Unified Patches | Uses the diff library to create standard unified patches for modified files. | packages/cli/src/commands/diff.ts:114 |
| Registry Fetching | Dynamically resolves and fetches file content from the upstream registry URL. | packages/cli/src/commands/diff.ts:101-105 |
| Lockfile Integration | Validates installations using ocx.lock before attempting comparisons. | packages/cli/src/commands/diff.ts:42-53 |
| Hash Verification | The update system uses SHA-256 hashes to detect updates without full diffs. | packages/cli/src/commands/update.ts:358-378 |
Qualitative Auditing (The Reviewer Agent)
Auditing in OCX extends beyond technical diffs into qualitative analysis via the reviewer agent. This agent is responsible for auditing implementation plans and code changes against specific quality standards and the project's core philosophy.
The 4 Review Layers
The auditing process is structured into four distinct layers to ensure comprehensive coverage:
- Correctness: Logic errors, edge cases, and type safety.
- Security: Input validation, sanitization, and credential protection.
- Performance: Caching, query patterns, and algorithmic complexity.
- Style & Maintainability: Adherence to project conventions and DRY violations.
Sources: workers/kdco-registry/files/skill/code-review/SKILL.md:17-43, workers/kdco-registry/files/agent/reviewer.md:46-56
The 5 Laws of Elegant Defense
Auditors verify code against these five mandatory principles:
- Early Exit: Using guard clauses to handle edge cases at the top of functions.
- Parse, Don't Validate: Converting data into trusted types at boundaries.
- Atomic Predictability: Ensuring pure functions and predictable side effects.
- Fail Fast, Fail Loud: Descriptive immediate errors for invalid states.
- Intentional Naming: Ensuring code reads like natural language.
Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:10-33, workers/kdco-registry/files/agent/reviewer.md:26-44
Plan Auditing
Before code is even written, implementation plans are audited via the plan-review skill. This ensures that the proposed architecture is sound and well-cited.
Quality Assessment Criteria
The plan audit focuses on three primary categories:
| Category | Requirement | Check |
|---|---|---|
| Citation Quality | Decisions must reference sources. | ref:delegation-id format used. |
| Completeness | Goal must be specific and measurable. | Clear progression through logical phases. |
| Actionability | Tasks must be clear and specific. | Specific files or components are identified. |
Sources: workers/kdco-registry/files/skill/plan-review/SKILL.md:15-60
Severity Classification
Audit findings are classified by severity, which dictates the necessary action:
The diagram shows the triage process for findings during a code or plan audit.
Sources: workers/kdco-registry/files/skill/code-review/SKILL.md:47-52, workers/kdco-registry/files/skill/plan-review/SKILL.md:64-69
Automated Auditing Triggers
The WorkspacePlugin automates the invocation of auditing processes during development. It monitors tool execution and injects system reminders to ensure reviews are not bypassed.
Coder-to-Reviewer Workflow
When a coder subagent completes a task, the system tracks the completion and prompts for a mandatory audit by the reviewer agent.
This sequence ensures that every implementation task is followed by a qualitative audit before the orchestrator reports completion.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:446-465, workers/kdco-registry/files/plugin/workspace-plugin.ts:474-486
Summary
Diffing and Auditing in OCX provide a robust safety net for software evolution. While technical diffs via the CLI identify what has changed, the agent-led auditing system evaluates why and how those changes were made. By enforcing strict adherence to the 5 Laws and the 4 Review Layers, the project ensures that contributions remain technically accurate, secure, and philosophically aligned with the core architecture.