@mrciphersmith/keryx 0.2.70 → 0.2.71

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -4,10 +4,9 @@ description: |
   Use when: a code review is requested and the user does not explicitly name a specialized reviewer.
   Handles "review", "code review", "review PR", "review --frontend", "review --backend",
   "review --architecture", "review --security", "review --performance", "review --style",
-  "review --strict", "review --project-conventions", "review --legacy-profiles", "review --all". Routes to specialized reviewers in parallel and
+  "review --verify", "review --project-conventions", "review --legacy-profiles", "review --all". Routes to specialized reviewers in parallel and
   consolidates findings into one unified report.
   NOT for: running a single specialized reviewer — invoke it directly by name instead.
-version: "1.6.0"
 triggers:
   - "review"
   - "code review"
@@ -18,7 +17,7 @@ triggers:
   - "review --security"
   - "review --performance"
   - "review --style"
-  - "review --strict"
+  - "review --verify"
   - "review --all"
   - "review --clean-code"
   - "review --highload"
@@ -34,10 +33,10 @@ triggers:
   - "review --mobx-store"
 metadata:
   author: "MrCipherSmith"
-  version: "1.6.0"
+  version: "1.8.0"
   category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 # Review Orchestrator
@@ -52,20 +51,47 @@ unified report sorted by severity. It does not perform any review logic itself.
 
 ```
 Review Orchestrator Progress:
+- [ ] Step 0: On a PR target, collect external comments — `keryx review comments collect`
 - [ ] Step 1: Build Review Context Pack (PR metadata, scope, rules, context_doc summary)
 - [ ] Step 2: Detect review mode (diff mode vs. path mode)
-- [ ] Step 3: Collect bounded scope - git diff OR file list from path
+- [ ] Step 3: Build the bounded scope with `keryx review scope` — never by hand
+- [ ] Step 3b: On a deep round, compute scope B with `keryx review blast-radius` — never by browsing — and KEEP the `--json` file; `review ingest --blast-radius <file>` is refused without it
 - [ ] Step 4: Parse flags / auto-detect domain from scope
 - [ ] Step 5: Ask user to confirm optional convention reviewers (legacy/profile reviewers are flag-only, never prompted)
-- [ ] Step 6: Plan sub-agent dispatch, token budgets, and model strategy
+- [ ] Step 6: Plan sub-agent dispatch and token budgets, and compute each dispatch's model with `keryx review tier` — never by hand
 - [ ] Step 7: Stage 1 gate - spec compliance check (if issue/task provided)
 - [ ] Step 8: Dispatch selected reviewers in PARALLEL with reviewer-input schema
 - [ ] Step 9: Collect reviewer-finding schema results and handle NEEDS_CONTEXT
-- [ ] Step 10: Run strict synthesis when blockers/majors exist or --strict is set
+- [ ] Step 10: Wave C — dispatch `review-verifier` over the consolidated findings
 - [ ] Step 11: Sort by severity, deduplicate, emit unified report
 - [ ] Step 12: Emit the machine-readable `keryx:findings` block alongside the report
+- [ ] Step 13: Report the stage counts: dropped by pre-filter, refuted by the verifier, retained
+- [ ] Step 14: AFTER THE FINAL ROUND ONLY — answer every external comment once, `keryx review comments reply --final`
 ```
 
+Step 0 runs on **every** round. Step 14 runs **once**, after the last one. They are
+two commands for that reason: a caller that already runs collection per round
+would carry the posting along with it, and the reviewer would get six replies to
+one comment.
+
+### Step 6 — the model is computed, not chosen
+
+Before dispatching each reviewer, run `keryx review tier` with the signals you
+already hold (`--scope`, `--findings`, `--diff-lines`, `--fix-attempt`,
+`--verifier`, `--security`, `--forced-strategy-change`) and paste the `model`
+block it prints into that dispatch.
+
+Do NOT assign the tier by reading the table in `rules/core/model-selection.mdc`.
+Working it out in your head is exactly the mechanical step that rule moves into
+code — and it is the step that was documented as running for a whole release
+while nothing called it.
+
+The command names no model. It ranks whatever your provider reports at runtime
+and places the tiers relative to your own model; when it cannot rank anything it
+prints `inherit: true` and exits 0, which means the dispatch runs on the session
+model. That is a correct answer, not a failure — never "fix" it by writing a
+model id into a dispatch.
+
 ---
 
 ## Step 12 — the `keryx:findings` block
@@ -127,7 +153,7 @@ which of its inputs were recovered and which were never written down.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `flags` | string[] | no | One or more of: `--frontend`, `--backend`, `--architecture`, `--security`, `--performance`, `--style`, `--clean-code`, `--highload`, `--project-conventions`, `--frontend-conventions`, `--testing-practices`, `--core-boundaries`, `--flow-graph`, `--legacy-profiles`, `--code-ai`, `--b091`, `--code-style`, `--mobx-store`, `--strict`, `--all` |
+| `flags` | string[] | no | One or more of: `--frontend`, `--backend`, `--architecture`, `--security`, `--performance`, `--style`, `--clean-code`, `--highload`, `--project-conventions`, `--frontend-conventions`, `--testing-practices`, `--core-boundaries`, `--flow-graph`, `--legacy-profiles`, `--code-ai`, `--b091`, `--code-style`, `--mobx-store`, `--verify`, `--all` |
 | `path` | string | no | File or directory path to review (e.g., `src/stores/`, `src/components/UserCard.tsx`). Activates **path mode** — reviews the files at this path directly, not a git diff. |
 | `commit_range` | string | no | Explicit commit hash or range (e.g., `abc123..HEAD`). Overrides merge-base detection. Ignored in path mode. |
 | `issue_url` | string | no | GitHub issue or task URL. If provided, Stage 1 gate checks spec compliance before dispatching reviewers. |
