@mmerterden/multi-agent-pipeline 17.3.0 → 17.4.0

package/CHANGELOG.md

@@ -14,6 +14,73 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [17.4.0] - 2026-09-15
+
+Phase 4 now answers two questions it could not answer before: does the evidence a
+review cites actually exist, and which files did the reviewer read.
+
+### Added
+
+- `verify-citations.mjs`: resolves every `file:line` a run claims against git
+  rather than against the writer. Reads reviewer findings, triage
+  accepted/deferred/rejected, analysis `repoEvidence` buckets and markdown prose,
+  checks the path with `git cat-file` and the line against the blob's real
+  length. Exit 0/1/2/64.
+  - Phase 4 runs it with `--worktree`: a fix made during a review round is
+    uncommitted, so pinning to HEAD would call every citation to it invented.
+  - The analysis pre-dispatch gate runs it pinned to a commit, because a
+    document cites repos it only reads.
+  - Until now the only check was a regex asking whether a row LOOKED like a
+    citation, which `Foo.swift:9999` satisfies in a repo with no Foo.swift.
+- `review-file-filter.mjs` and `schemas/review-file-exclusions.json`: Phase 4
+  Step 1.85 decides what the reviewers read before the diff cap decides what
+  fits. The cap truncates the largest files first, so a regenerated lockfile was
+  not merely wasted budget - it was what survived while real code was cut. 45
+  generic patterns (generated trees, lockfiles, recorded snapshots, vendored
+  source, build output, binary assets); every exclusion carries its reason and
+  the glob that matched. Fails open: an unreadable pattern list reviews
+  everything and says so.
+- `fileCoverage[]` on `reviewer-output.schema.json` (v1.3.0), enforced by
+  `validate-reviewer.mjs --coverage`. A reviewer that opened one file of ten and
+  one that read all ten returned the identical empty `findings[]`; now each file
+  in the set gets a `reviewed` or `skipped` verdict, and `skipped` owes a reason.
+- `graph-mermaid.mjs`: draws the blast radius `graph-affected.mjs` already
+  measures, as a mermaid flowchart in the PR body's impact section. GitHub
+  renders it natively, so the diagram costs no renderer and no dependency. Over
+  the node ceiling it reports what was left out rather than quietly drawing a
+  small radius for a large change.
+- `validate-analysis-doc.mjs` check 2d-2: a sequence-diagram participant that
+  appears nowhere else in the document, and a named service that appears in no
+  diagram, are both reported.
+- Shared modules `glob-match.mjs` and `git-path.mjs`. Two glob matchers would
+  duplicate meaning, not code: the day they disagree, a file is excluded from the
+  review and still counted in the conformance denominator.
+
+### Fixed
+
+- `verify-citations` read `wiki.example.com:8443` out of any URL with a port and
+  called it an absolute path. An analysis document is made of Confluence, Jira
+  and Figma links, so the gate would have failed every real document with the
+  wrong reason. URLs are stripped first, and an extension must start with a
+  letter so `v1.2:30` is not a path either.
+- `review-file-filter` dropped every non-ASCII filename. With `core.quotePath` on
+  git prints a Turkish name as `"G\303\266r..."`, which matches no glob and
+  resolves to no file - so it did not fail, it vanished from the denominator.
+- `smoke-own-punctuation.sh` and `smoke-personal-data.sh` used `git grep` and
+  `git ls-files` without `--untracked` / `--others`, so a brand-new file was
+  invisible until committed. The run that would have caught a violation was
+  always the run after the one that introduced it.
+- `analysis/locked.md` heading said 36 decisions over a list of 37, with nothing
+  counting.
+
+### Changed
+
+- `phase-4-review.md` was compressed to stay under its ceiling rather than
+  raising it. Two passages moved to the refs that own them:
+  `features/design-conformance.md` gained "Why this runs as a gate", and
+  `cross-cli-contract.md` gained "Panel diversity per host" with the per-host
+  reviewer table it had been describing in prose.
+
 ## [17.3.0] - 2026-09-14
 
 A three-pass review of 17.2.0 found two things it had declared finished. Both

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "17.3.0",
+  "version": "17.4.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/agents/code-reviewer.md

