@sabaiway/agent-workflow-kit 1.29.0 → 1.31.0

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

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 ""