@renzrollon/interlock 1.0.0

package/skills/graph/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: graph
+description: Build and query a local, deterministic codebase knowledge graph (imports, symbols, OpenSpec specs, memory) so agents navigate with token-budgeted subgraphs instead of re-grepping. Use when indexing a repo, finding who consumes a symbol, tracing how one module reaches another, or before a deep explore or review sweep.
+license: MIT
+compatibility: Requires Node.js >= 18. The interlock-graph CLI ships with this plugin and is on PATH automatically.
+allowed-tools: Bash(interlock-graph *) Read Grep Glob
+metadata:
+  type: discovery
+  outputs:
+    - .claude/graph/graph.json
+    - .claude/graph/GRAPH_REPORT.md
+    - .claude/graph/docs-index.json
+---
+
+Build and query a **local, deterministic** codebase knowledge graph. No vector store, no external service, no network.
+
+**What gets indexed:** JS/TS, Python (`.py`/`.pyi`), shell (`.sh`/`.bash`), and curated small config JSON (`package.json`, `tsconfig*.json` — not lockfiles). Markdown stays on the bounded-retrieval path (`DOCS_DIGEST.md` / `context` / `docs`) plus the OpenSpec overlay — never dump every `*.md` into `graph.json`.
+
+Languages outside that set (Go, Rust, Java, Ruby) are **not** structurally indexed: you still get the docs and OpenSpec overlays, but no import/symbol edges. Say so plainly rather than implying the graph is complete.
+
+**Artifacts, all project-local under `.claude/graph/`:**
+
+| Path | Role |
+|------|------|
+| `graph.json` | Node-link graph — the query source of truth |
+| `GRAPH_REPORT.md` | Cheap bootstrap: hubs, modules, inferred edges |
+| `docs-index.json` | Deterministic docs TOC + content hashes |
+| `DOCS_DIGEST.md` | Agent-only prose bootstrap (written by `/interlock:docs-digest`) |
+| `manifest.json` | File hashes powering incremental `update` |
+
+Add `.claude/graph/` to `.gitignore` — these are generated per-checkout and should never be committed.
+
+---
+
+## The CLI
+
+`interlock-graph` is on PATH whenever this plugin is enabled. Do not probe for it, do not build a fallback path, do not shell out to `node` with an absolute path.
+
+```bash
+interlock-graph --help      # full subcommand list
+interlock-graph which       # print the resolved CLI path, if you need to report it
+```
+
+---
+
+## Modes
+
+### Build — when the graph is missing, or the user asks to index
+
+```bash
+interlock-graph build .
+```
+
+Then read `.claude/graph/GRAPH_REPORT.md` and summarize the top hub nodes and module boundaries. **Do not rebuild on every query.** If `graph.json` already exists, query it or update it.
+
+### Update — after merges, or when paths look stale
+
+```bash
+interlock-graph update .
+```
+
+No-ops when file hashes still match `manifest.json`.
+
+### Query — the default mode
+
+For "where is X", "what connects to Y", "how does A reach B", "who uses Z":
+
+1. Expand the user's wording into graph vocabulary (use labels from a prior `query` or from `GRAPH_REPORT.md`).
+2. Run the matching subcommand:
+
+```bash
+interlock-graph query "<tokens>" --budget 1500
+interlock-graph consumers <symbol-or-file>
+interlock-graph path <A> <B>
+interlock-graph explain <node>
+```
+
+3. Answer from the returned subgraph. Cite `source_file:source_location`.
+4. Only then reach for Grep/Read to cover what the graph structurally cannot see: dynamic imports, string-keyed lookups, generated code, reflection.
+
+### Docs and context — bounded prose retrieval
+
+Never read all of `docs/*.md` upfront.
+
+1. **Prose bootstrap** — if `.claude/graph/DOCS_DIGEST.md` exists, read it once. Rebuild with `/interlock:docs-digest` when it is missing or stale.
+2. **Rebuild the deterministic TOC** the digest is derived from:
+
+```bash
+interlock-graph docs-index . --write
+```
+
+3. **Task-specific excerpts:**
+
+```bash
+interlock-graph context "<task tokens>" --budget 2000 --changed path/a.ts,path/b.ts
+interlock-graph docs "<domain terms>" --budget 800 --dirs docs,openspec/specs
+```
+
+`context` combines a structural subgraph (~45% of budget) with ranked Markdown sections (~55%). Sections cite `file — heading (Lstart-Lend)`.
+
+---
+
+## Arguments
+
+This skill takes free text, treated as a query. Two forms are recognized ahead of that:
+
+| Input | Action |
+|-------|--------|
+| "index the repo" / "build the graph" / "rebuild" | `build .`, summarize the report, stop |
+| "update the graph" | `update .`, report what changed, stop |
+| anything else | Query mode |
+
+Note these map to CLI **subcommands**, not flags. There is no `--rebuild` or `--consumers` flag; `interlock-graph --rebuild` is an error.
+
+---
+
+## When other skills call this
+
+| Situation | Command |
+|-----------|---------|
+| Session explore / architecture mapping | Read `GRAPH_REPORT.md`, then `query` per subsystem |
+| Domain prose bootstrap | Read `DOCS_DIGEST.md`; rebuild via `/interlock:docs-digest` if stale |
+| Invariant sweep, structural layer | `consumers <field-or-symbol>` first, then grep for string-keyed readers |
+| explain-code "called by" / "calls into" | `explain` / `consumers` / `path` |
+| Brownfield onboarding | `build`, then seed the architecture doc from report hubs and modules |
+
+Follow `${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md` and `${CLAUDE_PLUGIN_ROOT}/shared/INVARIANT-SWEEP.md`.
+
+---
+
+## Stance
+
+- **Graph first, files second.** The graph is an index, not a substitute for reading real code when you implement or verify semantics.
+- **Confidence matters.** Prefer `EXTRACTED` edges. Treat `INFERRED` edges (OpenSpec, memory overlays) as hints to verify, not facts.
+- **Never invent nodes.** If the CLI reports no match, say so and fall back to grep. Do not synthesize a plausible-looking path.
+- **Read-only by default.** `build` and `update` write only under `.claude/graph/`.