@@ -136,6 +162,8 @@ which of its inputs were recovered and which were never written down.
 | `token_budget` | object | no | Optional budget controls: `{total, per_reviewer, diff_max_chars, file_max_chars}`. |
 | `model_strategy` | string | no | `current`, `ask`, or `adaptive`. Default: `current`; do not switch models unless user or automation allows it. |
 | `managed_review` | object | no | Optional managed review mode: `{mode, target, target_ref, flow_id, reviewers}` where mode is `lightweight`, `attach-review`, `review-flow`, or `ingest`. |
+| `verification_mode` | string | no | `off`, `annotate`, or `filter`. Default `annotate` — verdicts are recorded and nothing is removed. See Wave C. |
+| `pr_comments` | object | no | `{enabled, max_replies_total, max_sentences_per_reply}`. Defaults: enabled when a PR exists, `30`, `2`. Collect every round, reply once at the end. See External PR comments. |
 
 ---
 
@@ -166,10 +194,66 @@ Runtime CLI surface:
 keryx review attach --flow <id> --target <kind> --ref <ref>
 keryx review start --target <kind> --ref <ref>
 keryx review ingest --report <path> [--flow <id>] --ref <ref>
+                    [--verifications <file>] [--verification-mode off|annotate|filter]
+                    [--scope <scope.json>] [--blast-radius <blast-radius.json>]
+                    [--refuted <file>]
+                    # --blast-radius is REQUIRED whenever this round dispatched a
+                    # scope-B reviewer (review-regression). See below.
 keryx review status <review-id-or-path>
 keryx review complete <review-id-or-path>
+                      [--finding <id> --disposition <state> --evidence <ref>]...
 ```
 
+**An unrecognised option is refused, not ignored.** A misspelling used to be
+accepted with exit 0, so `review complete --disposition ...` printed
+`status: closed` and wrote nothing at all.
+
+`--verifications` takes what `review-verifier` returned. `--scope` takes the
+whole `--json` output of `keryx review scope`, so the package records what the
+pre-filter dropped, **with a reason per drop**, as well as what the verifier
+refuted. Without it — and with no `## Pre-filter scope` block already in the
+package — the record says **`not recorded`** for that stage rather than `0`;
+"dropped nothing" and "never ran" are different facts.
+
+`--blast-radius` is **not optional on any round that dispatched
+`review-regression`** — which is every `recommended` and `full` round, because
+`review-regression` is in both profiles. AC3 is enforced in code: an ingest
+carrying a scope-B finding with no blast-radius record is **refused**, and the
+round is not recordable until the set is supplied. Pass the `--json` output of
+`keryx review blast-radius` — the same record you computed at dispatch time to
+bound the round.
+
+Two channels, and both work:
+
+- `--blast-radius <file>` — always correct, and the one to use.
+- `.metaproject/reviews/blast-radius.json` (or
+  `.metaproject/flows/<flow>/reviews/blast-radius.json` for a flow-attached
+  round) — the handoff slot, read when no flag is passed. The ingest **consumes**
+  it: it is copied into the package it screened and removed from the slot, so a
+  later round cannot be screened against a set nobody recomputed.
+
+Do **not** write the record inside the package directory before the ingest. A
+round that names no `--review-id` has not allocated that directory yet, and
+creating it makes the ingest take the next free name instead.
+
+`--refuted` takes the findings this round **raised and then dismissed**, in the
+same finding shape, each carrying `disposition: {state, evidence}` with one of
+the `dismissed-*` states. Without it a package keeps only the survivors of an
+unlogged triage — which is why precision measured over the recorded corpus
+returns 100% whatever the reviewers actually got right.
+
+`review complete --finding <id> --disposition <state> --evidence <ref>` records
+what became of a finding when the fix round closes; the triple is repeatable, one
+group per finding. States: `unknown`, `acted-on`, `dismissed-incorrect`,
+`dismissed-wont-fix`, `dismissed-out-of-scope`, `dismissed-deprioritised`.
+Everything except `unknown` must cite where the outcome is written down — the
+commit, the test, the decision. A recorded state and its citation cannot be
+overwritten by a later close; record a correction as a new round.
+
+**Closing a fix round without dispositions leaves every finding reading
+`unknown`.** That is not "the reviewers were right"; it is "nobody wrote down
+what happened", and it is the single reason the precision figure cannot be read.
+
 Managed modes:
 
 - `lightweight`: report-only; no flow or managed review artifacts are created.
