@sabaiway/agent-workflow-kit 1.24.0 → 1.25.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.
 
+## 1.25.0 — The bridge driving contract at the point of use (advisor render + wrapper `--help`)
+
+A **feature** release (additive; ships the bundled bridges at **2.1.0**). An agent told to run a
+bridge no longer re-derives the invocation from wrapper source — where it missed documented levers
+(agy's `--facts`/`--decided` grounding, the `agy-review --continue` round-2 delta) and wasted
+subscription runs on ungrounded reviews. The contract is now **delivered at the moment a recipe
+dispatches a backend**, from ONE machine-readable source:
+
+- **Manifest as source.** Each bridge `capability.json` dispatchable role (`review`, `execute`) now
+  carries a structured `contract`: exact copy-pasteable **invocation descriptors** (operands and
+  alternatives included), the **grounding** note, the closed **flag** set (agy-review), the
+  **round-2 / resume** descriptors, and codex-exec's **tiered guarded passthrough**
+  (always-blocked vs `CODEX_PROBE=1`-relaxable). Documented in `tools/manifest/schema.md`.
+- **Advisor renders it at the point of use.** `/agent-workflow-kit procedures <activity>` prints,
+  under every dispatched backend of every slot (review recipes AND `execute=delegated`), the full
+  driving contract VERBATIM — e.g. council shows `agy-review code [--facts @f] [--decided @f] …`
+  plus the `agy-review --continue` delta beside `codex-review plan|code`. `--json` carries the same
+  in an **additive** `slots[*].contracts` field (`backends: string[]` unchanged).
+- **Every wrapper answers `--help`/`-h`** — pre-preflight (no CLI, no login, no git tree, no
+  AGENTS.md needed); keyed on the FIRST argument only, so an open wrapper's passthrough payload
+  (`codex-exec - -- --help`) is never intercepted. The three **dispatchable** wrappers
+  (`codex-review`, `agy-review`, `codex-exec`) print the manifest contract; `agy-run` (probe role —
+  never dispatched by a recipe slot) ships a lightweight wrapper-authored help, pinned for
+  pre-preflight reachability only, with no manifest pivot by design.
+- **Drift-guarded in both directions (test-as-spec), for the dispatchable wrappers.** The kit
+  registry mirror (`wrapperContractFor`) deep-equals each manifest; the advisor's rendered
+  descriptor set set-EQUALS the manifest (a missing AND a stale-extra descriptor both fail); each
+  dispatchable wrapper's `--help` set-EQUALS the manifest; and a **source-level reverse guard**
+  extracts each dispatchable wrapper's real parser arms (mode/flag/resume/passthrough-tier `case`
+  arms, heredocs excluded) and pins them to the manifest — adding a wrapper mode or flag without
+  updating the surfaced contract fails a test.
+- Stale "unguarded codex flags" wording in the codex bridge docs corrected to the real **guarded**
+  passthrough contract.
+
 ## 1.24.0 — Humanize the deploy/version report: hide the internal structure number in the happy path
 
 A **feature** release (report-contract only — no logic, migration, or lineage change; the

package/README.md

@@ -228,7 +228,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
-| `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a redirection/command-substitution residual remains, closed by a deferred hook); a direct commit/push/publish still asks. `--dry-run` first. |

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.24.0'
+  version: '1.25.0'
 ---
 
 # agent-workflow-kit
@@ -111,7 +111,7 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit recipes`** — read-only **orchestration advisor**: present the four recipes (Solo / Reviewed / Council / Delegated) over the bridges' role vocabulary, plan + recommend one for the current environment, and offer the choice. **The orchestrator executes the chosen recipe via the bridge skills and always commits** — the kit only surfaces/selects/plans it; it never executes a recipe, never runs a subscription CLI, never commits.
-- **`/agent-workflow-kit procedures <activity>`** — read-only **activity-procedures advisor**: print the ordered steps of a named activity (`plan-authoring` / `plan-execution`) read **live** from the installed engine (`references/procedures.md`), and the **resolved effective recipe per slot** from the per-project `docs/ai/orchestration.json` (strict JSON; agent-writable via `set-recipe` or hand-edit) + backend readiness (default = Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated; graceful default vs loud override degradation). A per-run `--override <slot>=<recipe>` overrides one slot. Composes with `recipes` (which stays read-only); never writes, never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit procedures <activity>`** — read-only **activity-procedures advisor**: print the ordered steps of a named activity (`plan-authoring` / `plan-execution`) read **live** from the installed engine (`references/procedures.md`), and the **resolved effective recipe per slot** from the per-project `docs/ai/orchestration.json` (strict JSON; agent-writable via `set-recipe` or hand-edit) + backend readiness (default = Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated; graceful default vs loud override degradation) — plus, for every dispatched backend, the **full driving contract at the point of use**: the exact copy-pasteable invocation descriptor(s), the grounding levers (agy `--facts`/`--decided`), the round-2 `--continue` delta, and the guarded passthrough tiers, rendered verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same contract). A per-run `--override <slot>=<recipe>` overrides one slot. Composes with `recipes` (which stays read-only); never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit set-recipe`** — the **config writer** for `docs/ai/orchestration.json`: turn the user's plain language into explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, merges, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe). Resolves the effective recipe vs live readiness (degradation honesty on both paths). **Writes only `docs/ai/orchestration.json`; never runs a backend, never commits.** Hand-editing the file stays fully supported.
 - **`/agent-workflow-kit uninstall`** — the **guarded teardown** companion to `init`/`setup`. Removes what they placed — installed skill dirs + the bridge wrappers — and, in a project, reverses the hidden-mode fence + the marker pre-commit hook. **Never deletes user-authored content**: it prints the exact `rm` for `docs/ai` / `AGENTS.md` and an **edit** for `.claude/settings.json` (the `includeCoAuthoredBy` key + any velocity `permissions.*`), for you to run by hand. `--dry-run` first, always; preflight-then-mutate; never commits.
 - **`/agent-workflow-kit velocity`** — opt-in onboarding **velocity profile**: seed a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. **Writes only `.claude/settings.json`, never allowlists commit/push/publish, never writes `settings.local.json`, never commits.** `--dry-run` first.

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.0.0'
+  version: '2.1.0'
 ---
 
 # antigravity-cli-bridge

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

@@ -44,6 +44,41 @@
 #                            staging dir and pass it via --add-dir (re-enables Issue-001 stall risk)
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no agy, no login, no git tree needed) ---------
+# Keyed ONLY on the FIRST argument — never a scan of all args (uniform rule across
+# the four wrappers). Drift-guarded against capability.json roles.review.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+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 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)
+  --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)
+
+Round-2 / resume:
+  agy-review --continue [--decided @f] [--focus "…"]
+  agy-review --conversation <id> [--decided @f] [--focus "…"]
+  (a continuation sends a small delta — agy holds the artifact server-side; --facts is invalid on a continuation)
+
+Closed grammar: unknown flags are rejected; no '--' passthrough (the only escapes are AGY_PROBE=1 and AGY_REVIEW_ALLOW_ADDDIR=1).
+Requires at run time: the agy CLI on PATH + a Google AI subscription login (--help needs neither).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_AGY_REVIEW_MODEL="Gemini 3.1 Pro (High)"
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"

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