package/skills/manual-test-plan/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: manual-test-plan
+description: Produce an expert-QA manual UI test plan from an OpenSpec change plus a git commit range — every touched file accounted for, spec scenarios and tasks mapped to numbered test cases, and non-UI-testable changes flagged rather than dropped. Use when asked for a manual test plan, QA checklist, or UI verification plan after implementing and before opening an MR.
+license: MIT
+compatibility: Requires git. Optional openspec CLI for change scoping. Node.js >= 18 for the bundled interlock CLI.
+argument-hint: "[change-name] [commit-range]"
+allowed-tools: Bash(git *) Bash(interlock *) Bash(interlock-graph *) Bash(openspec *) Read Write Grep Glob
+metadata:
+  type: generation
+  outputs:
+    - openspec/changes/<change>/manual-test-plan.md
+---
+
+Produce a precise, executable **manual UI test plan** from an OpenSpec change and a git commit range.
+
+Write for a junior tester who will not read the code: exact navigation paths, exact expected results, explicit pass/fail criteria. If a step needs someone to already know how the feature works, rewrite it.
+
+---
+
+## 1. Resolve scope
+
+```bash
+interlock changes                                  # active changes
+git log --oneline "$FROM".."$TO"
+git diff --stat "$FROM" "$TO"
+git diff --name-status "$FROM" "$TO"
+git diff "$FROM" "$TO" -- <source files>          # cap ~40; skip lockfiles and binaries
+```
+
+Default range: the merge base against the default branch. Read `proposal.md`, `design.md`, `tasks.md`, and `specs/**/*.md` for the change when one resolves.
+
+Optional context — do **not** preload all of `docs/`:
+- `.claude/graph/DOCS_DIGEST.md` if present
+- `interlock-graph context "<change> routes components forms" --budget 2000`
+
+---
+
+## 2. Classify the surface — deterministically
+
+```bash
+interlock surface --changed <files> --json
+```
+
+This returns the tri-state per file, and it is authoritative. **Do not re-derive the classification in prose**; the whole reason it is a CLI is that this question used to get two different answers on the same diff.
+
+| Class | Meaning |
+|---|---|
+| `UI-TESTABLE` | Directly user-visible — pages, components, forms, navigation, copy, layout, client validation, loading and error states |
+| `UI-INDIRECT` | Reachable only through UI side effects — API routes the UI calls, server actions, data shaping that changes what is displayed |
+| `NOT-UI-TESTABLE` | Backend, infra, docs, tests, config, tooling with no user-visible effect |
+
+If `needsManualTestPlan` is false, say so and stop. A backend-only change does not get a UI test plan, and writing one anyway teaches the reader to ignore these documents.
+
+---
+
+## 3. Analyze
+
+1. **Inventory** every changed file from `--name-status`.
+2. **Map specs and tasks to cases.** Spec scenarios and unchecked `tasks.md` items are the backbone; findings visible only in the diff become additional cases.
+3. **Cover the whole surface.** Every `UI-TESTABLE` and `UI-INDIRECT` file appears in at least one test case (or is explicitly deferred to a shared flow). Every `NOT-UI-TESTABLE` file appears in the Non-UI table. **Never silently drop a changed file** — an unmentioned file reads as "tested" when it wasn't.
+
+---
+
+## 4. Write the plan
+
+Write to `openspec/changes/<change-name>/manual-test-plan.md`. If nothing scopes it, write `./manual-test-plan.md` and say so.
+
+Output **exactly** this structure — no preamble, no sign-off inside the file:
+
+```markdown
+# Manual UI Test Plan — <change-name or "unscoped">
+
+**Scope:** <N commits / merge-base vs base> · HEAD `<short-hash>` · <branch>
+**Intent:** <1–2 sentences from proposal.md, or inferred from commit subjects>
+**Persona:** Expert QA — assume a clean session unless a case says otherwise
+**Environment prep:** <accounts, feature flags, seed data, base URL — or "none">
+
+---
+
+## Coverage Matrix
+
+| File | Status | Class | Covered by |
+|------|--------|-------|------------|
+| path/to/file | M/A/D/R | UI-TESTABLE / UI-INDIRECT / NOT-UI-TESTABLE | TC-01, TC-03 / — see Non-UI |
+
+Every changed source file in the range MUST appear here.
+
+---
+
+## Test Cases
+
+### TC-01 — <short title>
+- **Priority:** P0 (blocks ship) / P1 (core flow) / P2 (edge / polish)
+- **Traces to:** <spec scenario / task id / diff observation>
+- **Covers files:** `path/a`, `path/b`
+- **Preconditions:** …
+- **Steps:**
+  1. …
+  2. …
+- **Expected:** …
+- **Pass / Fail:** Pass if … · Fail if …
+
+### Happy path
+TC ids proving the primary journey works end to end.
+
+### Edge / negative
+TC ids for validation errors, empty states, permissions, failure UX.
+
+### Regression watch
+TC ids for adjacent UI that tends to break when this area changes.
+
+---
+
+## Non-UI Changes (not manually testable in the UI)
+
+| File | Why not UI-testable | Suggested verification |
+|------|---------------------|------------------------|
+| path/to/x | pure utility / infra / docs-only | unit test / CI job / manual CLI invoke / N/A |
+```
+
+Group assertions into one case when they share a navigation path; split them when the outcomes differ.

