@sabaiway/agent-workflow-kit 1.28.0 → 1.30.0

package/CHANGELOG.md

@@ -4,6 +4,99 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.30.0 — Review-recipe enforcement: the configured recipe is impossible to miss, "reviewed ≠ shipped" is detectable, grounding is a command (AD-038)
+
+A **feature** release (ships the bundled bridges refreshed to **2.2.0**). Origin: a real
+council-substitution incident + independent kit-user feedback — the configured review recipe could
+be silently skipped, downgraded, or run before later edits, and nothing could detect it. Three
+mechanisms, each self-firing at its point of use:
+
+- **The discovery line** — `tools/recipes.mjs --active-line` (`Mode: recipes`): exactly ONE
+  machine-composed line rendering the **CONFIGURED** recipe of every activity/slot from
+  `docs/ai/orchestration.json` + live readiness — source labeled, degradation stated, wrapper set
+  named, explicitly contrasted with the readiness recommendation (which is informational). Wired
+  where a session already reads: the deployed `agent_rules.md` §1.1 gains step 2 (read the
+  orchestration config BEFORE picking a task; a silent recipe downgrade is a forbidden
+  substitution) and `handover.md` gains a standing **"Active recipes:"** slot — both template
+  regions byte-identical with the memory copies (new `test/template-region-parity.test.mjs`,
+  injected-divergence non-vacuous); `set-recipe` now ECHOES the freshly composed line + a
+  handover-slot reminder after every successful `--write` (additive `activeLine` field in
+  `--json`). New `test/active-recipe-line.test.mjs` proves the line derives from the CONFIG, not
+  the recommendation.
+- **`/agent-workflow-kit review-state`** (`tools/review-state.mjs`, read-only + colocated tests) —
+  makes "reviewed ≠ shipped" mechanically detectable. The 2.2.0 review wrappers append one JSONL
+  receipt per SUCCESSFUL review to `<git dir>/agent-workflow-review-receipts.jsonl`
+  (`AW_REVIEW_RECEIPTS` overrides; never committable by construction); the checker resolves the
+  effective `plan-execution.review` recipe, recomputes the canonical **uncommitted-state
+  fingerprint** (sha256 over staged diff + unstaged diff + untracked-not-ignored contents — exactly
+  the review-payload domain), and `--check` exits 0 only when every recipe-named backend holds a
+  **fresh, grounded, current-fingerprint** receipt (**presence, not unanimity** — verdicts stay
+  orchestrator judgment). Any later edit stales the receipts; plan/diff receipts and continuations
+  (`fresh:false`) are informational-only — after a fold, only a fresh grounded re-run restores
+  green. Normative exit contract in the tool header; plan-in-flight detector keyed on the
+  documented `docs/plans` naming convention; honest residual stated (`--no-verify`, receipt-file
+  deletion — discipline, not a sandbox). The gate line is **never auto-seeded** ([[AD-021]]): the
+  template `gates.json` stays empty; the candidate line lives in `Mode: review-state`/`Mode: gates`
+  prose. New `test/review-fingerprint-parity.test.mjs` proves bash (both wrappers, byte-identical
+  block) ↔ node fingerprint parity — hash, serialization, AND behavioral domain equality.
+- **`/agent-workflow-kit grounding`** (`tools/grounding.mjs` + colocated tests) — the
+  grounded-review facts assembler, catalogued honestly as a **WRITER**: `--constraints` slices the
+  root `AGENTS.md` Hard-Constraints section verbatim (exactly-one-match, else a loud STOP);
+  `--plan <path>` extracts the decision-bearing sections (`## Approach` + `## Verification`
+  required, `## Decisions (locked)` when present; duplicates STOP); output honors the wrapper's
+  `AGY_MAX_PROMPT_BYTES` budget minus `--reserve-bytes` with a loud tail-trim; `--out` accepts only
+  gitignored / out-of-repo scratch (a tracked or in-repo not-ignored path is refused — a new
+  untracked file would move the fingerprint it grounds). `procedures.mjs` renders the invocation as
+  a POPULATED pre-step whenever agy is dispatched (exactly one plan in flight → its path; else a
+  placeholder + discovery caveat; additive `groundingPreStep` in `--json`).
+- **Bundled bridges 2.2.0** (mirrors byte-refreshed): `codex-review.sh` mandates + parses ONE
+  literal `Verdict: ship|revise|rethink` line (schema mode reads the JSON field); `agy-review.sh`
+  records the `### Verdict` token verbatim (SHIP / SHIP WITH NITS / REWORK), `grounded` +
+  `factsHash` from `--facts` (an empty payload is visible), and marks continuations `fresh:false`
+  with a one-line fresh-run notice; a receipt write failure warns and never fails the review. The
+  review-role `capability.json` contracts gain the `receipt` block (the fingerprint definition
+  home) — three-way lockstep wrapper `--help` ↔ manifest ↔ `detect-backends.mjs` registry,
+  drift-guarded.
+- **Catalog/report wiring:** two new SKILL modes + README rows; the bootstrap/upgrade report
+  footers paste the active-recipe line beside the backend-status line; `package-content` pin
+  94 → 96 (the two new tools).
+
+## 1.29.0 — Velocity scope C: an opt-in PreToolUse gate-approval hook
+
+A **feature** release (ships the bundled bridges unchanged at **2.1.0**). The shipped, probe-proven
+closure of the velocity trust-posture residual ([[AD-021]] scope C, recorded in **AD-037**) — a
+new opt-in `.claude/` writer, the family's third:
+
+- **`/agent-workflow-kit hook`** (`tools/gate-hook.mjs`) — places a **self-contained** hook runtime
+  (`references/hooks/gate-approve.mjs` → `.claude/hooks/agent-workflow-gates.mjs`; no kit imports, so
+  the placed copy survives an uninstall) and wires ONE `PreToolUse` "Bash" entry into
+  `.claude/settings.json`. Velocity writer discipline verbatim: `--dry-run` default, deployment-gated
+  `--apply`, symlink-safe, refuses unsafe modes in either settings file, merge-don't-clobber,
+  idempotent, never `settings.local.json`, never commits. Place-file-FIRST-then-wire; a malformed
+  existing `hooks` shape or a diverged-and-unwired target file is a STOP with zero writes (it refuses
+  to wire an unknown script as a hook); the target is re-verified no-follow immediately before wiring.
+- **The hook's decision ladder**, read against `docs/ai/gates.json` LIVE per call (one declaration,
+  two consumers with *Mode: gates* — editing gates.json never needs re-wiring): **(a)** a command
+  BYTE-EXACT to a declared gate `cmd` (trim-only; never a pattern — the rejected AD-021 shape),
+  invoked from the project root, under `default`/`acceptEdits` → `allow`; **(b)** a seeded-read-only
+  command carrying a documented runtime residual (output redirection, command/process substitution
+  `$(…)`/`` ` ``/`<(…)`, or the `--output` write-flag family — matched as a whole-command substring so
+  a quoted/escaped form can't hide it) → `ask`, overriding a settings allow rule (**proven live** on
+  Claude Code 2.1.185); **(c)** else no decision. Never `deny`. Fail-safe is **decoupled**: a broken
+  `gates.json` disables only (a), the guard keeps running; every anomaly exits 0, never 2. Validation
+  parity with the runner (`_README` included) — an invalid declaration approves nothing.
+- **Integration.** `/.claude/hooks/` joins the hidden-mode footprint registry; `uninstall` gains the
+  hook seam (reports the settings edit + preserves a still-wired or non-bundle file, removes only a
+  byte-identical unwired one and cleans an emptied `.claude/hooks/`, all lstat-no-follow + AD-011
+  preflight; the wired-probe reads DECODED settings JSON so an escaped `\/` path still counts as
+  wired); `status` gains one row (wired / file placed / declaration present) through the full
+  surface→view-model→renderers pipeline; the velocity residual notice + SKILL/README point at the
+  shipped hook instead of a "deferred" one. Kit-only; the runtime + writer ride the tarball.
+- **Review.** Council at the diff converged over four rounds (codex + agy, grounded): every finding
+  closed one obfuscation-of-a-string-scan class (process substitution, quoted/escaped `--output`,
+  JSON-escaped `\/`) or a TOCTOU/symlink window — folded by code with red→green regressions; the
+  final round was codex **ship** + agy **SHIP**, 0 blockers / 0 majors.
+
 ## 1.28.0 — Lens-mirror guards the checked-vs-unchecked plan boundary
 
 A **feature** release (template + test only; ships the bundled bridges unchanged at **2.1.0**).

package/README.md

@@ -234,9 +234,12 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
+| `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand** (never auto-seeded). Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
+| `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. Prints to stdout; `--out` writes **one scratch file only** (gitignored / outside the repo — a tracked or not-ignored in-repo path is refused). Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
-| `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a redirection/command-substitution residual remains, closed by a deferred hook); a direct commit/push/publish still asks. `--dry-run` first. |
+| `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
+| `/agent-workflow-kit hook` | Claude Code · opt-in | **gate-approval hook** — places a self-contained PreToolUse hook (`.claude/hooks/`) and wires it into `.claude/settings.json`: a Bash command **byte-identical** to a gate you declared in `docs/ai/gates.json` (run from the project root) is auto-approved — no prompt, no idle; a seeded read-only command carrying a runtime residual (output redirection, command substitution, `--output` writes) now **asks** even where an allow rule would have silently passed it (proven live — hook `ask` overrides an allow rule). Exact matches only, never patterns; never `deny`; a broken `gates.json` only disables auto-approval, never the guard. Preview by default; never writes `settings.local.json`; never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.28.0'
+  version: '1.30.0'
 ---
 
 # agent-workflow-kit
@@ -177,8 +177,11 @@ backend-status line** → **welcome mat**. Only the version block comes from
 `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json` (add `--dir <project>` for the deploy
 axis) — **never hardcoded semver**; the backend-status line is its own shared contract (above), and
 the welcome mat **composes signals already gathered** (the version block's notes + the backend-status
-line), not a fresh helper call. Present everything in the user's conversational language; never paste
-the JSON or any internal field name.
+line), not a fresh helper call. **Beside the backend-status line**, when the target project carries a
+`docs/ai/orchestration.json`, also paste the one-line **configured-recipe line** verbatim from
+`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --active-line` (run from the project root; *Mode: recipes*
+documents it; same agent-host skip-with-reason contract as the status line). Present everything in the
+user's conversational language; never paste the JSON or any internal field name.
 
 **Success state — the happy path never leads with a structure number.** No happy-path report surfaces
 the project's internal `docs/ai` structure version, the stamp filename, or the internal versioning
@@ -273,6 +276,10 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/run-gates.mjs [--cwd <project>] [--only <id>
 
 The declaration is **seeded at bootstrap** (the template loop, step 6) and **ensured-if-missing on upgrade** from THIS kit's own template twin (*Mode: upgrade* step 3) — independent of the installed memory substrate's age; an existing file is always **preserved byte-for-byte**. It is deliberately **not** a delegation-required memory asset: gates are optional, and absence is an honest runner outcome, not a deployment failure.
 
+Declared gates can also be **auto-approved** (no permission prompt on a byte-exact invocation from the project root) via the opt-in PreToolUse hook — *Mode: hook*: the SAME declaration, a second consumer; editing gates.json needs no re-wiring.
+
+**Candidate line — the review-receipt gate (opt-in, never auto-seeded; AD-021).** Projects that configure a reviewed/council `plan-execution.review` recipe can declare the AD-038 review-state check as one more gate — the exact candidate `{ id, title, cmd }` line and its contract live under *Mode: review-state* (step 3). The template `gates.json` stays EMPTY; adding the line is the maintainer's explicit consent, by hand.
+
 **Invariants:** the runner writes nothing · never commits · never runs a subscription CLI · executes only the project's OWN declared commands (never a kit-invented one) · the bash contract fails loud, never reinterprets.
 
 ### Mode: bootstrap
@@ -311,7 +318,7 @@ The declaration is **seeded at bootstrap** (the template loop, step 6) and **ens
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat ends on **one** recommended next step — including the optional, opt-in `/agent-workflow-kit velocity` (a read-only allowlist so routine read-only commands stop prompting; *Mode: velocity*) when nothing more pressing applies, never run without a yes. Then **ask before committing** — never auto-commit.
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat ends on **one** recommended next step — including the optional, opt-in `/agent-workflow-kit velocity` (a read-only allowlist so routine read-only commands stop prompting; *Mode: velocity*) or, once gates are declared, `/agent-workflow-kit hook` (auto-approve your own declared gate commands; *Mode: hook*) when nothing more pressing applies, never run without a yes. Then **ask before committing** — never auto-commit.
 
 Fill strategy:
 
@@ -445,6 +452,8 @@ The four recipes (defined over each bridge's `provides` roles — `codex`: execu
 2. **Offer the choice** via **`AskUserQuestion` where your agent supports it** (`AskUserQuestion` in Claude Code) — one option per recipe, the `recommendRecipe` choice listed **first** — otherwise in prose. Then print `planRecipe(chosen, detection)` (the per-stage dispatch + degradation reasons + quota/health notes) so the user sees exactly what running it entails.
 3. **Availability = `readiness === ready`, full stop.** Every other readiness supplies the human reason (needs-skill → "not installed — `/agent-workflow-kit setup`"; needs-cli → "install the CLI"; needs-credentials → "log in"; degraded → "wrapper not on PATH — `/agent-workflow-kit setup`"). This is set-up state only — **never** a claim that a backend's service is responsive (the detector cannot observe a runtime stall; `agy`'s Issue-001 is a *standing advisory*, not a readiness signal).
 
+**The configured-recipe line (`--active-line`, read-only).** `node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs --active-line` prints exactly **one** machine-composed line: the **CONFIGURED** recipe of every activity/slot, resolved from the target project's `docs/ai/orchestration.json` (read from the current directory) + live readiness — each slot with its source (configured vs computed default), its degradation stated, and its dispatched wrapper set — explicitly contrasted with the readiness **recommendation** (which is informational; the configured recipes are what runs). Paste it verbatim: it fills the session-start discovery step (the deployed `agent_rules.md` §1.1) and the handover "Active recipes:" slot; `set-recipe` echoes the same line after every successful write. A malformed config fails loud (exit 1), never a silent fallback.
+
 **Invariants:** read-only · never runs a subscription CLI · never commits · the orchestrator executes the recipe via the bridge skills, not the kit.
 
 ### Mode: procedures
@@ -511,7 +520,7 @@ It classifies every surface into four classes and acts accordingly:
 
 ### Mode: velocity
 
-The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes only `.claude/settings.json`**, on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below), closed by the deferred hook.
+The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes only `.claude/settings.json`**, on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below) — its closure is **shipped, opt-in: *Mode: hook***.
 
 **Version-status routing (like the other writer modes):** read `docs/ai/.workflow-version` first — not-deployed → bootstrap; stamp < `1.3.0` → `upgrade`; stamp > head / unparseable → STOP. The tool enforces this in code too (`--apply` STOPs unless the stamp is the lineage head).
 
@@ -520,7 +529,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 1. **`--dry-run` first, always** (the default — changes nothing). It prints: the fixed read-only core it would add; a **read-only advisory** that lists your `package.json` `scripts` as **unaudited candidates you may add BY HAND** (inspect each first) to `.claude/settings.json` / `settings.local.json` — the tool **never** writes them and flags obviously-mutating names as "do not add"; any **pre-existing non-read-only `Bash(...)` entries** to consider removing by hand; and the honest residual notice (below). It STOPs (zero writes) on a symlinked `.claude` / non-regular `settings.json`, malformed settings JSON, or an unsafe `permissions.defaultMode` — `bypassPermissions` or anything outside `default`/`acceptEdits`/`plan`, present in **either** `settings.json` or `settings.local.json`.
 2. **Ask the `acceptEdits` opt-in** via **`AskUserQuestion` where supported**, the safe option FIRST:
    - **"Keep per-edit approval prompts (recommended)"** — seed only the read-only allowlist; file edits still prompt.
-   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — but that same redirection/substitution residual means they are not *fully* closed until the deferred PreToolUse hook (family backlog). Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes only `.claude/settings.json`.
+   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — and the residual guard for the seeded core ships as the opt-in PreToolUse hook (*Mode: hook*; probe-proven on the `--output` family — current engine builds already intercept redirection/substitution upstream). Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes only `.claude/settings.json`.
 3. **Only on an explicit yes**, re-run with `--apply` (add `--accept-edits` only if they chose the second option). It merges-don't-clobber (preserves `includeCoAuthoredBy`, every key, and existing allow entries) and writes **only** `.claude/settings.json`.
 4. **Surface delegation-readiness, read-only.** If they want a step run Delegated, set it with `/agent-workflow-kit set-recipe --set plan-execution.execute=delegated` (*Mode: set-recipe*) or by hand-editing `docs/ai/orchestration.json`; **velocity itself never writes the orchestration config.**
 
@@ -540,6 +549,58 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/cheap-agents.mjs [--dry-run | --apply] [--cw
 
 **Invariants:** writer (writes only `.claude/agents/`) · preview by default · a diverged existing file is reported and preserved, never clobbered · never touches settings · never commits · vehicles are pinned to `model: haiku` + `effort: low` + read-only tools (content-tested).
 
+### Mode: hook
+
+The opt-in **gate-approval PreToolUse hook** — the family's third `.claude/` writer (velocity discipline), and the shipped closure of the velocity trust-posture residual (**AD-021 scope C, probe-proven in AD-037**). It places a **self-contained** hook runtime at `.claude/hooks/agent-workflow-gates.mjs` (no kit imports — it keeps working if the kit is uninstalled) and wires ONE `PreToolUse` `"Bash"` entry into `.claude/settings.json`. Per Bash call the hook then walks a decision ladder, first match wins:
+
+- **Auto-approve** a command **byte-identical** (leading/trailing trim only — no whitespace collapsing, no quote/glob/variable interpretation, no prefix or pattern matching, ever: patterns are what made AD-021 auto-seeding rejected) to a gate `cmd` declared in `docs/ai/gates.json` — read **LIVE on every call** (editing gates.json never needs re-wiring; one declaration, two consumers with *Mode: gates*) — invoked **from the project root** (gates run from the root by contract; the same bytes from a subdirectory are NOT approved) and under `default`/`acceptEdits` permission mode (an approval never loosens `plan`/`bypassPermissions`).
+- **Ask** on a command whose leading tokens match the velocity **seeded read-only core** when it carries the documented runtime residual — output redirection, command substitution, or the bounded `--output` write-flag family — surfacing a human prompt even where a seeded allow rule would have silently approved (**hook `ask` overrides an allow rule — proven live**: on Claude Code 2.1.185 a seeded `Bash(git log:*)` silently wrote a file via `git log --output=…`; with the hook wired the same call prompts). Detection is string-level and conservative: a quoted metacharacter may over-ask, never under-allow.
+- **Stay silent otherwise** — the normal permission flow proceeds unchanged. The hook **never emits `deny`**; nothing is hard-blocked.
+
+**Honest residual status (AD-037):** current engine builds already intercept `>` redirection and `$()` substitution upstream (observed headless on 2.1.185); the **`--output` family was proven open** and is the seam this hook demonstrably closes. The guard still covers all three documented classes (defense-in-depth — engine behavior may vary across surfaces/versions). **Fail-safe, decoupled:** a missing/broken/invalid `gates.json` disables ONLY gate auto-approval — the residual guard keeps running; every anomaly path exits 0 (the hook is never the blocker or the noise — the `gates` runner reports a broken declaration at its own point of use). **Not a sandbox:** it closes the named residual for the seeded core and auto-approves declared gates; it does not police arbitrary commands or user-added rules.
+
+**Trust posture (state it plainly when asking consent):** the hook removes the PROMPT only for commands the human already declared in `docs/ai/gates.json` — the same trust boundary as the `gates` runner, which executes them with the caller's privileges. **gates.json thereby becomes a privileged file**: whoever can edit it can get its commands auto-approved. An invalid declaration approves NOTHING (strict parse, exact validation parity with the runner).
+
+**Version-status routing** like the other writer modes (stamp head `1.3.0`; `--apply` enforces it in code).
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/gate-hook.mjs [--dry-run | --apply] [--cwd <dir>]`:
+
+1. **`--dry-run` first, always** (the default — changes nothing): previews the placement and the exact settings entry it would merge. It STOPs (zero writes) on: a symlinked `.claude` / `.claude/hooks` / target file / non-regular `settings.json`; malformed settings JSON; a **malformed existing `hooks` shape** (never a merge-through-clobber); an unsafe `permissions.defaultMode` in **either** settings file; or a target hook file with **different** content while our entry is not wired (**it refuses to wire an unknown script as a PreToolUse hook** — the recovery is named: delete the file to reseed from the bundle).
+2. **Ask consent** via **`AskUserQuestion` where supported**, the no-change option first: keep prompting for gate commands, or place + wire the hook — presenting the trust posture above in plain language.
+3. **Only on an explicit yes**, re-run with `--apply`. It places the file FIRST, then wires settings (a wired-but-missing entry would error on every Bash call); merge-don't-clobber (foreign hooks/matchers/keys and existing permissions preserved; re-apply never duplicates); **settings hot-reload — the hook is active for new Bash calls, no session restart needed**. An identical existing file is *already current*; a diverged-but-already-wired file is reported, never clobbered or unwired.
+4. **Hidden-mode deployments:** after apply, run the hide-footprint reconcile (`node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile`) — `/.claude/hooks/` is in the known-footprint registry; the apply report reminds you.
+
+**Invariants:** writes ONLY `.claude/hooks/agent-workflow-gates.mjs` + `.claude/settings.json` · never `settings.local.json` · never commits · exact-match approval only (no patterns) · never `deny` · never auto-wired by `init`/`upgrade` (placement stays opt-in — the AD-011/AD-034 boundary: init/upgrade may refresh placed things, never place new ones).
+
+**Exit codes:** `0` done / dry-run (incl. the reported diverged-but-wired state); `1` a precondition STOP; `2` bad arguments.
+
+### Mode: review-state
+
+Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shipped"* mechanically detectable. The bridge review wrappers (`codex-review` / `agy-review`, from bridge version 2.2.0) append one receipt line per **successful** review to a file **inside the git dir** (`<git dir>/agent-workflow-review-receipts.jsonl` — never committable by construction; `AW_REVIEW_RECEIPTS` overrides). This mode resolves the effective `plan-execution.review` recipe (the SAME config + read-only detector the `procedures` advisor reads), recomputes the canonical **uncommitted-state fingerprint** (staged + unstaged + untracked-not-ignored contents — exactly the review-payload domain; the prose definition lives in each bridge's `capability.json` review contract, implementations cross-checked by the kit's fingerprint-parity test), and reports, per recipe-named backend, whether a **fresh, grounded, current-fingerprint** receipt exists. It **never writes, never commits, never runs a subscription CLI**; it does spawn **read-only `git` queries** to compute the fingerprint — stated honestly (that is still read-only, but it is a subprocess).
+
+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**; exit 1 when a backend is missing, **stale** (ANY edit after its review moves the fingerprint), or grounded:false under reviewed/council. **Presence, not unanimity:** verdict adjudication (ship/revise, the divergence crossover) stays orchestrator judgment — the gate only proves the configured backends really reviewed THIS tree. 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.
+3. **Wire it as a gate by hand — never auto-seeded (AD-021).** 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. Once declared, the opt-in *Mode: hook* auto-approves it like any other declared gate.
+
+**Human residual (stated, accepted):** `git commit --no-verify` and receipt-file deletion/forgery remain possible — this is a self-discipline mechanism against silent process drift, not a security boundary.
+
+**Invariants:** read-only · never writes · never commits · never runs a subscription CLI · spawns read-only `git` queries only · the receipt writers are the bridge review wrappers, never the kit.
+
+### Mode: grounding
+
+The **grounded-review facts assembler** (AD-038) — an ungrounded `agy` review GUESSES, and while the grounding contract is mechanized (`agy-review code --facts @f`), populating the facts file was a manual chore. This mode emits the two **mechanical** halves of a facts payload; the orchestrator still owns any judgment-bearing additions. **Catalogued honestly as a WRITER** — `--out <path>` writes one file — with the invariant: `--out` accepts **only gitignored / out-of-repo scratch destinations** and REFUSES a tracked path AND an in-repo not-ignored path (a new untracked file would itself move the review fingerprint the facts are about to ground); **stdout is the default**. It never commits and never runs a subscription CLI.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/grounding.mjs [--constraints] [--plan <path>] [--reserve-bytes <n>] [--out <path>]`:
+
+1. **`--constraints`** — slice the root `AGENTS.md` **Hard Constraints** section, verbatim and whole (exactly ONE matching heading; zero or several is a loud STOP, never a guess — the marker-slot discipline).
+2. **`--plan <path>`** — extract the plan's decision-bearing canonical sections, verbatim + whole: `## Approach` (REQUIRED — its "What we are NOT doing" text rides inside; it is not a heading in canon) and `## Verification` (REQUIRED — STOP if missing), plus `## Decisions (locked)` when present (the optional engine §7 heading); a DUPLICATE heading is always a STOP.
+3. **Byte budget** — the output honors the same `AGY_MAX_PROMPT_BYTES` contract the agy wrapper enforces (override may only tighten; the OS argv ceiling is rejected), MINUS **`--reserve-bytes <n>`** — the artifact share the caller expects `agy-review` to add around these facts. Overflow is trimmed tail-first with a loud in-band marker + stderr report — never a silent cut.
+4. Feed the result to the wrapper: `agy-review code --facts @<out>`. The `procedures` advisor renders this invocation as a concrete pre-step whenever the resolved review dispatch includes agy — populated with the in-flight plan path when exactly one plan is in flight.
+
+**Invariants:** writer (writes at most the ONE `--out` scratch file — gitignored / out-of-repo only) · never commits · never runs a subscription CLI · verbatim slices only (assembly is mechanical; facts judgment stays with the orchestrator).
+
 ---
 
 ## Gotchas

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
 metadata:
-  version: '2.1.0'
+  version: '2.2.0'
 ---
 
 # antigravity-cli-bridge

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -42,6 +42,8 @@
 #   AGY_PROBE=1              throwaway probe — silences the off-frontier model advisory
 #   AGY_REVIEW_ALLOW_ADDDIR=1  oversized CODE review: offload the change set to a private
 #                            staging dir and pass it via --add-dir (re-enables Issue-001 stall risk)
+#   AW_REVIEW_RECEIPTS       override the review-receipt file (default: <git dir>/
+#                            agent-workflow-review-receipts.jsonl — see the --help Receipt block)
 set -euo pipefail
 
 # --- --help / -h (pre-preflight: no agy, no login, no git tree needed) ---------
@@ -72,6 +74,18 @@ Round-2 / resume:
   agy-review --conversation <id> [--decided @f] [--focus "…"]
   (a continuation sends a small delta — agy holds the artifact server-side; --facts is invalid on a continuation)
 
+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) 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
+
 Closed grammar: unknown flags are rejected; no '--' passthrough (the only escapes are AGY_PROBE=1 and AGY_REVIEW_ALLOW_ADDDIR=1).
 Requires at run time: the agy CLI on PATH + a Google AI subscription login (--help needs neither).
 HELP
@@ -80,6 +94,10 @@ HELP
 esac
 
 DEFAULT_AGY_REVIEW_MODEL="Gemini 3.1 Pro (High)"
+# Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
+# version (drift-guarded by agy-review.test.mjs against capability.json).
+AW_RECEIPT_BACKEND="agy"
+AW_BRIDGE_VERSION="2.2.0"
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # Frontier review models. ANY model is allowed; a sub-frontier one only earns a soft, silenceable warning.
@@ -181,6 +199,95 @@ is_binary() {
   [[ "${nul:-0}" -gt 0 ]]
 }
 
+# --- Review receipts (AD-038) — byte-identical in codex-review.sh and agy-review.sh ---------------
+# sha256 hex of stdin. sha256sum, else shasum -a 256; neither → warn + fail (the caller records a
+# null fingerprint — a null never satisfies the review-state checker, fail-safe direction).
+sha256_stdin() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then shasum -a 256 | awk '{print $1}'
+  else
+    echo "warning: no sha256sum/shasum on PATH — cannot compute the review fingerprint." >&2
+    return 1
+  fi
+}
+
+# The canonical uncommitted-state fingerprint payload (code mode). Domain == the review payload:
+# tracked staged + unstaged changes + untracked-not-ignored file contents (binary/symlink/non-regular
+# untracked paths ride as name-only notes, mirroring the assembled change set). The prose definition
+# lives in capability.json roles.review.contract.receipt (both bridges, lockstep); the kit checker
+# (tools/review-state.mjs) implements the SAME serialization in node — cross-checked by the kit's
+# review-fingerprint-parity.test.mjs.
+emit_fingerprint_payload() {
+  git diff --cached --no-ext-diff
+  git diff --no-ext-diff
+  local path
+  while IFS= read -r -d '' path; do
+    if [[ -L "$path" ]]; then
+      printf 'untracked-symlink:%s -> %s\n' "$path" "$(readlink -- "$path" 2>/dev/null || echo '?')"
+    elif [[ ! -f "$path" ]]; then
+      printf 'untracked-nonregular:%s\n' "$path"
+    elif is_binary "$path"; then
+      printf 'untracked-binary:%s\n' "$path"
+    else
+      printf 'untracked:%s\n' "$path"
+      cat -- "$path"
+    fi
+  done < <(git ls-files --others --exclude-standard -z)
+}
+
+# sha256 of the canonical payload, emitted from the work-tree ROOT (a subdir invocation hashes the
+# same bytes). Empty output on failure (no git tree / no sha256 tool) — recorded as null.
+compute_tree_fingerprint() {
+  ( cd "$(git rev-parse --show-toplevel)" && emit_fingerprint_payload ) | sha256_stdin
+}
+
+# JSON-encode a receipt scalar: empty → null, else a quoted string (every value comes from a closed
+# vocabulary or a hex digest — no escaping needed by construction).
+receipt_json_scalar() {
+  if [[ -z "${1:-}" ]]; then printf 'null'; else printf '"%s"' "$1"; fi
+}
+
+# write_review_receipt <artifact|""> <fresh: true|false> <fingerprint|""> <verdict> <grounded: true|false> <factsHash|"">
+# Appends ONE receipt line (the AD-038 fixture shape) as a side effect of a SUCCESSFUL review —
+# to $AW_REVIEW_RECEIPTS when set, else <git dir>/agent-workflow-review-receipts.jsonl (inside the
+# git dir by construction, so it is never committable). Fail-safe: every failure here warns loudly
+# and returns 0 — a missing receipt fails the kit's review-state CHECKER, never the review run.
+write_review_receipt() {
+  local artifact="$1" fresh="$2" fingerprint="$3" verdict="$4" grounded="$5" facts_hash="$6"
+  local receipts="${AW_REVIEW_RECEIPTS:-}"
+  if [[ -z "$receipts" ]]; then
+    local receipt_git_dir
+    if ! receipt_git_dir="$(git rev-parse --absolute-git-dir 2>/dev/null)"; then
+      echo "warning: not inside a git work tree and AW_REVIEW_RECEIPTS is unset — skipping the review receipt." >&2
+      return 0
+    fi
+    receipts="$receipt_git_dir/agent-workflow-review-receipts.jsonl"
+  fi
+  local line
+  line="$(printf '{"schema":1,"artifact":%s,"fresh":%s,"fingerprint":%s,"backend":"%s","verdict":"%s","grounded":%s,"factsHash":%s,"wrapperVersion":"%s","timestamp":"%s"}' \
+    "$(receipt_json_scalar "$artifact")" "$fresh" "$(receipt_json_scalar "$fingerprint")" \
+    "$AW_RECEIPT_BACKEND" "$verdict" "$grounded" "$(receipt_json_scalar "$facts_hash")" \
+    "$AW_BRIDGE_VERSION" "$(date -u +%Y-%m-%dT%H:%M:%SZ)")"
+  if ! printf '%s\n' "$line" >>"$receipts" 2>/dev/null; then
+    echo "warning: could not append the review receipt to $receipts — the review itself succeeded;" >&2
+    echo "         the review-state gate will read the current tree as un-receipted." >&2
+  fi
+}
+
+# Parse the mandated '### Verdict' section of a captured review: the first non-empty line after the
+# heading, matched against the closed verdict vocabulary (SHIP WITH NITS before SHIP — substring).
+# No heading / no match → "unknown" (recorded, never guessed).
+parse_agy_verdict() { # $1 = captured-output file
+  local line
+  line="$(awk '/^### Verdict/{flag=1; next} flag && NF {print; exit}' "$1" 2>/dev/null)"
+  case "$line" in
+    *"SHIP WITH NITS"*) printf 'SHIP WITH NITS' ;;
+    *REWORK*)           printf 'REWORK' ;;
+    *SHIP*)             printf 'SHIP' ;;
+    *)                  printf 'unknown' ;;
+  esac
+}
+
 # Emit the full code-review surface: repo map, status, staged + unstaged diffs, and the CONTENTS of
 # every untracked REGULAR file (NUL-safe iteration). Symlinks are shown as their target (never
 # followed — no out-of-repo leak); other non-regular paths (FIFO/socket/device/dir) are skipped.