@@ -193,6 +277,147 @@ When attaching to a flow, resolve the flow by explicit `flow_id`, PR URL, issue
 URL, or branch metadata. Never mutate `.metaproject/flows/*/flow.json` from
 review code; Task Manager state changes remain owned by `keryx flow`.
 
+---
+
+## External PR comments
+
+A human or a bot reviews our pull request. Before this existed, nothing collected
+it, nothing fixed it and nothing answered it — silence was the behaviour for every
+comment, and to the person who wrote it silence is indistinguishable from
+disagreement.
+
+**Collect every round. Answer once, at the end.** Both halves are mechanical and
+both live in the CLI; the judgement — is this comment right, what do we say — stays
+here.
+
+```text
+keryx review comments collect --repo <owner/repo> --pr <n> --sha <head-sha>
+                              [--self <login>] [--round <n>] [--out <findings.json>] [--json]
+keryx review comments reply   --repo <owner/repo> --pr <n> --outcomes <file|->
+                              --sha <head-sha> --final [--dry-run]
+                              [--max-replies <n>] [--max-sentences <n>] [--max-chars <n>]
+                              [--flow-link <url>]
+```
+
+Add `--fixtures <dir>` to either to run the whole loop against JSON on disk —
+no token, no network, nothing posted. Use it to see what a reply pass would say
+before it says it.
+
+`--sha` is the commit you collected against, and it is required. The completion
+gate compares it to the pull request's head: a collection that ran before the
+comments arrived is **stale**, and a gate that could not tell the difference
+would pass a flow with unanswered reviewers on it while printing
+`0 outstanding`. A record with no SHA reads as "cannot be shown current", never
+as "fresh".
+
+### What collection does, so you do not do it by hand
+
+- Reads **all three** sources: inline review comments, review submissions and
+  their bodies, and PR-level discussion.
+- **A bot reviewer is a reviewer.** CodeRabbit, Greptile and Copilot comments go
+  down exactly the same path as a human's. The bot flag is recorded so a report
+  can say who spoke; nothing filters on it.
+- Excludes our own identity, and comments already answered — **unless** the thread
+  has a newer reply from somebody else, which makes the comment new again.
+- Everything filtered is listed with its reason. A filter that removes silently
+  reads as "nobody commented".
+
+### Severity is classified, never invented
+
+A comment on a review whose state is `CHANGES_REQUESTED` starts at **`major`**.
+Everything else starts at **`minor`**. There is no third rule and no model call.
+
+When the classifying fact is missing — an inline comment whose parent review was
+not returned, or a review state GitHub does not document — the comment is **not
+dropped and the severity is not guessed**: it takes the `minor` floor and carries
+`basis: unclassified` naming what was missing. A derived `minor` and a defaulted
+one are different claims, and a record that cannot tell them apart is the
+`dismissed-out-of-scope: 0` failure in a new field.
+
+You may **lower** a severity only by assigning a terminal disposition with a
+reason. You may never silently drop an external comment.
+
+### The verifier cannot refute an external comment
+
+An external finding enters the same fix loop as an internal one with one
+exception: **a `refuted` verdict does not remove it and does not dismiss it.** A
+human asked a question; a machine deciding the question was invalid is not an
+answer. `keryx review ingest` turns that verdict into the disposition
+`answered-disagree`, keeps the finding, and records the reclaim in `scope.md`.
+`answered-disagree` still owes a reply explaining why.
+
+The per-reviewer findings cap does not truncate external comments either, for the
+same reason: the cap drops silently, and an external comment may not be dropped
+silently.
+
+### Replying — once, at the end, briefly
+
+The reply pass runs **after the final round and before the completion gate**, so
+every reply states a settled outcome rather than an intention. `keryx review
+comments reply` refuses without `--final`; it is not a reminder you can skip.
+
+| Outcome | Reply is |
+|---|---|
+| `acted-on` | one sentence naming what changed, plus the commit SHA |
+| `answered-disagree` | one or two sentences on why not, and a link to the flow's journal entry |
+| `dismissed-out-of-scope` / `dismissed-deprioritised` | one sentence, and where it was recorded instead |
+
+Rules, all of them enforced in code rather than asked for here:
+
+- **At most two sentences per comment.** A longer reply is CUT to two and the
+  remainder is replaced by a link — the long version is not reachable from the
+  command's output. A truncation with no link to point at is refused outright: the
+  conclusion posted and the explanation nowhere is worse than either alternative.
+- A fenced code block in a reply is refused. Link, do not paste.
+- Replies go **in the thread**. A review submission body and a PR-level comment
+  have no thread — GitHub offers no reply endpoint for either — so those become one
+  top-level comment that names what it answers.
+- **Never resolve or hide a thread we did not open.** Replying is ours; resolving
+  is the reviewer's call, and auto-resolving is how a bot silences a human. The
+  resolve, hide, minimise and dismiss endpoints are unreachable through the port
+  this command uses, GraphQL included.
+- Exactly **one** reply per comment, and one disposition. A round that changed
+  nothing for a comment still gets a reply saying so, with a terminal disposition
+  — `unknown` is refused, because it is what an unanswered comment already reads
+  as.
+- Capped at **30** replies. Beyond it, one summary comment and a backlog reported
+  by id.
+- Handling is durable: `.metaproject/reviews/pr-comments/<owner>__<repo>__<n>.json`
+  records id, thread, author, url, first-seen round, handled-at, sha, disposition
+  and reply url, written after **every** post. A resumed session answers nobody
+  twice.
+
+**The trade-off, stated rather than hidden:** a reviewer who comments early waits
+until the end. That is deliberate — answering with a work-in-progress state that
+later changes is worse. If a comment **blocks** progress rather than reporting a
+problem, mark its outcome `escalate: true`: it leaves the reply queue, is reported
+to the operator immediately, and the command exits non-zero. Answering a blocking
+question at the end answers the wrong question late.
+
+---
+
+## Everything written to GitHub is brief
+
+One rule, applied to every outward surface: **PR bodies, PR comments, review
+replies, issue comments, and commit messages going to a PR.**
+
+- Lead with the conclusion. No preamble, no restating the question, no apology,
+  no summary of the flow.
+- Say what changed and where. **Link, do not paste.**
+- The reasoning, the evidence, the rejected alternatives and the round history live
+  in the flow package — `journal.md`, `context.md`, the review artifacts — which is
+  durable, searchable, and costs a reader nothing to skip.
+- A GitHub artifact that needs more than a short paragraph is a signal that the
+  detail belongs in the flow with a link out, **not** that the paragraph should
+  grow.
+- No orchestrator-written PR comment or reply exceeds two sentences without
+  carrying a link to the artifact holding the detail. The reply pass enforces
+  this; for anything else you write outward, hold yourself to it.
+
+This is deliberately asymmetric: **verbose in the flow, terse on GitHub.** The
+flow is written for whoever resumes the work; GitHub is read by someone who did
+not ask for our reasoning and is reading between other tasks.
+
 ## Review Context Pack
 
 Before routing reviewers, build a compact `review_context` object. This is the shared source of truth for all sub-agents and must follow `skills/review-orchestrator/review-context.schema.json`.
