@sabaiway/agent-workflow-kit 1.49.0 → 2.1.0

package/bridges/antigravity-cli-bridge/references/driving-agy.md

@@ -58,13 +58,17 @@ prompt for `agy-run`. It **mechanizes the grounded-review contract** (see
 [`review-prompt.md`](./review-prompt.md)) so grounding is the enforced default, not a per-call effort:
 
 ```bash
-agy-review code  [--facts @facts.md] [--decided @decided.md] [--focus "…"] [extra focus…]
-agy-review plan  <plan-file> [--facts @f] [--decided @f] [--focus "…"]
+agy-review code  --facts @facts.md [--decided @decided.md] [--focus "…"] [extra focus…]   # facts REQUIRED — refuses pre-spend
+agy-review code  --ungrounded                  # explicit escape: throwaway ungrounded opinion (never attests)
+agy-review plan  <plan-file> [--facts @f] [--decided @f] [--focus "…"]   # no facts ⇒ loud warning, proceeds
 agy-review diff  <diff-file> [--facts @f] [--decided @f] [--focus "…"]
 agy-review --continue          [--decided @f] [--focus "…"]   # round-2 delta — no re-assembly
 agy-review --conversation <id> [--decided @f] [--focus "…"]
 ```
 
+`code` fails CLOSED without a non-empty `--facts` payload — the refusal fires before any run is
+spent; the explicit escapes are `--ungrounded` and `AGY_PROBE=1` (a probe never attests).
+
 What it does for you, and what YOU must supply:
 
 - **It** assembles POSTURE + a model/cutoff GUARD + your facts + your already-decided list + your focus

package/bridges/antigravity-cli-bridge/references/models-and-flags.md

@@ -48,14 +48,15 @@ subscription invariant, and the byte ceiling all apply once. The playbook is in
 [`driving-agy.md`](./driving-agy.md); the surface:
 
 ```bash
-agy-review code|plan <file>|diff <file> [--facts @f] [--decided @f] [--focus "…"]
+agy-review code --facts @f [--decided @f] [--focus "…"]   # facts REQUIRED — refuses pre-spend (escapes: --ungrounded, AGY_PROBE=1)
+agy-review plan <file>|diff <file> [--facts @f] [--decided @f] [--focus "…"]
 agy-review --continue | --conversation <id>   [--decided @f] [--focus "…"]   # round-2 delta
 ```
 
 | Var | Default | Effect |
 |---|---|---|
 | `AGY_MODEL` | `Gemini 3.1 Pro (High)` | frontier default; **any** model is allowed — a sub-frontier one earns a silenceable advisory (quality-first, not a gate) |
-| `AGY_PROBE` | `0` | `1` silences the off-frontier model advisory (throwaway probe) |
+| `AGY_PROBE` | `0` | `1` silences the off-frontier model advisory AND lets `code` run without `--facts` (an ungrounded probe never attests — its receipt is probe-marked) |
 | `AGY_REVIEW_ALLOW_ADDDIR` | `0` | `1` lets an oversized `code` review offload ONLY the change set to a private staging dir via `--add-dir` (the grounding stays inline; re-enables the Issue-001 stall risk — prefer splitting into focused reviews) |
 | `AGY_HARD_TIMEOUT` | `30m` | the review's hard cap (longer default than a probe — reviews are slower) |
 | `AGY_MAX_PROMPT_BYTES` | `120000` | the same single-argv byte ceiling; oversized → trim/split (or the `--add-dir` escape above) |

package/bridges/antigravity-cli-bridge/references/review-prompt.md

@@ -23,7 +23,7 @@ GUARD    Do NOT comment on AI model names/versions or your own knowledge cutoff
          and a known source of false positives. Review ONLY the engineering, AGAINST the facts.
 
 ## Grounded facts — review AGAINST these, do NOT guess the code