package/skills/mr/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: mr
+description: Generate a merge-request or pull-request summary from the change artifacts and diff, then create or update it on whichever platform the remote points at — GitLab via glab, GitHub via gh. Optional comment-only add-ons post the manual test plan or a teaching walkthrough. Use when opening an MR/PR, refreshing its description, or attaching a test plan.
+license: MIT
+compatibility: Requires git, plus glab (GitLab) or gh (GitHub) authenticated. Optional openspec CLI for change context.
+argument-hint: "[change-name] [--create] [--test-plan] [--explain]"
+disable-model-invocation: true
+allowed-tools: Bash(git *) Bash(glab *) Bash(gh *) Bash(openspec *) Bash(interlock *) Bash(interlock-graph *) Read Write Grep Glob
+metadata:
+  type: generation
+  outputs:
+    - openspec/changes/<change>/mr-summary.md
+---
+
+Turn a finished change into a merge request a reviewer can actually review.
+
+Almost all of this skill is platform-agnostic — the summary, the risk assessment, the test plan. Only the last step differs between GitLab and GitHub, so **detect the platform, do not ask about it.**
+
+| Flag | Effect |
+|------|--------|
+| `--create` | Create the MR/PR instead of updating an existing one |
+| `--test-plan` | Also post the full manual test plan **as a comment** |
+| `--explain` | Also post a per-file teaching walkthrough **as a comment** |
+
+---
+
+## 1. Detect the platform
+
+```bash
+git remote get-url origin
+```
+
+| Remote host contains | Platform | CLI | Check |
+|---|---|---|---|
+| `gitlab` | GitLab | `glab` | `glab auth status` |
+| `github` | GitHub | `gh` | `gh auth status` |
+
+Self-hosted instances often carry neither string — fall back to whichever CLI is installed and authenticated, and say which one you chose. If both or neither resolve, ask once; this is a genuinely ambiguous fact about the user's setup, not a default you can pick.
+
+---
+
+## 2. Resolve the MR/PR and the change
+
+```bash
+# GitLab
+glab mr view 2>/dev/null
+# GitHub
+gh pr view 2>/dev/null
+```
+
+No open MR/PR and no `--create` → stop: *"No open merge request for this branch. Push the branch and re-run with `--create`."*
+
+Resolve the OpenSpec change with `interlock changes` and the branch name. If several are plausible, ask which one — a wrong change here produces a confidently wrong description.
+
+---
+
+## 3. Gather
+
+```bash
+git diff --stat <base>...HEAD
+git diff --name-status <base>...HEAD
+git log --oneline <base>...HEAD
+```
+
+Read `proposal.md` (the why), `design.md` (the how), `tasks.md` (what was done), and `specs/**/*.md`. Use `interlock-graph consumers <symbol>` to check blast radius when the graph exists.
+
+---
+
+## 4. Compose the description
+
+```markdown
+## Summary
+2–4 bullets: what changed and why. Lead with the why.
+
+## Changes
+Grouped by capability, using spec names as headers where possible:
+- **<capability>**: <one-line user-visible change>
+  - <files or modules touched>
+
+## High Risk Changes
+Production risks, each with a mitigation or rollback note. Write `None` if there are none.
+
+## Prerequisites to Production
+Env vars, migrations, feature flags, config. Write `None` if there are none.
+
+## Testing
+- Unit: <N added / N updated> — `<command>` passing
+- Verified locally: <one line on what was exercised>
+- Not covered: <gap, or "none">
+```
+
+**`## Testing` answers "was this verified?", not "how do I test it by hand?"** Three to five bullets, readable without scrolling.
+
+**Never embed the manual test plan in the description.** It goes in a comment, via `--test-plan`. When you post one in this run, add a single closing line to `## Testing`:
+
+```
+Manual UI test plan: see MR comment.
+```
+
+Omit that line when `--test-plan` was not passed.
+
+Be honest in the risk assessment. An inflated confidence level is worse than no assessment, because it is the section a reviewer uses to decide how hard to look.
+
+---
+
+## 5. Write the local artifact
+
+Write `openspec/changes/<change-name>/mr-summary.md` with the branch name, commit message, MR title (≤70 chars), and the full description. This survives the session; the platform copy can be regenerated from it.
+
+---
+
+## 6. Publish
+
+```bash
+# GitLab — update
+glab mr update <id> --description "$(cat <<'EOF'
+<description>
+EOF
+)"
+# GitLab — create
+glab mr create --title "<title>" --description "..." 
+
+# GitHub — update
+gh pr edit <id> --body "$(cat <<'EOF'
+<description>
+EOF
+)"
+# GitHub — create
+gh pr create --title "<title>" --body "..."
+```
+
+Updating **replaces the description entirely.** If the existing description contains anything hand-written by a human, say so and confirm before overwriting it.
+
+---
+
+## 7. Optional comments
+
+**`--test-plan`** — reuse `openspec/changes/<change>/manual-test-plan.md` when it is fresh relative to HEAD; otherwise run `/interlock:manual-test-plan` first. Post it as a comment (`glab mr note -m` / `gh pr comment -b`). Split across comments if it exceeds the platform's size limit.
+
+**`--explain`** — run `/interlock:explain-code` in commit teach-in mode and post the walkthrough as a comment.
+
+Both are **comment-only, always.** Neither ever enters the description — a reviewer opening the MR should see the summary, not a 200-line test script.
+
+---
+
+## 8. Close the loop: say what still needs archiving
+
+This is the last point the change is in your hands, so it is where the spec lifecycle gets a mention.
+
+Pass the changed-file list you already resolved in §2:
+
+```bash
+interlock drift --changed <files> --json
+```
+
+**Never blocks.** It exits 0 whatever it finds — do not branch on the exit code here, and do not refuse to publish because of it.
+
+Four findings, in descending order of how much they deserve the reader's attention. Report only what is non-empty:
+
+- **`unarchived`** — earlier changes finished their tasks but were never archived, so their delta specs never reached `openspec/specs/` and the living specs no longer describe what shipped. Name them and give the command:
+  ```bash
+  openspec archive <change-name>
+  ```
+- **`stale.broken`** — a spec cites a file that no longer exists. This is **evidence**, not inference: the file was there when the graph was built. Report it as a real finding. If `stale.graphBuiltAt` is old, say so too — a rename against a stale graph looks identical to a deletion.
+- **`orphans.orphans`** — changed source files no spec describes. **Always report `orphans.coverage` alongside the count.** "2 files have no spec" is alarming; "2 of 6, in a repo where 34% of source files have one" is informative, and on a repo still being specced the second is the honest framing.
+- **`stale.aging`** — living specs older than files they cite. Weakest of the four: it compares dates on **inferred** edges, and a file can be refactored without the spec becoming wrong. Mention it only if it names a spec relevant to this change.
+
+Then close with the one line that matters for *this* change: once the MR merges, run `openspec archive <this-change>`. Interlock does not archive for you, and nothing downstream will notice if nobody does.
+
+If `drift` reports nothing, say nothing. A clean lifecycle does not need a paragraph.