@@ -352,34 +577,152 @@ Before anything else, determine whether the request is **diff mode** or **path m
 
 See shared script: `skills/shared/git-merge-base.md`
 
-Run the script to determine `BASE_SHA`, then:
+Run the script to determine `BASE_SHA`, then let the pre-filter build the scope:
 
 ```bash
-git diff --name-only "${BASE_SHA}"   # changed files for auto-detection
-git diff "${BASE_SHA}"               # full diff passed to reviewers
+keryx review scope --ref "${BASE_SHA}" --json > scope.json   # KEEP THIS FILE
+keryx review scope --ref "${BASE_SHA}" --scoped-diff         # what reviewers get
 ```
 
+**Keep `scope.json` until the round is ingested, and pass it as `--scope`.** That
+file is how the drop list reaches the review record. `--append
+"<review-package>/scope.md"` also writes it and is still supported — it now
+REPLACES an existing `## Pre-filter scope` block rather than adding a second, and
+`review ingest` carries any block it finds forward verbatim rather than
+overwriting it — but `--scope scope.json` is the supported path, because it is
+the one that does not depend on running two commands against the same file in the
+right order.
+
+**Do not run `git diff` yourself, and do not decide what to leave out.** The
+pre-filter is deterministic code with no model call: it drops generated,
+lockfile, snapshot, vendored and minified paths, drops whitespace-only and
+comment-only change blocks, and bounds every retained change to ±20 lines of
+context (`--context <n>`) instead of the whole file. Dropping a lockfile needs no
+judgement, so it does not get one.
+
+The record carries the retained scope **and every drop with its reason**. Both
+halves are required: a scope that shrank without saying so reads afterwards as
+"we reviewed everything". Note that `--scope` takes the WHOLE `--json` document —
+handing over only its `counts` object is refused, because eight integers carry no
+reason for any individual drop.
+
+Use `.files` from `scope.json` for the auto-detection table below. A dropped path
+must not select a reviewer, and **neither may a blast-radius path**: scope B is
+under regression check, so a `.tsx` file that only appears there must not pull in
+`review-frontend`. Reviewer selection is driven by the scope-A file list alone.
+
 Scope is limited to **changes introduced in the current branch since merge-base**.
 
 ---
 
