@mrciphersmith/keryx 0.3.84 → 0.3.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.84",
+  "version": "0.3.86",
   "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/rules/core/model-selection.mdc

@@ -326,6 +326,12 @@ recording them is one copy rather than four decisions.
   remove.
 - **Do not ask the operator which model to use per dispatch.** Asking every time
   is what made adaptive selection impossible.
+- **An interactive review round shows the computed plan once.** It is the third
+  start question of `review-orchestrator` (`model_strategy: ask`, the
+  interactive default): the complexity the round's signals give, each role's tier
+  and the model it resolves to here. The operator accepts it, takes every role to
+  `deep`, or sets it — for that round. An unattended round dispatches the
+  computed plan without asking (`adaptive`).
 - Never write a concrete model name into a skill, a rule, a dispatch template, or
   the resolution code.
 - Take the candidate set from runtime detection. Never from a literal list of

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -21,6 +21,10 @@ license: "MIT"
 
 # Flow Orchestrator
 
+## Preflight
+
+Run in the main session: this skill dispatches workers. Without the `Agent` tool, or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
+
 ## Purpose
 
 Flow Orchestrator is the Task Manager-aware implementation orchestrator. Plan bridge: publish the tasks with `plan_set` under the ids `T1`…`Tn`, mirror each `keryx flow task done` with `plan_update`, and publish Phase 4's completion choice as `proposed` — see the `session-plan-bridge` rule.
@@ -28,8 +32,6 @@ It wraps the existing gdskills pipeline with `keryx flow` state.
 
 Use this skill instead of `job-orchestrator` when the user wants a managed story/issue lifecycle with frozen acceptance criteria, task state, an explicit completion choice, Code Health, and a durable flow package in `.metaproject/flows/`.
 
-Do not modify `job-orchestrator` or `task-implementer` behavior. They remain usable without Task Manager. This skill coordinates them through flow state.
-
 ## Hard Preconditions
 
 1. Read `.metaproject/index.md` and `.metaproject/metaproject.json`.
@@ -122,9 +124,8 @@ it already tried. The flow package does.
       keryx flow next <id> --json
       ```
 
-      This is the first task whose `status` is not `done` and whose declared
-      `dependsOn` are all `done` — the ordering computed from the package
-      instead of re-derived by you from prose.
+      This is the first task not `done` whose declared `dependsOn` are all
+      `done` — computed from the package, not re-derived from prose.
 
    4. **Read the `resume` field before dispatching anything.** It has three
       answers and they are not interchangeable:
@@ -141,10 +142,9 @@ it already tried. The flow package does.
         or close the task (`keryx flow task done <id> <Tn>`). Re-dispatching
         over an unresolved attempt is how the same work gets done twice.
 
-      `keryx flow next` also lists every OTHER not-done task carrying an
-      unresolved attempt, under `unresolved`. Those are parallel dispatches that
-      never reported back; resolve them the same way before assuming the flow is
-      idle.
+      `keryx flow next` also lists every OTHER not-done task with an unresolved
+      attempt, under `unresolved`: parallel dispatches that never reported back.
+      Resolve them the same way before assuming the flow is idle.
 
    5. Before dispatching a worker for that task, record the attempt:
 
@@ -433,22 +433,20 @@ Before accepting implementation:
 1. Run focused tests for touched scope.
 2. Run `code-verifier`.
 3. Run `keryx health run` when Code Health is enabled.
-4. Check the bounds, then run `review-orchestrator` with relevant domains.
-
+4. Check the bounds, then run `review-orchestrator` with relevant domains — in this session,
+   never handed whole to one subagent: one without a dispatch tool returns `STATUS: BLOCKED`.
    ```bash