@@ -246,6 +353,8 @@ mode=""
 target=""
 PLAN_CONTENT=""
 DIFF_CONTENT=""
+REVIEW_ARTIFACT=""
+REVIEW_FINGERPRINT=""
 if [[ -z "$resume_mode" ]]; then
   mode="${1:-}"; shift || true
   case "$mode" in
@@ -259,7 +368,10 @@ if [[ -z "$resume_mode" ]]; then
         echo "error: $mode file '$target' not found." >&2; exit 2
       fi
       # Read the target NOW (before any cd) — its path is relative to the invocation cwd.
-      if [[ "$mode" == "plan" ]]; then PLAN_CONTENT="$(cat -- "$target")"; else DIFF_CONTENT="$(cat -- "$target")"; fi ;;
+      if [[ "$mode" == "plan" ]]; then PLAN_CONTENT="$(cat -- "$target")"; else DIFF_CONTENT="$(cat -- "$target")"; fi
+      # Plan/diff receipt identity: the artifact-file sha256 (informational-only for the tree checker).
+      REVIEW_ARTIFACT="$mode"
+      REVIEW_FINGERPRINT="$(sha256_stdin <"$target" || true)" ;;
     *)
       usage; exit 2 ;;
   esac
@@ -392,6 +504,10 @@ else
       echo "agy-review: no uncommitted changes to review — the working tree is clean." >&2
       exit 0
     fi