@@ -439,3 +439,189 @@ describe('agy-review.sh — subdir invocation is repo-complete (13)', () => {
     assert.match(r.prompt, /SUBDIR_RELATIVE_FACT/, 'a relative --facts path resolves against the invocation cwd, before the cd');
   });
 });
+
+// ── driving contract: --help ⟷ manifest ⟷ real arg-parsing (drift-guarded) ─────
+// The manifest roles.review.contract is the single machine-readable source of the
+// driving contract; these suites pin (a) --help renders it verbatim (set-EQUALITY,
+// both directions), (b) the wrapper's REAL parser arms equal the declared sets
+// (source-level reverse guard), (c) each declared mode/flag is really accepted and
+// the CLOSED grammar really rejects an invented flag. Helpers are inline — each
+// bridge test file stays standalone (mirror byte-equality).
+
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+const REVIEW_CONTRACT = MANIFEST.roles.review.contract;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+const leadingFlag = (descriptor) => {
+  const m = norm(descriptor).match(/(^|\s)(--[a-z-]+)/);
+  assert.ok(m, `descriptor "${descriptor}" carries no --flag token`);
+  return m[2];
+};
+
+// Run `--help`/-h with PATH stripped of codex/agy/git, from a non-git cwd —
+// proving the short-circuit fires BEFORE every preflight.
+const runHelp = (arg) => {
+  const root = mkdtempSync(join(tmpdir(), 'agy-review-help-'));
+  const nongit = join(root, 'nongit');
+  mkdirSync(nongit, { recursive: true });
+  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const r = spawnSync('bash', [WRAPPER, arg], {
+    cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return r;
+};
+
+// The lines of a labelled --help section (header line → the next blank line).
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+// Source-level parser-arm extractor — the reverse drift guard. Scans ONLY `case`
+// statements whose SUBJECT is a CLI-argument variable (allowlisted), skipping
+// heredoc bodies (a heredoc may carry non-CLI `case` arms — e.g. codex-exec's
+// git-shim). Returns Map(subject → [raw arm label, …]) in source order.
+const ARG_SUBJECTS = new Set(['"$mode"', '"${1:-}"', '"$1"', '"$_arg"']);
+const extractArgCaseArms = (source) => {
+  const arms = new Map();
+  const stack = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (raw.trimStart().startsWith('#')) continue; // a comment line may carry a stray ')'
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    const cs = raw.match(/^\s*case\s+(\S+)\s+in\b/);
+    if (cs) { stack.push(cs[1]); continue; }
+    if (/^\s*esac\b/.test(raw)) { stack.pop(); continue; }
+    if (stack.length && ARG_SUBJECTS.has(stack[stack.length - 1])) {
+      const arm = raw.match(/^\s*([^)(\s][^)(]*)\)/);
+      if (arm) {
+        const subject = stack[stack.length - 1];
+        if (!arms.has(subject)) arms.set(subject, []);
+        arms.get(subject).push(arm[1].trim());
+      }
+    }
+  }
+  return arms;
+};
+const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
+
+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']) {
+      const r = runHelp(arg);
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.match(r.stdout, /Usage:/, `${arg} prints the contract to stdout`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+    }
+  });
+
+  it('Usage set-EQUALS the manifest invocation descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Usage:').filter((l) => l.startsWith('agy-review')).map(norm);
+    assert.ok(REVIEW_CONTRACT.invocations.length > 0, 'manifest invocations must be non-empty');
+    setEq(got, REVIEW_CONTRACT.invocations.map(norm), 'help Usage ⟷ manifest invocations');
+  });
+
+  it('Flags set-EQUALS the manifest flag descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Flags:').filter((l) => l.startsWith('--')).map(norm);
+    assert.ok(REVIEW_CONTRACT.flags.length > 0, 'manifest flags must be non-empty');
+    setEq(got, REVIEW_CONTRACT.flags.map(norm), 'help Flags ⟷ manifest flags');
+  });
+
+  it('Grounding renders the manifest grounding note verbatim', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Grounding:').join(' ')), norm(REVIEW_CONTRACT.grounding));
+  });
+
+  it('Round-2 / resume set-EQUALS the manifest continue descriptors', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Round-2 / resume:').filter((l) => l.startsWith('agy-review')).map(norm);
+    assert.ok(REVIEW_CONTRACT.continue.length > 0, 'manifest continue must be non-empty');
+    setEq(got, REVIEW_CONTRACT.continue.map(norm), 'help continue ⟷ manifest continue');
+  });
+});
+
+describe('agy-review.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
+  const arms = extractArgCaseArms(readFileSync(WRAPPER, 'utf8'));
+
+  it('the real mode arms equal the manifest modes (adding a mode without the manifest fails here)', () => {
+    // Deliberately a UNION over every `case "$mode"` in the wrapper (the CLI dispatch AND the
+    // emit_artifact renderer): the union can only be conservative — a mode added to EITHER case
+    // without the manifest goes red; no renderer-only arm can make a missing manifest entry green.
+    const modes = splitArms(arms.get('"$mode"')).filter((a) => a !== '*');
+    assert.ok(MANIFEST.roles.review.modes.length > 0, 'manifest modes must be non-empty');
+    setEq(new Set(modes), MANIFEST.roles.review.modes, 'parser mode arms ⟷ manifest modes');
+  });
+
+  it('the real flag arms equal the manifest flag set (closed grammar; catch-alls excluded)', () => {
+    const flagArms = splitArms(arms.get('"$1"')).filter((a) => !['--', '--*', '*'].includes(a));
+    const declared = REVIEW_CONTRACT.flags.map(leadingFlag);
+    assert.ok(declared.length > 0, 'manifest flag set must be non-empty');
+    setEq(new Set(flagArms), new Set(declared), 'parser flag arms ⟷ manifest flags');
+  });
+
+  it('the first-arg entrypoints are exactly --help/-h + the manifest continue flags', () => {
+    const declared = REVIEW_CONTRACT.continue.map(leadingFlag);
+    assert.ok(declared.length > 0, 'manifest continue set must be non-empty');
+    setEq(new Set(splitArms(arms.get('"${1:-}"'))), new Set(['--help', '-h', ...declared]));
+  });
+});
+
+describe('agy-review.sh — declared contract is really accepted (forward guard)', () => {
+  it('every manifest mode runs green', () => {
+    const drive = {
+      code: () => ['code', '--facts', 'f'],
+      plan: (sb) => { writeFileSync(join(sb.repo, 'p.md'), '# p\n'); return ['plan', 'p.md', '--facts', 'f']; },
+      diff: (sb) => { writeFileSync(join(sb.repo, 'c.diff'), 'diff body\n'); return ['diff', 'c.diff', '--facts', 'f']; },
+    };
+    for (const mode of MANIFEST.roles.review.modes) {
+      assert.ok(drive[mode], `no test drive for manifest mode "${mode}" — add one`);
+      const sb = makeSandbox();
+      const r = run(sb, { args: drive[mode](sb) });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `mode ${mode}: ${r.stderr}`);
+      assert.equal(r.invoked, true, `mode ${mode} must reach agy`);
+    }
+  });
+
+  it('every manifest flag is accepted in code mode', () => {
+    for (const descriptor of REVIEW_CONTRACT.flags) {
+      const flag = leadingFlag(descriptor);
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', flag, 'f'] });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `${flag}: ${r.stderr}`);
+    }
+  });
+
+  it('an invented flag is rejected (closed grammar negative)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f', '--bogus-flag'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /unknown flag '--bogus-flag'/);
+    assert.equal(r.invoked, false, 'an unknown flag must not spend a run');
+  });
+
+  it('--help NOT in first position is an unknown flag, never an intercepted help', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f', '--help'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2, 'help is keyed on the FIRST argument only');
+    assert.doesNotMatch(r.stdout, /Usage:/);
+  });
+});

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

