@sabaiway/agent-workflow-kit 1.29.0 → 1.30.0

package/bridges/codex-cli-bridge/bin/codex-review.sh

@@ -52,7 +52,16 @@ Grounding:
 Round-2 / resume:
   (none — one-shot; a follow-up review is a fresh run)
 
-Environment: CODEX_REVIEW_SCHEMA=1 (structured JSON findings), CODEX_HARD_TIMEOUT (seconds, default 1800), CODEX_PROBE=1 (throwaway probe only).
+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) 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
+
+Environment: CODEX_REVIEW_SCHEMA=1 (structured JSON findings), CODEX_HARD_TIMEOUT (seconds, default 1800), CODEX_PROBE=1 (throwaway probe only), AW_REVIEW_RECEIPTS (receipt file override).
 Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
 HELP
     exit 0
@@ -61,6 +70,10 @@ esac
 
 DEFAULT_CODEX_MODEL="gpt-5.5"
 DEFAULT_CODEX_EFFORT="xhigh"
+# Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
+# version (drift-guarded by codex-review.test.mjs against capability.json).
+AW_RECEIPT_BACKEND="codex"
+AW_BRIDGE_VERSION="2.2.0"
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"
 CODEX_EFFORT="${CODEX_EFFORT:-$DEFAULT_CODEX_EFFORT}"
 # Generous hard cap for a slow xhigh review (subscription latency varies).
@@ -140,8 +153,10 @@ if [[ "${CODEX_REVIEW_SCHEMA:-}" == "1" ]]; then
   OUTPUT_FORMAT_CODE="$_json_fmt"
   OUTPUT_FORMAT_PLAN="$_json_fmt"
 else
-  OUTPUT_FORMAT_CODE="Output findings ONLY, one per line, as: [blocker|major|minor|nit] — file:line — issue — suggested fix. End with a one-line overall verdict (ship / revise / rethink)."
-  OUTPUT_FORMAT_PLAN="Output findings ONLY, one per line, as: [blocker|major|minor|nit] — location — issue — suggested change. End with a one-line overall verdict (ship / revise / rethink)."
+  # The verdict line is machine-parsed into the review receipt (AD-038) — mandate ONE exact literal.
+  _verdict_fmt="End with EXACTLY ONE final verdict line in this literal, machine-parsed form (that word pair alone on the line, nothing else): 'Verdict: ship' or 'Verdict: revise' or 'Verdict: rethink'."
+  OUTPUT_FORMAT_CODE="Output findings ONLY, one per line, as: [blocker|major|minor|nit] — file:line — issue — suggested fix. ${_verdict_fmt}"
+  OUTPUT_FORMAT_PLAN="Output findings ONLY, one per line, as: [blocker|major|minor|nit] — location — issue — suggested change. ${_verdict_fmt}"
 fi
 
 # True (exit 0) when $1 looks BINARY: a NUL byte in the first 8 KiB (git's own
@@ -153,6 +168,81 @@ 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
+}
+
 # Emit the full review surface to stdout: 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
@@ -191,6 +281,9 @@ assemble_code_diff() {
 mode="${1:-}"
 shift || true
 
+REVIEW_ARTIFACT=""
+REVIEW_FINGERPRINT=""
+
 case "$mode" in
   plan)
     target="${1:-}"
@@ -203,6 +296,9 @@ case "$mode" in
       echo "error: unexpected arguments after plan file: $*" >&2
       exit 2
     fi
+    # Plan-mode receipt identity: the artifact-file sha256 (informational-only for the tree checker).
+    REVIEW_ARTIFACT="plan"
+    REVIEW_FINGERPRINT="$(sha256_stdin <"$target" || true)"
     fence_plan="Do not read files outside this git working tree; the plan above plus the in-repo code it references are your whole surface."
     directive="You are REVIEWING an implementation plan — ADVISORY ONLY. You are in a read-only sandbox: do NOT edit, create, or delete any file, and do NOT rewrite the plan. Obey the project's Hard Constraints from its root AGENTS.md (already merged into your context). Read the plan below and the relevant repository code it references. ${fence_plan} ${OUTPUT_FORMAT_PLAN} Cover: correctness risks, missing or mis-ordered steps, ambiguities a cold executor would trip on, violated project Hard Constraints, scope creep, and missing verification/gates."
     prompt="${directive}"$'\n\nPLAN:\n'"$(cat -- "$target")"
@@ -214,6 +310,10 @@ case "$mode" in
       echo "codex-review: no uncommitted changes to review — the working tree is clean." >&2
       exit 0
     fi
+    # The canonical fingerprint of the tree codex is about to review — computed at assembly time
+    # (BEFORE the EXIT trap can fire), so the receipt attests exactly the reviewed state.
+    REVIEW_ARTIFACT="code"
+    REVIEW_FINGERPRINT="$(compute_tree_fingerprint || true)"
     # Assemble DIRECTLY to a git-dir-local temp file (git-invisible + worktree /
     # submodule safe; 600 perms). Measuring size from the file keeps the whole
     # change set off the bash-variable path (no NUL drop, byte-accurate size).
