spec-review

Review the given diff against the spec layer. The registry is the substrate: never re-derive capability boundaries from the code.

Inputs

The argument is a diff target: a base ref (main), a range (a..b), a commit, or nothing (default: working tree + staged vs HEAD; if clean, HEAD~1..HEAD).

Procedure

1. Gate. Run node specs/registry.mjs check. If it fails, report that first and stop — reviewing against a broken registry proves nothing. A VIOLATED invariant caused by this diff is already a finding.
2. Ownership. git diff --name-only <target> | xargs node specs/registry.mjs owns Partition the files:
   • Owned by a pinned capability → review (steps 3–5).
   • (tests <src>) → evidence for that capability; check step 5.
   • Seam → no spec delta by definition. Comment only if the diff makes a seam carry behaviour (then the finding is "this belongs in a capability").
   • Unowned → silence. Not this review's business.

3. Read the touched statements, not the whole spec. For each touched capability open specs/<spec>.md and run

   git diff --stat <target> | node ${CLAUDE_PLUGIN_ROOT}/scripts/openrouter.mjs review --spec specs/<spec>.md

   For each statement in the JSON, mustRead: false means a heading skim is enough. mustRead: true, or "acted": false, means read that block in full. The prior is not a verdict: you still judge every block you read, you still cite file:line, and a statement the diff obviously touches gets read even when the prior said otherwise. With no key the script does not act and this step is the manual selection it always was — match on the functions, channels, messages, and fields the diff changes, read those blocks in full, and skim headings for ones you may have missed.

4. Judge each selected statement against the diff, one of:
   • CONSISTENT — the change preserves the stated behaviour.
   • CONTRADICTS <ID> — the diff makes the statement false and no amendment accompanies it. Quote the statement, cite the diff hunk. This is the finding that matters most.
   • DRIFT — the diff adds or changes observable behaviour of owned paths that no statement covers and no amendment introduces. Spec-first means this arrives as an amendment; say which section of the spec it belongs in.
   • RESOLVES <U-ID> — the diff answers an open uncertainty in code. Flag it: the answer belongs in the spec, not only in the diff. If the choice was hard to reverse, surprising, and a real trade-off, say that the reasoning belongs in an ADR with registry.yaml pointing at it (FORMAT.md, "Recording a decision as an ADR") — never in the spec file.
5. Pins and plans. From the owns output:
   • If a touched capability's spec file no longer matches its pin, an amendment is outstanding — check the diff against the plan's tasks and say which statements it satisfies. Remind that the pin move (registry.mjs pin) is the last act.
   • If the diff deletes or weakens a test named in a verified-by:, flag it — evidence is detaching from a statement.
6. Report. Per capability: pin state, then findings as <VERDICT> <statement-id> — one sentence + file:line. End with a one-line overall: clean, needs amendment, or contradicts pinned spec. No general code-quality commentary — that is the standards axis of spec-system:review.

Rules

• Statement IDs are the language. Every finding cites one, or names the spec section where a missing statement belongs.
• An uncertainty (-U-) is not a licence: code that picks a side of an open uncertainty without recording the answer is a finding, not a resolution.
• Do not propose spec edits inline — findings say what contradicts; the amendment (spec-amend) decides how the spec moves.
• If every touched file is seam or unowned, say so in one line and stop.