package/skills/report/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: report
+description: Read the indicator report over Interlock's three recorded corpora — outcome records, run trajectories, review metrics — and say what it does and does not license. Use when someone asks how the loop is actually performing, whether continuity is working, how often review findings survive, which gate blocks most, or whether there is yet enough evidence to change a cap or a gate. The figures come from `interlock report`, never from your own counting; the judgement you add is about denominators, not about thresholds.
+license: MIT
+compatibility: Node.js >= 18 and the bundled interlock CLI. Offline — no model, no network, and nothing is written.
+allowed-tools: Bash(interlock *) Read Grep Glob
+metadata:
+  type: reading
+  outputs:
+    - a written reading of the census, with what each figure licenses
+---
+
+`interlock report` computes the numbers. You do not. Your job is the sentence
+that stops a number being misused — which is almost always a sentence about its
+denominator.
+
+## 1. Get the report
+
+```
+interlock report --json
+```
+
+Add `--since <iso>` for a window and `--change <name>` for one change. The
+command always exits 0: it gates nothing, and per §4.15(a) nothing in the loop
+reads its output. If you find yourself wanting an exit code, you have started
+designing a gate — that is decision §4.16 / slice F6.6 and it has not been made.
+
+Never recompute a figure by hand. If a number you need is absent, the corpus did
+not record it; say that instead of deriving a substitute from something nearby.
+
+When someone wants to *look* at the corpora rather than have them read to them:
+
+```
+interlock report --html > report.html
+```
+
+This renders the same report object as one self-contained HTML document — no
+stylesheet, script or font is fetched, so it opens offline and can be attached
+to an issue. It is **a generated file, not a service**: there is no server, no
+port and no watch mode to start, and nothing in the loop reads it. It is also
+**not a verdict**, and gains none by being visual: it draws no threshold, target
+or trend, no colour on it encodes health, and an unobserved indicator renders as
+`UNOBSERVED` with its reason at the same weight as a figure. Bare it writes to
+stdout; given a path it writes only there. It cannot be combined with `--json`.
+
+Handing someone the document does not discharge your job. The reading below is
+still yours to write — the page reports, and reporting is not interpretation.
+
+## 2. Read coverage first, and let it govern everything after it
+
+The `coverage` group is not preamble. It decides whether any indicator below it
+means anything:
+
+- `trajectories.withReceipt` is the denominator behind **every**
+  receipt-derived indicator — first-pass ship, remediation rounds, plan-reuse
+  status, the receipt finding series. If it is 0, all of those are unobserved,
+  and the finding to report is *that the receipt path has not fired*, not that
+  the runs were clean.
+- `outcomes.exists: false` means no ship run has recorded an outcome at all. The
+  continuity question — should the human checkpoint have been skipped — is then
+  unanswerable, and no amount of trajectory data substitutes, because the
+  trajectories hold no human judgement.
+- `metrics.unrecognized` names files that reached no indicator. That is normal:
+  `skills/review-artifacts` and `skills/fix-tests` both write into
+  `.claude/metrics/` in their own shapes. Report the count; do not treat an
+  unrecognized file as a missing one.
+- `trajectories.truncated` means the scan hit its cap. Narrow with `--since`
+  before reading any rate, or say the rate covers only the most recent files.
+
+## 3. State what each figure licenses
+
+For every indicator you present, give the value, the denominator, and one
+sentence on what it supports. The pattern:
+
+> **first-pass ship** — unobserved, 0 receipts. Licenses nothing. Would become
+> readable once ship runs write receipts; the trajectories on disk predate that
+> event type.
+
+> **gate exits non-zero** — 12.6% of 1 785 recorded exits, and 150 of the 225
+> are `wave-state record-batch`. Licenses a claim about which gate stops a run
+> most often. Licenses no claim about whether stopping was correct.
+
+Three rules hold without exception:
+
+1. **A denominator under ~20 licenses no trend.** Say "too few to read", name
+   what would have to accumulate, and stop. Do not soften it into a provisional
+   reading.
+2. **Never sum across provenance.** `fromMetrics` and `fromReceipts` are
+   different writers over different runs; the report keeps them apart and so do
+   you. The same rule separates a value a run *observed* from one an agent
+   *reported* — check each indicator's `source`.
+3. **`diffMatchesPlan` is computed one way only, and the other two plan figures
+   are not it.** It is the share of paths a run TOUCHED that its plan predicted
+   — read `direction` and quote it. Do not answer "does the merged diff match
+   the plan" with `planStatus` or with the mid-run revision rate: both are about
+   the plan, neither observes the diff. Read `excluded` before reading the
+   figure: a share over three qualifying runs while forty were excluded for a
+   recording gap is a fact about the recording, and saying so is the reading.
+
+## 4. Do not recommend a gate
+
+You may report a figure, name its denominator, and name what would have to be
+recorded for it to mean more. You may not recommend that a cap be raised, a
+threshold be set, a band be adjusted, or a gate be relaxed or tightened on the
+evidence of a figure — not even when the figure looks decisive, and not even
+when asked directly. The corpora exist to inform §4.16 later; converting them
+into a recommendation now is the decision that has not been made.
+
+If asked for a recommendation, answer with the evidence that is missing.
+
+## 5. Report the caps rather than restating them
+
+The scan bound comes from `interlock limits`, not from a number typed here. Cite
+the command.
+
+## Output
+
+A short written reading: the coverage headline, then each indicator with its
+value, denominator, and what it licenses. Close with the single most valuable
+missing measurement — the one whose absence blocks the most indicators. That
+sentence is usually the most useful thing in the report.