@@ -370,3 +470,20 @@ else
   echo "warning: codex produced no final-message file — printing the run-trace tail instead." >&2
   tail -n 40 "$trace"
 fi
+
+# --- Review receipt (AD-038): parse the verdict, append one receipt line ------
+# Text mode parses the mandated literal 'Verdict: <ship|revise|rethink>' line; CODEX_REVIEW_SCHEMA=1
+# reads the schema's "verdict" field instead; absent either way → "unknown" (recorded, never guessed).
+verdict=""
+if [[ -f "$out" && -s "$out" ]]; then
+  if [[ "${CODEX_REVIEW_SCHEMA:-}" == "1" ]]; then
+    verdict="$(sed -nE 's/.*"verdict"[[:space:]]*:[[:space:]]*"(ship|revise|rethink)".*/\1/p' "$out" | tail -n1)"
+  else
+    verdict="$(sed -nE 's/^Verdict: (ship|revise|rethink)[[:space:]]*$/\1/p' "$out" | tail -n1)"
+  fi
+fi
+[[ -z "$verdict" ]] && verdict="unknown"
+# codex is grounded by construction (AGENTS.md auto-merge + the precomputed change set): grounded
+# true, factsHash null (native grounding — no separate facts payload exists). Every codex run is a
+# full fresh run (one-shot, no resume) → fresh:true.
+write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" true ""

package/bridges/codex-cli-bridge/bin/codex-review.test.mjs

@@ -8,6 +8,7 @@ import { tmpdir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WRAPPER = join(HERE, 'codex-review.sh');
@@ -641,6 +642,12 @@ describe('codex-review.sh — --help contract (manifest-pinned)', () => {
     setEq(got, (REVIEW_CONTRACT.continue ?? []).map(norm), 'help continue ⟷ manifest continue');
     assert.deepEqual(REVIEW_CONTRACT.continue, [], 'codex-review is one-shot — no continue descriptor');
   });
+
+  it('Receipt renders the manifest receipt contract verbatim (AD-038 three-way lockstep)', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Receipt:').join(' ')), norm(REVIEW_CONTRACT.receipt));
+    assert.match(REVIEW_CONTRACT.receipt, /sha256 over the canonical uncommitted-state payload/, 'the fingerprint definition lives in the manifest contract');
+  });
 });
 
 describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
@@ -667,3 +674,128 @@ describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manife
     }
   });
 });