@@ -34,6 +34,29 @@
 #                                            # passthrough agy flags (future flows)
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no agy, no login needed) ----------------------
+# Keyed ONLY on the FIRST argument — never a scan of all args, else a passthrough
+# payload like `agy-run "prompt" -- --help` would be intercepted. agy-run is the
+# probe role (not dispatched by any activity slot), so this help is authored here
+# — not manifest-pinned (candidate C only).
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+agy-run — thin, flow-agnostic wrapper around Google's Antigravity CLI (agy; subscription-only, hard wall-clock cap).
+
+Usage:
+  agy-run "your prompt"
+  echo "your prompt" | agy-run -
+  agy-run @path/to/prompt.md
+  agy-run <prompt|-|@file> -- <extra agy flags...>
+
+Environment: AGY_MODEL (exact display string from `agy models`; empty ⇒ agy's settings.json), AGY_TIMEOUT / AGY_HARD_TIMEOUT (duration strings), AGY_MAX_PROMPT_BYTES (single-argv byte ceiling; the override only lowers it).
+Requires at run time: the agy CLI on PATH + a Google AI subscription login (--help needs neither).
+HELP
+    exit 0
+    ;;
+esac
+
 # 1. Make `agy` findable even when ~/.bashrc was not sourced.
 export PATH="$HOME/.local/bin:$PATH"
 

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

@@ -1,8 +1,8 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, existsSync, readdirSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
@@ -152,3 +152,59 @@ describe('agy.sh — argv byte-ceiling guard (AGY_MAX_PROMPT_BYTES)', () => {
     assert.equal(invoked, false, 'raising the ceiling past the OS limit must fail loud, not pass through to E2BIG');
   });
 });
+
+// ── --help (candidate C only — the probe role is not dispatched by any activity
+// slot, so this help is authored in the wrapper, NOT manifest-pinned; the lighter
+// guard pins pre-preflight reachability + the documented usage forms). ──────────
+
+// A PATH farm mirroring the real one MINUS the named binaries — so the reachability claim
+// ("--help needs no agy/git") holds even on a host that has the real CLIs installed.
+// Ported from agy-review.test.mjs (inline: each bridge test file stays standalone).
+const makePathWithout = (root, exclude = []) => {
+  const skip = new Set(exclude);
+  const dir = mkdtempSync(join(root, 'nobin-'));
+  for (const d of (process.env.PATH || '').split(':').filter(Boolean)) {
+    let names;
+    try { names = readdirSync(d); } catch { continue; }
+    for (const name of names) {
+      if (skip.has(name)) continue;
+      const link = join(dir, name);
+      if (existsSync(link)) continue;
+      try { symlinkSync(resolve(d, name), link); } catch { /* dup / race — ignore */ }
+    }
+  }
+  return dir;
+};
+
+describe('agy.sh — --help (pre-preflight, candidate C)', () => {
+  it('--help and -h exit 0 with NO agy on PATH and name the documented usage', () => {
+    for (const arg of ['--help', '-h']) {
+      // A bare HOME with no ~/.local/bin/agy stub AND a PATH farm stripped of agy/git —
+      // the help must not need the CLI even when the host has a real agy installed.
+      const home = mkdtempSync(join(tmpdir(), 'agy-help-'));
+      const r = spawnSync('bash', [WRAPPER, arg], {
+        env: { HOME: home, PATH: makePathWithout(home, ['agy', 'git']) },
+        encoding: 'utf8',
+        timeout: 15000,
+      });
+      rmSync(home, { recursive: true, force: true });
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+      assert.match(r.stdout, /Usage:/);
+      assert.match(r.stdout, /agy-run "your prompt"/);
+      assert.match(r.stdout, /agy-run @path\/to\/prompt\.md/);
+      assert.match(r.stdout, /agy-run <prompt\|-\|@file> -- <extra agy flags\.\.\.>/);
+    }
+  });
+
+  it('--help after the -- separator is passthrough payload, never intercepted', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    const sentinel = join(home, 'sentinel');
+    const r = runArgs(home, { args: ['prompt', '--', '--help'], env: { AGY_STUB_SENTINEL: sentinel } });
+    const invoked = existsSync(sentinel);
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stdout, /Usage:/, 'help is keyed on the FIRST argument only');
+    assert.equal(invoked, true, 'the run must proceed to agy with the payload');
+  });
+});

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

