@mrciphersmith/keryx 0.2.69 → 0.2.71

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

@@ -0,0 +1,276 @@
+---
+name: review-verifier
+model_tier: light
+description: |
+  Use when: consolidated findings from other reviewers need to be checked before they are
+  reported — by RUNNING something that fails if the finding is real, or by confirming the
+  sites the finding named actually exist. Covers "verify the findings", "check these
+  findings", "review --verify", or dispatched by review-orchestrator as Wave C.
+  This reviewer can only DELETE. It cannot raise a severity, add a finding, or change a
+  finding's text.
+  NOT for: first-pass review (run domain reviewers first); re-scoring findings by re-reading
+  them, which is the operation this skill replaced and which is measured to degrade accuracy.
+triggers:
+  - "verify findings"
+  - "review --verify"
+  - "check these findings"
+  - "verification pass"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+license: "MIT"
+---
+
+# Review — Verifier
+
+Wave C. Reads the findings the domain reviewers produced and tries to **make each
+one fail on purpose**. Emits one verdict per finding it checked. It removes; it
+never adds and never sharpens.
+
+---
+
+## What this replaced, and why it is not coming back
+
+This slot used to hold `review-strict`: a meta-pass that re-read the consolidated
+findings and adjusted their severity, under an elevation table biased 3:1 toward
+escalation, **with no new evidence**. It was removed rather than improved,
+because the operation it performed is measured to make accuracy worse:
+
+- **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) shows the same shape from the other side:
+  +49.2 on dialogue response generation, +0.2 on maths.** Self-refinement gains
+  live on subjective tasks and vanish on verifiable reasoning. Deciding whether a
+  null-guard is missing is verifiable reasoning.
+
+So: re-reading a finding and changing what happens to it, without running
+anything, is not a rigour pass. It is a coin flip weighted toward more findings.
+If you are about to reintroduce it because it looks obviously useful — it looked
+obviously useful the first time, and the numbers above are what happened.
+
+## Why this one is different
+
+It does not re-read. 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: **75% build → 57% build and pass → 25% improve
+  coverage** — and the surviving quarter reaches **73% human acceptance**
+  (arXiv:2402.09171). A hard filter that discards three quarters of its own
+  output is what makes the remainder trustworthy.
+- **80+ agents unanimously endorsed a padding-oracle vulnerability that did not
+  exist. A single empirical test killed it.** Consensus cannot detect a
+  hallucination its members share, so this skill never votes, never polls other
+  reviewers, and never treats agreement as evidence.
+
+---
+
+## Workflow
+
+```
+review-verifier Progress:
+- [ ] Step 1: Read the consolidated findings (global_id, reviewer, class_scope, evidence)
+- [ ] Step 2: Drop every finding raised by yourself — you may not verify those
+- [ ] Step 3: For each remaining finding, choose the strongest method that is actually available
+- [ ] Step 4: Run it. Record the command and its output verbatim
+- [ ] Step 5: Emit one claim per finding checked, conforming to verification-claim.schema.json
+- [ ] Step 6: Emit nothing else — no new findings, no severity, no rewrites
+```
+
+---
+
+## Input Contract
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `findings` | array | yes | The consolidated findings, each conforming to `review-finding.schema.json`. `global_id` and `reviewer` must be present. |
+| `verifier` | string | yes | Your own name. Recorded on every claim. |
+| `branch` / `base_sha` | string | no | So a command can be run against the change under review. |
+| `verification_mode` | string | no | `off` \| `annotate` \| `filter`. Informational for you — the mode is applied by the merge, not by you. Default `annotate`. |
+
+---
+
+## Step 3 — choosing a method
+
+Three methods, strongest first. **Take the strongest one that is genuinely
+available, not the strongest one you can describe.**
+
+### 1. `execution` — run something that fails if the finding is real
+
+This is the method that works, and in this repository it is nearly always
+available: keryx is a Bun project, so `bun test <file>`, `bun run typecheck`, or a
+three-line script is cheap and immediate.
+
+The test is not "does the suite pass". It is: **construct the situation the
+finding claims is broken, and see whether it breaks.**
+
+```bash
+# Finding: "createManagedReviewPackage writes a package even when the contract gate fails"
+bun test src/review/managed.test.ts -t "refuses"     # does the guard actually fire?
+
+# Finding: "this guard is asserted against a synthetic value, so it cannot fail"
+# Delete the guarded line and re-run. If the test stays green, the finding is CONFIRMED.
+
+# Finding: "the type allows undefined here"
+bun run typecheck
+```
+
+Record the command and the relevant output. "I ran the tests and they passed" is
+not evidence; the command you ran and its output is — `bun test <file>` with
+the counts it actually printed, not a count quoted from somewhere else. (This
+sentence used to quote a fixed number, which went stale twice in one day.)
+
+A finding is `confirmed` when the procedure **reproduced the defect**, and
+`refuted` when the procedure **that would have shown the defect did not**. If the
+command you ran would not have failed either way, you have not verified anything —
+use `unverifiable` and say what you ran.
+
+### 2. `site-check` — do the named sites exist?
+
+A `blocker` or `major` carries `class_scope.sites`: every location holding the
+shape, and how the set was enumerated. Check the list.
+
+```bash
+keryx ctx rg "ensureKeryxConfigDir\(" src
+```
+
+Weaker than execution, and the reason is worth keeping in mind: this establishes
+that the code the finding describes is there. It does not establish that the
+behaviour the finding claims occurs. A site list that is right about locations and
+wrong about consequences passes this check.
+
+- Sites named, sites found → the finding is about real code. Usually
+  `unverifiable` unless the check itself settles the claim.
+- Sites named, sites **absent** → `refuted`, and the evidence is the search that
+  returned nothing.
+- The enumeration is demonstrably incomplete → that is not a refutation. The
+  finding is understated, and understatement is not yours to correct. Record
+  `confirmed` if you established the shape exists, and say so in the evidence.
+
+### 3. `reasoning` — you could not do either
+
+**Capped at `unverifiable`. It can never be `confirmed`, and it can never be
+`refuted`.**
+
+The cap is not conservatism. Reasoning alone produces no new evidence, and a
+verdict is a claim about evidence; a "verified" verdict reached by re-reading is
+exactly the `review-strict` operation whose numbers are at the top of this file.
+`refuted` is capped for the same reason in the other direction: it is the one
+verdict that removes a finding, so granting it to the weakest method would
+reinstate the removed pass with the sign flipped.
+
+Nothing checkable is lost by this. "The line this finding cites does not exist" is
+a `site-check`, not reasoning. `reasoning` is the residual — the cases where you
+ran nothing and looked up nothing — and the honest thing for the residual to say
+is *I could not verify this*.
+
+The merge enforces the cap: a `reasoning` claim carrying `confirmed` or `refuted`
+is rewritten to `unverifiable`, and the attempt is recorded in the review record.
+
+---
+
+## Iron Laws
+
+| Rule | Why |
+|------|-----|
+| **You can only delete.** No new findings, no severity changes, no edits to a finding's text. | The merge builds the record from the ORIGINAL finding and takes only your verdict. A claim carrying anything else is discarded whole, including its verdict. |
+| **Never verify your own finding.** | The reviewer that raised a finding is the one actor whose agreement carries no information about it. Refused by the merge, by name. |
+| **Reasoning alone is `unverifiable`.** | See above. Capped in code, not by this instruction. |
+| **Every verdict cites what you ran.** | An unevidenced claim is discarded and the finding stays as reported. |
+| **Never poll, never vote, never count agreement.** | 80+ agents unanimously endorsed a vulnerability that did not exist. |
+| **`unverifiable` is a normal answer.** | Expect it to be the majority. Reaching for `refuted` to look productive is how a true blocker gets deleted. |
+| **Not checking a finding removes nothing.** | A finding with no claim is reported unchanged. Absence is not a verdict. |
+
+---
+
+## Output Contract
+
+```
+STATUS: DONE | NEEDS_CONTEXT | BLOCKED
+```
+
+- `DONE` — every finding you were given was either checked or explicitly left alone.
+- `NEEDS_CONTEXT` — you cannot run anything (no working tree, no test command); say what is missing.
+- `BLOCKED` — the findings input is unreadable or carries no `global_id`.
+
+There is no `DONE_WITH_CONCERNS`: a verifier has no concerns of its own.
+
+Return one object conforming to
+`skills/review-orchestrator/verification-claim.schema.json`:
+
+````text
+```json keryx:verifications
+{
+  "status": "DONE",
+  "verifier": "review-verifier",
+  "summary": "12 findings, 4 executed, 3 site-checked, 5 unverifiable",
+  "verifications": [
+    {
+      "finding": "2026-08-29-pr-273#F-001",
+      "verdict": "refuted",
+      "method": "execution",
+      "evidence": "bun test src/lib/config-dir.writers.test.ts -t 'group-writable' -> 3 pass, 0 fail; measured mode 0700 under umask 002, the finding read the wrong call site"
+    },
+    {
+      "finding": "2026-08-29-pr-273#F-004",
+      "verdict": "unverifiable",
+      "method": "reasoning",
+      "evidence": "no command distinguishes the two orderings without a scheduler hook; nothing was run"
+    }
+  ],
+  "stats": { "confirmed": 4, "refuted": 1, "unverifiable": 5, "not_checked": 2 }
+}
+```
+````
+
+Then a short markdown summary:
+
+```markdown
+# Verification Report
+
+## Method mix
+- execution: N
+- site-check: N
+- reasoning (capped to unverifiable): N
+- not checked: N (with the reason for each)
+
+## Refuted
+<[global_id] finding — the command that ran, and what it returned>
+
+## Confirmed
+<[global_id] finding — the command that reproduced it>
+
+## Unverifiable
+<[global_id] finding — what was attempted and why it settled nothing>
+```
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---------|------------|-------------|
+| Checking whether a reported finding is real | YES | — |
+| Removing a finding an executed check refuted | YES | — |
+| Raising a severity, adding a finding, rewriting one | **NO — structurally impossible** | report it as a new round |
+| First-pass logic / frontend / backend review | NO | `review-logic`, `review-frontend`, `review-backend` |
+| Deciding what became of a finding after the fix | NO | `keryx review complete --disposition` |
+| Architectural commentary and opinion | NO | file it as a finding in a domain reviewer, with evidence |
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "I read it carefully and it's clearly correct — `confirmed`." | Reading is not a method. That is capped at `unverifiable`, in code. |
+| "It's obviously a false positive, `refuted`." | Obvious to whom, on what evidence? 80+ agents found an obvious vulnerability that did not exist. |
+| "The finding is understated; I'll bump it to blocker." | You cannot. The merge discards the whole claim and records the attempt. |
+| "Most of my verdicts are `unverifiable`, that looks bad." | It is the expected shape. TestGen-LLM discards 75% of its own output and that is why the remainder is trusted. |
+| "I also spotted something the reviewers missed." | Report it through a domain reviewer in a new round, with evidence. This pass cannot add. |
+| "I raised this finding, so I know best whether it holds." | That is exactly the case AC9 forbids. |