+
+// ── review receipts (AD-038) ─────────────────────────────────────────────────────
+// The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; field VALUES with
+// dynamic content are asserted by shape):
+const RECEIPT_FIXTURE = JSON.parse(
+  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.2.0","timestamp":"2026-07-03T12:00:00Z"}',
+);
+const RECEIPTS_REL = join('.git', 'agent-workflow-review-receipts.jsonl');
+const readReceipts = (repo) => {
+  const p = join(repo, RECEIPTS_REL);
+  if (!existsSync(p)) return [];
+  return readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+};
+const sha256Hex = (buf) => createHash('sha256').update(buf).digest('hex');
+
+describe('codex-review.sh — review receipts (AD-038)', () => {
+  it('a successful code review appends ONE fixture-shaped receipt (text-mode verdict parse)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_FAKE_FINAL: '[major] — a.txt:1 — x — y\nVerdict: revise' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts.length, 1, 'exactly one receipt line');
+    const receipt = receipts[0];
+    assert.deepEqual(Object.keys(receipt), Object.keys(RECEIPT_FIXTURE), 'fixture key set + order');
+    assert.equal(receipt.schema, 1);
+    assert.equal(receipt.artifact, 'code');
+    assert.equal(receipt.fresh, true, 'every codex run is a fresh one-shot');
+    assert.match(receipt.fingerprint, /^[0-9a-f]{64}$/, 'a real sha256 hex fingerprint');
+    assert.equal(receipt.backend, 'codex');
+    assert.equal(receipt.verdict, 'revise', 'the mandated literal verdict line is parsed');
+    assert.equal(receipt.grounded, true, 'codex is grounded by construction');
+    assert.equal(receipt.factsHash, null, 'native grounding — no separate facts payload');
+    assert.equal(receipt.wrapperVersion, MANIFEST.version, 'receipt version ⟷ capability.json version');
+    assert.match(receipt.timestamp, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
+  });
+
+  it('the code-mode fingerprint tracks the uncommitted state (same tree → same hash; edit → different)', () => {
+    const sb = makeSandbox();
+    // Route the fake-codex capture files to /dev/null so the runs themselves leave the repo
+    // byte-identical (the default capture files land inside the repo and would change the tree).
+    const quiet = { CODEX_FAKE_ARGV: '/dev/null', CODEX_FAKE_ENV: '/dev/null', CODEX_FAKE_STDIN: '/dev/null', CODEX_FAKE_FINAL: 'Verdict: ship' };
+    run(sb, { env: quiet });
+    run(sb, { env: quiet });
+    writeFileSync(join(sb.repo, 'pending.txt'), 'edited after the first two reviews\n');
+    run(sb, { env: quiet });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(receipts.length, 3);
+    assert.equal(receipts[0].fingerprint, receipts[1].fingerprint, 'an unchanged tree re-fingerprints identically');
+    assert.notEqual(receipts[1].fingerprint, receipts[2].fingerprint, 'an edited tree changes the fingerprint');
+  });
+
+  it('CODEX_REVIEW_SCHEMA=1 reads the schema verdict field', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      env: { CODEX_REVIEW_SCHEMA: '1', CODEX_FAKE_FINAL: '{"findings":[],"verdict":"ship","notes":"ok"}' },
+    });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].verdict, 'ship');
+  });
+
+  it('no parseable verdict → recorded as "unknown", never guessed', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_FAKE_FINAL: 'looks fine to me overall' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].verdict, 'unknown');
+  });
+
+  it('plan mode: artifact "plan", fingerprint = the artifact-file sha256', () => {
+    const sb = makeSandbox();
+    const planBytes = readFileSync(join(sb.repo, 'plan.md'));
+    const r = run(sb, { args: ['plan', 'plan.md'], env: { CODEX_FAKE_FINAL: 'Verdict: ship' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].artifact, 'plan');
+    assert.equal(receipts[0].fingerprint, sha256Hex(planBytes), 'plan fingerprint = file sha256');
+  });
+
+  it('AW_REVIEW_RECEIPTS overrides the receipt destination', () => {
+    const sb = makeSandbox();
+    const override = join(sb.root, 'my-receipts.jsonl');
+    const r = run(sb, { env: { AW_REVIEW_RECEIPTS: override, CODEX_FAKE_FINAL: 'Verdict: ship' } });
+    const inGitDir = readReceipts(sb.repo);
+    const atOverride = existsSync(override) ? readFileSync(override, 'utf8') : '';
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(inGitDir.length, 0, 'nothing written to the default path');
+    assert.match(atOverride, /"backend":"codex"/);
+  });
+
+  it('a receipt write failure warns loudly but never fails the review (fail-safe direction)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      env: { AW_REVIEW_RECEIPTS: join(sb.repo, 'no-such-dir', 'r.jsonl'), CODEX_FAKE_FINAL: 'Verdict: ship' },
+    });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, 'the review run itself succeeds');
+    assert.match(r.stderr, /could not append the review receipt/);
+    assert.match(r.stdout, /Verdict: ship/, 'the findings still reach stdout');
+  });
+
+  it('a failed codex run writes NO receipt (only a successful review attests)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_FAKE_EXIT: '5' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.equal(receipts.length, 0);
+  });
+
+  it('the clean-tree preflight exits before any receipt is written', () => {
+    const sb = makeSandbox({ clean: true });
+    const r = run(sb);
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0);
+    assert.equal(receipts.length, 0, 'no review ran — no receipt');
+  });
+});

package/bridges/codex-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "provides": ["execute", "review"],
   "roles": {
     "execute": {
@@ -38,7 +38,8 @@
           "codex-review code [extra focus...]"
         ],
         "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": []
+        "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) 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"
       }
     }
   },

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.29.0",
+  "version": "1.30.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/templates/agent_rules.md

@@ -18,8 +18,9 @@ Every AI agent working on this project **must** adhere to this protocol before w
 ### 1.1. Start of Session
 Read in order, then confirm before starting:
 1. `docs/ai/handover.md` — where we left off.
-2. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
-3. Confirm with the user: *"I'm taking task X. Confirm?"*
+2. `docs/ai/orchestration.json` — the CONFIGURED orchestration recipes (per activity/slot). Honor them: a silent recipe downgrade is a forbidden substitution.
+3. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
+4. Confirm with the user: *"I'm taking task X. Confirm?"*
 
 ### 1.2. During Work
 **Before any feature:** read the relevant page spec (`docs/ai/pages/<page>.md`). If behaviour changes, update the spec FIRST so docs and code never diverge.

package/references/templates/handover.md

@@ -14,6 +14,7 @@ maxLines: 80
 
 **Last session:** {{DATE}}
 **Branch:** {{BRANCH}}
+**Active recipes:** not recorded yet — paste the configured-recipe line (composed from `docs/ai/orchestration.json`) and refresh it whenever the config changes.
 
 ## What was done last session
 

package/tools/commands.mjs

@@ -131,7 +131,7 @@ const CATALOG = [
     invocation: invocationOf('recipes'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated) and which one fits this environment.',
+    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated), which one fits this environment, and the configured per-activity line to paste at session start.',
   },
   {
     key: 'procedures',
@@ -147,6 +147,20 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Set the orchestration recipe for an activity from plain language — previews the change, then writes the config when you confirm.',
   },
+  {
+    key: 'review-state',
+    invocation: invocationOf('review-state'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Check that every configured review backend has receipted the current uncommitted tree with a fresh grounded review; --check turns it into a gate exit code.',
+  },
+  {
+    key: 'grounding',
+    invocation: invocationOf('grounding'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime

package/tools/detect-backends.mjs

@@ -88,6 +88,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) 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',
       },
     },
     bin: 'codex',
@@ -120,6 +121,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) 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",
       },
     },
     bin: 'agy',