+### Scope B — the blast radius (deep rounds)
+
+Everything above is **scope A**: the change, bounded. It answers *is this change
+correct?* It does not answer *did this change break something that was working*,
+and those are different questions — only the first has ever been asked here.
+
+A deep round dispatches under **both**. Scope B is computed, never browsed:
+
+```bash
+keryx review blast-radius --ref "${BASE_SHA}" --json > blast-radius.json   # KEEP THIS FILE
+keryx review blast-radius --ref "${BASE_SHA}" --brief                      # what a scope-B reviewer is told
+```
+
+**KEEP THIS FILE** is not advice. The ingest at Step 12 is **refused** if a
+scope-B finding arrives without it — pass it back as
+`review ingest ... --blast-radius blast-radius.json`.
+
+It walks `gdgraph affected` outward from every changed file, ranks by edge
+distance, keeps distance ≤ 2, cuts at 40 files closest-first, and adds a changed
+file's naming-related tests when the graph did not already reach them. Requires a
+built graph — run `keryx gdgraph build` if it refuses.
+
+**Do not pick the files yourself, and do not widen it.** "Review the
+functionality so nothing breaks" naively means "review the whole repository every
+round", which is unaffordable *and* actively harmful: review quality decays as
+context grows — measured F1 0.65 at round 2 falling to 0.29 at round 10. An
+unbounded scope B makes later rounds worse than earlier ones.
+
+The bounds are measured on this repository, not guessed: at depth 2 the set is a
+median of 19 files (p90 65); depth 3 buys eight more in the median and doubles
+the p90. The 40-file cap fires on 25% of commits and removes only hop-2 entries
+on all but 2 of 80, so it almost never costs a direct dependent — and when it
+does, it says so.
+
+**Record the whole thing.** `--out "<review-package>/blast-radius.md"` writes the
+set, the depth, and **every file the cap removed**. A truncation nobody can see
+reads afterwards as "we checked everything", which is the claim this pipeline
+exists to stop making. An empty radius is reported as `unresolved`, not as clean:
+the graph indexes code, so a change to a skill, a rule or a schema has no blast
+radius at all and that is a different fact from "nothing depends on it".
+
+#### The scope-B question, and what is rejected
+
+> Does this change break an existing behaviour **at these sites**?
+
+Nothing else. The blast-radius set is **under regression check, not under
+review**. A finding about style, naming or architecture in code the change did
+not touch is refused **by the orchestrator in code** — not discouraged here —
+under three rules, every one of them a fact about the claim rather than about who
+made it:
+
+| Rule | Refused because |
+|---|---|
+| `outside-set` | the file is neither in the computed set nor in the changed set; the reviewer went browsing |
+| `non-regression-severity` | below `major`. Under the canonical rubric `minor` states the code behaves correctly and `info` names neither trigger nor outcome; neither can be a claim that something broke |
+| `no-link-to-change` | nothing in the finding names a changed file, module or symbol. A regression claim says THE CHANGE broke this site |
+
+Rejections are **recorded, not deleted** — raise the observation under scope A or
+as a separate review. Pass `--brief` output verbatim into the scope-B dispatch:
+the code rejection is the enforcement, but a reviewer told afterwards has already
+spent the round producing findings that will all be refused.
+
+`class_scope` on a scope-B finding names the **caller that breaks**, not the
+changed line, because that is the site a human has to look at.
+
+#### When it is recomputed
+
+| Round | Scope A | Scope B |
+|---|---|---|
+| 1 (first after the draft PR) | yes | yes |
+| 2..N | yes | recomputed only if the changed-file set moved |
+| final | yes | **yes, always** |
+
+Do not decide this by memory:
+
+```bash
+keryx review blast-radius --ref "${BASE_SHA}" --previous blast-radius.json [--final]
+```
+
+It prints the decision and the reason, and reuses the previous record when
+nothing moved. The final round recomputes whatever the file set did — otherwise a
+fix introduced in round 3 gets no regression check at all, and the round that
+certifies the flow is the one that checked the least.
+
+---
+
 ### Path Mode
 
-When a path or target is named, collect the files to review:
+When a path or target is named, collect the candidate files:
 
 ```bash
 # If a directory path is given:
 find <path> -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) | sort
 
-# If a file path is given:
-cat <file>
-
 # If a module name is given (e.g. "UserStore", "pipelines module"):
 find . -type f -name "*<name>*" \( -name "*.ts" -o -name "*.tsx" \)
 # Also check common locations: src/stores/, src/modules/, src/components/
 ```
 
-Pass the full **file contents** (not a diff) to sub-reviewers. Set `SCOPE_MODE: path`.
+Then put the list through the same exclusions before reading anything:
+
+```bash
+keryx review scope --path "src/a.ts,src/b.ts" --json > scope.json
+```
+
+Pass the full **file contents** of the paths it **retained** to sub-reviewers, and
+read none of the ones it dropped. Set `SCOPE_MODE: path`. Path mode has no hunks
+and therefore no context window; the drop list is recorded exactly the same way.
 
 **Reviewer behavior in path mode:** reviewers check the entire file content — not just added lines. All findings apply to the current state of the code, not only to changes.
 
@@ -414,6 +757,33 @@ If the repository has local convention docs such as `CLAUDE.md`, `AGENTS.md`,
 These convention reviewers are additive: keep the generic reviewers selected by normal detection,
 then add the matching convention pass. Deduplicate reviewer names before dispatch.
 
+### Stack scoping — run it after detection, before dispatch
+
+The tables above select reviewers by **file shape**. A `.ts` file looks the same
+whether or not the repository has React in it, so those tables will happily
+dispatch a React/MobX conventions reviewer at a Bun CLI with no frontend — which
+is exactly what happened here, on every review, for months.
+
+So the selected set is filtered once more, by what the repository actually
+declares:
+
+```bash
+keryx review stack --json
+```
+
+It reads `package.json` and reports, per reviewer, `include` or `exclude` with a
+reason. A reviewer carrying `metadata.stack_requires` is dispatched when **any**
+tag it names is present — matching what `keryx review stack` actually computes,
+and failing toward inclusion rather than away from it.
+
+**Its failure mode is to include, never to skip.** A missing, unparsable or
+unexpected manifest sets `uncertain`, and an uncertain detection marks every tag
+present, so every reviewer runs. A reviewer that runs needlessly costs tokens; a
+reviewer wrongly skipped hides a real defect, and that asymmetry is not close.
+
+Record the exclusions with their reasons alongside the pre-filter drops. A
+reviewer silently absent from a report reads as "it had nothing to say".
+
 ### Convention Reviewer Confirmation
 
 When convention reviewers are auto-detected and the user did not explicitly pass
