@sabaiway/agent-workflow-kit 1.28.0 → 1.30.0

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -38,7 +38,7 @@ const FAKE_AGY = [
   '  fi; prev="$a"',
   'done',
   'if [[ -n "${AGY_FAKE_SLEEP:-}" ]]; then sleep "$AGY_FAKE_SLEEP"; fi',
-  'echo "FAKE_AGY_REVIEW_OUTPUT"',
+  'printf "%s\\n" "${AGY_FAKE_OUTPUT:-FAKE_AGY_REVIEW_OUTPUT}"',
   'exit "${AGY_FAKE_EXIT:-0}"',
   '',
 ].join('\n');
@@ -553,6 +553,13 @@ describe('agy-review.sh — --help contract (manifest-pinned)', () => {
     assert.ok(REVIEW_CONTRACT.continue.length > 0, 'manifest continue must be non-empty');
     setEq(got, REVIEW_CONTRACT.continue.map(norm), 'help continue ⟷ manifest continue');
   });
+
+  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');
+    assert.match(REVIEW_CONTRACT.receipt, /fresh:false/, 'the continuation informational-only clause is contractual');
+  });
 });
 
 describe('agy-review.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
@@ -625,3 +632,164 @@ describe('agy-review.sh — declared contract is really accepted (forward guard)
     assert.doesNotMatch(r.stdout, /Usage:/);
   });
 });