-   keryx review budget --spent <usd-so-far> --outstanding <subagents you already have in flight>
+   keryx review budget --spent <usd-so-far> --full --outstanding <subagents still running, 0 if none>
    ```
-
    A non-zero exit means the spend ceiling (3 USD by default) has been reached:
-   **stop and ask the user** rather than dispatching another fan-out.
+   **stop and ask the user** rather than dispatching another fan-out — never shrink the fan-out to fit.
+   Dispatch prompts point at sources (files, SHAs, the PR) and never paraphrase a contract.
 
-   `--outstanding` is the part that matters here. `review-orchestrator`
-   dispatches reviewers in parallel and runs *nested* under this skill, and
-   keryx cannot observe subagents in another process. Passing the count you
-   already have in flight is the only thing that makes the concurrency cap mean
-   anything across the nesting; omit it and the cap bounds the reviewer fan-out
-   alone, which the review record then states plainly rather than implying
-   otherwise.
+   `--outstanding` is the part that matters here. `review-orchestrator` runs inline
+   in this session and dispatches reviewers in parallel; keryx cannot observe other
+   subagents. Passing the count still running is the only thing that makes the
+   concurrency cap mean anything; omit it and the cap bounds the reviewer fan-out
+   alone, which the review record then states plainly. Add `--full` for `--all`.
 
 5. If findings require code changes, dispatch fix work through `task-implementer`
    and record the fix task in the flow.
@@ -586,7 +584,9 @@ the bound plus an escalation — never an unbounded loop.
    findings, affected graph, relevant wiki, and health/testing artifacts;
    identify the likely cycle cause; choose a materially different fix strategy
    or split the work into narrower tasks; record the decision in `journal.md`;
-   then continue with the enriched context.
+   then continue with the enriched context. The review round count is not reset:
+   past `REVIEW_ROUND_CAP` rounds on one merge-base..HEAD, report to the operator
+   instead of running another round.
 6. Never merge while findings or required checks remain unresolved. If the
    re-planned approach still cannot produce a mergeable PR, leave the flow
    `in-progress` and report the blocker instead of forcing completion.

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -22,14 +22,12 @@ metadata:
 license: "MIT"
 ---
 
-<SUBAGENT-STOP>
-If you were dispatched as a subagent to execute a specific task, skip this skill entirely.
-This skill is for orchestrators and interactive session-level routing only.
-Proceed directly with your assigned task.
-</SUBAGENT-STOP>
-
 # Job Orchestrator
 
+## Preflight
+
+Run in the main session: this skill dispatches sub-agents. Without the `Agent` tool, or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
+
 ## Purpose
 
 Dynamic orchestrator that builds execution plans based on user intent. Unlike a fixed pipeline, the orchestrator adapts its workflow to what the user actually needs — from "just analyze this issue" to "implement, review, and create a PR". It dispatches sub-agents (`issue-analyzer`, `context-collector`, `tests-creator`, `task-implementer`, `code-verifier`, `review-orchestrator`) and persists every step, document and retry through `keryx job`, which writes `.metaproject/jobs/<job-name>/`. Plan bridge: publish these steps with `plan_set` under the ids `keryx job status` reports, mirror each `keryx job step` with `plan_update`, and mark them `proposed` while the approval above is open — see the `session-plan-bridge` rule.
@@ -1059,16 +1057,14 @@ carried in the dispatch prompt and reported in 2.9.
 **Step 1 — check the budget before dispatching, while stopping is still possible.**
 
 ```bash
