@sabaiway/agent-workflow-kit 1.49.0 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,106 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 2.1.0 — agy code review fails CLOSED pre-spend: grounded facts required, `--ungrounded` is the explicit escape (AD-058)
+
+> ### ⚠ the bundled antigravity bridge takes MAJOR 3.0.0 — bare `agy-review code` now refuses
+>
+> `agy-review code` without a NON-EMPTY `--facts` payload exits 2 **before spending a run**
+> (previously: a loud warning, then a spent subscription run whose `grounded:false` receipt the
+> review-state gate rejects — a guaranteed-wasted spend). Scripts calling bare `agy-review code`
+> must add `--facts @f` (grounded) or `--ungrounded` (explicit throwaway opinion; the receipt still
+> records `grounded:false` and never attests). `plan`/`diff` modes and continuations are unchanged.
+> The kit itself is a MINOR carrier — the incompatibility is created, and declared, by the bridge.
+
+A **fail-closed** release (kit MINOR carrying antigravity-cli-bridge **3.0.0** MAJOR in-tarball;
+codex-cli-bridge 2.8.0 / engine 1.17.0 / memory 2.3.0 unchanged; the deployment-lineage head stays
+`2.0.0`). One theme: **a run that cannot produce a usable result refuses before the money is spent.**
+
+- **The refusal prints the recovery:** the exact `grounding.mjs` invocation — resolved from the
+  wrapper's own location across the three real install layouts (monorepo canon / deployed skills
+  sibling / kit-bundled mirror), quoted so an install path with spaces still yields a runnable
+  command — plus the `agy-review code --facts @<file>` re-run line.
+- **Escapes, both honest:** `--ungrounded` (code-mode only, contradicts `--facts`, refused on a
+  continuation) and `AGY_PROBE=1` (a probe may now run ungrounded — a probe receipt never attests
+  either way; its `modeCatalog` descriptor now marks the facts file optional).
+- **Every declaration home moves in lockstep** (drift-guarded both directions): `--help` ⟷
+  `capability.json` (`roles.review.contract` + `modeCatalog` `review.code` operands/guardrails +
+  the `AGY_PROBE` env-hook) ⟷ the kit registry mirror (`tools/detect-backends.mjs`) ⟷ `SKILL.md` ⟷
+  `references/driving-agy.md` / `models-and-flags.md` / `review-prompt.md`.
+- **Receipt contract scoped honestly:** in `code` mode an absent/empty facts payload now means NO
+  run and NO receipt; the `grounded:false`-on-empty clause applies to `plan`/`diff` only.
+
+## 2.0.0 — Bridge mode catalog (manifest-as-source) + a review receipt that SELF-DECLARES (AD-057)
+
+> ### ⚠ BREAKING — a review receipt written before this release no longer attests a tree
+>
+> The kit now **rejects an unmarked receipt**: a receipt must self-declare whether it came from a
+> probe run, and silence is not a declaration. Every receipt on disk from kit ≤ 1.49.0 / bridges
+> ≤ 2.7.1 / ≤ 2.6.1 predates the marker, so `review-state --check` and `review-ledger --check` will
+> RED on it where they previously passed.
+>
+> **How to upgrade:** `npx @sabaiway/agent-workflow-kit@latest init`, which also ATTEMPTS to refresh
+> the placed bridges — then read its per-bridge outcome. **`skipped-readonly` or `could not refresh`
+> means a compatible writer is not guaranteed:** the new reader may still be paired with an old bridge
+> writer, whose reviews write unmarked receipts this gate now rejects. Re-run the refresh from a
+> writable environment (using the recovery command if one was printed), then **re-run the review** on
+> the tree you are working on. That is the whole migration; no project file changes, and the
+> deployment-lineage stamp is untouched.
+>
+> **Why it is not opt-in.** The pre-marker wrappers already honoured `CODEX_PROBE` / `AGY_PROBE` and
+> wrote no marker, so an unmarked receipt is **indistinguishable from a probe receipt** — a review
+> that ran with the frontier-model/max-effort guard switched off. Any transitional window that keeps
+> accepting unmarked receipts keeps the hole fully open for exactly the receipts it targets: it would
+> not defer the break, it would cancel the fix.
+
+A **breaking + feature** release (kit MAJOR carrying codex-cli-bridge **2.8.0** + antigravity-cli-bridge
+**2.7.0** MINOR in-tarball — the bridges only ADD a field to the receipt they write, which is additive;
+the incompatibility is created by the kit READER that now refuses the old form. engine 1.17.0 / memory
+2.3.0 unchanged; the deployment-lineage head is a separate axis and stays `2.0.0`). Two independent
+contracts, one theme: **what a bridge offers, and what a receipt claims, must both be readable off the
+artifact itself — never inferred from source or from silence.**
+
+- **`modeCatalog` — a machine-readable answer to "what modes does this bridge offer, and why?"** A new
+  **top-level, additive-optional** manifest block (schema stays 1), typed-validated exactly like
+  `settings`: absent → valid (a bridge predating it keeps validating), present-but-malformed → invalid.
+  Both bridges now declare their real mode set — codex `{exec, exec.resume-last, exec.resume,
+  review.plan, review.code, CODEX_PROBE}`, agy `{review.code/plan/diff, review.continue,
+  review.conversation, run, AGY_PROBE}` — each entry carrying a closed taxonomy (`primary` /
+  `continuation` / `env-hook`, where an env-hook names `parents[]` rather than faking a role), a
+  required one-line `purpose` + `whenToUse`, and — declared only where they apply — `whenNotTo`, typed
+  `operands[]`, structured `guardrails` `{value, enforcement, condition?, source}` and `customHooks[]`
+  (`exec.resume` carries no `guardrails`; a mode with no operands omits `operands`). Invocation forms compose **by
+  reference** (`invocationRefs[]`) into the existing AD-033 driving contract — the catalog is the
+  user-facing DISCOVERY layer and never shadows it.
+- **Descriptor honesty is enforced, not promised.** Declared operand slots must set-EQUAL the
+  placeholders the referenced forms really carry, in **both** directions over the deduplicated union of
+  an entry's forms: an undeclared placeholder is as dishonest as an invented slot, since either way the
+  render shows a form as ready-to-run that the reader cannot actually fill. `enforced` is claimable only
+  for an OS- or code-enforced fact; a runtime bound rides in `condition`; anything a prompt merely asks
+  for renders `advisory`. Catalog `submode` values are drift-guarded against the wrappers' real parser
+  arms, and every declared env-hook must be a real EXECUTABLE condition (heredocs and comments excluded,
+  so a name-grep cannot stay green after the logic is deleted).
+- **A probe review can no longer attest a tree — and the receipt says so itself.** Both wrappers wrote
+  receipts unconditionally, so a `CODEX_PROBE=1` / `AGY_PROBE=1` review — which runs with the
+  frontier-model/max-effort guard **off** — minted a `fresh:true`/`grounded:true` receipt the
+  review-state gate accepted. Both wrappers now write `probe` on **every** successful review, `true` or
+  `false`, through the shared byte-identical `write_review_receipt` block: a receipt self-declares and
+  nothing has to infer it. The kit rejects a probe-marked receipt (a probe never attests) and **equally
+  rejects an unmarked one — silence is not a declaration**.
+- **One attesting predicate, three consumers.** `classifyReviewReceiptForTree` /
+  `summarizeReviewReceiptsForTree` / `describeMissingReviewAttestation` live in the neutral
+  `review-ledger-core.mjs` and are read by `review-state.mjs`, `receiptCrossCheck` and the round writer
+  — two gates disagreeing about what attests is precisely the class AD-050 closed, and a second copy
+  would re-open it. The shared summary also fixes a latent hole: the ledger took `own[own.length - 1]`,
+  so a probe landing **after** a real review became the authoritative verdict — a probe SHIP could bury
+  a real REWORK and let both gates report convergence. The summary now returns the latest **attesting**
+  receipt, never the last line.
+- **Scope of the claim.** What a marker carries is UNTRUSTWORTHINESS, never provenance — receipts are
+  not authenticated, and a forger could write `probe:false` as easily as any other field. This is
+  self-discipline made legible, not a security boundary. See the BREAKING callout above for the upgrade
+  path; full record, including the mid-execution amendment of the original design and the stated
+  residuals, in AD-057.
+
 ## 1.49.0 — Honesty/robustness bundle: refresh EROFS stated skip · settings integer-overflow parity (AD-056)
 
 A small **honesty/robustness** release (kit MINOR carrying the two bridge PATCH bumps in-tarball —

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.49.0'
+  version: '2.1.0'
 ---
 
 # agent-workflow-kit

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.6.1'
+  version: '3.0.0'
 ---
 
 # antigravity-cli-bridge
@@ -69,6 +69,14 @@ list wins.
 
 ## Usage
 
+> **The machine-readable mode catalog lives in [`capability.json`](capability.json) `modeCatalog`** —
+> every documented mode (`agy-run` raw prompts, the three `agy-review` modes, their continuations,
+> the `AGY_PROBE` escape) with its purpose, when to use it (and when not), the exact invocation form
+> with its operand slots, and the guardrails that really apply. The catalog tracks **the documented
+> wrapper mode set** (never "the CLI's modes"): an upstream Antigravity CLI change reaches it through
+> a bridge release, where the source-level drift tests fail loudly until the catalog is updated.
+> Nothing probes a live CLI. The prose below stays the human tour.
+
 Drive `agy` only through the wrapper [`bin/agy.sh`](bin/agy.sh) (installed on `PATH` as `agy-run`):
 
 ```bash
@@ -110,11 +118,16 @@ review **guesses** (stale-model and partial-diff false positives). `agy-review`
 POSTURE + a **model/cutoff GUARD** + your **`--facts`** (the verified facts the model reviews AGAINST)
 + **`--decided`** (the anti-circling list) + **`--focus`** + the artifact + a strict output shape, then
 delegates execution to `agy-run` (one home for the timeout, the subscription invariant, and the byte
-ceiling).
+ceiling). In `code` mode grounding **fails closed**: without a non-empty `--facts` payload the wrapper
+refuses **before spending a run** (an ungrounded code receipt records `grounded:false`, which the
+review-state gate rejects — the run would attest nothing). The explicit escapes are `--ungrounded`
+(a throwaway opinion) and `AGY_PROBE=1` (a probe never attests anyway); `plan`/`diff` keep the loud
+warning and proceed.
 
 ```bash
-agy-review code [--facts @facts.md] [--decided @decided.md] [--focus "…"]   # the repo-complete diff
-agy-review plan <plan-file> [--facts @f] …      # critique a plan
+agy-review code --facts @facts.md [--decided @decided.md] [--focus "…"]   # the repo-complete diff (facts REQUIRED — fails closed pre-spend)
+agy-review code --ungrounded                    # explicit escape: throwaway ungrounded opinion (receipt never attests)
+agy-review plan <plan-file> [--facts @f] …      # critique a plan (no facts ⇒ loud warning)
 agy-review diff <diff-file> [--facts @f] …      # review a supplied diff
 agy-review --continue --decided @round1.md --focus "still-open items"   # round-2 delta, no re-assembly
 ```

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

@@ -14,7 +14,8 @@
 #   1. POSTURE   read-only second-opinion reviewer; findings only, no edits/commits
 #   2. GUARD     do NOT opine on AI model names/versions or your knowledge cutoff
 #   3. FACTS     "## Grounded facts — review AGAINST these, do NOT guess the code"
-#                (omitted -> a one-line note in-prompt + a LOUD stderr warning)
+#                (code mode REFUSES pre-spend without a non-empty payload — escapes:
+#                --ungrounded / AGY_PROBE=1; plan/diff omitted -> a LOUD stderr warning)
 #   4. DECIDED   "## Decisions already made / already addressed — do NOT re-raise"
 #                (optional; the anti-circling lever — the round-2 payload)
 #   5. FOCUS     the merged --focus / trailing focus text (optional)
@@ -27,7 +28,7 @@
 # facts (--facts), the already-decided list (--decided), and the focus (--focus).
 #
 # Usage (installed on PATH as `agy-review`):
-#   agy-review code   [--facts @f] [--decided @f] [--focus "…"] [extra focus…]
+#   agy-review code   [--facts @f] [--ungrounded] [--decided @f] [--focus "…"] [extra focus…]
 #   agy-review plan   <plan-file> [--facts @f] [--decided @f] [--focus "…"]
 #   agy-review diff   <diff-file> [--facts @f] [--decided @f] [--focus "…"]
 #   agy-review --continue          [--decided @f] [--focus "…"]   # round-2 delta (no mode, no re-assembly)
@@ -55,19 +56,22 @@ case "${1:-}" in
 agy-review — grounded read-only ADVISORY review by Google's Antigravity CLI (agy; subscription-only).
 
 Usage:
-  agy-review code [--facts @f] [--decided @f] [--focus "…"] [extra focus…]
+  agy-review code [--facts @f] [--ungrounded] [--decided @f] [--focus "…"] [extra focus…]
   agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus "…"]
   agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus "…"]
 
 Flags:
-  --facts @f — verified facts the review runs AGAINST (omit ⇒ loud ungrounded-review warning)
+  --facts @f — verified facts the review runs AGAINST (code mode REQUIRES a non-empty payload; plan/diff warn loudly when omitted)
+  --ungrounded — deliberately ungrounded CODE review, a throwaway opinion (code mode only, contradicts --facts; the receipt records grounded:false and never attests)
   --decided @f — already-decided / already-addressed list; do NOT re-raise (anti-circling; the round-2 payload)
   --focus "…" — extra focus (repeatable; code mode also takes trailing focus words)
 
 Grounding:
   grounded review — agy reads NOTHING by default, an ungrounded review GUESSES:
   --facts @f = the verified facts to review AGAINST; --decided @f = decisions
-  already made, do NOT re-raise (anti-circling)
+  already made, do NOT re-raise (anti-circling). code mode REQUIRES a non-empty
+  --facts payload and refuses BEFORE spending a run (escapes: --ungrounded,
+  AGY_PROBE=1); plan/diff proceed with a loud warning
 
 Notes:
   pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts
@@ -88,17 +92,21 @@ Receipt:
   sockets — are excluded from the domain entirely, untracked symlinks/directories ride as
   name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict
   recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK);
-  grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records
+  grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without
+  one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records
   grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts
   payload; a continuation receipt is fresh:false (informational-only — it cannot attest the
-  folded tree); a write failure warns, never fails the review
+  folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY
+  receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe
+  review never attests) and equally rejects an unmarked one (silence is not a declaration); a write
+  failure warns, never fails the review
 
 Settings file (KEY=VALUE, parsed never sourced; env wins over file, file wins over built-in default):
   ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf
   AGY_HARD_TIMEOUT — hard wall-clock cap, duration string like 5m/30m/90s (built-in default 30m)
   AGY_REVIEW_ALLOW_ADDDIR — boolean 0/1: 1 arms the oversized --add-dir escape (re-enables the Issue-001 stall risk; default 0)
 
-Closed grammar: unknown flags are rejected; no '--' passthrough (the only escapes are AGY_PROBE=1 and AGY_REVIEW_ALLOW_ADDDIR=1).
+Closed grammar: unknown flags are rejected; no '--' passthrough (the flag escape is --ungrounded; the env 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
     exit 0
@@ -217,7 +225,7 @@ 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.6.1"
+AW_BRIDGE_VERSION="3.0.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.
@@ -228,6 +236,10 @@ FRONTIER_SET=("Gemini 3.1 Pro (High)" "Claude Opus 4.6 (Thinking)" "Claude Sonne
 AGY_HARD_TIMEOUT="${AGY_HARD_TIMEOUT:-30m}"
 AGY_TIMEOUT="${AGY_TIMEOUT:-$AGY_HARD_TIMEOUT}"
 AGY_PROBE="${AGY_PROBE:-0}"
+# A probe run is RECORDED, not just silently allowed: the receipt carries probe:true so the kit's
+# review-state gate rejects it — a guards-relaxed review must never attest a tree.
+REVIEW_PROBE=false
+if [[ "$AGY_PROBE" == "1" ]]; then REVIEW_PROBE=true; fi
 AGY_REVIEW_ALLOW_ADDDIR="${AGY_REVIEW_ALLOW_ADDDIR:-0}"
 AGY_MAX_PROMPT_BYTES="${AGY_MAX_PROMPT_BYTES:-120000}"
 if [[ ! "$AGY_MAX_PROMPT_BYTES" =~ ^[0-9]+$ ]]; then
@@ -432,13 +444,18 @@ 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|"">
+# write_review_receipt <artifact|""> <fresh: true|false> <fingerprint|""> <verdict> <grounded: true|false> <factsHash|""> [probe: true|false]
 # 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.
+# The optional 7th argument marks a PROBE run (CODEX_PROBE=1 / AGY_PROBE=1 — the quality guards
+# relaxed), which the kit's review-state gate rejects: a probe review must never attest a tree. The
+# marker is written ALWAYS, true or false: the receipt SELF-DECLARES, so the gate reads the fact
+# itself instead of inferring it from this wrapper's version (which bumps in a different release
+# phase). Silence is not a declaration — an unmarked receipt is untrustworthy and the gate rejects it.
 write_review_receipt() {
-  local artifact="$1" fresh="$2" fingerprint="$3" verdict="$4" grounded="$5" facts_hash="$6"
+  local artifact="$1" fresh="$2" fingerprint="$3" verdict="$4" grounded="$5" facts_hash="$6" probe="${7:-false}"
   local receipts="${AW_REVIEW_RECEIPTS:-}"
   if [[ -z "$receipts" ]]; then
     local receipt_git_dir
@@ -448,11 +465,12 @@ write_review_receipt() {
     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"}' \
+  local line probe_field=',"probe":false'
+  if [[ "$probe" == "true" ]]; then probe_field=',"probe":true'; fi
+  line="$(printf '{"schema":1,"artifact":%s,"fresh":%s,"fingerprint":%s,"backend":"%s","verdict":"%s","grounded":%s,"factsHash":%s,"wrapperVersion":"%s","timestamp":"%s"%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)")"
+    "$AW_BRIDGE_VERSION" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$probe_field")"
   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
@@ -528,7 +546,7 @@ case "${1:-}" in
 esac
 
 usage() {
-  echo "usage: $0 code   [--facts @f] [--decided @f] [--focus \"…\"] [extra focus…]" >&2
+  echo "usage: $0 code   [--facts @f] [--ungrounded] [--decided @f] [--focus \"…\"] [extra focus…]" >&2
   echo "       $0 plan   <plan-file> [--facts @f] [--decided @f] [--focus \"…\"]" >&2
   echo "       $0 diff   <diff-file> [--facts @f] [--decided @f] [--focus \"…\"]" >&2
   echo "       $0 --continue          [--decided @f] [--focus \"…\"]" >&2
@@ -567,6 +585,7 @@ fi
 # --- Flag parse (--facts / --decided / --focus + trailing focus) -------------
 FACTS_RAW=""
 DECIDED_RAW=""
+UNGROUNDED=0
 FOCUS_PARTS=()
 # A value-taking flag must be followed by a real value — never end-of-args and never another flag.
 # Otherwise `agy-review code --facts --focus x` would silently take "--focus" as the facts and spend a
@@ -585,6 +604,12 @@ while [[ $# -gt 0 ]]; do
         exit 2
       fi
       need_value "$1" "${2:-}"; FACTS_RAW="$2"; shift 2 ;;
+    --ungrounded)
+      if [[ -n "$resume_mode" ]]; then
+        echo "error: --ungrounded is not valid on a continuation (the original round already set its grounding)." >&2
+        exit 2
+      fi
+      UNGROUNDED=1; shift ;;
     --decided)
       need_value "$1" "${2:-}"; DECIDED_RAW="$2"; shift 2 ;;
     --focus)
@@ -610,6 +635,18 @@ done
 # Merge --focus values and trailing focus words, in parse order, into ONE focus block.
 FOCUS="${FOCUS_PARTS[*]:-}"
 
+# --ungrounded closed grammar (D4): code-mode only, and an explicit contradiction with --facts refuses.
+if [[ "$UNGROUNDED" == "1" ]]; then
+  if [[ -n "$FACTS_RAW" ]]; then
+    echo "error: --ungrounded contradicts --facts — pass the verified facts (grounded) or drop them (--ungrounded), never both." >&2
+    exit 2
+  fi
+  if [[ "$mode" != "code" ]]; then
+    echo "error: --ungrounded is only valid in code mode — $mode mode already proceeds ungrounded with a loud warning." >&2
+    exit 2
+  fi
+fi
+
 # Resolve @file / literal for --facts and --decided NOW (cwd = invocation, before any code-mode cd).
 # The `@file` existence check runs at TOP LEVEL (not inside a command substitution) so its exit-2 exits
 # the whole script, not just a subshell.
@@ -635,6 +672,25 @@ if [[ -n "$DECIDED_RAW" ]]; then
 fi
 
 if [[ -z "$FACTS_CONTENT" && -z "$resume_mode" ]]; then
+  # code mode fails CLOSED before the spend (D4): an ungrounded CODE receipt records grounded:false,
+  # which the review-state gate rejects — the run would be paid for and attest nothing. Keyed on the
+  # resolved CONTENT, so --facts naming an empty payload refuses identically.
+  if [[ "$mode" == "code" && "$UNGROUNDED" != "1" && "$AGY_PROBE" != "1" ]]; then
+    # The recovery hint resolves the kit's grounding tool from THIS wrapper's location (monorepo
+    # canon / deployed skills sibling / kit-bundled mirror) — a repo-relative path would not exist
+    # for a globally installed kit. Quoted: an install path may carry spaces.
+    grounding_tool="node <agent-workflow-kit>/tools/grounding.mjs"
+    for _g in "$HERE/../../agent-workflow-kit/tools/grounding.mjs" "$HERE/../../../tools/grounding.mjs"; do
+      if [[ -f "$_g" ]]; then grounding_tool="node \"$_g\""; break; fi
+    done
+    echo "error: 'agy-review code' requires grounded facts and refuses BEFORE spending a run — an" >&2
+    echo "       ungrounded code review GUESSES, and its receipt (grounded:false) never attests." >&2
+    echo "       Assemble the verified facts, then re-run:" >&2
+    echo "         $grounding_tool --constraints [--plan <plan-file>] --out <facts-file>" >&2
+    echo "         agy-review code --facts @<facts-file>" >&2
+    echo "       Explicit escapes: --ungrounded (throwaway opinion) · AGY_PROBE=1 (a probe never attests)." >&2
+    exit 2
+  fi
   echo "warning: no --facts supplied. agy reads NOTHING by default, so an ungrounded review GUESSES" >&2
   echo "         (stale-model and partial-diff false positives). Pass --facts @file with the verified" >&2
   echo "         facts the model must review AGAINST. Proceeding without grounding." >&2
@@ -795,7 +851,7 @@ if [[ $rc -eq 0 ]]; 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 ""
+    write_review_receipt "" false "" "$verdict" false "" "$REVIEW_PROBE"
     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
@@ -805,7 +861,7 @@ if [[ $rc -eq 0 ]]; 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"
+    write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" "$grounded" "$facts_hash" "$REVIEW_PROBE"
   fi
 fi
 exit $rc