@sabaiway/agent-workflow-kit 1.49.0 → 2.1.0

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

@@ -190,17 +190,100 @@ describe('agy-review.sh — guard + grounding (2, 3)', () => {
     assert.match(r.prompt, /## Focus\nfirst second third/);
   });
 
-  it('warns LOUDLY when --facts is omitted, and proceeds', () => {
+  it('plan mode with no --facts keeps the warning and proceeds (unchanged contract)', () => {
     const sb = makeSandbox();
-    const r = run(sb, { args: ['code'] });
+    writeFileSync(join(sb.repo, 'p.md'), '# plan body\n');
+    const r = run(sb, { args: ['plan', 'p.md'] });
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.match(r.stderr, /no --facts supplied/);
-    assert.equal(r.invoked, true, 'an ungrounded review still proceeds (warn, not block)');
+    assert.equal(r.invoked, true, 'an ungrounded plan review still proceeds (warn, not block)');
     assert.match(r.prompt, /none supplied/, 'the prompt notes the missing facts in-band');
   });
 });
 
+// ── code mode fails CLOSED without grounded facts (D4) ───────────────────────────
+// An ungrounded CODE receipt records grounded:false, which the kit's review-state gate rejects —
+// the run would be paid for and attest nothing. The wrapper refuses BEFORE the spend, keyed on the
+// resolved CONTENT (an empty --facts payload refuses identically). Escapes: the explicit
+// --ungrounded flag (throwaway opinion) and AGY_PROBE=1 (a probe receipt never attests anyway).
+describe('agy-review.sh — code mode fails CLOSED without grounded facts (D4)', () => {
+  it('code mode with no --facts exits 2 before any agy invocation', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2, r.stderr);
+    assert.equal(r.invoked, false, 'the refusal must fire before any agy invocation — zero runs spent');
+    assert.match(r.stderr, /grounding\.mjs/, 'the refusal names the facts assembler');
+    assert.match(r.stderr, /agy-review code --facts @/, 'the refusal prints the exact re-run line');
+    const hint = r.stderr.match(/node "([^"]+grounding\.mjs)"/);
+    assert.ok(hint, 'the recovery hint resolves and QUOTES a real grounding.mjs path (an install path may carry spaces)');
+    assert.ok(existsSync(hint[1]), 'the resolved hint path exists on this layout');
+  });
+
+  it('code mode with --facts naming an EMPTY payload exits 2 before any agy invocation', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'empty-facts.md'), '');
+    const r = run(sb, { args: ['code', '--facts', '@empty-facts.md'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2, 'the refusal keys on the CONTENT, not the flag');
+    assert.equal(r.invoked, false, 'an empty payload must not spend a run');
+    assert.match(r.stderr, /agy-review code --facts @/);
+  });
+
+  it('code --ungrounded proceeds and the receipt records grounded:false', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--ungrounded'], 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(r.invoked, true, 'the explicit escape lets the run proceed');
+    assert.equal(receipts.length, 1);
+    assert.equal(receipts[0].grounded, false, 'an --ungrounded run still records grounded:false');
+    assert.equal(receipts[0].factsHash, null);
+    assert.match(r.stderr, /no --facts supplied/, 'the escape path stays loud, never silent');
+  });
+
+  it('AGY_PROBE=1 code with no --facts proceeds and the receipt records probe:true', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code'], env: { AGY_PROBE: '1', 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(r.invoked, true, 'an ungrounded probe is coherent — a probe receipt never attests');
+    assert.equal(receipts[0].probe, true);
+    assert.equal(receipts[0].grounded, false);
+  });
+
+  it('--ungrounded with --facts is a refusal (contradiction)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--ungrounded', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2);
+    assert.equal(r.invoked, false);
+    assert.match(r.stderr, /--ungrounded contradicts --facts/);
+  });
+
+  it('--ungrounded outside code mode is a refusal', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'p.md'), '# p\n');
+    const r = run(sb, { args: ['plan', 'p.md', '--ungrounded'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2);
+    assert.equal(r.invoked, false);
+    assert.match(r.stderr, /--ungrounded is only valid in code mode/);
+  });
+
+  it('--ungrounded on a continuation is a refusal', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['--continue', '--ungrounded'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2);
+    assert.equal(r.invoked, false);
+    assert.match(r.stderr, /--ungrounded is not valid on a continuation/);
+  });
+});
+
 describe('agy-review.sh — code-mode precomputed diff (4, 5, 8)', () => {
   it('assembles repo map + status + untracked CONTENTS', () => {
     const sb = makeSandbox();
@@ -521,6 +604,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('agy-review.sh — --help contract (manifest-pinned)', () => {
   it('--help and -h exit 0 pre-preflight (no agy, no git)', () => {
     for (const arg of ['--help', '-h']) {
@@ -597,6 +706,116 @@ describe('agy-review.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 cataloged review modes ARE the real parser arms, every declared contract
+// invocation is cataloged, and the env-hook the catalog aims at review is a real env var.
+describe('agy-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(new Set(reviewPrimaries.map((e) => e.submode)), new Set(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, 'AGY_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
+    // was never slot-checked at all. 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, 'AGY_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('AGY_PROBE really silences the advisory 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: the off-frontier advisory fires without it, is silent with it.
+    const hook = catalog.find((e) => e.key === 'AGY_PROBE');
+    const drive = {
+      'review.code': () => ['code', '--facts', 'f'],
+      'review.plan': (sb) => { writeFileSync(join(sb.repo, 'p.md'), '# p\n'); return ['plan', 'p.md', '--facts', 'f']; },
+      'review.diff': (sb) => { writeFileSync(join(sb.repo, 'c.diff'), 'diff body\n'); return ['diff', 'c.diff', '--facts', 'f']; },
+      'review.continue': () => ['--continue'],
+      'review.conversation': () => ['--conversation', 'conv-1'],
+    };
+    assert.ok(hook.parents.length > 0, 'AGY_PROBE must claim at least one parent');
+    for (const parent of hook.parents) {
+      assert.ok(drive[parent], `no behavioural drive for claimed parent "${parent}" — add one`);
+      // Both runs must really REACH agy: asserting the diagnostic text alone would let an early
+      // failure that never dispatched pass the probe-on branch (its stderr simply lacks the string).
+      const noisy = makeSandbox();
+      const off = run(noisy, { args: drive[parent](noisy), env: { AGY_MODEL: 'Some Weak Model' } });
+      rmSync(noisy.home, { recursive: true, force: true });
+      assert.equal(off.status, 0, `${parent}: ${off.stderr}`);
+      assert.equal(off.invoked, true, `${parent}: the control run must reach agy`);
+      assert.match(off.stderr, /non-frontier model/, `${parent}: the advisory must fire without the hook`);
+
+      const quiet = makeSandbox();
+      const on = run(quiet, { args: drive[parent](quiet), env: { AGY_MODEL: 'Some Weak Model', AGY_PROBE: '1' } });
+      rmSync(quiet.home, { recursive: true, force: true });
+      assert.equal(on.status, 0, `${parent}: ${on.stderr}`);
+      assert.equal(on.invoked, true, `${parent}: AGY_PROBE=1 must still reach agy — silence must come from the hook, not from an early exit`);
+      assert.doesNotMatch(on.stderr, /non-frontier model/, `${parent}: AGY_PROBE=1 must really silence it — the catalog claims it does`);
+    }
+  });
+});
+
 describe('agy-review.sh — declared contract is really accepted (forward guard)', () => {
   it('every manifest mode runs green', () => {
     const drive = {
@@ -618,7 +837,12 @@ describe('agy-review.sh — declared contract is really accepted (forward guard)
     for (const descriptor of REVIEW_CONTRACT.flags) {
       const flag = leadingFlag(descriptor);
       const sb = makeSandbox();
-      const r = run(sb, { args: ['code', flag, 'f'] });
+      // D4: code mode refuses without grounded facts, so a non-facts value flag is driven on a
+      // grounded run; --ungrounded takes no value, contradicts --facts, and is driven alone.
+      const args = flag === '--facts' ? ['code', '--facts', 'f']
+        : flag === '--ungrounded' ? ['code', '--ungrounded']
+          : ['code', '--facts', 'f', flag, 'f'];
+      const r = run(sb, { args });
       rmSync(sb.home, { recursive: true, force: true });
       assert.equal(r.status, 0, `${flag}: ${r.stderr}`);
     }
@@ -643,10 +867,10 @@ describe('agy-review.sh — declared contract is really accepted (forward guard)
 });
 
 // ── review receipts (AD-038) ─────────────────────────────────────────────────────
-// The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; backend/verdict here
+// The normative fixture: the AD-038 shape + the D3 self-declaring probe marker (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.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) => {
@@ -682,9 +906,44 @@ describe('agy-review.sh — review receipts (AD-038)', () => {
     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)', () => {
+  // The probe marker (BRIDGE-MODES-CATALOG, D3) — the twin of the sibling bridge's arm: an
+  // AGY_PROBE=1 review runs with the frontier-model advisory silenced, so its receipt is marked and
+  // the kit's review-state gate rejects it. 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('AGY_PROBE=1 stamps probe:true — a throwaway probe can never attest a tree (D3)', () => {
     const sb = makeSandbox();
-    const r = run(sb, { args: ['code'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_PROBE: '1', 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].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, { 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(receipts[0].probe, false, 'silence is not a declaration — the gate rejects an unmarked receipt');
+  });
+
+  it('a probe CONTINUATION is marked too (it is doubly unable to attest — fresh:false AND probe)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['--continue'], env: { AGY_PROBE: '1', 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].fresh, false);
+    assert.equal(receipts[0].probe, true, 'both write paths carry the marker — no unmarked probe lane');
+  });
+
+  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', '--ungrounded'], 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);
@@ -692,16 +951,15 @@ describe('agy-review.sh — review receipts (AD-038)', () => {
     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', () => {
+  it('an EMPTY --facts file in code mode refuses pre-spend — no run, no receipt (D4 fail-closed)', () => {
     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');
+    assert.equal(r.status, 2, 'vacuous grounding no longer spends a run');
+    assert.equal(r.invoked, false);
+    assert.equal(receipts.length, 0, 'no run — no receipt');
   });
 
   it('parses REWORK and plain SHIP; records "unknown" when the mandated section is absent', () => {

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

@@ -455,3 +455,79 @@ describe('agy.sh — settings surface ⟷ manifest (D6, manifest-pinned)', () =>
     }
   });
 });
+
+// ── mode catalog: the contract-free raw mode ⟷ this wrapper (BRIDGE-MODES-CATALOG) ─────
+// agy-run is the probe role: it is dispatched by no activity slot and so carries NO manifest
+// driving contract (`wrapperContractFor(_, 'probe')` stays null). Its catalog entry therefore
+// carries a LITERAL descriptor — the stated exception to no-duplication, because for a
+// contract-free mode the catalog IS canonical. That makes the catalog the only thing that can
+// drift from this wrapper, so these arms pin it in BOTH directions and then really drive it.
+const USAGE_HEADER = 'Usage:';
+const PROBE_CMD = 'agy-run';
+// The operand slots a rendered invocation form really carries: <angle> and [bracket] placeholders.
+// The optional `@` prefix rides WITH the slot — the catalog declares the whole token a user types.
+const SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+
+describe('agy.sh — mode catalog ⟷ wrapper reality (the contract-free raw mode)', () => {
+  const catalog = MANIFEST.modeCatalog ?? [];
+  const probeEntries = catalog.filter((e) => e.role === 'probe');
+
+  const helpText = () => {
+    const home = mkdtempSync(join(tmpdir(), 'agy-catalog-help-'));
+    const r = spawnSync('bash', [WRAPPER, '--help'], {
+      env: { HOME: home, PATH: makePathWithout(home, ['agy', 'git']) },
+      encoding: 'utf8',
+      timeout: 15000,
+    });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    return r.stdout;
+  };
+
+  it('the probe role is cataloged as exactly ONE contract-free primary carrying a literal descriptor', () => {
+    assert.equal(probeEntries.length, 1, 'agy-run is one mode — a raw prompt');
+    const [entry] = probeEntries;
+    assert.equal(entry.kind, 'primary');
+    assert.equal(MANIFEST.roles.probe.contract, undefined, 'the probe role carries no driving contract — the catalog must not invent one');
+    assert.ok(!Object.hasOwn(entry, 'invocationRefs'), 'a contract-free entry has nothing to reference');
+    assert.equal(typeof entry.descriptor, 'string', 'a contract-free entry is canonical for its own form');
+  });
+
+  it('the catalog descriptor IS a real --help Usage line (catalog → wrapper: no invented form)', () => {
+    const usage = helpSection(helpText(), USAGE_HEADER);
+    assert.ok(usage.includes(probeEntries[0].descriptor), `the cataloged form is in no Usage line: ${probeEntries[0].descriptor}`);
+  });
+
+  it('every --help Usage line belongs to the cataloged mode (wrapper → catalog: no uncataloged form)', () => {
+    const usage = helpSection(helpText(), USAGE_HEADER);
+    assert.ok(usage.length > 0, 'the wrapper must document its usage');
+    for (const line of usage) {
+      assert.ok(line.includes(PROBE_CMD), `Usage line "${line}" invokes something other than the one cataloged mode`);
+    }
+  });
+
+  it('the catalog operand slots set-EQUAL the slots the cataloged form really carries (both directions)', () => {
+    const [entry] = probeEntries;
+    const realSlots = new Set(entry.descriptor.match(SLOT_RE) ?? []);
+    setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, 'catalog operands ⟷ the slots the descriptor really carries');
+  });
+
+  it('the required operand really accepts every form the catalog says it takes (forward drive)', () => {
+    // <prompt|-|@file> is ONE slot with three real spellings — drive all three against the stub.
+    const home = makeSandbox('#!/usr/bin/env bash\nprintf "%s" "$*" >"$HOME/argv"\necho FAKE_REPLY\n');
+    const promptFile = join(home, 'p.md');
+    writeFileSync(promptFile, 'from a file\n');
+    const env = { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, TMPDIR: process.env.TMPDIR ?? '/tmp' };
+    const drives = [
+      { label: 'literal prompt', args: ['inline prompt'], stdin: undefined },
+      { label: 'stdin (-)', args: ['-'], stdin: 'from stdin\n' },
+      { label: '@file', args: [`@${promptFile}`], stdin: undefined },
+    ];
+    for (const drive of drives) {
+      const r = spawnSync('bash', [WRAPPER, ...drive.args], { env, encoding: 'utf8', timeout: 20000, input: drive.stdin });
+      assert.equal(r.status, 0, `${drive.label}: ${r.stderr}`);
+      assert.match(r.stdout, /FAKE_REPLY/, `${drive.label} never reached agy`);
+    }
+    rmSync(home, { recursive: true, force: true });
+  });
+});

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

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.6.1",
+  "version": "3.0.0",
   "provides": ["review", "probe"],
   "roles": {
     "review": {
@@ -14,13 +14,14 @@
       "output": "advisory",
       "contract": {
         "invocations": [
-          "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 \"…\"]"
         ],
-        "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)",
+        "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). 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",
         "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)"
         ],
@@ -28,7 +29,7 @@
           "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; 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/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",
+        "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; 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/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); 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); 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",
         "notes": [
           "pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt"
         ]
@@ -36,6 +37,166 @@
     },
     "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
   },
+  "modeCatalog": [
+    {
+      "key": "review.code",
+      "kind": "primary",
+      "role": "review",
+      "submode": "code",
+      "purpose": "Review the uncommitted working-tree change set against facts you supply.",
+      "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": 0 }],
+      "operands": [
+        { "slot": "[--facts @f]", "required": false, "description": "the verified facts to review AGAINST; code mode refuses pre-spend without a non-empty payload (escapes: --ungrounded, AGY_PROBE=1)" },
+        { "slot": "[--ungrounded]", "required": false, "description": "deliberately ungrounded code review — a throwaway opinion; the receipt records grounded:false and never attests" },
+        { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" },
+        { "slot": "[extra focus…]", "required": false, "description": "extra focus words appended to the review directive" }
+      ],
+      "guardrails": [
+        { "value": "read-only posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "receives no ambient repo/file context by default — the wrapper passes no --add-dir", "enforcement": "enforced", "source": "bin/agy-review.sh" },
+        { "value": "an ungrounded review guesses — stale-model and partial-diff false positives", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "without a non-empty --facts payload the run refuses BEFORE the spend (exit 2) — the only escapes are --ungrounded and AGY_PROBE=1", "enforcement": "enforced", "source": "bin/agy-review.sh" },
+        { "value": "an ungrounded run records grounded:false and the review-state gate rejects it", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" },
+        { "value": "an oversized prompt refuses rather than truncate", "enforcement": "enforced", "condition": "unless AGY_REVIEW_ALLOW_ADDDIR=1 offloads it to a private --add-dir staging dir", "source": "capability.json settings.AGY_REVIEW_ALLOW_ADDDIR" }
+      ],
+      "customHooks": ["AGY_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": 1 }],
+      "operands": [
+        { "slot": "<plan-file>", "required": true, "description": "the plan file under review" },
+        { "slot": "[--facts @f]", "required": false, "description": "the verified facts to review AGAINST; omitting it warns loudly and records the review ungrounded" },
+        { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" }
+      ],
+      "guardrails": [
+        { "value": "read-only posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "outside a git tree the receipt is skipped with a warning", "enforcement": "enforced", "condition": "unless AW_REVIEW_RECEIPTS names a destination", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "review.diff",
+      "kind": "primary",
+      "role": "review",
+      "submode": "diff",
+      "purpose": "Review a diff file you assembled yourself, rather than the live working tree.",
+      "whenToUse": [
+        "reviewing a diff that is not the current tree — a patch, a range, another branch",
+        "reviewing a change set trimmed to the hunks that matter"
+      ],
+      "whenNotTo": ["the current uncommitted tree — review.code assembles that for you"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 2 }],
+      "operands": [
+        { "slot": "<diff-file>", "required": true, "description": "the diff file under review" },
+        { "slot": "[--facts @f]", "required": false, "description": "the verified facts to review AGAINST; omitting it warns loudly and records the review ungrounded" },
+        { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" }
+      ],
+      "guardrails": [
+        { "value": "read-only posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "the receipt fingerprints the DIFF FILE, never the tree — it cannot attest the tree", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "review.continue",
+      "kind": "continuation",
+      "role": "review",
+      "purpose": "Send a round-2 delta into the review already open in this conversation.",
+      "whenToUse": [
+        "asking the same reviewer whether a fold really solves its own finding",
+        "a follow-up round that must not re-read the whole artifact"
+      ],
+      "whenNotTo": ["attesting a folded tree — a continuation records fresh:false and never satisfies the gate"],
+      "invocationRefs": [{ "contractField": "continue", "index": 0 }],
+      "operands": [
+        { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this round must look at (repeatable)" }
+      ],
+      "guardrails": [
+        { "value": "--facts is rejected on a continuation — the facts are already in the conversation", "enforcement": "enforced", "source": "bin/agy-review.sh" },
+        { "value": "a continuation receipt is fresh:false — informational only, never a gate pass", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "review.conversation",
+      "kind": "continuation",
+      "role": "review",
+      "purpose": "Resume a NAMED review conversation by its id, rather than the most recent one.",
+      "whenToUse": ["returning to a specific earlier review after other agy runs happened in between"],
+      "invocationRefs": [{ "contractField": "continue", "index": 1 }],
+      "operands": [
+        { "slot": "<id>", "required": true, "description": "the conversation id of the review to resume" },
+        { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this round must look at (repeatable)" }
+      ],
+      "guardrails": [
+        { "value": "a continuation receipt is fresh:false — informational only, never a gate pass", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "run",
+      "kind": "primary",
+      "role": "probe",
+      "purpose": "Send a raw advisory prompt to a selectable model and print the reply.",
+      "whenToUse": [
+        "a one-off question that needs no repo grounding",
+        "reaching a specific model (Gemini, Claude, GPT-OSS) from the terminal",
+        "a throwaway probe of the CLI, a model, or the wrapper plumbing"
+      ],
+      "whenNotTo": ["a code or plan review — agy-review owns the grounded posture and the receipt"],
+      "descriptor": "agy-run <prompt|-|@file> -- <extra agy flags...>",
+      "operands": [
+        { "slot": "<prompt|-|@file>", "required": true, "description": "the prompt text, - to read it from stdin, or @path to read it from a file" },
+        { "slot": "<extra agy flags...>", "required": false, "description": "raw agy flags passed straight through after --" }
+      ],
+      "guardrails": [
+        { "value": "subscription-only — every *_API_KEY env var is unset before the run", "enforcement": "enforced", "source": "bin/agy.sh" },
+        { "value": "any model is selectable via AGY_MODEL; the default is Gemini 3.1 Pro (High)", "enforcement": "advisory", "source": "bin/agy.sh" },
+        { "value": "hard wall-clock cap AGY_HARD_TIMEOUT (built-in default 5m)", "enforcement": "enforced", "condition": "only while timeout(1)/gtimeout is on PATH — otherwise the wrapper warns and runs uncapped", "source": "capability.json settings.AGY_HARD_TIMEOUT" },
+        { "value": "the prompt rides a single argv — over AGY_MAX_PROMPT_BYTES (120000) the run refuses", "enforcement": "enforced", "source": "bin/agy.sh" },
+        { "value": "no review posture, no grounding, no receipt — the reply is raw model output", "enforcement": "advisory", "source": "bin/agy.sh" }
+      ],
+      "customHooks": ["run"]
+    },
+    {
+      "key": "AGY_PROBE",
+      "kind": "env-hook",
+      "parents": ["review.code", "review.plan", "review.diff", "review.continue", "review.conversation"],
+      "purpose": "Silence the off-frontier model advisory for a THROWAWAY probe review.",
+      "whenToUse": [
+        "a probe whose answer cannot depend on the model",
+        "deliberately reviewing with a cheaper non-frontier model"
+      ],
+      "whenNotTo": ["any run whose output informs what ships — a probe never attests"],
+      "descriptor": "AGY_PROBE=1 agy-review code [--facts @<facts-file>]",
+      "operands": [
+        { "slot": "[--facts @<facts-file>]", "required": false, "description": "the verified facts the review runs AGAINST — a probe may run ungrounded (its receipt never attests either way)" }
+      ],
+      "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" }
+      ]
+    }
+  ],
   "settings": [
     {
       "key": "AGY_HARD_TIMEOUT",