-keryx review budget --spent <usd-so-far> --outstanding <subagents this orchestrator has in flight>
+keryx review budget --spent <usd-so-far> --full --outstanding <subagents still running, 0 if none>
 ```
 
-`--outstanding` is not optional here. `src/review/caps.ts` names `job-orchestrator`
-as the outermost of the three nesting levels — `job-orchestrator` →
-`flow-orchestrator` → `review-orchestrator` — that its cap of 4 in-flight reviewers
-was chosen to survive. keryx is a CLI invoked once per command; it cannot observe
-subagents running inside another orchestrator's process. **The cap binds the nested
-total only when the parent declares its own in-flight count.** Omit `--outstanding`
-and the cap bounds the reviewer fan-out alone, which the record then states plainly.
+`--outstanding` is the number of subagents this session still has running while the
+round starts (0 when none). All three orchestrators run inline in the main session, so the
+reviewers are the only fan-out; keryx cannot observe other subagents, so **the wave size
+(at most 10 for `--all` or a full review; add `--full`) binds the total only when you
+declare that count.** Omit it and the record states that the cap bounds the reviewers alone.
 
 A non-zero exit means the spend ceiling (3 USD by default) is reached: stop and ask
 the user rather than dispatching another fan-out.
@@ -1122,30 +1118,26 @@ replaced. The command names no model — it ranks what the provider reports at r
 and, when it cannot rank anything, prints `inherit: true`, which means the dispatch
 runs on the session model. That is a correct answer, not a failure.
 
-**Step 6 — dispatch `review-orchestrator`.**
+**Step 6 — run `review-orchestrator` inline, in this main session.** Load
+`skills/gdskills/review/review-orchestrator/SKILL.md` yourself; do **not** wrap it in a
+`Task` — a subagent cannot spawn the reviewers and the skill answers
+`STATUS: BLOCKED nested_dispatch_unavailable`. Give it these inputs:
 
 ```