package/skills/review-artifacts/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: review-artifacts
+description: Review OpenSpec change artifacts before anyone writes code — architecture quality and design completeness, then spec completeness and testability. Catches a wrong idea at the cheapest possible moment. Use after generating proposal, design, tasks and delta specs, and before implementing.
+license: MIT
+compatibility: Requires the openspec CLI. Node.js >= 18 for the bundled interlock CLI.
+argument-hint: "[change-name]"
+allowed-tools: Bash(interlock *) Bash(openspec *) Read Glob Grep
+metadata:
+  type: review
+  outputs:
+    - .claude/metrics/review-artifacts-<change>-<timestamp>.json
+---
+
+Review the change artifacts before implementation. This is the highest-leverage gate in the whole flow: a blocker caught here costs a paragraph, the same blocker caught after ship costs a day.
+
+Resolve the change:
+
+```bash
+interlock validate [change-name] --json
+```
+
+If it reports ambiguity, pick the change the user named. If they named none and several are active, review the most recently modified and **say which one you picked** — this skill runs inside automated chains where a question would stall the flow.
+
+Read all of `proposal.md`, `specs/**/*.md`, `design.md`, `tasks.md`.
+
+Detect the stack from the artifacts and the dependency manifest, and skip framework-specific checks that do not apply. Do not ask a Go service about accessibility requirements.
+
+---
+
+## Reviewer 1 — Architecture
+
+**Architecture quality**
+- Are layer boundaries placed correctly in `design.md` for this stack?
+- Does the structure follow the patterns already in this project?
+- Are state and ownership decisions appropriate?
+- Is the data flow clear — reads, writes, mutations, side effects?
+
+**Design completeness**
+- Does `design.md` specify an error-handling strategy?
+- When UI is in scope, are accessibility requirements present?
+- Is the approach consistent with the project's own architecture docs (`CLAUDE.md`, `AGENTS.md`, `docs/`)?
+
+**Pattern fitness**
+- Does the proposed structure introduce complexity it does not need?
+- Is there a simpler alternative that reaches the same outcome?
+
+---
+
+## Reviewer 2 — QA
+
+**Spec completeness**
+- Does every requirement in `specs/` have concrete Given/When/Then scenarios?
+- Are edge cases covered — empty, error, loading, boundary values, permission denied?
+- Which scenarios would a real user hit that the spec does not mention?
+
+**Testability**
+- Can every scenario become an automated test?
+- Are acceptance criteria specific enough to verify? "Should work properly" is not a criterion.
+
+**Task quality**
+- Does `tasks.md` pair a test task with every feature task?
+- Is the ordering right — do dependencies precede dependents?
+- Is each task small enough for one focused session?
+- **Same-file staircase.** Do consecutive checkboxes name the same production path — one per TDD beat, comment move or trap? That is one checkbox, not five. Report it as a warning naming the repeated path. It is not a ship halt: `planWaves` folds the resulting 1-task waves back together, so the cost is implementer count and lost parallelism, not checkpoints.
+- Does each numbered section hold work that could share a wave? Independent files belong in one section; a new section is only an output-exists boundary.
+
+**Delta spec quality**
+- Are ADDED / MODIFIED / REMOVED sections used correctly?
+- Do the deltas describe **behavior**, not implementation?
+
+---
+
+## Invariant check
+
+If the change transforms a shared or derived value — normalizing an identity, deriving a cache or dedup key, canonicalizing a field — then `tasks.md` must contain a task for **every consumer** of that value, not just the one the change is about.
+
+A change that updates one call site and leaves its siblings reading the raw form is a **blocker at this gate**, because it is far cheaper to add the tasks now than to discover the surviving bug after review. See `${CLAUDE_PLUGIN_ROOT}/shared/INVARIANT-SWEEP.md`.
+
+---
+
+## Output
+
+```
+── ARCHITECTURE ────────────────────────────────
+✓ [passed — brief]
+⚠ WARNING: [specific issue, with file reference]
+✗ BLOCKER: [critical issue]
+
+── QA ──────────────────────────────────────────
+✓ [passed — brief]
+⚠ WARNING: [specific issue, with file reference]
+✗ BLOCKER: [critical issue]
+
+SUMMARY: N blockers, N warnings, N suggestions
+Recommendation: [fix blockers | address warnings | proceed to /interlock:ship]
+```
+
+Be specific — name files and sections. Do not pad with generic praise. If the artifacts are genuinely good, say so briefly and recommend proceeding.
+
+---
+
+## Emit structured findings
+
+Write `.claude/metrics/review-artifacts-<change>-<YYYYMMDD-HHMMSS>.json` in this shape:
+
+```json
+{ "dimension": "artifacts",
+  "findings": [
+    { "severity": "blocker|warning|suggestion",
+      "file": "path/to/artifact.md", "line": 42,
+      "title": "short claim",
+      "description": "what is wrong and why",
+      "suggestion": "how to fix it" }
+  ] }
+```
+
+`severity`, `file`, `title` and `description` are required; `line` and `suggestion` are optional. Map BLOCKER→`blocker`, WARNING→`warning`, SUGGESTION→`suggestion`. Create `.claude/metrics/` if it does not exist. This is the complete emit contract — do not read `lib/findings.mjs` to rediscover it.
+
+Then let the deterministic gate decide, rather than deciding in prose:
+
+```bash
+interlock gate --findings .claude/metrics/review-artifacts-<change>-<ts>.json --metrics <change>
+```
+
+The gate blocks if and only if at least one finding is a `blocker`. Its exit status is the verdict: non-zero means blocked. Do not re-derive the verdict in prose.
+
+`--metrics <change>` is not optional decoration. It writes the four counts this gate produced — raised, dismissed, dropped by the quality band, surviving — to `.claude/metrics/` in the schema `interlock report` recognizes. Drop it and this review path becomes invisible to the report forever: the review-finding indicators read `unobserved` no matter how many gates ran. It is bookkeeping only and cannot change the verdict or the exit status.