Diff Manifest

diff_manifest schema

Canonical definition of the diff_manifest object. The producer (/execute-plan Phase 3 preamble) and the consumers (/domain-review, /code-review-professional, /review-adversarial) all reference this schema so changes stay in lockstep.

Schema (current: 1)

{
  "schema_version": 1,
  "base_sha": "<EXECUTE_PLAN_BASE_SHA>",
  "head_sha": "<git rev-parse HEAD>",
  "files": [
    {
      "path": "src/api/auth.ts",
      "language": "typescript",
      "lines_added": 42,
      "lines_removed": 7,
      "touches": ["public-surface", "persistence", "auth"]
    }
  ],
  "clusters": [
    { "id": "backend", "paths": ["src/api/**", "src/services/**"] },
    { "id": "ui",      "paths": ["src/web/**"] },
    { "id": "db",      "paths": ["migrations/**", "src/db/**"] }
  ],
  "languages": { "typescript": 7, "sql": 2, "markdown": 1 },
  "touches": {
    "persistence": true,
    "public_surface": true,
    "concurrency": false,
    "auth": true,
    "dependencies": false
  }
}

Field reference

Effective diff

The manifest describes the effective diff, not the raw git diff. Excluded from files[]:

1. Plan file edits. If the plan was edited mid-run, those hunks are execution bookkeeping, not product code.
2. Decision-record tree. Files under docs/decisions/<plan-slug>/ are meta-artefacts; reviewers should not be asked to review them as if they were product code.

Producer contract

/execute-plan Phase 3 preamble produces one manifest per review cycle. It is passed identically to /domain-review and /code-review-professional. /review-adversarial does not currently consume diff_manifest (it receives the diff and pr_description only); if a future change makes it a consumer, list it here and bump no version (additive).

Consumer contract

When diff_manifest is provided:

• Consumers MUST use clusters as the component boundaries — do not re-cluster the diff.
• Consumers MUST use touches flags as authoritative — do not recompute persistence/auth/etc. detection.
• Consumers MUST validate schema_version. Unknown version → log a warning and fall back to internal triage as if no manifest was provided.

When diff_manifest is absent (direct invocation of a consumer skill):

• The consumer falls back to its own internal triage step.
• Reports remain valid but cluster IDs may not match other consumers'.

Versioning

Bump schema_version on any breaking change (field renames, removals, type changes). Additive changes (new optional fields) do not require a bump but should be documented here.

Where this schema is referenced

• /execute-plan — producer (Phase 3 preamble)
• /domain-review — consumer
• /code-review-professional — consumer

Contract

• Inputs: none — this is a reference document, not an invokable skill.
• Preconditions: N/A.
• Outputs: the schema definition above; consumers and producers cite it by name (_internal/diff-manifest).
• Postconditions: N/A.
• Failure modes: N/A. Schema drift is detected at consumer side via schema_version validation.