-Task({
-  description: "Review round <n>: <job-name>",
-  subagent_type: "general-purpose",
-  prompt: |
-    Load skill: skills/gdskills/review/review-orchestrator/SKILL.md
-
-    flags:            <selected flags, e.g. --backend --security --testing-practices>
-    commit_range:     <BASE_SHA>..HEAD
-    issue_url:        <issue URL, when the job has one — enables the Stage 1 spec gate>
-    context_doc:      <JOBS_ROOT>/<job-name>/ai/context.md
-    verification_mode: annotate
-    managed_review:   { mode: "review-flow", target: "branch", target_ref: "<feature-branch>" }
-    is_fix_round:     <true on any round after the first>
-    pr_comments:      { enabled: <true when a PR exists> }
-
-    Emit the unified report AND the fenced ```json keryx:findings``` block.
-    Dispatch review-verifier (Wave C) over the consolidated findings and return
-    its verification claims as a file path.
-})
+flags:             <selected flags, e.g. --backend --security --testing-practices>
+commit_range:      <BASE_SHA>..HEAD
+issue_url:         <issue URL, when the job has one — enables the Stage 1 spec gate>
+context_doc:       <JOBS_ROOT>/<job-name>/ai/context.md
+verification_mode: annotate
+managed_review:    { mode: "review-flow", target: "branch", target_ref: "<feature-branch>" }
+is_fix_round:      <true on any round after the first>
+pr_comments:       { enabled: <true when a PR exists> }
 ```
 
+It emits the unified report AND the fenced ```json keryx:findings``` block, and runs
+`review-verifier` (Wave C) over the consolidated findings, returning its verification
+claims as a file path.
+
 **Step 7 — verification is part of the round, not an extra.** `review-orchestrator`
 dispatches `review-verifier` in Wave C over the consolidated findings. The verifier
 **runs something** and can only delete — it never raises a severity, adds a finding,
@@ -1310,7 +1302,7 @@ FOR iteration in [1, 2, 3]:
        keryx review comments collect --repo <r> --pr <n> --sha <new-head> --round <N+1> --out <file>
        keryx review scope        --ref "$BASE_SHA" --json > scope.json
        keryx review blast-radius --ref "$BASE_SHA" --previous blast-radius.json --json > blast-radius.json
-       <dispatch review-orchestrator with is_fix_round: true>
+       <run review-orchestrator inline, in this session, with is_fix_round: true>
        keryx review ingest  --report <new-report> --ref <feature-branch> --head <new-head> \
                             --scope scope.json --blast-radius blast-radius.json \
                             --verifications <file> --refuted <file> --outstanding <n>
@@ -1985,7 +1977,7 @@ What actually bounds this orchestrator:
 | review → fix rounds | 3 | 2.7, and `max_review_iterations` (`maximum: 3`) in the input contract |
 | repetition, whatever the count says | first repeat | the STUCK CHECK in 2.7, and `keryx review loop` against the durable record |
 | retries per step | recorded, not guessed | `metrics.steps[].retries`, incremented by `keryx job step --status in-progress` and read back with `keryx job status --json` |
-| reviewer fan-out | 4 in flight | `keryx review budget --outstanding <n>` before every dispatch (2.6.1) |
+| reviewer fan-out | ≤10 per wave | `keryx review budget --outstanding <n>` before every dispatch (2.6.1) |
 | spend | 3 USD by default | `keryx review budget --spent <usd>` — a non-zero exit means stop and ask |
 
 Each of these is a number some command reads or writes. A guard no command can

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -20,8 +20,7 @@ metadata:
   version: 1.0.0
 ---
 
-<!-- SUBAGENT-STOP: If you are a subagent dispatched by another orchestrator, HALT.
-     Return STATUS: BLOCKED — autodoc-orchestrator must run as top-level agent only. -->
+**Preflight:** run in the main session. Without the `Agent` tool or depth budget, output only `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`, with no tool calls.
 
 # autodoc-orchestrator
 

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

@@ -368,3 +368,292 @@ inside) the findings they annotate — same separation the finding schema
 itself draws between a reviewer's claim (`severity`, `problem`, …) and what
 became of it (`disposition`), which a reviewer never states and this pass
 does not either.
+
+## Start questions (Step 5) — once per round, after the context pack
+
+The round asks its operator three questions, once, in one interaction, after
+Step 1 (context pack) and Step 3 (scope) — never before them: the counterpart
+question cannot be answered well until the context pack has looked for the
+other side. On Claude Code that is one `AskUserQuestion` call carrying the
+three questions; on any other host, the lettered prompt below. An unattended
+round (job pipeline, trigger, schedule) asks nothing, applies the defaults and
+records them under `### How this review was run`.
+
+1. **Reviewers** — default `--all`: every reviewer the engine detects plus every
+   project and convention reviewer its gates admit. Narrowing is an explicit
+   choice (tests only, one domain, a custom list). Flags the caller passed
+   answer this question and skip it. Convention reviewers are part of this
+   question; the job setting `convention_reviewers` still answers it in a
+   `job-orchestrator` pipeline.
+2. **Counterpart** — the other side of every contract the diff consumes or
+   mirrors: the backend for a frontend change, the frontend and other consumers
+   for a backend change. Before asking, the context pack looks for it:
+   endpoints, DTOs and rules the diff calls or mirrors, a paired PR
+   (`gh pr list --repo <counterpart> --search <branch-or-feature>`), the
+   producer at a freshly fetched SHA. The question shows what was found —
+   "no link found" included — and one checkbox, **verify the counterpart**, ON
+   by default even when nothing was found. Verification is not limited to a
+   paired PR: the other side's contracts and logic are re-read at a pinned SHA
+   every round. When the round cannot locate that code itself (repository,
+   handler, validator), it asks the operator where it is; it never records
+   `state: unavailable` on its own. Skipping verification takes a reason, and
+   the reason goes in the report.
+3. **Models** — the complexity the round already holds signals for (changed
+   files and lines, the risk class from Depth floor below, domains, scope B),
+   the per-role tier `keryx review tier` prints for each planned dispatch, and
+   the model each tier resolves to on this host. Choices: accept the plan (the
+   default), all `deep`, or custom. The plan is shown once per round, never per
+   dispatch (`rules/core/model-selection.mdc`). Skills, rules and this file name
+   tiers only; model ids appear in the rendered question and the report.
+
+```text
+Context: <PR or branch>, <N> files / <N> lines, <domains>; risk: <class>
+
+1) Reviewers     A) --all (default)  B) tests only  C) <domain> only  D) choose
+2) Counterpart   found: <endpoints, rules, paired PR — or "no link found">
+                 A) verify <backend|frontend> (default)  B) skip — give a reason
+3) Models        complexity: <low|medium|high>; <role>: <tier> → <model>, …
+                 A) accept (default)  B) all deep  C) custom
+
+> answers (default: 1A 2A 3A)
+```
+
+## Depth floor — a gating round does not degrade
+
+A round is **gating** when its verdict lets a change move: the review step of a
+flow (`flow-orchestrator` Phase 3), a pre-merge or pre-ship review, a
+re-request after fixes. A gating round runs the composition the start questions
+selected.
+
+- **No dispatch tool, no review.** A host that cannot dispatch subagents — this
+  engine running inside a subagent, say — returns
+  `STATUS: BLOCKED` with reason `nested_dispatch_unavailable` and no verdict.
+  It does not review the diff alone and call that a round. Measured (flow 405):
+  a single-agent round on a 150-line frontend PR wrote "did not dispatch any
+  sub-reviewers", approved it with two cosmetic minors, and the next human round
+  filed six real findings, every one reachable from the diff and the backend at
+  a pinned SHA.
+- **Size never lowers depth below the risk class.** The budget table sizes the
+  context, not the depth.
+- **High-risk includes a client-side mirror of a server rule** — validation,
+  limits, permissions, uniqueness, reserved names — beside the triggers the main
+  file lists.
+
+## Counterpart verification — the contract is enumerated, not summarised
+
+For an **input rule** the diff mirrors or depends on (what the server accepts
+for a name, a value, a role), the `cross_repo` entry records the producer's
+complete check set in `checks` and how that set was found in
+`enumeration_method` (`review-context.schema.json`):
+
+- every check the producer runs on that input: validators, restriction
+  utilities, uniqueness queries, reserved-name registries, and the storage bound
+  (column width, index, a downstream identifier);
+- for each check: its `source` (`file:line` at the pinned SHA), whether it is
+  case-sensitive, and the `paths` it runs on (create, update, rename, copy,
+  import, move, …).
+
+Put these rules in every reviewer dispatch:
+
+- **The facts are a starting point, not a boundary.** A reviewer may read the
+  producer itself and file what the entry missed.
+- **"The producer has no limit" is a question, not a fact.** Find what bounds
+  the value — that is where an over-long or unexpected value fails, usually as a
+  server error.
+- **Build the surfaces × checks matrix**: every surface that sends the input
+  against every check, each cell `same`, `missing`, `stricter` or `looser`.
+  `missing` is a refusal the user meets late; `stricter` blocks legal input; a
+  check the producer lacks but storage enforces is a producer defect — filed as
+  pre-existing, or fixed by a paired change.
+- **Every refusal the producer can return is shown where the user can act on
+  it** — next to the field, not as a generic toast.
+
+## Round obligations — always on, never asked
+
+These apply to every round without a question:
+
+1. **Enumerate before concluding.** Every caller and surface of a changed value
+   is found with `keryx ctx rg` or gdgraph, and the query is recorded — never
+   taken from the diff's own list.
+2. **Quantified claims are checked.** "Every", "all", "only" and "never" in the
+   PR body or the commits are compared with that enumeration; an over-claim is a
+   `minor` finding, the same class as the description-versus-diff rule.
+3. **A verified-clean line names its sites.** Each line of the `Verified clean`
+   lane names the files, sites or commands it rests on; "the frontend does the
+   same" without them is not verified.
+4. **A pre-existing defect gets a disposition.** Every pre-existing defect the
+   round finds in the contract the change touches is recorded with one: fixed in
+   the change (small, same contract), named out of scope in the PR body, or a
+   recommended issue. Found and dropped is the failure this rule exists for.
+5. **Red on the parent, per test.** Every added test fails with the parent
+   commit's production files restored; the run is the evidence.
+6. **A threaded value is pinned per site.** A parameter, key or prop passed at
+   several render sites is asserted at each site, or centralised so there is
+   one.
+7. **One rule, one implementation.** The same check implemented twice is a
+   finding, even while both copies agree.
+8. **"Do not re-raise" needs a record.** A dispatch may exclude an item only by
+   citing the PR comment, issue or decision that settled it — never a whole
+   surface ("X has no test; covered elsewhere").
+
+### Runtime research-completion ledger
+
+New managed packages carry `research.json`, initially pending. Before closing a round, enumerate unresolved observations from raw reviewers and the changed-file/consumer census, assign stable obligation IDs, and investigate them. Run the probe or inspect the relevant source and assertions: merely proposing a check does not resolve it. An unexecuted probe is not a verified claim.
+
+Supply the ledger using `keryx review ingest --research <ledger.json>` alongside the report and findings. Format: `version: 1`, `scopeReviewed: true`, `rawReconciled: true`, `obligations: [...]`. Each obligation requires `id`, `source`, `question`, `status`, `evidence`, `reason`. Status `finding` additionally requires `finding` pointing to exactly one canonical finding ID or global ID. Other terminal statuses are `refuted` and `out-of-scope`, both requiring evidence and reason. Preserve distinct scenarios when deduplicating. Assert census/reconciliation flags only after performing those checks; an empty obligations array is valid only if the actual census found no open observations.
+
+Open, deferred and unverifiable obligations block completion. If context, runtime or budget prevents resolution, retain the obligation and report incomplete; do not relabel it refuted or out-of-scope. Completion and the flow gate re-read the ledger even when the manifest says closed. Legacy packages without this artifact remain compatible, not proven complete. This gate validates the declared ledger, not the truth or exhaustiveness of its census; independent source/raw audits remain necessary.
+
+## Why Wave C verifies instead of re-scoring
+
+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).
+
+## Scope B — bounds, rejections and recompute
+
+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.
+
+## Fix rounds — dispositions, regressions, withdrawal
+
+### Every prior finding leaves the round with a disposition
+
+A fix round that reports only new findings is unreadable: the author cannot tell
+which of their fixes landed. Close the loop explicitly — one line per prior
+finding, in the report, before the new findings:
+
+| Disposition | Meaning |
+|---|---|
+| `closed` | Checked against the code, not against the commit message, and the defect is gone |
+| `open` | The fix does not reach the defect; say what is still true |
+| `partial` | One site of the class was fixed and the enumeration named others |
+| `regressed` | The fix removed this defect and introduced another — file the new one separately |
+| `withdrawn` | The finding was wrong. See below |
+
+**Check the code, not the commit message.** A commit titled *"report an abandoned
+sync as abandoned"* is a claim; the disposition is whether the branch it renamed
+is reachable and pinned. On a recorded round, two such commits asserted behaviour
+on lines no test could reach.
+
+### A fix is a change, and changes get reviewed
+
+The most expensive class in a multi-round review is **the defect the fix
+introduced**. It is systematically under-found, for a structural reason: the fix
+arrives framed as the answer to a finding, so it is read as an answer rather than
+as new code. It is new code.
+
+So scope A of a fix round includes the fix, reviewed on its own merits, and the
+report carries its own section:
+
+```markdown
+## Regressions the fixes introduced
+<[F-NNN] — the finding it was answering, and the new defect it created>
+```
+
+Recorded shapes, all from fixes that correctly closed the finding they answered:
+an early return added to stop a fall-through, which then skipped the work the
+caller needed; a persistence call added to save expanded state, which then
+persisted the broken state on the error path too. Both were closed correctly and
+both shipped a new bug in the same commit.
+
+### Withdrawing your own earlier finding
+
+A finding from a previous round that this round disproves is **withdrawn**,
+explicitly, at the top of the report, with the evidence — before any new finding.
+
+This is not a courtesy. An uncorrected wrong finding costs the author a fix they
+did not need, and it stays in `prior_findings` steering later rounds. Withdrawal
+is also the one self-correction this pipeline permits, and it is permitted because
+it is asymmetric: it *deletes* a claim, so it cannot inflate the finding count,
+which is the failure mode that removed the re-scoring pass from Wave C.
+
+State what made the original claim wrong, in one sentence, and if the same
+reasoning error has now happened twice in one review, say that too. A reviewer
+that names its own recurring error is calibrating; one that quietly drops a
+finding is hiding a result.