+    # The canonical fingerprint of the tree agy is about to review — computed at assembly time,
+    # so the receipt attests exactly the reviewed state.
+    REVIEW_ARTIFACT="code"
+    REVIEW_FINGERPRINT="$(compute_tree_fingerprint || true)"
   fi
 
   emit_artifact() {
@@ -468,14 +584,39 @@ else
 fi
 
 # --- Execute via agy-run (single home of timeout + subscription + byte ceiling) ---
+# The output is teed into the private staging dir so the mandated '### Verdict' section can be
+# parsed into the review receipt — the user-facing stream is unchanged.
+review_out_file="$staging/review-output"
 set +e
 if (( ${#run_passthrough[@]} > 0 )); then
   AGY_MODEL="$AGY_MODEL" AGY_TIMEOUT="$AGY_TIMEOUT" AGY_HARD_TIMEOUT="$AGY_HARD_TIMEOUT" \
-    "$AGY_RUN" "@$prompt_file" -- "${run_passthrough[@]}"
+    "$AGY_RUN" "@$prompt_file" -- "${run_passthrough[@]}" | tee "$review_out_file"
+  rc=${PIPESTATUS[0]}
 else
   AGY_MODEL="$AGY_MODEL" AGY_TIMEOUT="$AGY_TIMEOUT" AGY_HARD_TIMEOUT="$AGY_HARD_TIMEOUT" \
-    "$AGY_RUN" "@$prompt_file"
+    "$AGY_RUN" "@$prompt_file" | tee "$review_out_file"
+  rc=${PIPESTATUS[0]}
 fi
-rc=$?
 set -e
+
+# --- Review receipt (AD-038): only a SUCCESSFUL review attests --------------------
+if [[ $rc -eq 0 ]]; then
+  verdict="$(parse_agy_verdict "$review_out_file")"
+  if [[ -n "$resume_mode" ]]; then
+    # A continuation never re-embeds the current artifact (agy holds the ORIGINAL round server-side;
+    # --facts is rejected above), so it cannot attest the folded tree: fresh:false, artifact /
+    # fingerprint / factsHash null, grounded false — informational-only, ignored by the state gate.
+    write_review_receipt "" false "" "$verdict" false ""
+    echo "notice: a continuation receipt is fresh:false (informational-only) — only a fresh grounded run" >&2
+    echo "        (agy-review code --facts @f) mints a receipt that satisfies the review-state gate." >&2
+  else
+    grounded=false
+    facts_hash=""
+    if [[ -n "$FACTS_CONTENT" ]]; then
+      grounded=true
+      facts_hash="$(printf '%s' "$FACTS_CONTENT" | sha256_stdin || true)"
+    fi
+    write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" "$grounded" "$facts_hash"
+  fi
+fi
 exit $rc