package/src/gdskills/contracts/review-finding.schema.json

@@ -16,7 +16,84 @@
   ],
   "properties": {
     "id": { "type": "string" },
+    "global_id": {
+      "title": "The finding's identity, unique across every review package",
+      "description": "`id` is the DISPLAY form (`F-001`) and is per-report: 15 of 43 distinct ids in the recorded corpus appear in more than one package, and `F-001` denotes six different findings, so joining a finding to a commit, a ledger row or a flow journal by `id` is unsafe for two thirds of it. `global_id` is the join key: `<reviewId>#<id>`, minted once when the finding is first recorded and CARRIED VERBATIM thereafter, so a finding re-reported in round N+1 keeps the key it was minted under in round N. Uniqueness comes from `reviewId` being a package directory name rather than from a registry, which is what makes the key recomputable from disk with no new state. Optional because 83 findings predate it and read back without one; a record written by the current pipeline always carries it. The `pattern` is not decoration: `mintGlobalFindingId` is the only writer inside this repository, but a producer outside it may supply any string, and a `global_id` that is not `<reviewId>#<id>` joins to nothing while looking like a key — the measurement in scripts/review-precision-baseline.ts splits on the separator to reach the package.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^#]+#[^#]+$"
+    },
     "reviewer": { "type": "string" },
+    "disposition": {
+      "title": "What became of this finding, and the evidence for saying so",
+      "description": "Declared HERE and deliberately NOT in the bundled reviewer-finding.schema.json: a reviewer states what is wrong, it never states what became of the finding. The measured reason this exists: precision = acted-on / (acted-on + dismissed-incorrect) computed over the recorded corpus returned 53/53 = 100%, not because the reviewers were right but because nothing on disk could express a wrong finding. `classification` looked like a validity verdict and was assigned from the ingest MODE; decisions.md said the same sentence for every finding. Only `acted-on` and `dismissed-incorrect` say anything about reviewer accuracy, which is why the three non-accuracy dismissals are separate states rather than one `dismissed` bucket — collapsing them is what makes a dismissal rate meaningless.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state"],
+      "properties": {
+        "state": {
+          "type": "string",
+          "enum": [
+            "unknown",
+            "acted-on",
+            "dismissed-incorrect",
+            "dismissed-wont-fix",
+            "dismissed-out-of-scope",
+            "dismissed-deprioritised",
+            "answered-disagree"
+          ],
+          "default": "unknown",
+          "description": "`unknown` is the default and the reading of an absent `disposition`: nobody recorded an outcome. It is never counted as valid — an unknown counted as acted-on inflates the very figure this field exists to make measurable."
+        },
+        "evidence": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the outcome is written down: the commit that closed it, the test that went red, the decision that dismissed it. A disposition without this is an assertion, and assertions are what produced a corpus whose findings all appear correct. `answered-disagree` is the one state that is NOT a dismissal: it records that our verifier refuted an external comment, which settles the code and settles nothing about the person who asked — the reply is still owed."
+        }
+      },
+      "if": {
+        "required": ["state"],
+        "properties": { "state": { "const": "unknown" } }
+      },
+      "else": { "required": ["evidence"] }
+    },
+    "verification": {
+      "title": "What an independent check found when it went looking for this finding",
+      "description": "Declared HERE and deliberately NOT in the bundled reviewer-finding.schema.json, on the same basis as `disposition`: a reviewer states what is wrong, and whether someone else could reproduce it is not something the reviewer knows. The rule is sharper for this field than for `disposition`, because the reviewer that raised a finding is the ONE actor forbidden to answer it (AC9) — declaring the property in the shape reviewers emit would put the forbidden field next to `severity` in every reviewer's output. This replaces `review-strict`, which re-read findings and adjusted severity with no new evidence: intrinsic self-correction is measured to degrade accuracy (GPT-4 on GSM8K 95.5 -> 91.5 -> 89.0 across rounds; GPT-3.5 on CommonSenseQA 75.8 -> 38.1; Huang et al., ICLR 2024, arXiv:2310.01798). An ABSENT verification means nobody checked — which is true of all 83 pre-contract findings on disk — and is never a reason to drop a finding.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["verdict", "method", "evidence"],
+      "properties": {
+        "verdict": {
+          "type": "string",
+          "enum": ["confirmed", "refuted", "unverifiable"],
+          "description": "`unverifiable` is not a failure state; it is the honest majority answer when nothing could be run. Only `refuted` removes anything, and only under verification_mode: filter."
+        },
+        "method": {
+          "type": "string",
+          "enum": ["execution", "site-check", "reasoning"],
+          "description": "Strongest first. `execution` ran a command or test that FAILS IF THE FINDING IS REAL — verification that executes rejects 85-96% of false reports against 4-15% unaided while finding 30-44% more true bugs (AnyPoC, arXiv:2604.11950). `site-check` confirmed the class_scope sites exist. `reasoning` is the residual, and it is capped: see the conditional below."
+        },
+        "evidence": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The command that ran and what it returned, or the search that enumerated the sites. A verdict with nothing behind it is the operation this replaces."
+        },
+        "verifier": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Who checked. Beyond the three properties AC7 names, and present because AC9 is otherwise untraceable after the fact: the merge refuses a claim whose verifier equals the finding's `reviewer`, but a record that does not say who verified cannot be audited for that rule — the same defect as `reviewer` being hardcoded to `review-orchestrator` on all 83 recorded findings."
+        }
+      },
+      "if": {
+        "required": ["method"],
+        "properties": { "method": { "const": "reasoning" } }
+      },
+      "then": {
+        "properties": { "verdict": { "const": "unverifiable" } },
+        "description": "Reasoning alone produces no new evidence, so it can never reach `confirmed` (AC7). It cannot reach `refuted` either, and that extension is deliberate: `refuted` is the only verdict with a destructive consequence, so granting it to the weakest method would reinstate review-strict with the sign flipped. Anything checkable is `site-check` or `execution`; `reasoning` is what is left when nothing was run."
+      }
+    },
     "severity": { "type": "string", "enum": ["blocker", "major", "minor", "info"] },
     "file": { "type": ["string", "null"] },
     "line": { "type": ["integer", "null"], "minimum": 1 },