@@ -3,10 +3,33 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "provides": ["review", "probe"],
   "roles": {
-    "review": { "cmd": "agy-review", "source": "bin/agy-review.sh", "template": "references/review-prompt.md", "modes": ["code", "plan", "diff"], "output": "advisory" },
+    "review": {
+      "cmd": "agy-review",
+      "source": "bin/agy-review.sh",
+      "template": "references/review-prompt.md",
+      "modes": ["code", "plan", "diff"],
+      "output": "advisory",
+      "contract": {
+        "invocations": [
+          "agy-review code [--facts @f] [--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)",
+        "flags": [
+          "--facts @f — verified facts the review runs AGAINST (omit ⇒ loud ungrounded-review warning)",
+          "--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)"
+        ],
+        "continue": [
+          "agy-review --continue [--decided @f] [--focus \"…\"]",
+          "agy-review --conversation <id> [--decided @f] [--focus \"…\"]"
+        ]
+      }
+    },
     "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
   },
   "detect": {

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.0.0'
+  version: '2.1.0'
 ---
 
 # codex-cli-bridge
@@ -77,7 +77,7 @@ Drive codex only through the two wrappers (installed on `PATH`), run from the ta
 # EXECUTION (workspace-write sandbox, network OFF, never prompts):
 codex-exec docs/plans/<slug>.md                 # drive a plan file
 echo "apply review fix: ..." | codex-exec -      # ad-hoc instruction from stdin
-codex-exec <file|-> -- <unguarded codex flags...> # passthrough codex flags after `--` (guarded ones rejected)
+codex-exec <file|-> -- <extra codex flags...>     # GUARDED passthrough after `--` (policy/model/capture flags rejected; some relaxed only under CODEX_PROBE=1)
 
 # RESUME (iterate on the SAME session without re-sending context):
 codex-exec --resume-last docs/plans/<slug>.md    # continue the last session (id from the sidecar)

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

@@ -40,6 +40,40 @@
 #   CODEX_PROBE=1 CODEX_MODEL=<slug> codex-exec <file>   # throwaway probe (relaxes the guard)
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no codex, no login, no git tree needed) -------
+# Keyed ONLY on the FIRST argument — never a scan of all args, else a passthrough
+# payload like `codex-exec f - -- --help` would be intercepted.
+# The contract below is drift-guarded against capability.json roles.execute.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+codex-exec — delegate plan/instruction EXECUTION to the OpenAI Codex CLI (subscription-only; workspace-write sandbox, network OFF, git writes blocked — the orchestrator commits).
+
+Usage:
+  codex-exec <plan-file|->
+  codex-exec <plan-file|-> -- <extra codex flags...>
+
+Grounding:
+  automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's
+  context and the wrapper prepends the orchestrator execution contract; no
+  grounding flags
+
+Round-2 / resume:
+  codex-exec --resume-last <plan-file|->
+  codex-exec --resume <session-id> <plan-file|->
+  (resume continues the recorded session without re-sending context; takes no '--' passthrough)
+
+Guarded passthrough after '--':
+  blocked always: -c* --config* -s* --sandbox* --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust --full-auto --oss --local-provider* -p* --profile* -m* --model* -o* --output-last-message* --json* --color* --output-schema* --ephemeral*
+  relaxed only under CODEX_PROBE=1: --add-dir* -C* --cd* --skip-git-repo-check --ignore-rules --enable* --disable*
+
+Environment: CODEX_HARD_TIMEOUT (seconds, default 3600), CODEX_PROBE=1 (throwaway probe only).
+Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_CODEX_MODEL="gpt-5.5"   # frontier coding model (verified locally) — pinned
 DEFAULT_CODEX_EFFORT="xhigh"    # maximum reasoning effort — pinned
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"

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

@@ -149,7 +149,8 @@ describe('codex-exec.sh — quality-first model/effort guard (1.1)', () => {
 // capture flags: rejected ALWAYS, even under CODEX_PROBE=1.
 const ALWAYS_BLOCKED = [
   ['-s', 'read-only'], ['--sandbox', 'danger-full-access'], ['-c', 'k=v'], ['--config', 'k=v'],
-  ['--full-auto'], ['--dangerously-bypass-approvals-and-sandbox'], ['--oss'], ['--local-provider', 'x'],
+  ['--full-auto'], ['--dangerously-bypass-approvals-and-sandbox'], ['--dangerously-bypass-hook-trust'],
+  ['--oss'], ['--local-provider', 'x'],
   ['-p', 'prof'], ['--profile', 'prof'], ['-m', 'gpt-5.5'], ['--model', 'gpt-5.5'],
   ['-o', '/x'], ['--output-last-message', '/x'], ['--json'], ['--color', 'always'],
   ['--output-schema', '/x'], ['--ephemeral'],
@@ -591,3 +592,161 @@ describe('codex-exec.sh — session id absent', () => {
     assert.match(r.stdout, /FAKE_FINAL_MESSAGE/, 'the run still succeeds');
   });
 });
+
+// ── driving contract: --help ⟷ manifest ⟷ real arg-parsing (drift-guarded) ─────
+// The manifest roles.execute.contract is the single machine-readable source of the
+// driving contract; these suites pin (a) --help renders it verbatim (set-EQUALITY,
+// both directions, incl. the TIERED guarded-passthrough sets), (b) the wrapper's
+// REAL parser arms equal the declared sets (source-level reverse guard — the
+// git-shim heredoc's own `case` arms are NOT CLI modes and must be skipped).
+// Helpers are inline — each bridge test file stays standalone (mirror byte-equality).
+
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+const EXEC_CONTRACT = MANIFEST.roles.execute.contract;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+const leadingFlag = (descriptor) => {
+  const m = norm(descriptor).match(/(^|\s)(--[a-z-]+)/);
+  assert.ok(m, `descriptor "${descriptor}" carries no --flag token`);
+  return m[2];
+};
+
+// Run `--help`/-h with PATH stripped of codex/agy/git, from a non-git cwd with no
+// AGENTS.md — proving the short-circuit fires BEFORE every preflight.
+const runHelp = (arg) => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-exec-help-'));
+  const nongit = join(root, 'nongit');
+  mkdirSync(nongit, { recursive: true });
+  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const r = spawnSync('bash', [WRAPPER, arg], {
+    cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return r;
+};
+
+// The lines of a labelled --help section (header line → the next blank line).
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+// Source-level parser-arm extractor — the reverse drift guard. Scans ONLY `case`
+// statements whose SUBJECT is a CLI-argument variable (allowlisted), skipping
+// heredoc bodies (codex-exec's git-shim heredoc carries its own `case "$verb"`
+// git-verb arms that are NOT CLI modes). Returns Map(subject → [raw arm label, …]).
+const ARG_SUBJECTS = new Set(['"$mode"', '"${1:-}"', '"$1"', '"$_arg"']);
+const extractArgCaseArms = (source) => {
+  const arms = new Map();
+  const stack = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (raw.trimStart().startsWith('#')) continue; // a comment line may carry a stray ')'
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    const cs = raw.match(/^\s*case\s+(\S+)\s+in\b/);
+    if (cs) { stack.push(cs[1]); continue; }
+    if (/^\s*esac\b/.test(raw)) { stack.pop(); continue; }
+    if (stack.length && ARG_SUBJECTS.has(stack[stack.length - 1])) {
+      const arm = raw.match(/^\s*([^)(\s][^)(]*)\)/);
+      if (arm) {
+        const subject = stack[stack.length - 1];
+        if (!arms.has(subject)) arms.set(subject, []);
+        arms.get(subject).push(arm[1].trim());
+      }
+    }
+  }
+  return arms;
+};
+const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
+
+describe('codex-exec.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']) {
+      const r = runHelp(arg);
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.match(r.stdout, /Usage:/, `${arg} prints the contract to stdout`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+    }
+  });
+
+  it('Usage set-EQUALS the manifest invocation descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Usage:').filter((l) => l.startsWith('codex-exec')).map(norm);
+    assert.ok(EXEC_CONTRACT.invocations.length > 0, 'manifest invocations must be non-empty');
+    setEq(got, EXEC_CONTRACT.invocations.map(norm), 'help Usage ⟷ manifest invocations');
+  });
+
+  it('Grounding renders the manifest grounding note verbatim', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Grounding:').join(' ')), norm(EXEC_CONTRACT.grounding));
+  });
+
+  it('Round-2 / resume set-EQUALS the manifest continue descriptors', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Round-2 / resume:').filter((l) => l.startsWith('codex-exec')).map(norm);
+    assert.ok(EXEC_CONTRACT.continue.length > 0, 'manifest continue must be non-empty');
+    setEq(got, EXEC_CONTRACT.continue.map(norm), 'help continue ⟷ manifest continue');
+  });
+
+  it('the guarded-passthrough TIERS set-EQUAL the manifest tiers (never a flat set)', () => {
+    const help = runHelp('--help').stdout;
+    const section = helpSection(help, "Guarded passthrough after '--':");
+    const tier = (prefix) => {
+      const line = section.find((l) => l.startsWith(prefix));
+      assert.ok(line, `passthrough section must carry a "${prefix}" line`);
+      return line.slice(prefix.length).trim().split(/\s+/);
+    };
+    assert.ok(EXEC_CONTRACT.passthrough.blocked.length > 0, 'manifest blocked tier must be non-empty');
+    assert.ok(EXEC_CONTRACT.passthrough.probeRelaxed.length > 0, 'manifest probe tier must be non-empty');
+    setEq(tier('blocked always:'), EXEC_CONTRACT.passthrough.blocked, 'help tier-1 ⟷ manifest blocked');
+    setEq(tier('relaxed only under CODEX_PROBE=1:'), EXEC_CONTRACT.passthrough.probeRelaxed, 'help tier-2 ⟷ manifest probeRelaxed');
+  });
+
+  it('--help after the -- separator is passthrough payload, never intercepted', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['-', '--', '--help'], input: 'go' });
+    rmSync(sb.root, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stdout, /Usage:/, 'help is keyed on the FIRST argument only');
+    assert.match(r.argv, /(^|\n)--help(\n|$)/, 'the payload --help reaches codex argv');
+  });
+});
+
+describe('codex-exec.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
+  const arms = extractArgCaseArms(readFileSync(WRAPPER, 'utf8'));
+
+  it('the first-arg entrypoints are exactly --help/-h + the manifest resume flags', () => {
+    const declared = EXEC_CONTRACT.continue.map(leadingFlag);
+    assert.ok(declared.length > 0, 'manifest resume set must be non-empty');
+    setEq(new Set(splitArms(arms.get('"${1:-}"'))), new Set(['--help', '-h', ...declared]));
+  });
+
+  it('the real passthrough tier arms equal the manifest tiers (git-shim heredoc excluded)', () => {
+    const tierArms = arms.get('"$_arg"') ?? [];
+    assert.equal(tierArms.length, 2, 'exactly two passthrough tiers: always-blocked, probe-relaxed');
+    setEq(tierArms[0].split('|'), EXEC_CONTRACT.passthrough.blocked, 'tier-1 arm ⟷ manifest blocked');
+    setEq(tierArms[1].split('|'), EXEC_CONTRACT.passthrough.probeRelaxed, 'tier-2 arm ⟷ manifest probeRelaxed');
+  });
+
+  it('the in-test tier samples cover every manifest tier pattern (behavioural forward guard)', () => {
+    // ALWAYS_BLOCKED / PROBE_RELAXABLE drive the real behaviour suite above; pin them
+    // to the manifest so a tier edit cannot leave the behavioural samples stale.
+    const sample = (patterns) => patterns.map((p) => p.replace(/\*$/, ''));
+    const covered = (flags, patterns) =>
+      sample(patterns).every((p) => flags.some(([f]) => f === p || f.startsWith(p)));
+    assert.ok(covered(ALWAYS_BLOCKED, EXEC_CONTRACT.passthrough.blocked), 'every blocked pattern has a behavioural sample');
+    assert.ok(covered(PROBE_RELAXABLE, EXEC_CONTRACT.passthrough.probeRelaxed), 'every probe pattern has a behavioural sample');
+  });
+});

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