@@ -498,7 +868,7 @@ Skipped reviewers:
 | `--core-boundaries` | `review-core-boundaries` |
 | `--flow-graph` | `review-flow-graph` |
 | `--all` | all reviewers above (including `review-clean-code`, `review-highload`, applicable legacy/profile reviewers, and project convention reviewers when local convention docs exist) |
-| `--strict` | runs AFTER all others; adds a strict commentary pass on consolidated findings |
+| `--verify` | `review-verifier`, AFTER all others; checks the consolidated findings by running something. Delete-only. |
 | (auto) | detected from diff file extensions — see Auto-detection table |
 
 Multiple flags may be combined. Example: `review --backend --security` dispatches
@@ -526,7 +896,85 @@ Dispatch selected reviewers in parallel when independent. Use waves when token b
 
 1. Wave A - core correctness/risk reviewers: logic, architecture, security/highload when selected.
 2. Wave B - domain reviewers: frontend/backend/testing/convention reviewers filtered to relevant files.
-3. Wave C - synthesis: strict pass when blockers/majors exist, `--strict` is set, or PR is high-risk.
+3. Wave C - **verification**: `review-verifier` over the consolidated findings, when blockers/majors
+   exist, `--verify` is set, or the PR is high-risk. See below.
+
+### Wave C — verification, and what it replaced
+
+Wave C used to run `review-strict`: a meta-pass that re-read the consolidated
+findings and **adjusted their severity with no new evidence**, under an elevation
+table biased 3:1 toward escalation. It was **removed, not improved**, and the
+reason is measured rather than stylistic:
+
+- **GPT-4 on GSM8K across self-correction rounds: 95.5 → 91.5 → 89.0.**
+  **GPT-3.5 on CommonSenseQA: 75.8 → 38.1.** Among the answers that changed,
+  correct → incorrect exceeded incorrect → correct (Huang et al., *Large Language
+  Models Cannot Self-Correct Reasoning Yet*, ICLR 2024, arXiv:2310.01798).
+- **Self-Refine (arXiv:2303.17651): +49.2 on dialogue response generation, +0.2
+  on maths.** Self-refinement gains are on subjective tasks and vanish on
+  verifiable reasoning. Judging whether a null-guard is missing is verifiable
+  reasoning.
+
+Re-scoring a finding by re-reading it is therefore not a rigour pass; it is a
+coin flip weighted toward more findings. **Do not restore it because it looks
+obviously useful — it looked obviously useful the first time.**
+
+`review-verifier` occupies the slot and differs in exactly one way that matters:
+**it runs something.** Verification that executes rejects 85–96% of false reports
+against 4–15% unaided while finding 30–44% more true bugs (AnyPoC,
+arXiv:2604.11950); Meta's TestGen-LLM funnel discards 75% of its own output
+(75% build → 57% build and pass → 25% improve coverage) and the surviving quarter
+reaches 73% human acceptance (arXiv:2402.09171).
+
+It also **never votes.** 80+ agents unanimously endorsed a padding-oracle
+vulnerability that did not exist, and a single empirical test killed it: consensus
+cannot detect a hallucination its members share, so agreement between reviewers is
+not evidence and must never be recorded as verification.
+
+That rule is about agreement *standing in for* evidence. It is not a rule that
+two verifiers may not both check the same finding: each claim is admitted on its
+own — a named non-author, a real method, real evidence, with `reasoning` already
+capped — and when two such claims reach the **same** verdict the merge records it,
+naming both verifiers and carrying both pieces of evidence. Claims that
+**disagree** still cancel, because there the only thing deciding the outcome
+would be claim order.
+
+Dispatch rules:
+
+- Pass the consolidated findings, each carrying `global_id` and the **real**
+  originating `reviewer`. A finding whose `reviewer` is the orchestrator cannot be
+  routed away from its author, so the never-self-verify rule silently stops
+  applying — that field was hardcoded to `review-orchestrator` on all 83 recorded
+  findings and is fixed only from 0.2.70 onward.
+- **A finding is never verified by the reviewer that raised it.** When only one
+  reviewer ran, its findings are simply left unverified; verifying them yourself
+  is worse than not verifying them. The merge compares the two names after
+  normalising case, surrounding whitespace, `_`/`-`, and a trailing `(model)`
+  annotation, so `review-logic `, `Review-Logic` and `review-logic (sonnet)` are
+  all the same actor. Do not try to route around it by respelling the name — the
+  comparison deliberately over-matches, because a refused claim only ever costs a
+  verdict while a missed self-verification costs the finding.
+- The verifier returns `verification-claim.schema.json`. Merge it with
+  `keryx review ingest --verifications <file>`; do not apply verdicts by hand.
+- **The verifier can only delete.** If it returns a severity, a new finding, or a
+  rewritten finding, the merge discards that whole claim and records the attempt.
+  Do not "help" by applying it.
+
+### `verification_mode`
+
+`off` | `annotate` | `filter`. **Default `annotate`, and it stays `annotate` for
+one release.**
+
+| Mode | What happens |
+|---|---|
+| `off` | No verification. Claims are refused rather than silently ignored. |
+| `annotate` | Verdicts are recorded on the findings. **Nothing is removed.** A `refuted` finding is still reported, marked refuted. |
+| `filter` | An applied `refuted` verdict removes the finding from the reported set and records it as `dismissed-incorrect`, with the verification evidence. |
+
+`annotate` is the default so the drop rate is a **measured number** before it
+costs a real finding. The risk is named rather than assumed away: SWE-agent keeps
+its equivalent step opt-in because it sometimes rejects correct patches. Do not
+switch a project to `filter` on the strength of one round.
 
 ### Agent Runtime Compatibility
 