@@ -30,6 +107,36 @@
     "blocking_merge": { "type": "boolean", "default": false },
     "related_skill": { "type": ["string", "null"] },
     "learning_candidate": { "type": "boolean", "default": false },
+    "source": {
+      "title": "Who raised this finding: one of our reviewers, or somebody on the pull request",
+      "type": "string",
+      "enum": ["internal", "external"],
+      "default": "internal",
+      "description": "Absent reads as `internal`, which is every reviewer-emitted finding and all 83 pre-contract records; it is written only for `external`, on the same rule as `disposition` — a property present on every record says nothing. The value is not descriptive: three mechanisms branch on it. An external finding cannot be removed by the verifier (a machine deciding a human's question was invalid is not an answer), is not truncated by the per-reviewer findings cap, and blocks `flow complete` while it has no reply. A finding that lost this property would quietly acquire all three of the behaviours the criteria forbid."
+    },
+    "external_ref": {
+      "title": "The GitHub comment this finding is the record of",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "author", "url", "submitted_at"],
+      "description": "Every property here exists to make ONE operation possible after a session restart: replying in the right place, to the right person, exactly once. `id` is namespaced (`review-comment:12`) because the three GitHub endpoints number independently and a bare integer collides across them.",
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "author": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "minLength": 1 },
+        "path": { "type": ["string", "null"] },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "thread_id": {
+          "type": ["string", "null"],
+          "description": "The root comment of the review thread. Null for a review submission body and for a PR-level comment, neither of which has a thread — which is why the reply for those is a new top-level comment and is recorded as such rather than pretending to be threaded."
+        },
+        "submitted_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What decides whether a later reply from someone else makes an already-handled comment new again."
+        }
+      }
+    },
     "class_scope": {
       "title": "Every site of this shape, and how the set was derived",
       "description": "A finding anchored to one file:line is a claim about one site. Repeatedly, a fix repaired that site and left its siblings — one writer of five, one operator instruction of four, six readers of eight — and the next review round found them. Required for blocker and major; optional below, because enumerating the class for every info finding is theatre.",
@@ -55,5 +162,16 @@
     "required": ["severity"],
     "properties": { "severity": { "enum": ["blocker", "major"] } }
   },