-{{GROUNDED_FACTS}}   # from --facts @file (omitted -> an in-band note + a LOUD stderr warning)
+{{GROUNDED_FACTS}}   # from --facts @file (code: REQUIRED non-empty, refuses pre-spend — escapes --ungrounded / AGY_PROBE=1; plan/diff omitted -> an in-band note + a LOUD stderr warning)
 
 ## Decisions already made / already addressed — do NOT re-raise these
 {{ALREADY_DECIDED}}  # from --decided @file (optional — the anti-circling lever; the round-2 payload)

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.7.1'
+  version: '2.8.0'
 ---
 
 # codex-cli-bridge
@@ -71,6 +71,13 @@ waste, never lowering quality. Full knob list: [§ Environment knobs](#environme
 
 ## Usage
 
+> **The machine-readable mode catalog lives in [`capability.json`](capability.json) `modeCatalog`** —
+> every documented mode 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 Codex 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 codex only through the two wrappers (installed on `PATH`), run from the target project root:
 
 ```bash

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

@@ -821,6 +821,139 @@ describe('codex-exec.sh — source-level reverse guard (parser arms ⟷ manifest
   });
 });
 
+// ── mode catalog ⟷ wrapper reality (BRIDGE-MODES-CATALOG) ─────────────────────────
+// The kit validator owns the catalog's INTERNAL shape; these arms pin the half only this wrapper's
+// source can settle — the execute role's cataloged modes really exist here, every declared contract
+// invocation is cataloged, and the env-hook the catalog aims at exec really changes the run.
+
+// The source lines that really EXECUTE: a heredoc body (the --help text) and a comment both carry
+// names without carrying logic, so a bare name-grep stays green after the logic is deleted.
+const executableLines = (source) => {
+  const out = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    if (raw.trimStart().startsWith('#')) continue;
+    out.push(raw);
+  }
+  return out;
+};
+const consultsEnv = (source, name) =>
+  executableLines(source).some((l) => new RegExp(`\\[\\[[^\\]]*\\$\\{?${name}\\b[^\\]]*(==|!=)`).test(l));
+// The optional `@` prefix rides WITH the slot — the catalog declares the whole token a user types.
+const SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+
+describe('codex-exec.sh — mode catalog ⟷ wrapper reality (manifest-pinned)', () => {
+  const source = readFileSync(WRAPPER, 'utf8');
+  const catalog = MANIFEST.modeCatalog ?? [];
+  const execEntries = catalog.filter((e) => e.role === 'execute');
+
+  it('the execute role is cataloged: one primary plus a continuation per resume flag', () => {
+    const primaries = execEntries.filter((e) => e.kind === 'primary');
+    const continuations = execEntries.filter((e) => e.kind === 'continuation');
+    assert.equal(primaries.length, 1, 'codex-exec has exactly one primary drive form');
+    assert.equal(continuations.length, EXEC_CONTRACT.continue.length, 'one continuation entry per declared resume descriptor');
+  });
+
+  it('every execute entry composes BY REFERENCE and every reference resolves', () => {
+    for (const entry of execEntries) {
+      assert.ok(
+        Array.isArray(entry.invocationRefs) && entry.invocationRefs.length > 0,
+        `${entry.key}: a contract-backed entry references at least one contract descriptor`,
+      );
+      assert.ok(!Object.hasOwn(entry, 'descriptor'), `${entry.key}: a contract-backed entry never restates a literal descriptor`);
+      for (const ref of entry.invocationRefs) {
+        assert.equal(
+          typeof EXEC_CONTRACT[ref.contractField]?.[ref.index], 'string',
+          `${entry.key}: ref ${ref.contractField}[${ref.index}] does not resolve into the manifest contract`,
+        );
+      }
+    }
+  });
+
+  it('every execute contract invocation is claimed by exactly ONE catalog entry (no uncataloged form)', () => {
+    const claims = execEntries.flatMap((e) => e.invocationRefs.map((r) => `${r.contractField}[${r.index}]`));
+    assert.equal(new Set(claims).size, claims.length, 'a contract invocation is claimed at most once');
+    const declared = [
+      ...EXEC_CONTRACT.invocations.map((_, i) => `invocations[${i}]`),
+      ...EXEC_CONTRACT.continue.map((_, i) => `continue[${i}]`),
+    ];
+    setEq(new Set(claims), declared, 'catalog claims ⟷ declared contract invocations');
+  });
+
+  it('every env-hook the catalog aims at an execute mode is a real EXECUTABLE guard, not a mention', () => {
+    const hooks = catalog.filter((e) => e.kind === 'env-hook' && e.parents.some((p) => execEntries.some((x) => x.key === p)));
+    assert.ok(hooks.length > 0, 'CODEX_PROBE must be cataloged as an env-hook over codex-exec');
+    for (const hook of hooks) {
+      assert.ok(
+        consultsEnv(source, hook.key),
+        `env-hook ${hook.key} is named in the source but never TESTED in an executable condition — a help/comment mention would keep a name-grep green after the logic is deleted`,
+      );
+    }
+  });
+
+  it('the catalog operand slots set-EQUAL the slots its rendered forms really carry (both directions)', () => {
+    for (const entry of execEntries) {
+      const forms = entry.invocationRefs.map((r) => EXEC_CONTRACT[r.contractField][r.index]);
+      // The DEDUPLICATED UNION over every resolved form: `exec` legitimately spreads its slots across
+      // two descriptors, so per-form equality would false-fail a correct catalog.
+      const realSlots = new Set(forms.flatMap((f) => f.match(SLOT_RE) ?? []));
+      setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, `${entry.key}: catalog operands ⟷ the slots its forms really carry`);
+    }
+  });
+
+  it('the catalog claims CODEX_PROBE over the resume modes because the guard really precedes resume parsing', () => {
+    // Verified in source: the quality guard runs BEFORE the resume dispatch, so a resume run is
+    // relaxed too — the catalog must say so, and this pins the ORDER the claim rests on.
+    const lines = executableLines(source);
+    const guardAt = lines.findIndex((l) => /\$\{?CODEX_PROBE/.test(l));
+    const resumeAt = lines.findIndex((l) => /^\s*--resume-last\)/.test(l));
+    assert.ok(guardAt !== -1 && resumeAt !== -1, 'both the probe guard and the resume arm must exist');
+    assert.ok(guardAt < resumeAt, 'the probe guard must precede resume parsing — else the resume parents are a false claim');
+    const hook = catalog.find((e) => e.key === 'CODEX_PROBE');
+    for (const key of ['exec.resume-last', 'exec.resume']) {
+      assert.ok(hook.parents.includes(key), `${key} is relaxed by the hook, so the catalog must declare it a parent`);
+    }
+  });
+
+  it('CODEX_PROBE really relaxes the guard on EVERY execute parent the catalog claims (behavioural)', () => {
+    // Source ORDER alone is not the claim: a branch bug after resume parsing would keep it green.
+    // Drive each claimed parent for real — the guard must stop the dispatch without the hook, and
+    // codex must really be reached with it (r.argv is non-empty only on a real invocation).
+    const hook = catalog.find((e) => e.key === 'CODEX_PROBE');
+    const drive = {
+      exec: (sb) => ({ args: ['-'], input: 'do a thing' }),
+      'exec.resume-last': (sb) => {
+        writeFileSync(join(sb.repo, '.codex-last-session'), 'sess-from-sidecar\n');
+        return { args: ['--resume-last', '-'], input: 'continue' };
+      },
+      'exec.resume': () => ({ args: ['--resume', 'sess-xyz', '-'], input: 'continue' }),
+    };
+    const execParents = hook.parents.filter((p) => execEntries.some((x) => x.key === p));
+    assert.ok(execParents.length > 0, 'CODEX_PROBE must claim at least one execute parent');
+    for (const parent of execParents) {
+      assert.ok(drive[parent], `no behavioural drive for claimed parent "${parent}" — add one`);
+
+      const guarded = makeSandbox();
+      const off = run(guarded, { ...drive[parent](guarded), env: { CODEX_MODEL: 'not-the-pinned-model' } });
+      rmSync(guarded.root, { recursive: true, force: true });
+      assert.equal(off.status, 2, `${parent}: the quality guard must refuse an off-pin model without the hook`);
+      assert.equal(off.argv, '', `${parent}: the guard must refuse BEFORE spending a run`);
+
+      const probed = makeSandbox();
+      const on = run(probed, { ...drive[parent](probed), env: { CODEX_MODEL: 'not-the-pinned-model', CODEX_PROBE: '1' } });
+      rmSync(probed.root, { recursive: true, force: true });
+      assert.equal(on.status, 0, `${parent}: CODEX_PROBE=1 must really relax the guard — the catalog claims it does`);
+      assert.notEqual(on.argv, '', `${parent}: CODEX_PROBE=1 must really reach codex, not merely exit 0`);
+    }
+  });
+});
+
 // ── bridge settings file + service tier knob (bridges 2.3.0) ─────────────────────
 // ${XDG_CONFIG_HOME:-$HOME/.config}/agent-workflow/bridge-settings.conf holds KEY=VALUE
 // lines, PARSED (never sourced). Precedence: explicit env (even empty: KEY= disables the

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

@@ -62,7 +62,10 @@ Receipt:
   symlinks/directories ride as name-only notes) 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
+  factsHash null); probe = whether the run relaxed the quality guards (CODEX_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
@@ -190,7 +193,7 @@ 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.7.1"
+AW_BRIDGE_VERSION="2.8.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).
@@ -217,7 +220,11 @@ fi
 CHATGPT_LOGIN_GUARD="Logged in using ChatGPT"
 
 # --- Quality-first guard: refuse a silent model/effort downgrade ---------------
+# A relaxed run is RECORDED, not just warned about: the receipt carries probe:true so the kit's
+# review-state gate rejects it — "do NOT use this as a real review" becomes a mechanism, not a plea.
+REVIEW_PROBE=false
 if [[ "${CODEX_PROBE:-}" == "1" ]]; then
+  REVIEW_PROBE=true
   echo "warning: CODEX_PROBE=1 — THROWAWAY PROBE MODE. Quality guards relaxed; do NOT use this run's" >&2
   echo "         output as a real review (model='$CODEX_MODEL' effort='$CODEX_EFFORT')." >&2
 else
@@ -414,13 +421,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
@@ -430,11 +442,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
@@ -687,5 +700,5 @@ 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 ""
+# full fresh run (one-shot, no resume) → fresh:true. $REVIEW_PROBE marks a guards-relaxed run.
+write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" true "" "$REVIEW_PROBE"

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

@@ -618,6 +618,32 @@ const extractArgCaseArms = (source) => {
 };
 const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
 
+// The source lines that really EXECUTE: a heredoc body (the --help text) and a comment both carry
+// names without carrying logic, so a bare name-grep over the whole source stays green after the
+// logic is deleted. Reuses the same heredoc discipline as extractArgCaseArms.
+const executableLines = (source) => {
+  const out = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    if (raw.trimStart().startsWith('#')) continue;
+    out.push(raw);
+  }
+  return out;
+};
+// An env var is really CONSULTED when an executable test compares it: [[ "${NAME:-}" == … ]].
+const consultsEnv = (source, name) =>
+  executableLines(source).some((l) => new RegExp(`\\[\\[[^\\]]*\\$\\{?${name}\\b[^\\]]*(==|!=)`).test(l));
+// The operand slots a rendered invocation form really carries: <angle> and [bracket] placeholders.
+// The optional `@` prefix rides WITH the slot (`@<facts-file>` is one operand, not a bare
+// `<facts-file>` behind a stray character) — the catalog declares the whole token a user types.
+const SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+
 describe('codex-review.sh — --help contract (manifest-pinned)', () => {
   it('--help and -h exit 0 pre-preflight (no codex, no git, no AGENTS.md)', () => {
     for (const arg of ['--help', '-h']) {
@@ -679,11 +705,114 @@ describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manife
   });
 });
 
+// ── mode catalog ⟷ wrapper reality (BRIDGE-MODES-CATALOG) ─────────────────────────
+// The kit validator owns the catalog's INTERNAL shape; these arms pin what only the wrapper source
+// can settle — the catalog documents THIS wrapper's real modes and real escape hatches, and every
+// contract invocation the wrapper honours is cataloged (adding a mode without one fails here).
+describe('codex-review.sh — mode catalog ⟷ wrapper reality (manifest-pinned)', () => {
+  const source = readFileSync(WRAPPER, 'utf8');
+  const arms = extractArgCaseArms(source);
+  const catalog = MANIFEST.modeCatalog ?? [];
+  const reviewEntries = catalog.filter((e) => e.role === 'review');
+  const reviewPrimaries = reviewEntries.filter((e) => e.kind === 'primary');
+
+  it('the catalog submodes ARE the wrapper\'s real parser mode arms (both directions)', () => {
+    const modes = splitArms(arms.get('"$mode"')).filter((a) => a !== '*');
+    assert.ok(reviewPrimaries.length > 0, 'the manifest must catalog its review modes');
+    setEq(reviewPrimaries.map((e) => e.submode), modes, 'catalog submodes ⟷ real parser mode arms');
+  });
+
+  it('every review entry composes BY REFERENCE and every reference resolves', () => {
+    for (const entry of reviewEntries) {
+      assert.ok(
+        Array.isArray(entry.invocationRefs) && entry.invocationRefs.length > 0,
+        `${entry.key}: a contract-backed entry references at least one contract descriptor`,
+      );
+      assert.ok(!Object.hasOwn(entry, 'descriptor'), `${entry.key}: a contract-backed entry never restates a literal descriptor`);
+      for (const ref of entry.invocationRefs) {
+        assert.equal(
+          typeof REVIEW_CONTRACT[ref.contractField]?.[ref.index], 'string',
+          `${entry.key}: ref ${ref.contractField}[${ref.index}] does not resolve into the manifest contract`,
+        );
+      }
+    }
+  });
+
+  it('every review contract invocation is claimed by exactly ONE catalog entry (no uncataloged mode)', () => {
+    const claims = reviewEntries.flatMap((e) => e.invocationRefs.map((r) => `${r.contractField}[${r.index}]`));
+    assert.equal(new Set(claims).size, claims.length, 'a contract invocation is claimed at most once');
+    const declared = [
+      ...REVIEW_CONTRACT.invocations.map((_, i) => `invocations[${i}]`),
+      ...(REVIEW_CONTRACT.continue ?? []).map((_, i) => `continue[${i}]`),
+    ];
+    setEq(new Set(claims), declared, 'catalog claims ⟷ declared contract invocations');
+  });
+
+  it('every env-hook the catalog aims at a review mode is a real EXECUTABLE guard, not a mention', () => {
+    const hooks = catalog.filter((e) => e.kind === 'env-hook' && e.parents.some((p) => reviewPrimaries.some((r) => r.key === p)));
+    assert.ok(hooks.length > 0, 'CODEX_PROBE must be cataloged as an env-hook over the review modes');
+    for (const hook of hooks) {
+      assert.ok(
+        consultsEnv(source, hook.key),
+        `env-hook ${hook.key} is named in the source but never TESTED in an executable condition — a help/comment mention would keep a name-grep green after the logic is deleted`,
+      );
+    }
+  });
+
+  it('the catalog operand slots set-EQUAL the slots its rendered forms really carry (both directions)', () => {
+    for (const entry of reviewEntries) {
+      const forms = entry.invocationRefs.map((r) => REVIEW_CONTRACT[r.contractField][r.index]);
+      // The DEDUPLICATED UNION over every resolved form: a plural-ref entry legitimately spreads its
+      // slots across forms, so per-form equality would false-fail a correct catalog.
+      const realSlots = new Set(forms.flatMap((f) => f.match(SLOT_RE) ?? []));
+      setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, `${entry.key}: catalog operands ⟷ the slots its forms really carry`);
+    }
+  });
+
+  it('an entry rendering a LITERAL descriptor is slot-checked too (env-hooks have no role to filter on)', () => {
+    // The contract-backed arm above filters by role — and an env-hook HAS no role, so its descriptor
+    // would never be slot-checked. That is exactly how a hardcoded dead path can reach the discovery
+    // surface looking ready-to-run. Every literal-descriptor kind is covered here: env-hooks and
+    // contract-free primaries.
+    const literalEntries = catalog.filter((e) => typeof e.descriptor === 'string');
+    assert.ok(literalEntries.length > 0, 'CODEX_PROBE must be cataloged with a literal descriptor');
+    for (const entry of literalEntries) {
+      const realSlots = new Set(entry.descriptor.match(SLOT_RE) ?? []);
+      setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, `${entry.key}: catalog operands ⟷ the slots its descriptor really carries`);
+    }
+  });
+
+  it('CODEX_PROBE really relaxes the guard on EVERY review parent the catalog claims (behavioural)', () => {
+    // The catalog CLAIMS these modes are modified by the hook; prove it per parent rather than
+    // trusting a source scan: an off-pin model is exit 2 normally, exit 0 under probe.
+    const hook = catalog.find((e) => e.key === 'CODEX_PROBE');
+    const drive = { 'review.plan': ['plan', 'plan.md'], 'review.code': ['code'] };
+    const reviewParents = hook.parents.filter((p) => reviewPrimaries.some((r) => r.key === p));
+    assert.ok(reviewParents.length > 0, 'CODEX_PROBE must claim at least one review parent');
+    for (const parent of reviewParents) {
+      assert.ok(drive[parent], `no behavioural drive for claimed parent "${parent}" — add one`);
+      // The exit code alone is weak evidence: pin the real DISPATCH too (capStdin is non-empty only
+      // when codex was actually invoked), so a run that dies early can never pass the probe-on branch.
+      const guarded = makeSandbox();
+      const off = run(guarded, { args: drive[parent], env: { CODEX_MODEL: 'not-the-pinned-model' } });
+      rmSync(guarded.root, { recursive: true, force: true });
+      assert.equal(off.status, 2, `${parent}: the quality guard must refuse an off-pin model without the hook`);
+      assert.equal(off.capStdin, '', `${parent}: the guard must refuse BEFORE spending a run`);
+
+      const probed = makeSandbox();
+      const on = run(probed, { args: drive[parent], env: { CODEX_MODEL: 'not-the-pinned-model', CODEX_PROBE: '1' } });
+      rmSync(probed.root, { recursive: true, force: true });
+      assert.equal(on.status, 0, `${parent}: CODEX_PROBE=1 must really relax the guard — the catalog claims it does`);
+      assert.notEqual(on.capStdin, '', `${parent}: CODEX_PROBE=1 must really reach codex, not merely exit 0`);
+    }
+  });
+});
+
 // ── review receipts (AD-038) ─────────────────────────────────────────────────────
-// The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; field VALUES with
+// The normative fixture: the AD-038 shape + the D3 self-declaring probe marker (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.3.0","timestamp":"2026-07-03T12:00:00Z"}',
+  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.3.0","timestamp":"2026-07-03T12:00:00Z","probe":false}',
 );
 const RECEIPTS_REL = join('.git', 'agent-workflow-review-receipts.jsonl');
 const readReceipts = (repo) => {
@@ -715,6 +844,40 @@ describe('codex-review.sh — review receipts (AD-038)', () => {
     assert.match(receipt.timestamp, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
   });
 
+  // The probe marker (BRIDGE-MODES-CATALOG, D3): a CODEX_PROBE=1 review runs with the
+  // frontier-model/max-effort guard OFF, so its receipt must be distinguishable — the kit's
+  // review-state gate rejects a probe-marked receipt. EVERY receipt carries the marker (true or
+  // false): it self-declares, so the gate reads the fact rather than inferring it from a version
+  // string that bumps in a different release phase. Silence is not a declaration.
+  it('CODEX_PROBE=1 stamps probe:true — a throwaway probe can never attest a tree (D3)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_PROBE: '1', 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].probe, true, 'a probe-relaxed run marks its own receipt');
+    assert.deepEqual(Object.keys(receipts[0]), Object.keys(RECEIPT_FIXTURE), 'fixture key set + order');
+  });
+
+  // Every receipt SELF-DECLARES: the kit's gate reads the marker, never the wrapper version — so
+  // the marker must not depend on a version bump landing in the same release phase.
+  it('a normal review self-declares probe:false — the receipt states the fact, not a version', () => {
+    const sb = makeSandbox();
+    run(sb, { env: { CODEX_FAKE_FINAL: 'Verdict: ship' } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(receipts[0].probe, false, 'silence is not a declaration — the gate rejects an unmarked receipt');
+  });
+
+  it('the marker tracks the RELAXED GUARD, not the model — a probe on an off-pinned model still marks', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { env: { CODEX_PROBE: '1', CODEX_MODEL: 'gpt-5-mini', CODEX_EFFORT: 'low', 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].probe, true, 'exactly the runs the guard let through unpinned are marked');
+  });
+
   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

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

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "provides": ["execute", "review"],
   "roles": {
     "execute": {
@@ -42,10 +42,126 @@
         ],
         "grounding": "automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags",
         "continue": [],
-        "receipt": "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) 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"
+        "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; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) 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); probe = whether the run relaxed the quality guards (CODEX_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"
       }
     }
   },
+  "modeCatalog": [
+    {
+      "key": "exec",
+      "kind": "primary",
+      "role": "execute",
+      "purpose": "Execute a bounded plan in a sandboxed workspace and hand back a diff to review.",
+      "whenToUse": [
+        "a bounded sub-task whose acceptance criteria are already pinned",
+        "work you will review and commit yourself — the backend never commits"
+      ],
+      "whenNotTo": [
+        "work whose design is still open — decide it first, then delegate",
+        "anything you cannot check: the diff is advisory until you review it"
+      ],
+      "invocationRefs": [
+        { "contractField": "invocations", "index": 0 },
+        { "contractField": "invocations", "index": 1 }
+      ],
+      "operands": [
+        { "slot": "<plan-file|->", "required": true, "description": "the plan or instruction file, or - to read it from stdin" },
+        { "slot": "<extra codex flags...>", "required": false, "description": "extra codex flags, filtered by the guarded passthrough tiers" }
+      ],
+      "guardrails": [
+        { "value": "runs under codex's OWN OS sandbox (workspace-write)", "enforcement": "enforced", "condition": "it cannot nest inside another sandbox — the FS turns read-only; route it outside on the OBSERVED failure", "source": "capability.json roles.execute.contract.notes" },
+        { "value": "the guarded passthrough blocks model / sandbox / approval overrides", "enforcement": "enforced", "source": "bin/codex-exec.sh" },
+        { "value": "hard wall-clock cap CODEX_HARD_TIMEOUT (built-in default 3600s)", "enforcement": "enforced", "condition": "only while timeout(1)/gtimeout is on PATH — otherwise the wrapper warns and runs uncapped", "source": "capability.json settings.CODEX_HARD_TIMEOUT" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "exec.resume-last",
+      "kind": "continuation",
+      "role": "execute",
+      "purpose": "Continue the most recent codex-exec session with a follow-up instruction.",
+      "whenToUse": ["a small delta on work the same session already holds in context"],
+      "whenNotTo": ["a fresh task — a stale session carries stale assumptions"],
+      "invocationRefs": [{ "contractField": "continue", "index": 0 }],
+      "operands": [
+        { "slot": "<plan-file|->", "required": true, "description": "the follow-up instruction file, or - to read it from stdin" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "exec.resume",
+      "kind": "continuation",
+      "role": "execute",
+      "purpose": "Continue a NAMED codex-exec session by the session id it printed.",
+      "whenToUse": ["resuming a specific earlier session after other runs happened in between"],
+      "invocationRefs": [{ "contractField": "continue", "index": 1 }],
+      "operands": [
+        { "slot": "<session-id>", "required": true, "description": "the session id the original run printed on stderr" },
+        { "slot": "<plan-file|->", "required": true, "description": "the follow-up instruction file, or - to read it from stdin" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "review.plan",
+      "kind": "primary",
+      "role": "review",
+      "submode": "plan",
+      "purpose": "Critique an implementation plan before any of its code exists.",
+      "whenToUse": [
+        "a plan draft heading into its review council",
+        "checking whether a cold executor could really run the plan"
+      ],
+      "whenNotTo": ["a working-tree change set — that is review.code"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 0 }],
+      "operands": [
+        { "slot": "<plan-file>", "required": true, "description": "the plan file under review" }
+      ],
+      "guardrails": [
+        { "value": "read-only sandbox — codex cannot edit, create or delete a file", "enforcement": "enforced", "source": "bin/codex-review.sh" },
+        { "value": "runs on the pinned frontier model at max effort", "enforcement": "enforced", "condition": "unless CODEX_PROBE=1 relaxes the guard for a throwaway probe", "source": "bin/codex-review.sh" },
+        { "value": "a successful review appends one receipt line the review-state gate reads", "enforcement": "enforced", "condition": "a receipt write failure warns and the review still succeeds — the tree then reads un-receipted", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "review.code",
+      "kind": "primary",
+      "role": "review",
+      "submode": "code",
+      "purpose": "Review the uncommitted working-tree change set, precomputed in full for codex.",
+      "whenToUse": [
+        "a finished segment heading into its review round",
+        "a second opinion on real code before the commit ask"
+      ],
+      "whenNotTo": ["a clean tree — the wrapper exits before spending a run"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 1 }],
+      "operands": [
+        { "slot": "[extra focus...]", "required": false, "description": "extra focus words appended to the review directive" }
+      ],
+      "guardrails": [
+        { "value": "read-only sandbox — codex cannot edit, create or delete a file", "enforcement": "enforced", "source": "bin/codex-review.sh" },
+        { "value": "an oversized change set rides via a git-dir temp file, never truncated", "enforcement": "enforced", "source": "bin/codex-review.sh" },
+        { "value": "a successful review appends one receipt line the review-state gate reads", "enforcement": "enforced", "condition": "a receipt write failure warns and the review still succeeds — the tree then reads un-receipted", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["CODEX_PROBE"]
+    },
+    {
+      "key": "CODEX_PROBE",
+      "kind": "env-hook",
+      "parents": ["exec", "exec.resume-last", "exec.resume", "review.plan", "review.code"],
+      "purpose": "Relax the quality guards for a THROWAWAY probe run.",
+      "whenToUse": [
+        "a probe whose answer cannot depend on model or effort",
+        "checking that the wrapper plumbing works at all"
+      ],
+      "whenNotTo": ["any run whose output informs what ships — a probe never attests"],
+      "descriptor": "CODEX_PROBE=1 codex-review code",
+      "guardrails": [
+        { "value": "a probe review mints a probe-marked receipt the review-state gate rejects", "enforcement": "enforced", "source": "agent-workflow-kit tools/review-state.mjs" },
+        { "value": "on codex-exec it also relaxes the passthrough to the probeRelaxed tier", "enforcement": "enforced", "source": "bin/codex-exec.sh" }
+      ]
+    }
+  ],
   "settings": [
     {
       "key": "CODEX_SERVICE_TIER",

package/capability.json

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