@@ -579,6 +1027,7 @@ Each reviewer must return a `REVIEW_RESULT` object matching `skills/review-orche
 | Security vulnerabilities | NO | `review-security-code` |
 | Performance anti-patterns | NO | `review-performance` |
 | Style / naming / import order | NO | `review-style` |
+| Checking whether a reported finding is real | NO | `review-verifier` |
 | Clean Code principles + SOLID at code level | NO | `review-clean-code` |
 | Concurrency, resource pools, caching, queues, idempotency | NO | `review-highload` |
 | Frontend repository conventions | NO | `review-frontend-conventions` |
@@ -602,6 +1051,93 @@ Before consolidation, validate every reviewer result:
 
 ---
 
+## Severity (canonical)
+
+**This is the only severity rubric in the review domain.** Reviewers do not carry
+their own. Ten private rubrics feeding one sort produce a ranking that means ten
+different things at once, and ranking is what an operator uses to decide what to
+read first. A reviewer may state which of *its* conditions land where; it may not
+redefine the levels.
+
+### `blocker` — merge-blocking, and nothing else
+
+Exactly four shapes. Nothing outside this list is a `blocker`, however strongly
+the reviewer feels about it:
+
+1. **A crash** — the process, request, or render dies on an input the change
+   admits.
+2. **Data loss or corruption** — something persisted, transmitted, or returned is
+   destroyed or silently wrong.
+3. **An exploitable vulnerability** — an attacker action with a named entry point
+   and a named impact.
+4. **An unimplemented acceptance criterion** — the change claims work the diff
+   does not contain.
+
+Everything else is at most `major`. "This will definitely cause problems later"
+is not one of the four. Neither is "this violates the architecture", "this fails
+the linter", or "this is how the last outage started".
+
+### `major` / `minor` / `info` — the boundary test
+
+Ask one question, and ask it of the **finding**, not of the code:
+
+> **Does it name a trigger, and the observable outcome that trigger produces?**
+
+- **`major`** — it does. There is an input, a call, a render, or a load level, and
+  a resulting behaviour a user or a caller would call wrong: a wrong value, a lost
+  update, a leak, a hang, a cost stated together with the frequency that makes it
+  a cost. Not one of the four shapes above, so not merge-blocking — but the code
+  does the wrong thing.
+- **`minor`** — it does not, and does not claim to. The code behaves correctly;
+  the cost lands on whoever reads or edits it next, and the finding names that
+  cost at a named site.
+- **`info`** — it names neither. An observation, a preference, or a risk with no
+  demonstrated path.
+
+The test is procedural on purpose. It is applied by reading the finding, so
+someone who did not write it — and has not read the code — reaches the same
+answer: look for the trigger and the outcome. Present → `major`. Absent, but a
+concrete maintenance cost is named → `minor`. Neither → `info`.
+
+Two consequences, both previously decided differently in different files:
+
+- A finding that **claims** runtime harm and cannot name the trigger is `info`,
+  not `major`. It is not demoted to `minor`: `minor` is for findings that never
+  claimed runtime harm at all. The two are different failures and stay
+  distinguishable.
+- Severity is a property of the demonstrated outcome, never of the reviewer that
+  found it. A security reviewer's unproven concern is `info` under the same test
+  that puts a style reviewer's unproven concern there.
+- **And never of how crisply the finding is worded.** An outcome that costs a
+  user, a caller or persisted state nothing is `minor` however precisely its
+  trigger is named. Without this clause the test above rates prose quality: a
+  cosmetic wording nit stated as "trigger X produces output Y" reads as `major`,
+  while a real defect stated tersely reads as `info`. That is not academic — the
+  findings cap truncates by severity, so the well-written typo would survive and
+  the terse real defect would be cut.
+
+The boundary this rubric does **not** draw is `major` against `major`. Two
+findings that both name a trigger and an outcome are the same severity even when
+one is obviously worse; the ordering inside a severity is the operator's, and
+inventing a fifth level to express it would put us back where we started.
+
+### Shared laws (every reviewer)
+
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
+   name the input, call, or condition that reaches the code, you have an
+   observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code
+   under review. Do not report a safe API because it could be misused, or a
+   pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears
+   at several sites, report it once and list every site. Ten findings that are one
+   finding hide the other nine problems.
+
+`review-security-code` carries a fourth — every security finding states its attack
+vector — which does not generalise and stays there.
+
+---
+
 ## Finding Format
 
 ### Class scope — required for `blocker` and `major`
@@ -702,6 +1238,18 @@ STATUS: DONE | DONE_WITH_CONCERNS
 - minor: N
 - info: N
 
+## Stage counts
+<!-- Required. State what each stage REMOVED, and never state it as a precision
+     improvement: no precision baseline exists to improve on. The one measured
+     from the review packages on disk was 53/53 = 100% — pinned there by
+     construction, because nothing in that corpus could record a finding as
+     wrong. Copy these from `scope.md`; do not re-count by hand. -->
+- dropped by pre-filter: <files>, <blocks>, <changed lines> (or `not recorded` if no scope was built)
+- verification mode: `<off | annotate | filter>`
+- verdicts: confirmed N, refuted N, unverifiable N, unverified N
+- refuted by the verifier: N (removed: N — always 0 outside `filter`)
+- retained: N
+
 ## Blockers (must fix before merge)
 <[F-NNN] findings with severity=blocker, sorted by file>
 
@@ -770,13 +1318,22 @@ Publish this review report to the PR?
 
 ### Concise PR Comment
 
-The visible PR comment is for humans. It must be written in English only and stay concise.
+The visible PR comment is for humans. It must be written in English only and stay
+concise, under the brevity rule above: **the summary is at most two sentences and
+carries a link to the artifact holding the detail.**
+
+The finding rows below are a bounded exception, not a licence: they exist because
+a reviewer scanning a PR needs the blockers in front of them. Keep them to the
+`blocker` and `major` rows; everything at `minor` or below goes behind the
+`<details>` fold or, better, into the AI artifact and is linked. The full findings
+set, the round history and the reasoning belong in the flow package — pasting them
+here is the failure this rule names.
 
 ```markdown
 ## AI Review Report
 
 **Verdict:** REQUEST_CHANGES