-  "then": { "required": ["class_scope"] }
+  "then": { "required": ["class_scope"] },
+  "allOf": [
+    {
+      "title": "An external finding must say which comment it is the record of",
+      "description": "Kept in `allOf` rather than merged into the root `if`/`then` above, because that pair is pinned identical to the bundled reviewer-finding schema by review-finding-class-scope.test.ts — and `external_ref` deliberately does NOT belong there. A reviewer never emits an external finding; only the comment collector does. A `source: external` without a ref is a finding that can never be replied to, which is the one outcome AC13 calls unacceptable.",
+      "if": {
+        "required": ["source"],
+        "properties": { "source": { "const": "external" } }
+      },
+      "then": { "required": ["external_ref"] }
+    }
+  ]
 }

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

@@ -79,17 +79,73 @@
         "max_prompt_tokens": { "type": ["integer", "null"], "minimum": 1000 },
         "max_output_tokens": { "type": ["integer", "null"], "minimum": 500 },
         "max_runtime_ms": { "type": ["integer", "null"], "minimum": 1000 },
-        "max_findings": { "type": ["integer", "null"], "minimum": 1 }
+        "max_findings": { "type": ["integer", "null"], "minimum": 1, "default": 10, "description": "Findings a reviewer may report. Per reviewer, not per review: a global cap on a fan-out is spent by whichever reviewer runs first. Blockers and merge-blocking findings are exempt and consume no budget. Applies to reported findings only, never to dismissal or refutation records - truncating those would rebuild the triage-survivor corpus that made precision unmeasurable." }
       }
     },
     "model": {
+      "description": "Which model runs this dispatch. Skills declare a `tier`; at dispatch time src/gdskills/model-tier.ts DISCOVERS the models runtime provider detection reported for the active provider, ranks them by size markers in their names, and places the tier relative to the session's own model — `standard` is the session model, `deep` a discovered model ranked above it, `light` one ranked below. No table of model ids exists anywhere in the resolution. When the candidates cannot be ranked, every tier keeps the session's model. `provider`/`model` remain available for an explicit lateral selection, and an omitted block inherits the parent verbatim. Two things fill this block. The interactive `spawn_subagent` tool does it in code: it builds the tier map with `buildTierMap` from its host's detection result, hands it to `resolveChildModel`, and records the outcome on the dispatch's run trace. An orchestrator authoring a dispatch document RUNS `keryx review tier`, which takes the §4.4 signals as flags and prints exactly the fields below, ready to paste (`--json` prints this object alone). It is a command rather than a documented function call because an orchestrator is an agent following prose and cannot call a TypeScript function: told to `decideDispatchModel`, it computed the tier in its head from a table, which is the mechanical step that belongs in code. When nothing can be worked out the command emits `inherit: true` instead of `provider`/`model` — the dispatch runs on the caller's own model, never a downgrade. Neither path is enforced by a reader — nothing validates a recorded resolution against the model that actually ran — so these fields are a record, not a gate.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "provider": { "type": "string", "minLength": 1 },
         "model": { "type": "string", "minLength": 1 },
-        "tier": { "type": "string", "minLength": 1 },
-        "inherit": { "type": "boolean" }
+        "tier": {
+          "description": "`light` is mechanical, verifiable work (pre-filter, class_scope existence checks, comment collection, formatting a reply); `standard` is ordinary reviewing and implementation and is the default; `deep` is genuinely hard reasoning (regression review across a blast radius, a strategy change after a failed loop, synthesis across many findings). An ENUM, not a free string, and that is the enforcement: a skill cannot write a model name into this field. The older `cheap` spelling frozen into docs/requirements/keryx-multi-agent-engine/schemas/child-model-selection.schema.json is still READ by parseModelTier, but is not accepted here — new dispatches use the three names above.",
+          "type": "string",
+          "enum": ["light", "standard", "deep"]
+        },
+        "tier_reasons": {
+          "description": "The ordered rule ids `assignTier` applied, e.g. [\"base:standard\", \"floor:blast-radius\"]. Produced by `keryx review tier` from the signals passed as flags, never written by hand: a reason list an author composes records the story they tell about the tier rather than the rules that produced it. Recorded so a tier can be explained after the run instead of re-derived from a state nobody kept. Ids rather than prose, because they are compared across runs.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "tier_resolution": {
+          "description": "Which of three outcomes produced the model, as `resolveTierModel` reports it on `TierResolution.source`. `discovered` — a model reported by runtime provider detection was assigned to this tier. `session-ranked` — ranking WORKED and placed the tier at the session's own model (always so for `standard`; for `light`/`deep` when nothing discovered ranks below/above the session). `session-fallback` — ranking was refused, or the ranking carried no rank for the session model, so the session's model is used because nothing could be worked out. Collapsing the last two would hide whether the environment was understood. Recorded, never read back: it explains a finished run and gates nothing.",
+          "type": "string",
+          "enum": ["discovered", "session-ranked", "session-fallback"]
+        },
+        "model_discovery": {
+          "description": "What was on the table when the tier was resolved: which models runtime detection reported for the active provider, how the size-marker hints ordered them, and — when ranking was refused — why. `tier_resolution` alone says a fallback happened and never says what it fell back FROM.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["provider", "candidates", "ranked", "session_rank", "fallback_reason"],
+          "properties": {
+            "provider": {
+              "description": "The provider whose catalogue was consulted. Always the session's own: candidates are never taken from a provider the parent holds no grant for.",
+              "type": "string"
+            },
+            "candidates": {
+              "description": "Every model discovered for that provider, de-duplicated, in the order detection reported it. Empty when nothing was discovered.",
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "ranked": {
+              "description": "The subset the hints could place, best first. A candidate absent from this list carried no size marker and was therefore not orderable — recorded by its absence rather than by a guessed rank.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["model", "rank"],
+                "properties": {
+                  "model": { "type": "string", "minLength": 1 },
+                  "rank": { "description": "Ordinal only. Absolute values mean nothing; only comparisons between candidates are read.", "type": "integer" }
+                }
+              }
+            },
+            "session_rank": {
+              "description": "Where the session's own model sits in the same ordering, or null when the hints could not place it — which is itself a refusal to rank, because nothing can be called above or below an unplaced anchor.",
+              "type": ["integer", "null"]
+            },
+            "fallback_reason": {
+              "description": "Why ranking was refused, or null when it was not. Prose, because it is read by a person reconstructing a run and never compared across runs.",
+              "type": ["string", "null"]
+            }
+          }
+        },
+        "inherit": {
+          "description": "Run this dispatch on the caller's own model. `keryx review tier` writes it — in place of `provider`/`model`, never alongside them — when the environment could not be worked out: no persisted session selection, an unrankable catalogue, or an unrankable session model. It is the recorded form of \"never a downgrade\": the alternative is an empty `provider`/`model` pair, which is schema-invalid and still reads like an answer. A `tier` and `tier_reasons` may accompany it, because the tier was assigned from signals even when no model could be named for it.",
+          "type": "boolean"
+        }
       }
     },
     "runtime": {