+
+// ── review receipts (AD-038) ─────────────────────────────────────────────────────
+// The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; backend/verdict here
+// carry this bridge's vocabulary; dynamic values 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 sha256HexOf = async (buf) => {
+  const { createHash } = await import('node:crypto');
+  return createHash('sha256').update(buf).digest('hex');
+};
+const VERDICT_OUTPUT = '### Verdict\nSHIP WITH NITS — solid, two nits.\n### Blocking\nnone\n### Non-blocking\n1. nit\n### Questions\nnone';
+
+describe('agy-review.sh — review receipts (AD-038)', () => {
+  it('a fresh grounded code review appends ONE fixture-shaped receipt (verdict verbatim, factsHash real)', async () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { 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);
+    assert.match(receipt.fingerprint, /^[0-9a-f]{64}$/, 'a real sha256 hex fingerprint');
+    assert.equal(receipt.backend, 'agy');
+    assert.equal(receipt.verdict, 'SHIP WITH NITS', 'the mandated ### Verdict section is recorded verbatim');
+    assert.equal(receipt.grounded, true, '--facts was supplied');
+    assert.equal(receipt.factsHash, await sha256HexOf('a tiny fact'), 'sha256 of the facts payload — an empty/changed facts file is visible');
+    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('an ungrounded fresh run records grounded:false + factsHash null (the vacuous-grounding hole stays visible)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].grounded, false);
+    assert.equal(receipts[0].factsHash, null);
+  });
+
+  it('an EMPTY --facts file records grounded:false (fail-closed — vacuous grounding never satisfies the gate) and still warns', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.home, 'empty-facts.md'), '');
+    const r = run(sb, { args: ['code', '--facts', `@${join(sb.home, 'empty-facts.md')}`], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].grounded, false, 'an empty payload is recorded as ungrounded, never as grounded-by-flag');
+    assert.equal(receipts[0].factsHash, null);
+    assert.match(r.stderr, /no --facts supplied|ungrounded review GUESSES/, 'the ungrounded warning fires for an empty payload');
+  });
+
+  it('parses REWORK and plain SHIP; records "unknown" when the mandated section is absent', () => {
+    for (const [output, want] of [
+      ['### Verdict\nREWORK — the contract is violated.', 'REWORK'],
+      ['### Verdict\nSHIP — clean.', 'SHIP'],
+      ['free-form text with no verdict heading', 'unknown'],
+    ]) {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_OUTPUT: output } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(receipts[0].verdict, want, `verdict for: ${output.slice(0, 30)}`);
+    }
+  });
+
+  it('a continuation receipt is fresh:false with null identity fields, and the wrapper prints the fresh-run notice', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['--continue', '--decided', 'already folded'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts.length, 1);
+    const receipt = receipts[0];
+    assert.deepEqual(Object.keys(receipt), Object.keys(RECEIPT_FIXTURE), 'same fixture shape');
+    assert.equal(receipt.fresh, false, 'a continuation cannot attest the folded tree');
+    assert.equal(receipt.artifact, null);
+    assert.equal(receipt.fingerprint, null);
+    assert.equal(receipt.grounded, false);
+    assert.equal(receipt.factsHash, null);
+    assert.equal(receipt.verdict, 'SHIP WITH NITS', 'the round-2 verdict is still recorded (informational)');
+    assert.match(r.stderr, /fresh grounded run/, 'the one-line notice names the required fresh run');
+    assert.match(r.stderr, /review-state gate/);
+  });
+
+  it('plan mode: artifact "plan", fingerprint = the artifact-file sha256', async () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'p.md'), '# plan body\n');
+    const r = run(sb, { args: ['plan', 'p.md', '--facts', 'f'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].artifact, 'plan');
+    assert.equal(receipts[0].fingerprint, await sha256HexOf('# plan body\n'), 'plan fingerprint = file sha256');
+  });
+
+  it('plan/diff outside a git work tree: warn + skip the receipt (exit 0) unless AW_REVIEW_RECEIPTS is set', () => {
+    const sb = makeSandbox();
+    const outside = join(sb.home, 'no-repo');
+    mkdirSync(outside, { recursive: true });
+    writeFileSync(join(outside, 'p.md'), '# plan outside git\n');
+
+    const skipped = run(sb, { args: ['plan', 'p.md', '--facts', 'f'], cwd: outside, env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    assert.equal(skipped.status, 0, skipped.stderr);
+    assert.match(skipped.stderr, /not inside a git work tree and AW_REVIEW_RECEIPTS is unset — skipping/);
+
+    const override = join(sb.home, 'receipts-override.jsonl');
+    const written = run(sb, {
+      args: ['plan', 'p.md', '--facts', 'f'],
+      cwd: outside,
+      env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_RECEIPTS: override },
+    });
+    const body = existsSync(override) ? readFileSync(override, 'utf8') : '';
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(written.status, 0, written.stderr);
+    assert.match(body, /"backend":"agy"/, 'the override path receives the receipt outside a git tree');
+    assert.match(body, /"artifact":"plan"/);
+  });
+
+  it('a receipt write failure warns loudly but never fails the review (fail-safe direction)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, {
+      args: ['code', '--facts', 'f'],
+      env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_RECEIPTS: join(sb.home, 'no-such-dir', 'r.jsonl') },
+    });
+    rmSync(sb.home, { 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, /SHIP WITH NITS/, 'the findings still reach stdout');
+  });
+
+  it('a failed agy run writes NO receipt (only a successful review attests)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_EXIT: '7' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { 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, { args: ['code', '--facts', 'f'] });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0);
+    assert.equal(receipts.length, 0, 'no review ran — no receipt');
+  });
+});

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

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "provides": ["review", "probe"],
   "roles": {
     "review": {
@@ -27,7 +27,8 @@
         "continue": [
           "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"
       }
     },
     "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }

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

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '2.1.0'
+  version: '2.2.0'
 ---
 
 # codex-cli-bridge

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.28.0",
+  "version": "1.30.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

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

@@ -27,6 +27,7 @@ diverge:
 |---|---|---|---|---|
 | `/.claude/skills/` | Claude Code | dir | no | local-dev skills; absorbs the AD-013 one-off |
 | `/.claude/agents/` | Claude Code | dir | no | project subagent definitions (incl. the kit-placed cheap-lane vehicles) |
+| `/.claude/hooks/` | Claude Code | dir | no | project hooks (incl. the kit-placed gate-approval hook) |
 | `/.cursor/rules/` | Cursor | dir | no | project rule files |
 | `/.cursorrules` | Cursor (legacy) | file | **yes** | legacy single-file rules |
 | `/.codeium/` | Codeium/Windsurf | dir | no | home-scoped launchers live under `~/`, out of scope |