@@ -25,13 +25,15 @@ Return ONLY a JSON object:
 {
   "findings": [{"severity": "blocking|important|suggestion", "file": "...", "line": N, "issue": "...", "fix": "...", "ruleId": "SEC-01", "criteriaSource": "ios-coding-standard"}],
   "conformance": [{"ruleId": "SEC-01", "verdict": "conformant|violated|not-applicable", "file": "Sources/X.swift", "line": 42, "reason": "..."}],
+  "fileCoverage": [{"path": "Sources/X.swift", "verdict": "reviewed|skipped", "reason": "..."}],
   "approved": true|false
 }
 ```
 
 `ruleId` + `criteriaSource` are required on a finding that comes from a cited
 rule and omitted otherwise. `conformance` is required whenever a `${CRITERIA}`
-block was supplied  -  see below.
+block was supplied, and `fileCoverage` whenever a `${REVIEW_FILES}` block was  -
+see below.
 
 ## Severity Classification
 
@@ -90,6 +92,38 @@ obvious breach; `judgement` rules are yours, and each needs the measurement its
 When no `${CRITERIA}` block is supplied, omit `conformance` entirely and review
 on the focus areas above.
 
+## Review file set (required when supplied)
+
+The orchestrator may pass a `${REVIEW_FILES}` block: the changed files you are
+accountable for, computed before you were dispatched. Generated output,
+lockfiles, recorded snapshots, vendored source and binaries are already removed,
+so what is left is human-authored code and the list is not negotiable.
+
+```
+${REVIEW_FILES}
+reviewed:
+  <repo-relative path>
+  ...
+excluded (not yours, listed so you can see the decision):
+  <repo-relative path>  -  <reason>
+```
+
+Return one `fileCoverage` row **per path under `reviewed`**, and no rows for
+paths outside it. Rules:
+
+- `reviewed` means you read the file's diff in full. There is no `partial`: what
+  you read but did not understand belongs in a `findings` entry, not in a
+  hedged verdict.
+- `skipped` requires a `reason` naming why you could not read it  -  the diff was
+  truncated, the content was unreadable. "Not relevant" is not a skip reason; a
+  file you read and found nothing in is `reviewed`.
+- A path that is neither read nor explicitly skipped fails the stage, for the
+  same reason an unanswered rule ID does: a reviewer that opened one file of ten
+  and one that read all ten return identical empty `findings` arrays, and this
+  list is what tells them apart.
+
+When no `${REVIEW_FILES}` block is supplied, omit `fileCoverage` entirely.
+
 ## Priority Files (advisory)
 
 When the orchestrator passes a `${PRIORITY_FILES}` block, treat it as a heuristic

package/pipeline/multi-agent-refs/analysis/locked.md

@@ -1,16 +1,16 @@
-# Locked decisions (36)
+# Locked decisions (37)
 
-> The 36 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
+> The 37 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
 
 ### Index by category (v9.1.0+)
 
-Browse-friendly grouping of the 36 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
+Browse-friendly grouping of the 37 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
 
 | Category | Decisions | Concern |
 |---|---|---|
 | **A. Governance** | 1, 5, 6, 7, 10, 26, 27, 32, 36 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile, document reviewed before publish |
 | **B. Citation and Evidence** | 3, 4, 8, 11, 24, 30, 34 | Every fact in the doc traces back to a source: citation discipline, forward-looking spec, standards binding, repo-evidence reuse-first, Pass B footnote mandatory, analysis self-contained (pipeline-wide), references built from the evidence record |
-| **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25, 33, 35 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode, corporate backbone always renders, stack-optional render |
+| **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25, 33, 35, 37 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode, corporate backbone always renders, stack-optional render, redesign records v1 before planning v2 |
 | **D. Design Source and Pipeline Architecture** | 12, 22, 23 | Where design comes from and how the pipeline renders: Figma 3-tier access (BLOCKING), platform-agnostic template + Pass B render, convention extraction (Phase 1c) |
 | **E. UI, Variant, and Test Coverage** | 15, 18, 19, 28, 29, 31 | UI artefact rules: SVG default for new assets, screenshots embedded, all Figma variants drilled, SwiftUI Preview block (iOS), variant usage explicit, business-rule to acceptance-criterion to test traceability |
 

package/pipeline/multi-agent-refs/analysis/render.md

@@ -124,10 +124,11 @@ Result: `state.analysisSpec.outputs.requested[]`.
 for f in /tmp/analysis-<feature-slug>-<ts>/*.md; do
   node "$HOME/.claude/scripts/validate-analysis-doc.mjs" "$f" || GATE_FAILED=1
   node "$HOME/.claude/scripts/build-references.mjs" <state.json> --check "$f" || GATE_FAILED=1
+  node "$HOME/.claude/scripts/verify-citations.mjs" "$f" --repo "$REPO_ROOT" || GATE_FAILED=1
 done
 ```
 