-**Summary:** 2-3 concise sentences with overall risk and the main merge blocker.
+**Summary:** At most two sentences: the overall risk and the main merge blocker. Detail: <link to the AI artifact or the flow package>.
 
 | Severity | Area | Finding | Suggested Fix | Owner |
 |---|---|---|---|---|
@@ -948,6 +1505,18 @@ If absent, proceed normally — context is optional and non-blocking.
 | "Spec compliance can wait until after quality review" | Stage 1 gate exists because unimplemented requirements invalidate quality work |
 | "I'll deduplicate findings manually in my head" | Always normalize to [F-NNN] format before consolidation to avoid losing findings |
 | "Minor findings from one reviewer cancel out the major from another" | Each finding stands independently; severity is per-finding, not averaged |
+| "The reviewer's own severity table said blocker" | There are no reviewer tables. One rubric, in **Severity (canonical)** above; a reviewer that ships one is the defect this replaced |
+| "It's a security/architecture finding, so it's a blocker" | Severity is the demonstrated outcome, not the domain that found it. `blocker` is exactly the four shapes |
+| "It will definitely break something eventually, so blocker" | Name the trigger and the outcome. Named → `major`. Unnamed → `info`. "Eventually" is neither |
+| "A strict re-read of the findings will sharpen them" | That pass existed and was removed: self-correction without new evidence measured 95.5 → 91.5 → 89.0 on GSM8K and 75.8 → 38.1 on CommonSenseQA. Run something instead |
+| "Three reviewers agree, so the finding is verified" | Consensus is not evidence. 80+ agents unanimously endorsed a vulnerability that did not exist; one empirical test killed it |
+| "The verifier suggested a higher severity, I'll apply it" | It cannot suggest one. A claim carrying a severity is discarded whole and the attempt is recorded |
+| "This finding has no `verification`, so it can be dropped" | Absent means nobody checked. All 83 recorded findings are in that state; none of them is thereby wrong |
+| "Precision went up after the verifier landed" | There is no precision baseline to have gone up from. State stage counts: dropped, refuted, retained |
+| "I'll widen the blast radius, this change looks risky" | It is bounded because review quality decays with context: F1 0.65 at round 2 → 0.29 at round 10. Widening makes the later rounds worse, not safer |
+| "The blast radius came back empty, so nothing can break" | Empty and unresolved are different facts. The graph indexes code — a Markdown or JSON change has no radius at all, and the record says which one you got |
+| "The changed files are the same as last round, so scope B can be skipped on the final round" | The final round always recomputes. A fix landed in round 3 is the change; skipping means the certifying round checked the least |
+| "This scope-B file has an obvious naming problem, I'll report it" | Rejected in code: a naming problem is `minor` at best, and the floor is `major`. The set is under regression check, not under review — raise it under scope A |
 | "No flags means no reviewers" | No flags → run auto-detection; never produce an empty review |
 | "User named a module so I'll use diff mode" | Named module/component/store → path mode; diff mode is only for branch changes |
 | "Path mode should only show lines I'd flag in diff mode" | Path mode reviews the entire file — all findings apply, not just added lines |