@@ -31,6 +31,34 @@
 # on disk remain readable under read-only — read-scoping is a prompt concern).
 set -euo pipefail
 
+# --- --help / -h (pre-preflight: no codex, no login, no git tree needed) -------
+# Keyed ONLY on the FIRST argument — never a scan of all args (uniform rule across
+# the four wrappers, so an open wrapper's passthrough payload is never intercepted).
+# The contract below is drift-guarded against capability.json roles.review.contract.
+case "${1:-}" in
+  --help|-h)
+    cat <<'HELP'
+codex-review — read-only ADVISORY review by the OpenAI Codex CLI (subscription-only; frontier model at max effort).
+
+Usage:
+  codex-review plan <plan-file>
+  codex-review code [extra focus...]
+
+Grounding:
+  automatic — the wrapper precomputes the full working-tree change set (repo map,
+  status, diffs, untracked contents) and codex auto-merges the root AGENTS.md;
+  no grounding flags
+
+Round-2 / resume:
+  (none — one-shot; a follow-up review is a fresh run)
+
+Environment: CODEX_REVIEW_SCHEMA=1 (structured JSON findings), CODEX_HARD_TIMEOUT (seconds, default 1800), CODEX_PROBE=1 (throwaway probe only).
+Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
+HELP
+    exit 0
+    ;;
+esac
+
 DEFAULT_CODEX_MODEL="gpt-5.5"
 DEFAULT_CODEX_EFFORT="xhigh"
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"

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