-`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, Full-mode business-rule traceability per Locked 31, and in the corporate profile the backbone presence and `EKLENECEK`-to-Section-20 pairing per Locked 33). `build-references.mjs --check` runs the References coverage gate (Locked 34): a source the run consumed but did not list, or a listed row with no evidence behind it, blocks dispatch. Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
+`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, Full-mode business-rule traceability per Locked 31, and in the corporate profile the backbone presence and `EKLENECEK`-to-Section-20 pairing per Locked 33). `build-references.mjs --check` runs the References coverage gate (Locked 34): a source the run consumed but did not list, or a listed row with no evidence behind it, blocks dispatch. `verify-citations.mjs` resolves each claimed `file:line` at HEAD with `git cat-file`, so `Foo.swift:9999` in a repo with no Foo.swift blocks dispatch (Locked 3, Locked 37). Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
 
 Iterate `state.analysisSpec.outputs.requested`. For each target:
 

package/pipeline/multi-agent-refs/channels/pr.md

@@ -77,6 +77,32 @@ Across stacks the same shape produces, for example: `LoginView.swift  -  ...` (i
 <none, or which service, contract or channel>
 ```
 
+Part 3 is the one part of this body that is MEASURED rather than recalled. The
+code graph already answers it, so draw the answer instead of re-typing it:
+
+```bash
+node "$HOME/.claude/scripts/graph-mermaid.mjs" "<changed symbol[,symbol]>"
+```
+
+Append the fenced block it prints under part 3, above the prose. GitHub renders
+mermaid natively in pull requests, so this costs no renderer and no plugin. The
+prose stays: the diagram says which symbols the change reaches, the sentence says
+which screens and flows a tester must open, and neither answers the other.
+
+Exit 1 means the repo has no graph yet (`/multi-agent:graph` builds it) or the
+symbol is not in it. That is a gap with a reason, not a failure: write the prose
+alone and say the graph was unavailable. Never hand-draw the diagram - a drawn
+blast radius nobody measured is worse than none, because a diagram is read as
+fact.
+
+The commit line the script prints stays with it. A graph built before the change
+draws the radius of an older tree, and the reader has no other way to notice.
+
+This is a GitHub-only section. `channels/jira.md` has no mermaid handling at all:
+a fence there converts to a literal `{code:mermaid}` block, so the Jira impact
+section keeps its prose. Confluence renders it through the `ac:name="mermaid"`
+macro (`md2confluence-v3.py`) when the space has the plugin.
+
 When the change deliberately fixes part of a wider problem, a closing **Risk and remaining scope** paragraph names what is still open and why it was left - a reviewer who can see the rest of the pattern in the repo will ask otherwise, and the honest answer is cheaper written down than defended in a thread.
 
 **`test_scenarios`**  -  the same titled-scenario shape the Jira adapter uses, so the tester reads one list on both surfaces, with symbols allowed here:

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -214,6 +214,28 @@ on skill directories would demand exactly the layout that breaks it.
 
 Future changes that break an item in the "stay identical" list must update **both** files in the same commit. `smoke-cross-cli-behavior.sh` enforces the identity-preserving axis (input parsing, routing, output shape); structural differences are left to manual review because enforcing them would require forcing the files to the same shape, which we intentionally don't want.
 
+### Panel diversity per host
+
+Phase 4 runs three reviewers everywhere, but the diversity those three buy is not the
+same on every host. Copilot CLI gets cross-VENDOR disagreement for free: GPT-5.4 sits
+beside two Claude models. Claude Code and Codex each run a one-vendor panel - three
+Anthropic models on one, three OpenAI models on the other - so the same three-way
+agreement is weaker evidence there, and Phase 4 says so in the triage note on a
+borderline finding.
+
+Where the budget goes instead, when vendor diversity is unavailable:
+
+| Host | Reviewer 1 | Reviewer 2 | Reviewer 3 |
+|---|---|---|---|
+| Copilot CLI | Fable/Opus, security + architecture | GPT-5.4, edge cases (cross-vendor) | Sonnet, quality |
+| Claude Code | Fable, security + architecture | Opus, edge cases | Sonnet, quality |
+| Codex | `xhigh`, security + architecture | a different family member, edge cases | `medium`, quality |
+
+On Codex the axis is reasoning effort as much as model identity, because the family
+members available there are closer to each other than Fable and Sonnet are. That is a
+weaker axis, not an equivalent one, and treating it as equivalent is the error this
+section exists to prevent.
+
 ## 3. Frontmatter Transform Rules (Claude ↔ Copilot)
 
 Each file has a different frontmatter schema. The sync flow transforms between them:

package/pipeline/multi-agent-refs/features/code-graph.md

@@ -1,5 +1,11 @@
 ## Code Graph (Phase 1 Step 2.6 + Phase 7 Step 3)
 
+<!-- toc -->
+- [Phase 1 Step 2.6  -  query before dispatching Explore](#phase-1-step-26---query-before-dispatching-explore)
+- [Phase 7 Step 3  -  refresh after the branch changed code](#phase-7-step-3---refresh-after-the-branch-changed-code)
+- [The graph is drawable, and one place already asks for it](#the-graph-is-drawable-and-one-place-already-asks-for-it)
+<!-- /toc -->
+
 A deterministic, LLM-free map of what a repo declares and what refers to what,
 written to `~/.claude/knowledge/<project>/code-graph.json`. Gated by
 `prefs.global.codeGraph.enabled` (default `false`); with it off, Phase 1 and
@@ -67,3 +73,37 @@ The rebuild costs no API tokens, so it runs every task rather than on a stalenes
 heuristic. A non-zero validator exit keeps the previous graph and logs
 `knowledge.graph_invalid`; it never fails the run  -  a stale graph is a degraded
 Phase 1, not a broken deliverable.
+
+### The graph is drawable, and one place already asks for it
+
+The PR body's Impact Analysis, part 3, asks which symbols and files a change
+reaches. That is `graph-affected.mjs`'s question, and until now the answer was
+re-typed as prose by a model while the measurement sat on disk unread.
+
+```bash
+node $HOME/.claude/scripts/graph-mermaid.mjs "<symbol[,symbol]>" [--depth N] [--max-nodes N]
+```
+
+It emits a fenced `flowchart` and nothing else - no renderer, no plugin, no
+dependency, because mermaid is text and GitHub renders it natively in pull
+requests, issues and markdown files. Traversal is not reimplemented: `findByName`
+and `affected` are imported from `graph-affected.mjs`, so the diagram and the
+text report cannot disagree about what is affected.
+
+Three properties that are enforced rather than promised
+(`smoke-graph-mermaid.sh`):
+
+- Every drawn node and edge resolves back into `code-graph.json`, with the edge
+  kind it claims. A diagram is read as fact and checked less than prose, so an
+  invented edge is the expensive failure.
+- Over `--max-nodes` the leftover count is printed inside the diagram, not
+  dropped. A small picture of a large blast radius reads as reassurance.
+- The graph's `baseCommit` is printed beside it. A graph built before the change
+  draws an older tree, and nothing else in the PR would reveal that.
+
+Exit 1 with a reason on stderr means no graph or no such symbol. The caller
+records the gap and writes the prose alone; it never hand-draws a replacement.
+
+Jira is not a target: its renderer turns the fence into a literal
+`{code:mermaid}` block. Confluence renders it through the `ac:name="mermaid"`
+macro when the space carries the plugin (`channels/confluence.md`).

package/pipeline/multi-agent-refs/features/design-conformance.md

@@ -1,6 +1,7 @@
 # Design conformance  -  the component walk, and why a glance is not a pass
 
 <!-- toc -->
+- [0. Why this runs as a gate](#0-why-this-runs-as-a-gate)
 - [1. Enumerate first, then fill every cell](#1-enumerate-first-then-fill-every-cell)
 - [2. Measure, never read the token](#2-measure-never-read-the-token)
 - [3. Adaptive per-component convergence](#3-adaptive-per-component-convergence)
@@ -24,6 +25,19 @@ Consumers: `/multi-agent:design-check` (the runner), Phase 4 review when a UI
 diff is under review, and `features/visual-evidence.md` when a capture has to
 prove a fix. Gate: `smoke-design-conformance.sh`.
 
+## 0. Why this runs as a gate
+
+`design-check` existed as a command for a while with no phase invoking it, so the only
+thing standing between a build and visual drift was the user opening the app and
+looking. On one run that produced 16pt padding where the frame said `Spacing/12`, and a
+full sheet rebuild afterwards.
+
+The reason it cannot be advice is structural, not historical: a reviewer reading a diff
+cannot see spacing. Every other Phase 4 check reads text and reasons about text; this
+one is the only thing in the pipeline that compares a rendered result against the
+design it was drawn from. Left optional, it is the check that gets skipped on exactly
+the runs that are in a hurry, which are the runs that produce drift.
+
 ## 1. Enumerate first, then fill every cell
 
 Do **not** walk by finding, and do not walk by headline. Build the inventory

package/pipeline/multi-agent-refs/features/review-file-set.md

@@ -0,0 +1,132 @@
+# The review file set  -  what was read, and what was not, on the record
+
+<!-- toc -->
+- [Why this exists](#why-this-exists)
+- [The set is fixed before the reviewer sees the diff](#the-set-is-fixed-before-the-reviewer-sees-the-diff)
+- [Every exclusion names the pattern that produced it](#every-exclusion-names-the-pattern-that-produced-it)
+- [The reviewer answers for each file](#the-reviewer-answers-for-each-file)
+- [Invocation](#invocation)
+- [What this is not](#what-this-is-not)
+<!-- /toc -->
+
+> The denominator for Phase 4's other axis. Loaded on demand by
+> `/multi-agent:review` and by pipeline Phase 4.
+
+## Why this exists
+
+Phase 4 had a size cap and no exclusion list. When the diff exceeds the phase
+token allowance the cap truncates the LARGEST files first, so a regenerated
+lockfile or a snapshot dump is not merely wasted budget: it is the thing that
+survives while real code is cut.
+
+The second half is worse and quieter. A reviewer that opened one file of ten and
+a reviewer that read all ten and found nothing return the identical
+`{"findings": [], "approved": true}`. Nothing in the pipeline could tell them
+apart, so "no findings" has been carrying two meanings at once.
+
+Both halves are one fix: decide what is worth reading BEFORE the cap decides
+what fits, and make the reviewer answer for each file it was given.
+
+## The set is fixed before the reviewer sees the diff
+
+The same rule `selectedRules[]` follows, for the same reason. After a model has
+seen the diff, "I did not open that one" and "there was nothing there" become
+the same sentence, and whichever one is cheaper to say is the one that gets
+said. So the set is computed from `git diff --name-only`, written to
+`.pipeline/review-files.json`, and never recomputed inside the round.
+
+```bash
+git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/review-file-filter.mjs \
+  > "$WORKTREE/.pipeline/review-files.json"
+```
+
+Report shape:
+
+```json
+{
+  "reviewed": ["src/App.swift"],
+  "excluded": [
+    {
+      "path": "package-lock.json",
+      "reason": "lockfile - resolved by the package manager, not written by hand",
+      "pattern": "**/package-lock.json"
+    }
+  ],
+  "total": 2,
+  "patternsSource": ".../schemas/review-file-exclusions.json",
+  "patternCount": 45
+}
+```
+
+`reviewed` is what goes into the diff cap and into the reviewer prompt, as a
+`${REVIEW_FILES}` block beside `${CRITERIA}` in the shared cache prefix. It has to
+be in the prompt: a reviewer asked to account for a set it was never shown can
+only guess, and `fileCoverage` would then fail on every single dispatch - a gate
+that always fires is a gate that gets switched off. `excluded` goes into the run
+report, never into silence.
+
+## Every exclusion names the pattern that produced it
+
+A file that disappears between the diff and the review is indistinguishable from
+a file nobody found anything in - which is the exact confusion this whole
+feature exists to remove, so reintroducing it in the filter would be
+self-defeating. Each excluded row carries both the human reason and the glob
+that matched, so a reviewer, a PR reader or a future maintainer can dispute the
+call rather than discover it.
+
+The pattern list is data, in `schemas/review-file-exclusions.json`, and it is
+generic: generated trees, lockfiles, recorded snapshots, vendored source, build
+output, binary assets. No stack, project or company name appears in it. A
+pattern with no reason invalidates the whole list rather than being defaulted -
+the default would be exactly the sentence the caller is supposed to print.
+
+**It fails open, on purpose.** An unreadable or malformed pattern file yields
+every file reviewed, the reason on stderr, and exit 2. Failing closed would
+review nothing and report a clean run.
+
+## The reviewer answers for each file
+
+`reviewer-output.schema.json` (v1.3.0) carries `fileCoverage[]`: one row per
+path in `reviewed`, `{path, verdict: reviewed|skipped, reason}`. There is
+deliberately no `partial` - a file read in part is read, and what was not
+understood belongs in a finding.
+
+`validate-reviewer.mjs --coverage <report>` enforces it, catching the same three
+failures the conformance checklist catches on the rule axis:
+
+| Failure | Why it matters |
+|---|---|
+| a file in the set with no row | silently unread, and the empty `findings[]` reads as clean |
+| a row for a path outside the set | an answer about something the reviewer was not given, the same shape as a hallucinated rule ID |
+| `skipped` with no reason | a drop with no cause is indistinguishable from a read |
+
+`skipped` is legitimate and expected: a file past the diff cap, a file whose
+content the host truncated. What it may not be is unexplained. "Not relevant" is
+a review decision and belongs in a verdict of `reviewed`, not a skip.
+
+An empty `reviewed` set (a diff that is entirely lockfiles) demands no checklist
+at all. Requiring an empty array there would fail honest output, and the
+filter's `excluded[]` is what carries that information onward.
+
+## Invocation
+
+```bash
+node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE" \
+  --criteria "$WORKTREE/.pipeline/criteria-manifest.json" \
+  --coverage "$WORKTREE/.pipeline/review-files.json"
+```
+
+Without `--coverage` the field stays optional, so every existing caller keeps
+working unchanged. With it, the checklist is enforced and exit 1 takes the same
+single self-correction rework the rest of the validator gate takes.
+
+## What this is not
+
+It is not a relevance filter. Nothing here decides that a file is uninteresting;
+it decides that a file is not human-authored source, which is a mechanical
+question with a mechanical answer. The moment a pattern starts encoding "we
+probably do not care about this directory", the list has become a way to hide
+work, and the near-miss assertions in `smoke-review-file-filter.sh`
+(`CodeGenerator.swift`, `generated-report.md`, `distribution/`, `buildSrc/`) are
+what fail when it does.

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -240,8 +240,7 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.criteria \
 Output conforms to `$HOME/.claude/schemas/criteria-manifest.schema.json`. The four parts that matter downstream:
 
 - **`selectedRules[]` is the denominator.** Rule IDs from every registry whose declared `scope` matches the diff, persisted BEFORE the reviewers run so the set cannot be renegotiated after one has seen the diff. That is what makes "applied completely" answerable rather than "looks fine": a reviewer finding nothing must still return a verdict per ID. Discovery is declared via `standards-registry:` frontmatter, so no stack-specific skill is named here.
-- **`coverage.declaredGaps[]` + `droppedReasons`.** An uncovered language, and every out-of-scope rule, is reported with a reason. "No rule applied", "every rule passed" and "the rule set was narrowed" must never render the same.
-- **`ledger`.** `state.telemetry.skillCalls[]` corroborates only; `ledger.source` defaults to `derived` and coverage is never computed from self-report. A declared skill the resolver cannot bind is flagged.
+- **`coverage.declaredGaps[]`, `droppedReasons`, `ledger`.** Every gap, dropped rule and unbindable declared skill is reported with a reason; coverage is never computed from self-report. Rationale: the contract above.
 - **`findings[]`.** Reviewer-shaped, merging at Step 3.0 alongside test-integrity: expired / unexplained / unknown-ID exception markers, plus any registry whose delegated linter is not wired here (those rules are unverified, so reporting no violations reports that nothing was measured).
 
 **Any non-zero exit halts** (1 = setup error incl. a bad `--skills-root`; 2 = no root resolved, unparseable registry, or a declared path escaping its skill dir): continuing would drop a rule set from the denominator, and since the reviewer validator skips the checklist when zero rules were selected, the run would report clean over criteria never loaded. A coverage gap halts only under `prefs.global.skillConformance.blockOnCoverageGap`. No opt-out for the stage or the exception-expiry check, on the same grounds as Step 1.76.
@@ -266,13 +265,25 @@ Visual-fidelity mismatches against the captured screenshot are BLOCKING findings
 
 When `state.figmaAccess.tier === 3` (user-attached screenshot, no Code Connect snippet), the reviewer additionally sets `findings[i].severity = "blocking"` and `findings[i].tag = "review_blocking_tier3"` on every UI atom that lacks a confirmed canonical-component mapping. The triage step preserves these findings unless the user has explicitly cleared the open question.
 
+#### Step 1.85  -  Review file set (the denominator, required)
+
+Decides what the reviewers read before the cap decides what fits: the cap truncates the largest files first, so a lockfile survives while real code is cut. Zero LLM. Full contract: `$HOME/.claude/multi-agent-refs/features/review-file-set.md`.
+
+```bash
+git -C "$WORKTREE" diff --name-only "$BASE_BRANCH"...HEAD \
+  | node $HOME/.claude/scripts/review-file-filter.mjs \
+  > "$WORKTREE/.pipeline/review-files.json"
+```
+
+`reviewed[]` is the denominator, fixed here for the same reason `selectedRules[]` is. `excluded[]` reaches the run report with its reason and the glob that matched. Exit 2 means the pattern list is unreadable and everything is reviewed: continue, logging `review.file_filter_failed`.
+
 #### Step 1.9  -  Context economy (cache prefix + diff cap)
 
 Phase 4 sends the same diff to every reviewer and then to triage, so the diff is the dominant token cost. Two measures keep it bounded:
 
-**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger. The `<scope-self-check>` block and, from iteration 2, the `<previous-round-findings>` block (Step 2.1) close the shared block, after the plan and before the per-reviewer suffix.
+**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the `${CRITERIA}` block from Step 1.78, the `${REVIEW_FILES}` list from Step 1.85, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. `${CRITERIA}` goes in the prefix, identical for every reviewer: subsetting it per reviewer would invalidate the prefix for the whole panel and re-bill the largest block in the phase. Per-reviewer emphasis stays a one-line pointer in the suffix. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger. The `<scope-self-check>` block and, from iteration 2, the `<previous-round-findings>` block (Step 2.1) close the shared block, after the plan and before the per-reviewer suffix.
 
-**Single-repo diff cap.** If the diff exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
+**Single-repo diff cap.** Applied to the Step 1.85 `reviewed[]` set only. If it exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
 
 #### Step 2  -  Parallel AI Review (CLI-aware reviewer set)
 
@@ -291,9 +302,8 @@ Reviewer count per host: **Claude Code 3, Copilot CLI 3, Codex CLI 3**  -  **2**
 
 #### Codex CLI  -  two constraints that fail silently
 
-Both were measured against Codex 0.145, not inferred, and both produce a review that
-looks like it ran. The full statement lives in the managed block at `~/.codex/AGENTS.md`
-(always loaded on that host, so it is not restated here):
+Both measured against Codex 0.145, both produce a review that looks like it ran. Full
+statement: the managed block in `~/.codex/AGENTS.md`, always loaded on that host.
 
 1. **`fork_turns: "none"` on every `spawn_agent` that sets `model` or
    `reasoning_effort`** - a full-history fork discards the override and collapses the
@@ -304,15 +314,10 @@ looks like it ran. The full statement lives in the managed block at `~/.codex/AG
 Sub-agent delegation itself is authorized by that same managed block; without it Phase 4
 degrades to a single in-thread review.
 
-**Single-vendor caveat.** Every Codex reviewer is an OpenAI model, and every Claude
-Code reviewer is an Anthropic model, so the cross-vendor disagreement that Copilot CLI
-gets for free (GPT-5.4 beside two Claude models) is absent on both. The diversity budget
-shifts to model generation, reasoning effort and persona focus: on Codex Reviewer 1 runs
-`xhigh` on security and architecture, Reviewer 2 runs a different model family member
-on edge cases, Reviewer 3 runs `medium` on quality; on Claude Code the three slots are
-three different Claude tiers. Treat consensus among a single-vendor panel as weaker
-evidence than the same consensus on Copilot CLI, and say so in the triage note when all
-three agree on a borderline finding.
+**Single-vendor caveat.** Claude Code and Codex both run a one-vendor panel, so their
+consensus is weaker evidence than Copilot CLI's; say so in the triage note on a
+borderline finding. Where the diversity budget goes instead:
+`cross-cli-contract.md`, "Panel diversity per host".
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 
@@ -331,7 +336,7 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 
 ##### 2.1 Previous-round findings (iteration >= 2) and 2.2 scope self-check (every iteration)
 
-A reviewer has no memory of the round before, so it rediscovers last round's findings in new words. From iteration 2, render the previous round's accepted blocking/important findings (`.pipeline/triage-round-$((ITERATION-1)).json`, max 40) into a `<previous-round-findings>` block at the end of the shared prefix: a still-present issue is reported with the SAME fingerprint and the current line, a fixed one is omitted, anything new leaves `fingerprint` unset. Every iteration also renders `.pipeline/scope-check.json` (Phase 3 Step 3.7) plus `scope-check-gate.mjs --advisory` output as `<scope-self-check>`: file reasons, unjustified files, and `notDone[]` (never re-raised as findings); a missing record logs `review.scope_check=missing`. Block text and recipes: `$HOME/.claude/multi-agent-refs/features/review-delta.md`.
+From iteration 2, render the previous round's accepted blocking/important findings (`.pipeline/triage-round-$((ITERATION-1)).json`, max 40) into a `<previous-round-findings>` block at the end of the shared prefix. Every iteration also renders `.pipeline/scope-check.json` (Phase 3 Step 3.7) plus `scope-check-gate.mjs --advisory` output as `<scope-self-check>`: file reasons, unjustified files, and `notDone[]` (never re-raised as findings); a missing record logs `review.scope_check=missing`. Block text and recipes: `$HOME/.claude/multi-agent-refs/features/review-delta.md`.
 
 #### Step 2.8  -  Visual conformance gate (component / screen work only)
 
@@ -350,11 +355,7 @@ disk with `Code Connect: Not published` in Figma means the binding does not exis
 anyone but the author. Assert the publish step ran; an unpublished binding is a
 blocking finding.
 
-Why this is a gate and not advice: `design-check` existed as a command for a while
-with **no phase invoking it**, so the only thing standing between a build and visual
-drift was the user opening the app and looking. On one run that produced 16pt padding
-where the frame said `Spacing/12`, and a full sheet rebuild afterwards. A reviewer
-reading a diff cannot see spacing; something has to compare against the design.
+Why this is a gate and not advice: `design-conformance.md`, "Why this runs as a gate".
 
 Skip only when the diff has no UI change. Record the outcome in
 `consensus.visualConformance` so Phase 7 reports whether it ran.
@@ -374,10 +375,11 @@ Step 2 produces N reviewer-output objects (one per dispatched reviewer), each co
 ```json
 {"findings":[{"severity":"blocking|important|suggestion","file":"...","line":N,"issue":"...","fix":"...","ruleId":"SEC-01","criteriaSource":"ios-coding-standard"}],
  "conformance":[{"ruleId":"SEC-01","verdict":"conformant|violated|not-applicable","file":"...","line":N,"reason":"..."}],
+ "fileCoverage":[{"path":"src/App.swift","verdict":"reviewed|skipped","reason":"..."}],
  "approved":true|false}
 ```
 
-`ruleId` + `criteriaSource` appear on a finding that cites a rule from `${CRITERIA}`. `conformance` is required whenever Step 1.78 selected at least one rule, with exactly one row per selected ID and none outside the set.
+`ruleId` + `criteriaSource` appear on a finding that cites a rule from `${CRITERIA}`. `conformance` is required whenever Step 1.78 selected at least one rule, and `fileCoverage` whenever Step 1.85 left at least one file in `reviewed[]`: one row per ID, one row per path, none outside either set.
 
 **Required: validator gate (deterministic)  -  run immediately after each reviewer returns, before merging findings.** Persist each reviewer's output and validate the file  -  the validator's exit code decides, not the LLM turn:
 
@@ -386,9 +388,15 @@ REVIEWER_FILE="$WORKTREE/.pipeline/reviewer-$N.json"
 printf '%s' "$REVIEWER_JSON" > "$REVIEWER_FILE"
 node $HOME/.claude/scripts/validate-reviewer.mjs "$REVIEWER_FILE" \
   --criteria "$WORKTREE/.pipeline/criteria-manifest.json" \
+  --coverage "$WORKTREE/.pipeline/review-files.json" \
+  && node $HOME/.claude/scripts/verify-citations.mjs "$REVIEWER_FILE" --repo "$WORKTREE" --worktree \
   && node $HOME/.claude/scripts/finding-fingerprint.mjs annotate --in-place "$REVIEWER_FILE"
 ```
 
+`verify-citations.mjs` resolves each finding's `file:line` against the checkout,
+not a commit: a round's fix is uncommitted, and HEAD would call it invented.
+Exit 1 takes the single rework below; exit 2 means not a repository.
+
 Progress line: `    → checking validator validate-reviewer ({reviewer})`
 
 `finding-fingerprint.mjs` stamps each finding with its cross-round id once the validator passes; an echoed one is kept, and anonymization leaves it intact.