@sabaiway/agent-workflow-kit 1.49.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.49.0",
+  "version": "2.1.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/review-ledger.md

@@ -13,7 +13,7 @@ The review-round **LEDGER** (DEBT-REVIEW-CAP / AD-045) — it turns the prose re
    - **`--telemetry`** → read-only COUNTS across ALL loops and BOTH ledgers (never combined with the other flags — a mixed-mode gate cmd would silently pass): rounds/segments per loop, finding-origin totals, classification distribution (incl. `refuted`), per-backend verdict + divergence-round counts, override usage by scope, gate-run counts (quality-green / red results by gate id), fold runs, observed-red receipts, quarantined probes. Counts only — which gates earn their keep stays the maintainer's judgment.
 
 2. **Writer** — `node ${CLAUDE_SKILL_DIR}/tools/review-ledger-write.mjs record|classify|override|batch --json '<payload>'` (the SOLE writer, over the shared `atomic-write` core):
-   - `record` appends one round — `{ loop, round, origins, backends, findings }` (activity defaults to `plan-execution`). **The teeth (Decision 5 + AD-048, all per SEGMENT):** it REFUSES (typed STOP) to append a round WHILE `decideStop` on the segment's records is `triage-required` (an UNCLASSIFIED surviving blocking finding at/after the cap); refuses ANY round beyond the **hard-max ceiling of 3 within one segment** unconditionally (the counter reopens only at the next gated commit); refuses while a blocking finding of the segment's previous round **VANISHED unclassified** (present means present-as-blocking — a downgrade to minor does not survive; a pending `escalate` never clears; `refuted` is the honest phantom lane); refuses while the changed source surface exceeds the **diff-size cap** (`AW_REVIEW_DIFF_CAP`, default 400 new-side lines of assessable + unsupported SOURCE — tests and out-of-domain never count, pure deletions are free) without a recorded segment `size-cap` override; and refuses without a **quality-green gate-run** at the current fingerprint (`run-gates --record` — gates-before-review is computed, not remembered; a `--only` subset or a tree-changed run never satisfies; red PROCESS gates — the kit's own `--check` loop gates — never block). **Integrity binding (Decision 7):** each NON-degraded backend needs a grounded **code** receipt (from `codex-review code` / `agy-review code --facts @f`) for the current tree — a round cannot be recorded for a tree no bridge reviewed. **`--from-receipts`** (BUGFREE-3 / AD-049) DRAFTS the `backends[]` from those receipts instead of hand-composing them: each recipe-named backend's verdict comes from its fresh grounded code receipt and its counts are computed from the supplied `findings` (`origins` / `findings` stay explicit input); a recipe-named backend with no receipt is a LOUD stop — the draft never invents one (supply it explicitly as a degraded backend if the bridge really is down).
+   - `record` appends one round — `{ loop, round, origins, backends, findings }` (activity defaults to `plan-execution`). **The teeth (Decision 5 + AD-048, all per SEGMENT):** it REFUSES (typed STOP) to append a round WHILE `decideStop` on the segment's records is `triage-required` (an UNCLASSIFIED surviving blocking finding at/after the cap); refuses ANY round beyond the **hard-max ceiling of 3 within one segment** unconditionally (the counter reopens only at the next gated commit); refuses while a blocking finding of the segment's previous round **VANISHED unclassified** (present means present-as-blocking — a downgrade to minor does not survive; a pending `escalate` never clears; `refuted` is the honest phantom lane); refuses while the changed source surface exceeds the **diff-size cap** (`AW_REVIEW_DIFF_CAP`, default 400 new-side lines of assessable + unsupported SOURCE — tests and out-of-domain never count, pure deletions are free) without a recorded segment `size-cap` override; and refuses without a **quality-green gate-run** at the current fingerprint (`run-gates --record` — gates-before-review is computed, not remembered; a `--only` subset or a tree-changed run never satisfies; red PROCESS gates — the kit's own `--check` loop gates — never block). **Integrity binding (Decision 7):** each NON-degraded backend needs an **attesting** code receipt for the current tree — a round cannot be recorded for a tree no bridge really reviewed. *Attesting* is the SHARED predicate (`review-ledger-core`) that `review-state` and the round cross-check read too, so the gates can never disagree about what counts: a fresh `code` receipt at the current fingerprint that is **grounded** AND carries an explicit **`probe:false`**. A `probe:true` receipt never attests (a probe review runs with the quality guards off), and a **malformed or ABSENT** marker is rejected fail-closed — silence is not a declaration, so a receipt from a pre-marker bridge no longer counts (refresh it: `npx @sabaiway/agent-workflow-kit@latest init`). Each exclusion states its own reason, because the recoveries differ. **`--from-receipts`** (BUGFREE-3 / AD-049) DRAFTS the `backends[]` from those receipts instead of hand-composing them: each recipe-named backend's verdict comes from its fresh grounded code receipt and its counts are computed from the supplied `findings` (`origins` / `findings` stay explicit input); a recipe-named backend with no receipt is a LOUD stop — the draft never invents one (supply it explicitly as a degraded backend if the bridge really is down).
    - `classify` appends one triage — each surviving blocking finding of a SEGMENT round classified `fixable-bug` / `inherent-layer-residual` / `escalate` / **`refuted`** (v4 — the honest lane for a phantom finding, refuted against code: a MANDATORY non-empty `note` cites the grounds; never silently dropped, never folded). **A `fixable-bug` REQUIRES a `testId`** (M2/AD-046, schema v2) — the red→green test that pins the fold, formatted `<test-file>#<test-name-pattern>` (a `#` separator, both halves non-empty; no file-suffix rule); `inherent-layer-residual` / `escalate` may omit it. The writer validates the FORMAT only. **This is what BREAKS the deadlock:** once every surviving blocking finding is classified, `record` permits the next round (a `fixable-bug` classification lets the fix round run — no deadlock).
    - `override` appends one override record (schema v3, BUGFREE-1/AD-047) — the LOUD, durable waiver the **fold-completeness** gate consumes, `{ loop, round, scope, reason }` plus the per-scope payload (EXACT — a stray key is refused): scope **`oracle-change`** → `files[]`, the repo-relative pre-existing test files whose tamper flag it lifts (a fix diff that deliberately rewrote test expectations); scope **`red-proof`** → `testId`, the ONE bound test whose observed-red receipt + custody it waives (a red genuinely unestablishable pre-fold, or a custody file legitimately edited post-fix); scope **`size-cap`** (v4) → `sanctionedLines`, the EXACT changed-surface magnitude the waiver sanctions — **segment-scoped** (it dies at the next commit; a grown surface needs a fresh recorded sanction). Teeth: schema validation, fail-closed ledger read, round-sequence integrity, and the loop must be the SINGLE in-flight plan. QUARANTINE (a flaky/timed-out probe) has NO override lane. Overrides never enter `decideStop` — the two v3 scopes are fold-completeness inputs; `size-cap` is a writer-tooth input.
    - **`gate-run` records (v4, kind `gate-run`)** are minted by `run-gates --record` through the writer's `recordGateRun` API (the runner never opens the ledger itself) — the D5 green-baseline receipt: the FULL declaration + exactly what ran + the tree fingerprint BEFORE and AFTER the run, segment-framed with NO round number, minted only inside the single in-flight loop. A red run records honestly (telemetry fuel); **quality-green** (every declared NON-process gate green, tree unchanged under the run) is judged at read time. Revert-first beyond this is not mechanically observable at this layer — it ships as protocol + telemetry visibility (consecutive red gate-runs), stated plainly.

package/references/modes/review-state.md

@@ -4,8 +4,8 @@ Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shippe
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
-1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, per-backend receipt state (current / stale / ungrounded / missing) with verdict + grounding + timestamp.
-2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a solo-resolved recipe (configured, or degraded there — no ready reviewer), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend receipted **current + grounded** — **or degraded-exempt**: the current segment's latest **review-ledger** round records that backend `degraded:true` at the current tree fingerprint, with ≥1 non-degraded recipe-named backend present + grounded and the ledger reading clean (AD-050; a corrupt ledger DENIES the exemption fail-closed but never fails an otherwise-satisfied tree — the tool header is the single home). Exit 1 when a backend is missing, **stale** (ANY edit after its review moves the fingerprint), or grounded:false under reviewed/council, and is not degraded-exempt. **Presence, not unanimity:** verdict adjudication (ship/revise, the divergence crossover) stays orchestrator judgment — the gate only proves the configured backends really reviewed THIS tree (a recorded degrade counts as "reviewed", never as "converged" — that stays `review-ledger`'s job). Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green.
+1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, per-backend receipt state (current / stale / ungrounded / probe / rejected / missing) with verdict + grounding + timestamp.
+2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a solo-resolved recipe (configured, or degraded there — no ready reviewer), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend receipted **current + grounded** — **or degraded-exempt**: the current segment's latest **review-ledger** round records that backend `degraded:true` at the current tree fingerprint, with ≥1 non-degraded recipe-named backend present + grounded and the ledger reading clean (AD-050; a corrupt ledger DENIES the exemption fail-closed but never fails an otherwise-satisfied tree — the tool header is the single home). Exit 1 when a backend is missing, **stale** (ANY edit after its review moves the fingerprint), or grounded:false under reviewed/council, and is not degraded-exempt. **Presence, not unanimity:** verdict adjudication (ship/revise, the divergence crossover) stays orchestrator judgment — the gate only proves the configured backends really reviewed THIS tree (a recorded degrade counts as "reviewed", never as "converged" — that stays `review-ledger`'s job). Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — a backend whose only current receipts are probes fails with its own stated reason, distinct from stale. The filter is **per receipt**, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a marker-aware wrapper writes `probe` on **every** successful review — `true` or `false` — so the receipt states the fact itself, and a **malformed** *or* **absent** marker is rejected **fail-closed** and stated in the check line, never silently dropped. This is deliberately **not** keyed on the wrapper version: the version bumps in a different release phase than the marker lands, so a version floor would reject the very receipts the current wrappers write — and it could only ever proxy a fact the receipt already carries. Accepted cost: a pre-marker receipt stops satisfying — re-run the review with a marker-aware bridge. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
 3. **Wire it as a gate by hand OR via the explicit-consent seeder — never without consent (AD-021/AD-042).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated seeder (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`, consent-seed section) offers exactly this entry — path resolved and quoted — ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces); it writes nothing without your explicit yes. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate.
 4. **`--await [--timeout <s>]`** (BUGFREE-3 / AD-049) → BLOCK until every recipe-named backend is SATISFIED for the current tree (i.e. until `--check` would PASS), or the bounded timeout elapses (a loud exit 1; default 900s). Run it after dispatching the review bridges to WAIT for their receipts to land instead of hand-polling a pid: the durable completion signal is the **receipt**, never a process event (a harness "completed" notification fires early; a bridge's output late-flushes). It waits until each backend has a fresh grounded receipt **OR is degraded-exempt**: once a current-tree degrade is recorded in the review-ledger, `--await` stops waiting for that backend and returns READY (AD-050 — it inherits the `--check` exemption via the shared decision), so you no longer hand-`--await` around a known degrade. Still read-only (it only re-reads state, now the ledger too); solo / no-plan / clean-tree resolve instantly.
 

package/tools/detect-backends.mjs

@@ -91,7 +91,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
-        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); a write failure warns, never fails the review',
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); a write failure warns, never fails the review',
       },
     },
     bin: 'codex',
@@ -110,13 +110,14 @@ const RAW_BACKENDS = [
     roleContracts: {
       review: {
         invocations: [
-          'agy-review code [--facts @f] [--decided @f] [--focus "…"] [extra focus…]',
+          'agy-review code [--facts @f] [--ungrounded] [--decided @f] [--focus "…"] [extra focus…]',
           'agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus "…"]',
           'agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus "…"]',
         ],
-        grounding: 'grounded review — agy reads NOTHING by default, an ungrounded review GUESSES: --facts @f = the verified facts to review AGAINST; --decided @f = decisions already made, do NOT re-raise (anti-circling)',
+        grounding: 'grounded review — agy reads NOTHING by default, an ungrounded review GUESSES: --facts @f = the verified facts to review AGAINST; --decided @f = decisions already made, do NOT re-raise (anti-circling). code mode REQUIRES a non-empty --facts payload and refuses BEFORE spending a run (escapes: --ungrounded, AGY_PROBE=1); plan/diff proceed with a loud warning',
         flags: [
-          '--facts @f — verified facts the review runs AGAINST (omit ⇒ loud ungrounded-review warning)',
+          '--facts @f — verified facts the review runs AGAINST (code mode REQUIRES a non-empty payload; plan/diff warn loudly when omitted)',
+          '--ungrounded — deliberately ungrounded CODE review, a throwaway opinion (code mode only, contradicts --facts; the receipt records grounded:false and never attests)',
           '--decided @f — already-decided / already-addressed list; do NOT re-raise (anti-circling; the round-2 payload)',
           '--focus "…" — extra focus (repeatable; code mode also takes trailing focus words)',
         ],
@@ -124,7 +125,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); a write failure warns, never fails the review",
         notes: [
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
         ],

package/tools/manifest/schema.md

@@ -20,6 +20,7 @@ expansion), never via the shell. The validator is [`validate.mjs`](./validate.mj
 | `settings` | array | no | the bridge's **settings-file surface** (typed; see *Settings*). Unlike `contract`, a malformed entry **fails** `--strict`. |
 | `networkHosts` | string[] | no | the backend CLI's **observed egress host families** (see *Network hosts*). A malformed list **fails** `--strict`. |
 | `writableDirs` | object[] | no | the backend CLI's **writable state-dir declarations** — `{env, default}` entries (see *Writable dirs*). A malformed list **fails** `--strict`. |
+| `modeCatalog` | object[] | no | the bridge's **user-facing operating modes** — what each mode is FOR and when to reach for it (see *Mode catalog*). A malformed block **fails** `--strict`. |
 | `install` / `uninstall` | object | no | `install.npm` is a package name, not a path |
 | `cost` / `quota` / `provenance` | misc | no | informational |
 | `available` | boolean | no | `false` = a declared-but-not-installed stub; skips fs/version checks |
@@ -128,6 +129,67 @@ declared path is only the **default under no override**. Rules:
   `sandbox.filesystem.allowWrite` or any other filesystem allowance — the entries feed the
   sandbox-lane discoverability item (session/host sandbox config is hand-applied territory).
 
+## Mode catalog (BRIDGE-MODES-CATALOG)
+
+`modeCatalog` answers the question the `contract` block deliberately does not: **what modes does
+this bridge offer, and what is each one FOR?** The `contract` is the internal DRIVING contract (how
+a dispatching agent invokes a role); the catalog is the **user-facing discovery surface**. They are
+related, never nested: a catalog entry backed by a contract **composes by reference** and never
+restates a descriptor.
+
+**Additive-optional.** The schema stays `1`. An absent block is **valid** — a bridge released before
+the catalog keeps validating, and the mode renders a stated *"no catalog — this bridge predates it"*
+line rather than `invalid-manifest` or an empty silent list. A **present** block is typed-validated
+like `settings`: the renderer prints these strings verbatim and builds invocation forms from the
+refs, so a malformed entry would render a lying discovery surface.
+
+**Currency claim (honest scope):** the catalog tracks the **documented wrapper mode set** — never
+"the CLI's modes". Upstream CLI evolution enters through a bridge release, where the source-level
+drift tests fail loudly until the catalog is updated. Nothing here ever probes a live CLI.
+
+An **array** of entries (an object would silently dedupe keys under `JSON.parse`). Each entry:
+
+- `key` (string, required) — a **unique bare token** (`exec`, `review.plan`, `exec.resume-last`).
+  For an `env-hook` the key **IS** its env-var name, so it must be UPPER_SNAKE_CASE.
+- `kind` (string, required) — the closed taxonomy:
+  - `primary` — a mode you drive directly (`codex exec`, `agy-review code`, the raw `agy-run`).
+  - `continuation` — resumes a mode already in flight (`--resume-last`, `--continue`).
+  - `env-hook` — an env var that MODIFIES named modes (`CODEX_PROBE`). It names `parents[]`, never
+    a role: an env var is not a capability, and a fake role would corrupt the recipe planner.
+- `role` (string) — required on `primary`/`continuation`, must be a declared key of `roles`;
+  **forbidden** on an `env-hook`.
+- `parents` (string[]) — required and non-empty on an `env-hook`, resolving to catalog keys (never
+  itself); **forbidden** elsewhere.
+- `submode` (string) — the **explicit** binding to the wrapper's parser mode arm. Present exactly
+  when the entry is a `primary` **and** its role declares `modes[]`; must be one of them. The
+  bridge drift tests set-equal these against the wrapper's REAL arms — the binding is never parsed
+  back out of the key.
+- `purpose` (string, required) — one line: what the mode is for.
+- `whenToUse` (string[], required, non-empty) / `whenNotTo` (string[], optional) — the reach-for-it
+  and reach-for-something-else signals.
+- `invocationRefs` (object[]) — **composition by reference**: `{contractField, index}` into
+  `roles[<role>].contract.invocations` / `.continue`. Required (non-empty) on a contract-backed
+  entry; every ref must resolve, and a contract invocation is claimed by **at most one** entry.
+- `descriptor` (string) — the literal invocation form. Allowed **only** where no contract exists (a
+  contract-free primary such as a raw-prompt mode, or an env-hook): for those the catalog IS
+  canonical — the stated exception to no-duplication.
+- `operands` (object[], optional) — `{slot, required, description}`. Typed **catalog data**, never
+  parsed out of contract strings. Each `slot` is unique within the entry and must really appear in
+  one of the entry's rendered invocation forms — the render labels an unfilled form a **template**
+  and names each required operand, so a slot with nowhere to go would be a lie.
+- `guardrails` (object[], optional) — `{value, enforcement, condition?, source}`. `enforcement` is
+  `enforced` **only** for an OS-/code-enforced fact; where the guarantee has a runtime bound, the
+  `condition` carries it (e.g. a hard timeout is enforced *only when `timeout(1)`/`gtimeout` is on
+  PATH*). Anything a prompt merely asks for renders `advisory`. `source` names where the fact lives.
+- `customHooks` (string[], optional) — this mode's escape hatches, as catalog keys. Each is either
+  an **env-hook that really lists this mode in its `parents[]`** (a hook can never lie about a mode
+  it does not target), or the entry's **own key** — the raw-mode carve-out: a contract-free primary
+  IS its own escape, so it references itself rather than repeating one it does not have.
+
+Every string the renderer prints (`purpose`, `whenToUse`/`whenNotTo` items, `descriptor`, operand
+`description`, guardrail `value`/`condition`/`source`) is ONE line of at most **200** characters
+with no control characters — the surface is a terminal-width list and a pasted form.
+
 ## Path-field rules (Windows-safe, traversal-safe)
 
 These rules govern the **repo/project-relative path fields** enumerated below (`source`,

package/tools/manifest/validate.mjs

@@ -60,6 +60,31 @@ export const settingValueValid = (entry, value) => {
   }
 };
 
+// ── `modeCatalog` vocabulary (BRIDGE-MODES-CATALOG, D2/D4/D6) ────────────────────────
+// Every `modeCatalog` string the mode renderer prints is ONE capped line: the surface is a
+// terminal-width discovery list, and a control character would break the line (or a pasted form).
+export const CATALOG_LINE_MAX = 200;
+// The closed entry taxonomy (D4): a `primary` is a mode you drive; a `continuation` resumes one; an
+// `env-hook` MODIFIES named parents (an env var is never a fake role).
+export const CATALOG_KINDS = new Set(['primary', 'continuation', 'env-hook']);
+// `enforced` is claimable only for an OS-/code-enforced fact (a runtime bound rides in `condition`);
+// everything a prompt merely asks for is `advisory` (D6).
+export const CATALOG_ENFORCEMENT = new Set(['enforced', 'advisory']);
+// The AD-033 `contract` fields that carry invocation descriptors — the only referenceable ones.
+export const CATALOG_CONTRACT_FIELDS = new Set(['invocations', 'continue']);
+// The operand-slot grammar the RENDERER speaks: `<angle>` and `[bracket]` placeholders, with an
+// optional `@` riding WITH the slot (`@<facts-file>` is one operand a user types, not a bare
+// `<facts-file>` behind a stray character). Production owns it here; the bridge test suites keep
+// their own local copy ON PURPOSE — they ship as standalone bridge payload and must not import the
+// kit, so their regex is an INDEPENDENT drift oracle across the package boundary, not a duplicate.
+export const CATALOG_SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+export const extractCatalogOperandSlots = (form) => (typeof form === 'string' ? form.match(CATALOG_SLOT_RE) ?? [] : []);
+
+const CATALOG_KEY_RE = /^[A-Za-z][A-Za-z0-9._-]*$/;
+const ENV_HOOK_KEY_RE = /^[A-Z][A-Z0-9_]*$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
+
 const hasTraversal = (p) => p.split(/[\\/]/).includes('..');
 const isUnresolved = (s) => /\{\{|\}\}|\$\{/.test(s);
 
@@ -124,6 +149,292 @@ export const readAuthoritativeVersion = (skillDir) => {
   return { version: null, from: 'no package.json or SKILL.md' };
 };
 
+// Validate a PRESENT `modeCatalog` block against `roles` (BRIDGE-MODES-CATALOG, D1/D2/D4/D6). It is
+// the USER-FACING mode catalog the `bridge-modes` renderer prints verbatim and composes invocation
+// forms from — RELATED TO, never shadowing, the AD-033 `contract` (the internal driving contract):
+// a contract-backed entry composes BY REFERENCE and never restates a descriptor; a contract-FREE
+// primary (a raw prompt mode) and an env-hook carry a literal one — the stated exception to
+// no-duplication, because for them the catalog IS canonical. Errors are appended, never thrown.
+const validateModeCatalog = (catalog, roles, errors) => {
+  const oneLine = (label, value) => {
+    if (typeof value !== 'string' || !value) {
+      errors.push(`${label} must be a non-empty string`);
+      return false;
+    }
+    if (CONTROL_CHAR_RE.test(value)) {
+      errors.push(`${label} must not carry control characters`);
+      return false;
+    }
+    if (value.length > CATALOG_LINE_MAX) {
+      errors.push(`${label} must be one line of at most ${CATALOG_LINE_MAX} characters`);
+      return false;
+    }
+    return true;
+  };
+  const stringList = (label, value) => {
+    if (!Array.isArray(value) || value.length === 0) {
+      errors.push(`${label} must be a non-empty array of one-line strings`);
+      return;
+    }
+    value.forEach((v, i) => oneLine(`${label}[${i}]`, v));
+  };
+
+  // The key index is built FIRST: `parents[]` and `customHooks[]` resolve ACROSS entries, so a
+  // forward reference resolves exactly like a backward one (declaration order is not a contract).
+  const byKey = new Map();
+  for (const entry of catalog) {
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    if (typeof entry.key === 'string' && entry.key && !byKey.has(entry.key)) byKey.set(entry.key, entry);
+  }
+
+  const seenKeys = new Set();
+  const claimedRefs = new Set(); // "<role>.<field>[<index>]" — one contract invocation, at most one entry
+  catalog.forEach((entry, i) => {
+    const at = `\`modeCatalog[${i}]\``;
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push(`${at} must be an object`);
+      return;
+    }
+    const isEnvHook = entry.kind === 'env-hook';
+
+    if (typeof entry.key !== 'string' || !CATALOG_KEY_RE.test(entry.key)) {
+      errors.push(`${at}.key must be a bare token (a letter, then letters/digits/._-)`);
+    } else if (!oneLine(`${at}.key`, entry.key)) {
+      // The key IS the mode's printed identity — it obeys the same one-line contract as any other
+      // rendered string (the token regex already bars control characters; this bars a giant key).
+    } else if (seenKeys.has(entry.key)) {
+      errors.push(`duplicate modeCatalog key "${entry.key}" (${at})`);
+    } else {
+      seenKeys.add(entry.key);
+      if (isEnvHook && !ENV_HOOK_KEY_RE.test(entry.key)) {
+        errors.push(`${at}.key must be an UPPER_SNAKE_CASE env-var name (an env-hook's key IS its env var)`);
+      }
+    }
+    if (!CATALOG_KINDS.has(entry.kind)) {
+      errors.push(`${at}.kind must be one of primary|continuation|env-hook`);
+      return; // every rule below is keyed on the kind
+    }
+
+    oneLine(`${at}.purpose`, entry.purpose);
+    stringList(`${at}.whenToUse`, entry.whenToUse);
+    if (Object.hasOwn(entry, 'whenNotTo')) stringList(`${at}.whenNotTo`, entry.whenNotTo);
+
+    let role = null;
+    if (isEnvHook) {
+      if (Object.hasOwn(entry, 'role')) errors.push(`${at}.role is not allowed on an env-hook (it names parents[], never a role)`);
+      if (!Array.isArray(entry.parents) || entry.parents.length === 0) {
+        errors.push(`${at}.parents is required for an env-hook (the catalog keys it modifies)`);
+      } else {
+        const seenParents = new Set();
+        for (const p of entry.parents) {
+          const target = typeof p === 'string' ? byKey.get(p) : undefined;
+          if (target === undefined) {
+            errors.push(`${at}.parents names ${JSON.stringify(p)} which is no modeCatalog key`);
+            continue;
+          }
+          if (p === entry.key) {
+            errors.push(`${at}.parents must not name the env-hook itself`);
+            continue;
+          }
+          if (seenParents.has(p)) {
+            errors.push(`duplicate parent ${JSON.stringify(p)} (${at})`);
+            continue;
+          }
+          seenParents.add(p);
+          if (target.kind === 'env-hook') {
+            errors.push(`${at}.parents names ${JSON.stringify(p)}, which is an env-hook — a hook modifies a mode, never another hook`);
+            continue;
+          }
+          // The linkage is SYMMETRIC. The forward rule below stops a customHook from lying about a
+          // hook that does not target it; this is the reverse: a hook that claims a mode must be
+          // declared BY that mode, or the mode's rendered detail silently omits a hook that really
+          // changes how it runs — an incomplete discovery surface is the failure this block exists
+          // to prevent.
+          if (!Array.isArray(target.customHooks) || !target.customHooks.includes(entry.key)) {
+            errors.push(`${at}.parents names ${JSON.stringify(p)}, which does not list ${JSON.stringify(entry.key)} in its customHooks[]`);
+          }
+        }
+      }
+    } else {
+      if (Object.hasOwn(entry, 'parents')) errors.push(`${at}.parents is only allowed on an env-hook`);
+      if (!Object.hasOwn(entry, 'role')) errors.push(`${at}.role is required for a ${entry.kind} entry`);
+      else if (typeof entry.role !== 'string' || !Object.hasOwn(roles, entry.role)) {
+        errors.push(`${at}.role ${JSON.stringify(entry.role)} is no role of this manifest`);
+      } else {
+        role = entry.role;
+      }
+    }
+
+    // `submode` is the EXPLICIT parser-arm binding (D4) — the drift test set-equals these against the
+    // wrapper's real mode arms, so the binding is never parsed back out of the key.
+    const roleModes = role != null && Array.isArray(roles[role]?.modes) ? roles[role].modes : null;
+    if (Object.hasOwn(entry, 'submode')) {
+      if (typeof entry.submode !== 'string' || !entry.submode) errors.push(`${at}.submode must be a non-empty string (it names a parser mode arm)`);
+      else if (entry.kind !== 'primary') errors.push(`${at}.submode is only allowed on a primary entry (only a primary binds a parser mode arm)`);
+      else if (roleModes == null || roleModes.length === 0) errors.push(`${at}.submode is only allowed when the entry's role declares modes[]`);
+      else if (!roleModes.includes(entry.submode)) errors.push(`${at}.submode ${JSON.stringify(entry.submode)} is no declared mode of role "${role}"`);
+    } else if (entry.kind === 'primary' && roleModes != null && roleModes.length > 0) {
+      errors.push(`${at}.submode is required (a primary whose role declares modes[] binds one)`);
+    }
+
+    const contract = role != null ? roles[role]?.contract : null;
+    const contractBacked = !isEnvHook && contract != null && typeof contract === 'object' && !Array.isArray(contract);
+    // The kind BINDS the contract field it may claim: a primary DRIVES a mode (`invocations`), a
+    // continuation RESUMES one (`continue`). Crossing them would render a resume form as a drive
+    // form (or the reverse) — a lie in exactly the surface the catalog exists to make honest.
+    const requiredField = entry.kind === 'primary' ? 'invocations' : 'continue';
+    // A continuation has nothing to be canonical ABOUT: D6's literal-descriptor exception covers a
+    // contract-free PRIMARY (a raw prompt mode) and an env-hook only. A role with no `continue`
+    // contract simply has no continuation to catalog.
+    if (entry.kind === 'continuation' && !contractBacked) {
+      errors.push(`${at}: a continuation must be contract-backed (the literal-descriptor exception covers contract-free primaries and env-hooks only)`);
+    }
+    // The invocation forms this entry really renders — the domain every operand slot must live in.
+    const forms = [];
+    if (contractBacked) {
+      if (Object.hasOwn(entry, 'descriptor')) errors.push(`${at}.descriptor is only allowed on a contract-free primary or an env-hook (a contract-backed entry composes BY REFERENCE)`);
+      if (!Array.isArray(entry.invocationRefs) || entry.invocationRefs.length === 0) {
+        errors.push(`${at}.invocationRefs is required (non-empty) for a contract-backed entry`);
+      } else {
+        entry.invocationRefs.forEach((ref, j) => {
+          const rat = `${at}.invocationRefs[${j}]`;
+          if (ref == null || typeof ref !== 'object' || Array.isArray(ref)) {
+            errors.push(`${rat} must be a {contractField, index} object`);
+            return;
+          }
+          if (!CATALOG_CONTRACT_FIELDS.has(ref.contractField)) {
+            errors.push(`${rat}.contractField must be one of invocations|continue`);
+            return;
+          }
+          if (ref.contractField !== requiredField) {
+            errors.push(`${rat}.contractField must be "${requiredField}" for a ${entry.kind} entry (a primary drives, a continuation resumes)`);
+            return;
+          }
+          if (!Number.isSafeInteger(ref.index) || ref.index < 0) {
+            errors.push(`${rat}.index must be a non-negative integer`);
+            return;
+          }
+          const declared = contract[ref.contractField];
+          const form = Array.isArray(declared) ? declared[ref.index] : undefined;
+          if (typeof form !== 'string' || !form) {
+            errors.push(`${rat} does not resolve (roles.${role}.contract.${ref.contractField}[${ref.index}])`);
+            return;
+          }
+          // A REFERENCED form is printed exactly like a literal descriptor, so it obeys the same
+          // one-line contract. The AD-033 `contract` block is otherwise validator-TOLERATED (its
+          // shape is drift-guarded by the bridge tests, not here) — this checks only the invocations
+          // a catalog entry causes to be PRINTED, and the label names the contract as their home.
+          if (!oneLine(`${rat} → roles.${role}.contract.${ref.contractField}[${ref.index}]`, form)) return;
+          const claim = `${role}.${ref.contractField}[${ref.index}]`;
+          if (claimedRefs.has(claim)) errors.push(`duplicate modeCatalog invocation reference ${claim} (${at})`);
+          else claimedRefs.add(claim);
+          forms.push(form);
+        });
+      }
+    } else {
+      if (Object.hasOwn(entry, 'invocationRefs')) errors.push(`${at}.invocationRefs is only allowed on a contract-backed entry`);
+      if (!Object.hasOwn(entry, 'descriptor')) errors.push(`${at}.descriptor is required (a contract-free entry is canonical for its own invocation form)`);
+      else if (oneLine(`${at}.descriptor`, entry.descriptor)) forms.push(entry.descriptor);
+    }
+
+    // Descriptor honesty (D2), BOTH ways. The render labels an unfilled form a TEMPLATE and names
+    // each required operand, so the declared slots and the placeholders the forms really carry must
+    // be the SAME set: an invented slot names an operand with nowhere to go, and an UNDECLARED
+    // placeholder is worse — the render shows a form as if it were ready to run while the reader has
+    // no idea what to put there or whether it is required. `required` is deliberately NOT inferred
+    // from the bracket shape (`<extra flags...>` is legitimately optional): the grammar fixes a
+    // slot's IDENTITY, the catalog fixes its semantics.
+    const renderedSlots = new Set(forms.flatMap((f) => extractCatalogOperandSlots(f)));
+    const hasOperands = Object.hasOwn(entry, 'operands');
+    if (forms.length > 0 && renderedSlots.size > 0 && !hasOperands) {
+      errors.push(`${at}.operands is required because its invocation forms contain rendered operand slots`);
+    }
+    if (hasOperands) {
+      if (!Array.isArray(entry.operands) || entry.operands.length === 0) {
+        errors.push(`${at}.operands must be an array of typed operand slots`);
+      } else {
+        const seenSlots = new Set();
+        entry.operands.forEach((op, j) => {
+          const oat = `${at}.operands[${j}]`;
+          if (op == null || typeof op !== 'object' || Array.isArray(op)) {
+            errors.push(`${oat} must be a {slot, required, description} object`);
+            return;
+          }
+          const slotOk = oneLine(`${oat}.slot`, op.slot);
+          if (typeof op.required !== 'boolean') errors.push(`${oat}.required must be a boolean`);
+          oneLine(`${oat}.description`, op.description);
+          if (!slotOk) return;
+          if (seenSlots.has(op.slot)) errors.push(`duplicate operand slot "${op.slot}" (${oat})`);
+          else seenSlots.add(op.slot);
+          // Checked only once the forms really resolved (else the error is noise).
+          if (forms.length > 0 && !renderedSlots.has(op.slot)) {
+            errors.push(`${oat}.slot "${op.slot}" is not a rendered placeholder in this entry's invocation forms`);
+          }
+        });
+        if (forms.length > 0) {
+          for (const slot of renderedSlots) {
+            if (!seenSlots.has(slot)) errors.push(`${at}.operands is missing rendered slot "${slot}"`);
+          }
+        }
+      }
+    }
+
+    if (Object.hasOwn(entry, 'guardrails')) {
+      if (!Array.isArray(entry.guardrails) || entry.guardrails.length === 0) {
+        errors.push(`${at}.guardrails must be an array of typed guardrail entries`);
+      } else {
+        entry.guardrails.forEach((g, j) => {
+          const gat = `${at}.guardrails[${j}]`;
+          if (g == null || typeof g !== 'object' || Array.isArray(g)) {
+            errors.push(`${gat} must be a {value, enforcement, condition?, source} object`);
+            return;
+          }
+          oneLine(`${gat}.value`, g.value);
+          if (!CATALOG_ENFORCEMENT.has(g.enforcement)) errors.push(`${gat}.enforcement must be one of enforced|advisory`);
+          if (Object.hasOwn(g, 'condition')) oneLine(`${gat}.condition`, g.condition);
+          oneLine(`${gat}.source`, g.source);
+        });
+      }
+    }
+
+    if (Object.hasOwn(entry, 'customHooks')) {
+      if (!Array.isArray(entry.customHooks) || entry.customHooks.length === 0) {
+        errors.push(`${at}.customHooks must be a non-empty array of modeCatalog keys`);
+      } else {
+        const seenHooks = new Set();
+        for (const hook of entry.customHooks) {
+          const target = typeof hook === 'string' ? byKey.get(hook) : undefined;
+          if (target === undefined) {
+            errors.push(`${at}.customHooks names ${JSON.stringify(hook)} which is no modeCatalog key`);
+            continue;
+          }
+          if (seenHooks.has(hook)) {
+            errors.push(`duplicate customHook "${hook}" (${at})`);
+            continue;
+          }
+          seenHooks.add(hook);
+          if (hook === entry.key) {
+            // The raw-mode carve-out (D4): a contract-free primary IS its own escape, so it names
+            // itself rather than repeating an escape it does not have.
+            if (contractBacked || entry.kind !== 'primary') {
+              errors.push(`${at}.customHooks may name this entry itself only on a contract-free primary (the raw mode)`);
+            }
+            continue;
+          }
+          if (target.kind !== 'env-hook') {
+            errors.push(`${at}.customHooks names ${JSON.stringify(hook)}, which is neither an env-hook nor this entry itself`);
+            continue;
+          }
+          // A customHook can never LIE about a hook that does not target this mode.
+          if (!Array.isArray(target.parents) || !target.parents.includes(entry.key)) {
+            errors.push(`${at}.customHooks names env-hook "${hook}", which does not list ${JSON.stringify(entry.key)} in its parents[]`);
+          }
+        }
+      }
+    }
+  });
+};
+
 export const validateManifest = (skillDir) => {
   const manifestPath = join(skillDir, 'capability.json');
   let raw;
@@ -377,6 +688,22 @@ export const validateManifest = (skillDir) => {
     }
   }
 