@@ -540,3 +540,130 @@ describe('codex-review.sh — assemble & output edge cases', () => {
     assert.match(r.stdout, /FAKE_FINAL_MESSAGE/);
   });
 });
+
+// ── driving contract: --help ⟷ manifest ⟷ real arg-parsing (drift-guarded) ─────
+// The manifest roles.review.contract is the single machine-readable source of the
+// driving contract; these suites pin (a) --help renders it verbatim (set-EQUALITY,
+// both directions), (b) the wrapper's REAL parser arms equal the declared sets
+// (source-level reverse guard), (c) each declared mode is really accepted.
+// Helpers are inline — each bridge test file stays standalone (mirror byte-equality).
+
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+const REVIEW_CONTRACT = MANIFEST.roles.review.contract;
+const norm = (s) => s.replace(/\s+/g, ' ').trim();
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+
+// Run `--help`/-h with PATH stripped of codex/agy/git, from a non-git cwd with no
+// AGENTS.md — proving the short-circuit fires BEFORE every preflight.
+const runHelp = (arg) => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-review-help-'));
+  const nongit = join(root, 'nongit');
+  mkdirSync(nongit, { recursive: true });
+  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const r = spawnSync('bash', [WRAPPER, arg], {
+    cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
+  });
+  rmSync(root, { recursive: true, force: true });
+  return r;
+};
+
+// The lines of a labelled --help section (header line → the next blank line).
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+// Source-level parser-arm extractor — the reverse drift guard. Scans ONLY `case`
+// statements whose SUBJECT is a CLI-argument variable (allowlisted), skipping
+// heredoc bodies (a heredoc may carry non-CLI `case` arms — e.g. codex-exec's
+// git-shim). Returns Map(subject → [raw arm label, …]) in source order.
+const ARG_SUBJECTS = new Set(['"$mode"', '"${1:-}"', '"$1"', '"$_arg"']);
+const extractArgCaseArms = (source) => {
+  const arms = new Map();
+  const stack = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    if (raw.trimStart().startsWith('#')) continue; // a comment line may carry a stray ')'
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    const cs = raw.match(/^\s*case\s+(\S+)\s+in\b/);
+    if (cs) { stack.push(cs[1]); continue; }
+    if (/^\s*esac\b/.test(raw)) { stack.pop(); continue; }
+    if (stack.length && ARG_SUBJECTS.has(stack[stack.length - 1])) {
+      const arm = raw.match(/^\s*([^)(\s][^)(]*)\)/);
+      if (arm) {
+        const subject = stack[stack.length - 1];
+        if (!arms.has(subject)) arms.set(subject, []);
+        arms.get(subject).push(arm[1].trim());
+      }
+    }
+  }
+  return arms;
+};
+const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
+
+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']) {
+      const r = runHelp(arg);
+      assert.equal(r.status, 0, `${arg}: ${r.stderr}`);
+      assert.match(r.stdout, /Usage:/, `${arg} prints the contract to stdout`);
+      assert.equal(r.stderr, '', `${arg} prints nothing to stderr`);
+    }
+  });
+
+  it('Usage set-EQUALS the manifest invocation descriptors (both directions)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Usage:').filter((l) => l.startsWith('codex-review')).map(norm);
+    assert.ok(REVIEW_CONTRACT.invocations.length > 0, 'manifest invocations must be non-empty');
+    setEq(got, REVIEW_CONTRACT.invocations.map(norm), 'help Usage ⟷ manifest invocations');
+  });
+
+  it('Grounding renders the manifest grounding note verbatim', () => {
+    const help = runHelp('--help').stdout;
+    assert.equal(norm(helpSection(help, 'Grounding:').join(' ')), norm(REVIEW_CONTRACT.grounding));
+  });
+
+  it('Round-2 / resume set-EQUALS the manifest continue descriptors (empty — one-shot)', () => {
+    const help = runHelp('--help').stdout;
+    const got = helpSection(help, 'Round-2 / resume:').filter((l) => l.startsWith('codex-review')).map(norm);
+    setEq(got, (REVIEW_CONTRACT.continue ?? []).map(norm), 'help continue ⟷ manifest continue');
+    assert.deepEqual(REVIEW_CONTRACT.continue, [], 'codex-review is one-shot — no continue descriptor');
+  });
+});
+
+describe('codex-review.sh — source-level reverse guard (parser arms ⟷ manifest)', () => {
+  const arms = extractArgCaseArms(readFileSync(WRAPPER, 'utf8'));
+
+  it('the real mode arms equal the manifest modes (adding a mode without the manifest fails here)', () => {
+    const modes = splitArms(arms.get('"$mode"')).filter((a) => a !== '*');
+    assert.ok(MANIFEST.roles.review.modes.length > 0, 'manifest modes must be non-empty');
+    setEq(new Set(modes), MANIFEST.roles.review.modes, 'parser mode arms ⟷ manifest modes');
+  });
+
+  it('the first-arg entrypoints are exactly --help/-h (no undeclared resume/flag entrypoint)', () => {
+    setEq(new Set(splitArms(arms.get('"${1:-}"'))), ['--help', '-h']);
+  });
+
+  it('every manifest mode is really accepted (forward guard)', () => {
+    const drive = { plan: ['plan', 'plan.md'], code: ['code'] };
+    for (const mode of MANIFEST.roles.review.modes) {
+      assert.ok(drive[mode], `no test drive for manifest mode "${mode}" — add one`);
+      const sb = makeSandbox();
+      const r = run(sb, { args: drive[mode] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, `mode ${mode}: ${r.stderr}`);
+    }
+  });
+});

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

@@ -3,11 +3,44 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "provides": ["execute", "review"],
   "roles": {
-    "execute": { "cmd": "codex-exec", "source": "bin/codex-exec.sh", "output": "diff" },
-    "review": { "cmd": "codex-review", "source": "bin/codex-review.sh", "modes": ["plan", "code"], "output": "advisory" }
+    "execute": {
+      "cmd": "codex-exec",
+      "source": "bin/codex-exec.sh",
+      "output": "diff",
+      "contract": {
+        "invocations": [
+          "codex-exec <plan-file|->",
+          "codex-exec <plan-file|-> -- <extra codex flags...>"
+        ],
+        "grounding": "automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's context and the wrapper prepends the orchestrator execution contract; no grounding flags",
+        "continue": [
+          "codex-exec --resume-last <plan-file|->",
+          "codex-exec --resume <session-id> <plan-file|->"
+        ],
+        "passthrough": {
+          "policy": "guarded",
+          "blocked": ["-c*", "--config*", "-s*", "--sandbox*", "--dangerously-bypass-approvals-and-sandbox", "--dangerously-bypass-hook-trust", "--full-auto", "--oss", "--local-provider*", "-p*", "--profile*", "-m*", "--model*", "-o*", "--output-last-message*", "--json*", "--color*", "--output-schema*", "--ephemeral*"],
+          "probeRelaxed": ["--add-dir*", "-C*", "--cd*", "--skip-git-repo-check", "--ignore-rules", "--enable*", "--disable*"]
+        }
+      }
+    },
+    "review": {
+      "cmd": "codex-review",
+      "source": "bin/codex-review.sh",
+      "modes": ["plan", "code"],
+      "output": "advisory",
+      "contract": {
+        "invocations": [
+          "codex-review plan <plan-file>",
+          "codex-review code [extra focus...]"
+        ],
+        "grounding": "automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags",
+        "continue": []
+      }
+    }
   },
   "detect": {
     "installed": {

package/bridges/codex-cli-bridge/references/driving-codex.md

@@ -50,7 +50,7 @@ object (raw-text fallback on failure).
 ```bash
 codex-exec docs/plans/<slug>.md                  # drive a plan file
 echo "apply review fix: tighten the guard in X, keep tests green" | codex-exec -
-codex-exec <file|-> -- <unguarded codex flags>   # passthrough AFTER `--` (policy/model/capture flags are rejected)
+codex-exec <file|-> -- <extra codex flags>       # GUARDED passthrough AFTER `--` (policy/model/capture flags rejected; some relaxed only under CODEX_PROBE=1)
 
 codex-exec --resume-last docs/plans/<slug>.md    # continue the last session, no re-send
 echo "now do step 2" | codex-exec --resume <id> -

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/tools/commands.mjs

@@ -113,7 +113,7 @@ const CATALOG = [
     invocation: invocationOf('procedures'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'Show a named activity’s steps and which recipe applies at each stage here.',
+    oneLine: 'Show a named activity’s steps, the recipe per stage, and each dispatched backend’s exact driving contract (invocation + grounding + round-2 delta).',
   },
   {
     key: 'set-recipe',

package/tools/detect-backends.mjs

@@ -60,6 +60,36 @@ const RAW_BACKENDS = [
     name: 'codex-cli-bridge',
     installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
     roleCmds: { execute: 'codex-exec', review: 'codex-review' },
+    // The per-role DRIVING CONTRACT (exact invocation descriptors + grounding + round-2 continue),
+    // mirroring the bridge manifest roles[role].contract byte-for-byte — drift-guarded like roleCmds.
+    // Scope = dispatchable recipe roles ONLY (review, execute): the probe role is never dispatched by
+    // an activity slot, so it carries NO contract here (wrapperContractFor(_, 'probe') → null).
+    roleContracts: {
+      execute: {
+        invocations: [
+          'codex-exec <plan-file|->',
+          'codex-exec <plan-file|-> -- <extra codex flags...>',
+        ],
+        grounding: "automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's context and the wrapper prepends the orchestrator execution contract; no grounding flags",
+        continue: [
+          'codex-exec --resume-last <plan-file|->',
+          'codex-exec --resume <session-id> <plan-file|->',
+        ],
+        passthrough: {
+          policy: 'guarded',
+          blocked: ['-c*', '--config*', '-s*', '--sandbox*', '--dangerously-bypass-approvals-and-sandbox', '--dangerously-bypass-hook-trust', '--full-auto', '--oss', '--local-provider*', '-p*', '--profile*', '-m*', '--model*', '-o*', '--output-last-message*', '--json*', '--color*', '--output-schema*', '--ephemeral*'],
+          probeRelaxed: ['--add-dir*', '-C*', '--cd*', '--skip-git-repo-check', '--ignore-rules', '--enable*', '--disable*'],
+        },
+      },
+      review: {
+        invocations: [
+          'codex-review plan <plan-file>',
+          'codex-review code [extra focus...]',
+        ],
+        grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
+        continue: [],
+      },
+    },
     bin: 'codex',
     credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
@@ -72,6 +102,26 @@ const RAW_BACKENDS = [
     name: 'antigravity-cli-bridge',
     installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
     roleCmds: { review: 'agy-review', probe: 'agy-run' },
+    // Mirror of the manifest roles.review.contract (see the codex entry note). probe: NO contract.
+    roleContracts: {
+      review: {
+        invocations: [
+          'agy-review code [--facts @f] [--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)',
+        flags: [
+          '--facts @f — verified facts the review runs AGAINST (omit ⇒ loud ungrounded-review warning)',
+          '--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)',
+        ],
+        continue: [
+          'agy-review --continue [--decided @f] [--focus "…"]',
+          'agy-review --conversation <id> [--decided @f] [--focus "…"]',
+        ],
+      },
+    },
     bin: 'agy',
     credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
@@ -91,6 +141,15 @@ export const KNOWN_BACKENDS = RAW_BACKENDS.map((entry) => ({ ...entry, wrapperCm
 export const wrapperCmdFor = (backendName, role) =>
   KNOWN_BACKENDS.find((b) => b.name === backendName)?.roleCmds?.[role] ?? null;
 
+// Resolve a dispatched (backend, role) to its structured DRIVING CONTRACT — the registry mirror of
+// the bridge manifest roles[role].contract: exact invocation descriptor(s), the grounding note, the
+// closed flag set (when the wrapper's grammar is closed), the round-2/continue descriptor(s), and
+// the guarded passthrough tiers (codex-exec). The point-of-use advisor (procedures.mjs) renders this
+// VERBATIM so a driving agent never re-derives the contract from wrapper source. `null` when the
+// pair is unknown or the role carries no contract (probe — never dispatched by an activity slot).
+export const wrapperContractFor = (backendName, role) =>
+  KNOWN_BACKENDS.find((b) => b.name === backendName)?.roleContracts?.[role] ?? null;
+
 // ── pure helpers ─────────────────────────────────────────────────────────────
 
 // Expand a leading "~" / "~/x" against home; absolute and relative paths pass through untouched.

package/tools/manifest/schema.md

@@ -38,6 +38,21 @@ Each `roles.<role>` is an object:
 - `template` (string, optional) — an in-skill prompt/template path (e.g.
   `references/review-prompt.md`); repo-relative, **must exist**.
 - `modes`, `output` (optional) — e.g. `["plan","code"]`, `"advisory"`.
+- `contract` (object, optional; execution-backend bridges) — the machine-readable **driving
+  contract** for a dispatchable recipe role (`review` / `execute`; the `probe` role carries none).
+  Rides as a validator-tolerated extra field (format-checked by the bridge/kit drift-guard tests,
+  not by `validate.mjs`), and is the single source the point-of-use advisor
+  (`/agent-workflow-kit procedures`) and each wrapper's `--help` render verbatim:
+  - `invocations` (string[], non-empty) — exact copy-pasteable invocation descriptors, one per
+    mode/variant, incl. operand placeholders (`<plan-file>`, `[extra focus...]`).
+  - `grounding` (string) — the grounding note (e.g. agy's `--facts @f` / `--decided @f` levers, or
+    "automatic — …" when the wrapper grounds itself).
+  - `flags` (string[], optional) — the closed per-mode flag descriptor set (closed-grammar
+    wrappers only).
+  - `continue` (string[]) — round-2 / resume invocation descriptors; `[]` when one-shot.
+  - `passthrough` (object, optional) — the guarded `--` passthrough tiers:
+    `{ policy: "guarded", blocked: string[], probeRelaxed: string[] }`, matching the wrapper's
+    real case-arm patterns (pinned by the source-level reverse-guard test).
 
 ## Path-field rules (Windows-safe, traversal-safe)
 

package/tools/procedures.mjs

@@ -19,7 +19,7 @@
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
-import { detectBackends, wrapperCmdFor } from './detect-backends.mjs';
+import { detectBackends, wrapperCmdFor, wrapperContractFor } from './detect-backends.mjs';
 import { ACTIVITIES, resolveActivityRecipe, planRecipe } from './recipes.mjs';
 import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
 // The config schema/read core lives in orchestration-config.mjs (the single config contract). procedures
@@ -131,10 +131,16 @@ const resolveAllSlots = ({ activity, config, detection, overrides }) =>
     // The concrete wrapper set this slot's EFFECTIVE recipe dispatches (empty for solo). Reuse
     // planRecipe's drift-guarded dispatch for WHICH backends, then resolve each (backend, role) to its
     // manifest wrapper cmd via the bridge registry — no wrapper name is hand-composed here.
-    const backends = planRecipe(resolved.recipe, detection).dispatch
-      .map((d) => wrapperCmdFor(d.backend, d.role))
-      .filter(Boolean);
-    return { slot, ...resolved, backends };
+    const { dispatch } = planRecipe(resolved.recipe, detection);
+    const backends = dispatch.map((d) => wrapperCmdFor(d.backend, d.role)).filter(Boolean);
+    // The full DRIVING CONTRACT per dispatched (backend, role) — resolved HERE, on the raw dispatch
+    // pairs, BEFORE they are flattened to wrapper names (the name array cannot reconstruct the role).
+    // Every slot with a non-empty dispatch gets contracts — including execute=delegated; the contract
+    // is NEVER gated by REVIEW_RECIPES (that set gates only the review-loop economics block).
+    const contracts = dispatch
+      .map((d) => ({ backend: d.backend, role: d.role, cmd: wrapperCmdFor(d.backend, d.role), contract: wrapperContractFor(d.backend, d.role) }))
+      .filter((c) => c.cmd && c.contract);
+    return { slot, ...resolved, backends, contracts };
   });
 
 // An unsatisfiable EXPLICIT override is the only "warning" (loud, flagged for the agent to relay). A
@@ -182,6 +188,28 @@ const reviewLoopAdvice = (slots) =>
       ]
     : [];
 
+// The verbatim per-backend DRIVING CONTRACT block (M-contract): the exact invocation descriptor(s),
+// the closed flag set, the grounding note, the round-2/continue delta, and the guarded passthrough
+// tiers — every descriptor printed VERBATIM from the registry mirror of the bridge manifest
+// roles[role].contract (drift-guarded), never re-derived or re-worded here. Rendered for EVERY
+// dispatched backend of EVERY slot (review AND execute=delegated); each wrapper's --help prints the
+// same contract, so the agent never needs to open the wrapper source.
+const contractLines = ({ cmd, contract }) => {
+  const lines = [`      ${cmd} — driving contract (as bundled with this kit; copy-paste — \`${cmd} --help\` prints the same):`];
+  for (const inv of contract.invocations) lines.push(`        ${inv}`);
+  for (const f of contract.flags ?? []) lines.push(`        ${f}`);
+  if (contract.grounding) lines.push(`        grounding: ${contract.grounding}`);
+  const cont = contract.continue ?? [];
+  if (cont.length) {
+    lines.push('        round-2 delta (resume — never re-send the reviewed artifact):');
+    for (const c of cont) lines.push(`          ${c}`);
+  }
+  if (contract.passthrough) {
+    lines.push(`        passthrough after '--' is ${contract.passthrough.policy}: blocked always: ${contract.passthrough.blocked.join(' ')}; relaxed only under CODEX_PROBE=1: ${contract.passthrough.probeRelaxed.join(' ')}`);
+  }
+  return lines;
+};
+
 const formatHuman = ({ activity, section, slots, warnings }) => {
   const lines = [
     section,
@@ -192,6 +220,7 @@ const formatHuman = ({ activity, section, slots, warnings }) => {
     const arrow = s.degradedFrom ? ` (requested ${s.degradedFrom} → degraded)` : '';
     lines.push(`  ${s.slot}: ${s.recipe} — ${SOURCE_LABEL[s.source]}${arrow}${backendSetLabel(s.backends)}`);
     if (s.reason) lines.push(`      ↳ ${s.reason}`);
+    for (const c of s.contracts ?? []) lines.push(...contractLines(c));
   }
   const advice = reviewLoopAdvice(slots);
   if (advice.length) lines.push('', ...advice);
@@ -206,7 +235,9 @@ const buildJson = ({ activity, section, slots, configSource, warnings }) => ({
   activity,
   section,
   slots: Object.fromEntries(
-    slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends }]),
+    // `backends: string[]` is the STABLE pre-existing shape (wrapper names) — never repurposed.
+    // `contracts` is the ADDITIVE per-dispatch driving-contract field (empty for solo).
+    slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends, contracts: s.contracts }]),
   ),
   reviewLoop: reviewLoopAdvice(slots),
   configSource,