@mrciphersmith/keryx 0.3.114 → 0.3.116

package/dist/core.js

@@ -1078,6 +1078,11 @@ var init_catalog = __esm(() => {
       "Anchor class_scope on the callers that break, never on the changed line.",
       "Say when the radius could not answer \u2014 a non-code change has an empty one."
     ]),
+    skill("review-pr-contract", "review", ["recommended", "full"], "Compare what the PR body claims (checklist boxes, stated changes) with the diff, and look for documentation outside the diff that the change made stale.", [
+      "Work every checklist box in pr-context.md as a row: quoted box, state, quoted diff line, expectation.",
+      "File a finding only where a quoted box or claim disagrees with a quoted diff or document line.",
+      "On a shell host stay read-only and answer NEEDS_CONTEXT with named paths instead of guessing a document."
+    ]),
     skill("review-core-boundaries", "review", ["recommended", "full"], "Review shared/core module coupling, public API stability, and dependency minimization.", [
       "Identify core/shared surfaces changed by the task.",
       "Check if feature-specific logic leaked into shared modules.",
@@ -9695,8 +9700,9 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 370,
-    "review/review-orchestrator": 1616,
+    "review/review-orchestrator": 1615,
     "review/review-performance": 359,
+    "review/review-pr-contract": 191,
     "review/review-pr-feedback": 895,
     "review/review-regression": 214,
     "review/review-security-code": 364,
@@ -28072,6 +28078,7 @@ var NOT_ROSTER = new Set([
   "review-orchestrator",
   "review-verifier",
   "review-regression",
+  "review-pr-contract",
   "review-pr-feedback",
   "review-greptile",
   "review-strict"
@@ -28125,6 +28132,10 @@ async function readSkill(root, relativePath) {
   }) : undefined;
 }
 var REGRESSION = "review-regression";
+var PR_CONTRACT = "review-pr-contract";
+function dispatchKnowsRole(dispatch, role) {
+  return Array.isArray(dispatch.roles) && dispatch.roles.includes(role);
+}
 async function requiredReviewers(root, mode, files, options = {}) {
   const inventory = await collectReviewers(root);
   const stack = await detectProjectStack(root);
@@ -28180,6 +28191,12 @@ async function requiredReviewers(root, mode, files, options = {}) {
     else
       excluded.push({ reviewer: REGRESSION, reason: "no blast radius computed for the package: there is no scope B to review" });
   }
+  if (inventory.bundled.some((r) => r.name === PR_CONTRACT)) {
+    if (options.prContext === true)
+      required.push(PR_CONTRACT);
+    else
+      excluded.push({ reviewer: PR_CONTRACT, reason: "no pr-context.md in the package: there is no PR body checklist to compare with the diff" });
+  }
   return { mode, required: required.sort(), excluded, filesKnown };
 }
 function isAttendedRun(env = process.env) {
@@ -28206,6 +28223,9 @@ async function packageHasBlastRadius(packageDir, name = "blast-radius.json") {
     return false;
   }
 }
+function packageHasPrContext(packageDir, name = "pr-context.md") {
+  return existsSync6(path46.join(packageDir, name));
+}
 async function coverageErrors(dispatch, options) {
   const record = dispatch && typeof dispatch === "object" && !Array.isArray(dispatch) ? dispatch : undefined;
   return [...await reviewerSetErrors(dispatch, options), ...record === undefined ? [] : mutationErrors(record, options)];
@@ -28226,7 +28246,10 @@ async function reviewerSetErrors(dispatch, options) {
   }
   if (record.mode === "diff" && options.files === undefined)
     return ["diff mode needs the scope-A file list: pass `--scope <scope.json>` to `keryx review start|ingest`, or run mode all"];
-  const need = await requiredReviewers(options.root, record.mode, options.files, { blastRadius: options.blastRadius });
+  const need = await requiredReviewers(options.root, record.mode, options.files, {
+    blastRadius: options.blastRadius,
+    prContext: options.prContext === true && dispatchKnowsRole(record, PR_CONTRACT)
+  });
   const selected = new Set(Array.isArray(record.selected) ? record.selected.filter(text) : []);
   const missing = need.required.filter((name) => !selected.has(name));
   if (!missing.length)
@@ -28657,6 +28680,7 @@ function dispatchErrors(value) {
 import { existsSync as existsSync8 } from "fs";
 import { cp, mkdir as mkdir9, mkdtemp, readFile as readFile23, readdir as readdir10, realpath as realpath12, rm as rm3, symlink, writeFile as writeFile6 } from "fs/promises";
 import path49 from "path";
+var MUTANT_KINDS = ["behavior", "presentation"];
 var MUTANTS_SPEC = "mutants.json";
 var EVIDENCE_DIR = "research-evidence";
 var SKIP_COPY = new Set([".git", "node_modules"]);
@@ -28676,9 +28700,39 @@ function parseMutantSpec(raw) {
     ids.add(id);
     if (m.anchor === m.replacement)
       throw new Error(`mutant ${id}: replacement equals the anchor, so nothing changes`);
-    return { id, file: m.file, anchor: m.anchor, replacement: m.replacement, note: typeof m.note === "string" ? m.note : undefined };
+    if (m.kind !== undefined && !MUTANT_KINDS.includes(m.kind))
+      throw new Error(`mutant ${id}: "kind" must be one of ${MUTANT_KINDS.join(", ")}`);
+    return {
+      id,
+      file: m.file,
+      anchor: m.anchor,
+      replacement: m.replacement,
+      note: typeof m.note === "string" ? m.note : undefined,
+      ...m.kind === undefined ? {} : { kind: m.kind }
+    };
   });
 }
+async function doneMutantIds(packageDir) {
+  const dir = path49.join(packageDir, EVIDENCE_DIR);
+  const done = new Set;
+  if (!existsSync8(dir))
+    return done;
+  for (const name of (await readdir10(dir)).filter((n) => /^mutation-\d+\.json$/.test(n))) {
+    try {
+      const record = JSON.parse(await readFile23(path49.join(dir, name), "utf8"));
+      for (const m of record.mutants)
+        if (m.status !== "invalid")
+          done.add(m.id);
+    } catch {
+      continue;
+    }
+  }
+  return done;
+}
+async function unjudgedMutants(packageDir, specs) {
+  const done = await doneMutantIds(packageDir);
+  return specs.filter((s) => !done.has(s.id));
+}
 async function pendingMutants(packageDir) {
   const dir = path49.join(packageDir, EVIDENCE_DIR);
   const specFile = path49.join(dir, MUTANTS_SPEC);
@@ -28693,18 +28747,7 @@ async function pendingMutants(packageDir) {
   } catch {
     return [];
   }
-  const done = new Set;
-  for (const name of (await readdir10(dir)).filter((n) => /^mutation-\d+\.json$/.test(n))) {
-    try {
-      const record = JSON.parse(await readFile23(path49.join(dir, name), "utf8"));
-      for (const m of record.mutants)
-        if (m.status !== "invalid")
-          done.add(m.id);
-    } catch {
-      continue;
-    }
-  }
-  return specs.filter((s) => !done.has(s.id));
+  return unjudgedMutants(packageDir, specs);
 }
 
 // src/review/research.ts
@@ -28768,6 +28811,7 @@ async function packageResearchErrors(packageDir, artifacts, findings, options =
       root: projectRootOfPackage(packageDir),
       files: await packageScopeFiles(packageDir),
       blastRadius: await packageHasBlastRadius(packageDir),
+      prContext: packageHasPrContext(packageDir),
       pendingMutants: (await pendingMutants(packageDir)).length
     });
     const completeness = a.reviewerDispatch === undefined || options.coverage === false || options.completeness === false || dispatch.length ? [] : await coverageGateErrors(packageDir, ledger);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.114",
+  "version": "0.3.116",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/install-manifest.json

@@ -465,6 +465,7 @@
         "src/gdskills/bundled/skills/review/review-clean-code/**",
         "src/gdskills/bundled/skills/review/review-highload/**",
         "src/gdskills/bundled/skills/review/review-regression/**",
+        "src/gdskills/bundled/skills/review/review-pr-contract/**",
         "src/gdskills/bundled/skills/review/review-core-boundaries/**",
         "src/gdskills/bundled/skills/review/review-flow-graph/**",
         "src/gdskills/bundled/skills/review/review-layout/**",

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

@@ -234,5 +234,5 @@ Report done only once all of these hold:
 - No finding invents a severity: each lands under **Severity (canonical)** in
   `review-orchestrator/SKILL.md`.
 - The reply is the `REVIEW_RESULT` the Orchestrated Review Contract asks for, with
-  finding ids prefixed `LY-`, or `NEEDS_CONTEXT` naming the context that was
-  missing — never a guess in its place.
+  finding ids prefixed `LY-`, or `NEEDS_CONTEXT` naming the measurement that was missing.
+  Measurements supplied as `context_files` count as evidence when they name the command and the viewport.

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

@@ -697,6 +697,11 @@ each proposed mutant to `<review-dir>/research-evidence/mutants.json`:
 `{ "mutants": [{ "id", "file", "anchor", "replacement" }] }`. `anchor` is exact text that
 occurs once in `file`; `"runnable": false` at the top level says the suite cannot run here.
 
+The testing reviewer's contract is `mutant_candidates` for **every changed branch**, including
+code downstream of the diff that the diff makes reachable differently. The main session writes
+that list to `mutants.json` unchanged. It may not narrow, drop or merge candidates to fit a
+budget: a smaller pass is a cap (below), stated, never a smaller list.
+
 Run `keryx review mutate --test "<the nearest suite command>" --package <review-dir>`. It
 applies each mutant in a scratch copy of the worktree (never in the worktree), refuses to
 start when the baseline is red, and writes the table to `research-evidence/mutation-<n>.md`
@@ -708,6 +713,12 @@ A survivor is evidence for the finding that names it.
 `dispatch.mutationWaiver = { operatorQuote, reason }` carries the operator's own words.
 `keryx review run --autonomous` is unchanged: it records `Not run: mutation pass` as before.
 
+`keryx review mutate --cap <n>` runs the first `n` candidates and records `cap` and `not_reached`
+in `mutation-<n>.json`. The table then prints `Not run: N candidates` (and the report must carry
+that line, see `keryx review report-parity`). A candidate the cap left out is still pending, so it
+keeps blocking the coverage gate until a later pass runs it; a cap moves work to the next pass, it
+never closes it.
+
 ### Severity audit — `keryx review severity-audit`
 
 A reviewer that argues a finding from a mutant writes `mutant:<id>` in the finding's `evidence`.
@@ -718,6 +729,34 @@ run executed stays minor (a major is capped at minor) and gets the label `unprov
 never deletes a finding and never touches a blocker; it is a separate pass from the verifier,
 which can only delete. `--dry-run` prints the changes without writing `findings.json`.
 
+Each mutant in `mutants.json` carries a `kind`: `behavior` (the default, and what a record written
+before the field reads as) or `presentation` (it changes only what a reader sees: a label, a
+column, copy, spacing). A behavior survivor raises as above. When the only survivors a finding
+cites are `presentation`, the severity stays, and the finding gets
+`severity_audit {held: {severity, mutant, kind: "presentation", evidence, reason}}` instead of
+`{from, to}`. A held note is not a raise and not a deletion; it is the record that a survivor was
+seen and did not move the severity, so the report must say so.
+
+`keryx review report-parity <review-dir>` prints what the round left behind as Markdown to paste
+into `report.md`: the `Not run: N candidates` line, each held note, and each follow-up still open
+as `Not verified: <text>`. The same lines show in `keryx review status`, in the shell
+`/review parity` view and in the sidebar. `keryx review complete` warns, and does not refuse, when
+any of them exists and the report names none.
+
+### Layout measurements on a shell host
+
+A shell reviewer cannot start a browser. Before dispatching `review-layout` the main session runs
+the browser measurements itself (Playwright, or Storybook with its test runner) for the changed
+components and passes the output files as `context_files` in the **first** dispatch. A measurement
+counts as evidence for `review-layout` when it names the command and the viewport it ran at; one
+without them is context, not evidence.
+
+`src/review/retry-plan.ts` treats `NEEDS_CONTEXT` as one refill: the first one re-dispatches the
+role with what it asked for. A second `NEEDS_CONTEXT` from the same role that covered no new slice and
+asks nothing new is `notRun`; the reason is `layout: no engine` for `review-layout` and `no engine` for any other
+role when its questions ask for a browser or engine and name no route without one, else `no progress after one
+context refill`, and the round goes on. A second one that covered a new slice or asked a new question still gets its refill.
+
 ### Pull request context — `keryx review context-collect`
 
 A pull-request review starts with `keryx review context-collect --repo <o/r> --pr <n> --package <review-dir>`.

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

@@ -87,6 +87,8 @@ A reviewer on this host cannot open a path: its file tool reads inside its worki
 3. **Check before dispatch.** `keryx review dispatch-check --payload <file> --manifest <dir>/manifest.json` for the wave; exit 1 means a payload names no slice, is over the wave ceiling (dispatch fewer slices, then the next wave), or breaks `reviewer-input.schema.json`. Fix it; do not dispatch around it.
 4. **One batch.** Dispatch the whole wave — up to 10 reviewers — in one message, not one at a time. Give each reviewer `max_rounds` of at least 40 (the default); a reviewer that spends its rounds reading the skill and the schema returns nothing. **Incomplete means the next wave while it makes progress, Not run when it stalls.** Every reviewer result lists the `slices` it covered, in its `REVIEW_RESULT` object, as ids (`"slices": ["slice-01", "slice-02"]`); an object with an `id` and an optional `coverage` note (`{"id": "slice-01", "coverage": "read in full"}`) is read the same way. An object with a `status` counts only when it is DONE, COMPLETE, COVERED or OK (any case); a slice marked NOT_READ, INCOMPLETE, SKIPPED or PARTIAL is not covered, so give a slice you did not read no `status` of that kind and leave it out. An entry with no id counts for nothing. **One driver file per dispatch.** Write `drivers/<reviewer>.json` next to `raw/` with `{"reviewer": "<name>", "slices": [<ids dispatched>], "result": "raw/<reviewer>.txt", "definition": "<path of the reviewer's SKILL.md>"}`: `ledger build` takes the reviewer's rule file from `definition` (a `skill_path` there, or inside a `payload` object, is read too) and the slices it was handed from `slices`. Only reviewer replies belong in `raw/`; a verification payload or a note filed there is reported as set aside and left in place, but it still costs a step. On `INCOMPLETE`, `BLOCKED` or `NEEDS_CONTEXT` (never accepted as a finished scope), and on a `DONE` that left slices open, `keryx review retry-plan --manifest <dir>/manifest.json --result <raw/reviewer.txt>` decides and hands out the next wave of only the slices still uncovered (`--next-wave` plans one without a result). A result that covered a new slice spends no attempt; two results in a row with nothing new, or six failed rounds, print the `- **Not run:** …` line to paste into the report, and a result with nothing new first has its open slices cut in half. Dispatch each wave, save its reply, and run `retry-plan` again until it says `accepted`. Only the operator can accept a smaller set than that, with their own quote. An unfinished reviewer is never counted as a clean pass. **Persist every result.** Pass each reviewer `save_result_to: .metaproject/data/review/raw/<reviewer>.txt`: the host writes its full final text there, so `review complete` has raw evidence even after the transcript is cut. Build `research.json` with `keryx review ledger build <input-dir> --package <review-dir>` — never by hand: it reads the saved results, `scope-files.json` and the retry state, marks a reviewer complete only when its result is finished and its payloads cover the scope, and prints each gap with the exact next command and the waves left (a `retry-plan --next-wave` call, or a `--dispositions` entry for a raw finding). Run `keryx review ingest --research <review-dir>/research.json` once it prints READY (exit 0). A refused `review complete` names what is missing: fix that with a command and run it again; it is never `blocked`. `--head` wants a SHA (`git rev-parse HEAD`), not `HEAD`.
 5. **Never print a scope or a slice.** The tool output of one call is cut at about 20 KB and `keryx review scope` of a large PR prints hundreds of KB. Run it as `keryx review scope --ref <base> --json > .metaproject/data/review/scope.json` and read the counts from the file (`keryx ctx read`, or `jq`); take `<base>` from `git symbolic-ref refs/remotes/origin/HEAD`, not a guessed `origin/main`. Create `.metaproject/data/review/` first (`mkdir -p`) — a missing directory is a command to run, not a blocker. **Machine artifacts by direct write.** Save slices, payloads and results by redirection or `keryx ctx run --raw -- <command>`; the summarized form of `keryx ctx run` drops the bytes a later step parses.
+6. **Write mutants whole.** A testing reviewer's `mutant_candidates` cover every changed branch, code downstream of the diff included. Write them to `research-evidence/mutants.json` unchanged; you may not narrow them, and a candidate no pass has run still blocks the coverage gate (`SKILL.detail.md`, mutation pass).
+7. **Measure before `review-layout`.** Run the browser measurements (Playwright/Storybook) yourself and pass them as `context_files` in its first dispatch; they count as evidence when the command and viewport are named. A second `NEEDS_CONTEXT` from one role is Not run (`layout: no engine`), not another refill (`SKILL.detail.md`).
 
 ## Control
 
@@ -871,6 +873,7 @@ If the repository has local convention docs such as `CLAUDE.md`, `AGENTS.md`,
 | `src/core/**`, `core/**`, `shared/**`, `foundation/**` | `review-core-boundaries` |
 | `src/core/flow/**`, `src/graph/**`, `src/shared/flow/**` | `review-flow-graph` |
 | A `.tsx`/`.jsx`/`.css`/`.scss` hunk that adds or changes a sizing or spacing utility on a rendered element — `w-*`, `min-w-*`, `max-w-*`, `flex-*`, `basis-*`, `grid-cols-*`, `truncate`, `line-clamp-*`, `overflow-*`, `p*`/`m*`/`gap-*` and their logical `ps-*`/`pe-*`/`ms-*`/`me-*` forms, or an inline `style` carrying a dimension | `review-layout` |
+| `pr-context.md` is in the package | `review-pr-contract` |
 
 These convention reviewers are additive: keep the generic reviewers selected by normal detection,
 then add the matching convention pass. Deduplicate reviewer names before dispatch.
@@ -1057,6 +1060,7 @@ Skipped reviewers:
 | `--core-boundaries` | `review-core-boundaries` |
 | `--flow-graph` | `review-flow-graph` |
 | `--layout` | `review-layout` |
+| `--pr-contract` | `review-pr-contract` |
 | `--all` | all reviewers above (including `review-clean-code`, `review-highload`, applicable legacy/profile reviewers, and project convention reviewers when local convention docs exist) |
 | `--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 |
@@ -1113,12 +1117,7 @@ Dispatch selected reviewers in parallel when independent — this engine dispatc
 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.
 
-**Execution belongs to both B and C, and they execute for opposite reasons.**
-Wave C runs a command to *decide the fate of a finding that exists*; it is
-delete-only and can produce nothing. Wave B runs commands to *make findings* —
-`review-testing-practices` deletes each gate the diff added and records whether
-the suite goes red, and `review-layout` measures rendered geometry in a real
-engine.
+**Execution belongs to both B and C, and they execute for opposite reasons.** Wave C runs a command to *decide the fate of a finding that exists*; it is delete-only and can produce nothing. Wave B runs commands to *make findings* — `review-testing-practices` deletes each gate the diff added and records whether the suite goes red, and `review-layout` measures rendered geometry in a real engine.
 
 The consequence is directional and easy to get wrong: **a surviving mutation is
 not something Wave C can hand you.** If Wave B skips its mutation pass, that

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-finding.schema.json

@@ -184,6 +184,15 @@
         "type": "string"
       }
     },
+    "follow_ups": {
+      "title": "Follow-ups handed back to the parent",
+      "description": "Work the reviewer could not do itself and leaves to the parent. Each entry becomes a research obligation `<raw>:fu<N>` (N counts from 1, in this order; a `Parent follow-up:` line after the REVIEW_RESULT block is appended) with status `unresolved`. It closes only through a disposition (`finding`, `refuted`, `out-of-scope` or `narrowed` with a \"what remains\" text); until then the ledger is not reconciled and the report lists it as not verified.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
     "slices": {
       "title": "Slices this result covered",
       "description": "The ids of the dispatched slices the reviewer read. An entry is an id string, or an object with an `id`, an optional `coverage` note and an optional `status`. `keryx review retry-plan` and `ledger build` read both. An object counts as covered only when its `status` is absent or one of DONE, COMPLETE, COMPLETED, COVERED, OK (any case); any other status (NOT_READ, INCOMPLETE, SKIPPED, PARTIAL, …) leaves the slice uncovered and is named in the plan reason or the ledger gap. An entry with no id counts for nothing.",

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-input.schema.json

@@ -89,6 +89,10 @@
           "type": "boolean",
           "description": "Run this dispatch on the caller's own model. Present in place of `provider`/`model`, never alongside them, when `keryx review tier` could not resolve a concrete model."
         },
+        "routed": {
+          "type": "boolean",
+          "description": "True when the provider/model were set by the routing table's `review` category (`keryx review tier` emits it on a routed pick) rather than tier-ranked discovery. Additive to `tier_resolution`, which still records how the tier resolved a model; the two questions are independent."
+        },
         "tier_resolution": {
           "type": "string",
           "enum": [

package/src/gdskills/bundled/skills/review/review-pr-contract/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: review-pr-contract
+model_tier: standard
+description: |
+  Use when a review package carries pr-context.md and the claims the author made there
+  need checking against the diff: a checklist box ("Documentation needed", "Tests
+  updated", "Breaking change") that the diff contradicts, and documentation outside the
+  diff that still describes the behaviour the change altered. Dispatched by
+  review-orchestrator for --pr-contract, --all, or whenever pr-context.md is in the
+  package.
+  NOT for: whether the code is correct (review-logic), whether the tests can fail
+  (review-testing-practices), or comments that the diff itself adds (review-jev-comments).
+triggers:
+  - "pr contract"
+  - "review pr contract"
+  - "pr checklist"
+  - "documentation needed"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  flags: "--pr-contract"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — PR Contract
+
+Reviewer for what the pull request says about itself.
+
+This lane exists because nobody else reads the PR body. `review-logic` reads the code,
+`review-testing-practices` reads the tests, and a retrospective review of a merged
+frontend PR missed a documentation gap that sat in plain view: the body left
+**Documentation needed** unticked while the diff added a user-visible table row, and
+the page that describes that table lives outside the diff. The box and the diff
+disagreed, and no reviewer held both.
+
+A finding here is a disagreement between two things you can quote: a line of
+`pr-context.md` and a line of the diff (or of a document). Nothing else is filed.
+
+---
+
+## What you are given
+
+- `pr-context.md` — the PR body, its checklist, the review comments and the round-1
+  intent, written by `keryx review context-collect`. Read it before the diff.
+- the diff slices the orchestrator supplies, as text in the task or as `context_files`;
+- documentation the orchestrator chose to supply with them.
+
+## The checklist form
+
+Work each checklist box and each stated claim of the PR body as one row. A row has four
+cells, and a row with an empty cell is not a finding:
+
+| Box or claim (quoted) | State | What the diff shows (`file:line`, quoted) | Expectation |
+|---|---|---|---|
+| `Documentation needed` | unticked | `src/admin/ExamplePage.tsx:41` adds a user-visible row label | A user-visible string or row is added, so the box should be ticked and a document should describe it |
+| `Tests updated` | ticked | no `*.test.*`, `*.spec.*` or `*.stories.*` file is in the diff | A ticked box names a test change; the diff has none |
+
+Boxes this lane checks, and the diff signal that contradicts each:
+
+- **Documentation** unticked, while the diff adds or changes a user-visible string, table
+  column or row, route, menu entry, command flag, config key, or error message.
+- **Tests updated** ticked, while no test, spec or story file is in the diff; or unticked
+  while one is.
+- **Breaking change** unticked, while the diff removes or renames an exported symbol, a
+  route, a flag, a schema field or a persisted key; or ticked with no such change.
+- **Screenshots / visual evidence** ticked, while `pr-context.md` links none.
+- Any other box or claim: quote it and apply the same test — what would the diff contain
+  if the box were true?
+
+A box that is not applicable (marked `N/A`) is read as the author's statement; contradict
+it only with a quoted diff line.
+
+## Documentation outside the diff
+
+When the diff changes behaviour a reader sees, look for documentation that describes it
+and was not touched:
+
+- `keryx gdgraph find <symbol>` and `keryx gdgraph affected <file>` — what points at the
+  changed file; a `.md` or docs-site file in the answer is a candidate.
+- `keryx wiki ask "<the changed behaviour>"` and `keryx wiki query` — the wiki pages that
+  name it.
+- `keryx ctx rg "<the old label or flag>" docs README.md` — the string the change
+  replaced, wherever it is still quoted.
+
+Name the document, the line that describes the old behaviour, and the diff line that
+moved it. A document that is merely related is not a finding.
+
+### On a shell host
+
+A reviewer on a shell host is read-only: its file tool reads inside its working directory
+and it runs no `keryx` command. Work from `pr-context.md` and the slices you were
+supplied. If answering needs a document you were not given, do not guess it: reply
+`STATUS: NEEDS_CONTEXT` and name the paths (or the symbol and the wiki query) the
+orchestrator should supply. Rows you could settle from what you hold are still reported.
+
+## Severity
+
+A disagreement between the body and the diff names no runtime trigger, so it is `minor`:
+the code is correct; the cost is a reader who trusts the box. A document that describes
+behaviour the diff now contradicts, where following it gives a wrong result, names its
+trigger and outcome and may be `major`. A box you cannot settle from what you hold is
+`info`, marked unverified, with the paths that would settle it.
+
+---
+
+## Class scope — required for `blocker` and `major`
+
+Every `blocker` and `major` finding must carry `class_scope`: **every** site that holds
+the shape you found, and **how you enumerated them** — the search you ran, or the guard
+that derives the set.
+
+A finding anchored to one `file:line` is a claim about one site. A document gap usually
+has siblings: the README, the docs-site page and the in-app help each quote the same
+label.
+
+```yaml
+class_scope:
+  sites: ["docs/admin/query-log.md:12", "README.md:88"]
+  enumeration_method: "keryx ctx rg for the old column label across docs and README; 2 documents still use it"
+```
+
+"I checked the others" is not an enumeration method. A single-entry `sites` list is a
+claim that the class has exactly one member — make it deliberately, because
+`review-finding.schema.json` accepts it and the next round tests it.
+
+`minor` and `info` may omit it.
+
+```markdown
+### [F-NNN] Title
+
+- **Severity**: blocker | major | minor | info
+- **File**: path/to/file:line
+- **Problem**: the box or claim, quoted, and the diff or document line that contradicts it
+- **Why it matters**: who trusts the box or the document, and what they get wrong
+- **Fix**: tick the box and add the document, or correct the claim
+```
+
+Severity comes from **Severity (canonical)** in `review-orchestrator/SKILL.md`; no table
+here. When dispatched, follow the `reviewer-input.schema.json` payload and return a
+`REVIEW_RESULT` object compatible with
+`.metaproject/skills/gdskills/review/review-orchestrator/reviewer-finding.schema.json`,
+finding ids prefixed `PC-`, then a short summary; `NEEDS_CONTEXT` rather than a guess.
+
+### 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.
+
+Severity levels are defined once, in `review-orchestrator/SKILL.md` → **Severity (canonical)**. This reviewer does not restate them: `blocker` is the four merge-blocking shapes named there and nothing else, and the `major`/`minor` boundary is the trigger-and-outcome test.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "The box is unticked, so documentation is missing." | The box is the claim under review, not the evidence. Quote the diff line that adds the user-visible string; with no such line there is nothing to file. |
+| "There is probably a docs page for this." | Probably is not a path. Find the page with `gdgraph`, `wiki ask` or `ctx rg`, or — on a shell host — return `NEEDS_CONTEXT` naming what you need. |
+| "`Tests updated` is ticked and the author is trustworthy." | Trust is not what this lane checks. If no test file is in the diff, the row is a disagreement and gets filed. |
+| "I could not open the docs, so I assume they are current." | An unread document is unverified, not clean. Say which paths were not read. |
+| "The PR body is long, I checked the main boxes." | Every box is a row. A box you skipped is a box the next round finds. |
+
+---
+
+## Verification
+
+Report done only once all of these hold:
+
+- Every checklist box in `pr-context.md` appears as a row in the checklist form, ticked or not, with the state quoted.
+- Every finding quotes both sides: the box or claim, and the diff or document line that contradicts it.
+- Every document named was found by a command or was supplied; none is inferred.
+- On a shell host, each document you needed and did not hold is named in a `NEEDS_CONTEXT` reply.
+- Every `blocker` and `major` carries `class_scope` with `sites` and an `enumeration_method` naming the search.
+- The reply is the `REVIEW_RESULT` the Orchestrated Review Contract asks for, or `NEEDS_CONTEXT` naming the context that was missing — never a guess in its place.
+
+<!-- keryx:layers-block:start -->
+## Project layers: graph, tests, wiki, memory
+
+Your payload may carry a `layers` block for your files: the files the graph says are affected, symbol neighbours, related tests, the wiki pages that describe the files and the memory entries for their module. It is bounded, and `truncated` names what was cut and the command that fetches the rest. When the diff alone does not settle a question, ask the project. Each command below is read-only and calls no model.
+
+- `keryx gdgraph affected <file>`: who depends on the file. Use it before you call a change contained, and whenever a changed export, signature or behaviour may have callers outside your files.
+- `keryx test related <file>`: the tests that cover the file. Use it before you say a behaviour is untested, and to judge whether a test would fail if the code broke.
+- `keryx wiki ask "<q>"`: what the project wiki says a module is for and which rules bind it. Use it when the intent of the code is unclear and the diff does not state it.
+- `keryx memory search "<q>"`: recorded lessons, decisions and known mistakes. Use it before you report a pattern the project may already have decided on, and when a failure looks like one it has seen.
+
+In a review package, `keryx gdgraph affected <file> --data-dir <package>/layers/graph` reads the graph built at the PR head; the tracked graph may be from another commit. A finding still rests on the code you read: what a layer says is a lead, not evidence. If a layer is empty or a command fails, say so in the report instead of guessing.
+<!-- keryx:layers-block:end -->

package/src/gdskills/bundled/skills/review/review-testing-practices/SKILL.md

@@ -85,14 +85,14 @@ this pass the class is unreachable for the whole round.
 
 ### Bounds
 
-- Mutate only gates inside **scope A**, one at a time, reverting each before the
+- Run mutants one at a time on gates inside **scope A**, reverting each before the
   next. Never leave a mutation in the tree.
 - Run the **nearest** suite, not the full one. This is not a `test:mutation`
   sweep — those are slow, opt-in, and answer a different question.
-- Cap it: the gates the diff added, plus any gate a previous round asked for. If
-  that set is larger than your budget, take the previous-round gates first and say
-  in your summary how many you did not reach. A stated cap is a result; silence
-  reads as a clean sweep.
+- Propose, do not cap: `mutant_candidates` in your `REVIEW_RESULT` names a mutant (`id`, `file`, `anchor`, `replacement`,
+  optional `kind`: `behavior` (default) or `presentation`, for copy or styling only) for **every changed branch**, code downstream of the diff included.
+  Run what your budget allows, previous-round gates first, and say how many you did not reach:
+  the main session writes your list to `mutants.json` unchanged and runs the rest. Silence reads as a clean sweep.
 - If you cannot run the suite at all, say so and skip the pass. Do **not** report
   a mutation you did not run — a predicted result is `info` at best, and this
   reviewer has no use for one.

package/src/gdskills/contracts/subagent-dispatch.schema.json

@@ -145,6 +145,10 @@
         "inherit": {
           "description": "Adaptive: the host picks the model. `keryx review tier` writes it — in place of `provider`/`model`, never alongside them — whenever it does not name a model other than the session's: no session was named by the caller (flags or KERYX_SESSION_PROVIDER/KERYX_SESSION_MODEL), the catalogue or the session model could not be ranked, or the tier resolved to the session's own model. The host resolves the accompanying `tier` against the models its own dispatch tool offers: `standard` on its session model, `deep` on its most capable class, `light` on its lighter class — each falling back to the session model when the host offers no choice. The alternative, an empty or stale `provider`/`model` pair, is schema-invalid or pins a model the runner may not have.",
           "type": "boolean"
+        },
+        "routed": {
+          "description": "True when the provider/model were set by the routing table's `review` category (`keryx review tier` emits it on a routed pick) rather than tier-ranked discovery. Additive to `tier_resolution`, which still records how the tier resolved a model; the two questions are independent.",
+          "type": "boolean"
         }
       }
     },