+  // `modeCatalog` (BRIDGE-MODES-CATALOG, D1): the user-facing mode catalog. ADDITIVE-OPTIONAL —
+  // an absent block is VALID (a bridge predating the catalog stays valid; the mode renders a stated
+  // "no catalog" line, never invalid-manifest and never an empty silent list). A PRESENT block is
+  // typed-validated like `settings`: the renderer prints its strings verbatim and composes runnable
+  // forms from its refs, so a malformed entry would render a lying discovery surface.
+  // Presence is keyed on the KEY, never on non-null: an explicit `modeCatalog: null` is a PRESENT
+  // malformed block, not an absence (absence is "this bridge predates the catalog"). An EMPTY array
+  // is likewise invalid — it would render as "this bridge has no modes", which is never true and is
+  // exactly the silent empty list D1 forbids; a bridge with nothing to say omits the block.
+  if (Object.hasOwn(manifest, 'modeCatalog')) {
+    const modeCatalog = manifest.modeCatalog;
+    if (!Array.isArray(modeCatalog)) errors.push('`modeCatalog` must be an array of mode entries');
+    else if (modeCatalog.length === 0) errors.push('`modeCatalog` must not be empty — a declared catalog states at least one mode (omit the block instead)');
+    else validateModeCatalog(modeCatalog, roles, errors);
+  }
+
   if (!isStub) {
     const auth = readAuthoritativeVersion(skillDir);
     if (auth.version == null) errors.push(`could not resolve an authoritative version (${auth.from})`);

package/tools/review-ledger-core.mjs

@@ -348,6 +348,80 @@ export const filterSegmentRecords = (records, { activity, loop, base }) =>
 // (no duplicate, gap, or out-of-order round). Checks the EXISTING sequence, not just the incoming
 // round: a ledger like [2] / [1,1] / [2,1] (reachable only by hand-editing the git-dir file — the
 // stated residual) must fail closed rather than be trusted to compute the "latest" round (codex R3).
+// ── the attesting-receipt predicate (BRIDGE-MODES-CATALOG, D3) ─────────────────────────
+// The ONE place that decides whether a review receipt may attest a tree. It lives in this neutral
+// core because all three consumers — review-state.mjs (the receipt gate), review-ledger.mjs (the
+// round cross-check) and review-ledger-write.mjs (the round writer) — need it, and the core imports
+// none of them: the same DAG reason this module exists at all. Two gates disagreeing about what
+// counts as an attestation is exactly the class AD-050 closed; a second copy would re-open it.
+export const REVIEW_RECEIPT_CLASS = Object.freeze({
+  NOT_CURRENT: 'not-current',
+  ATTESTING: 'attesting',
+  UNGROUNDED: 'ungrounded',
+  PROBE: 'probe',
+  UNMARKED: 'unmarked',
+  MALFORMED_MARKER: 'malformed-marker',
+});
+
+// Classify ONE receipt against a tree fingerprint. Order is load-bearing: identity first (is this
+// even about the current tree?), then the probe marker (may it attest at all?), then grounding.
+export const classifyReviewReceiptForTree = (receipt, fingerprint) => {
+  if (!isPlainObject(receipt) || receipt.fresh !== true || receipt.artifact !== 'code' || receipt.fingerprint !== fingerprint) {
+    return REVIEW_RECEIPT_CLASS.NOT_CURRENT;
+  }
+  if (!Object.hasOwn(receipt, 'probe')) return REVIEW_RECEIPT_CLASS.UNMARKED;
+  if (typeof receipt.probe !== 'boolean') return REVIEW_RECEIPT_CLASS.MALFORMED_MARKER;
+  if (receipt.probe === true) return REVIEW_RECEIPT_CLASS.PROBE;
+  if (receipt.grounded !== true) return REVIEW_RECEIPT_CLASS.UNGROUNDED;
+  return REVIEW_RECEIPT_CLASS.ATTESTING;
+};
+
+// Summarize one backend's receipts for a tree → { state, receipt, counts… }. `receipt` is the LATEST
+// ATTESTING one — never simply the last line: a probe (or a forged marker) written after a real
+// review must never become the authoritative verdict, which is precisely how a late probe SHIP could
+// override an earlier real REWORK and let both gates report convergence.
+export const summarizeReviewReceiptsForTree = (receipts, fingerprint) => {
+  const classified = receipts
+    .map((receipt) => ({ receipt, classification: classifyReviewReceiptForTree(receipt, fingerprint) }))
+    .filter(({ classification }) => classification !== REVIEW_RECEIPT_CLASS.NOT_CURRENT);
+  const rowsFor = (classification) => classified.filter((row) => row.classification === classification);
+  const attesting = rowsFor(REVIEW_RECEIPT_CLASS.ATTESTING);
+  const ungrounded = rowsFor(REVIEW_RECEIPT_CLASS.UNGROUNDED);
+  const probe = rowsFor(REVIEW_RECEIPT_CLASS.PROBE);
+  const unmarked = rowsFor(REVIEW_RECEIPT_CLASS.UNMARKED);
+  const malformedMarker = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_MARKER);
+  const counts = {
+    currentCount: classified.length,
+    ungroundedCount: ungrounded.length,
+    probeExcluded: probe.length,
+    markerRejected: malformedMarker.length,
+    unmarkedRejected: unmarked.length,
+  };
+  if (attesting.length > 0) return { state: 'current', receipt: attesting[attesting.length - 1].receipt, ...counts };
+  if (ungrounded.length > 0) return { state: 'ungrounded', receipt: ungrounded[ungrounded.length - 1].receipt, ...counts };
+  if (classified.length > 0) {
+    return { state: malformedMarker.length > 0 || unmarked.length > 0 ? 'rejected' : 'probe', receipt: null, ...counts };
+  }
+  return { state: 'none', receipt: null, ...counts };
+};
+
+// Why this backend has no attestation — one stated sentence, never a silent "no receipt". The four
+// causes have DIFFERENT recoveries (run a real review / refresh the bridge / fix the receipt source /
+// re-run grounded), so they are never collapsed into one message.
+export const describeMissingReviewAttestation = (summary) => {
+  if (summary.state === 'current') return null;
+  const exclusions = [
+    summary.probeExcluded > 0 ? `${summary.probeExcluded} probe receipt(s)` : null,
+    summary.markerRejected > 0 ? `${summary.markerRejected} receipt(s) with a malformed probe marker` : null,
+    summary.unmarkedRejected > 0 ? `${summary.unmarkedRejected} receipt(s) with no probe marker` : null,
+  ].filter(Boolean);
+  const exclusionSuffix = exclusions.length > 0 ? `; excluded ${exclusions.join(', ')}` : '';
+  if (summary.state === 'ungrounded') return `only ungrounded normal receipts exist for the current tree${exclusionSuffix}`;
+  if (summary.state === 'probe') return 'only probe receipts exist for the current tree — a probe review never attests';
+  if (summary.state === 'rejected') return `current-tree receipts have untrustworthy probe markers${exclusionSuffix}`;
+  return 'no fresh code receipt exists for the current tree';
+};
+
 export const roundSequenceIntact = (records) => {
   const nums = records.filter((r) => r.kind === 'round').map((r) => r.round);
   return nums.every((n, i) => n === i + 1);