@sabaiway/agent-workflow-kit 1.24.0 → 1.26.0

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.26.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.24.0",
+  "version": "1.26.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/family-members.mjs

@@ -13,7 +13,8 @@
 // ── the unified registry ───────────────────────────────────────────────────────
 // One entry per family member. `installed` is the detect.installed spec (env + home-relative default
 // + marker file); `deployed` is the project-relative stamp a deploy writes (kit + memory only);
-// `npm` is the install package (null for the bridges, which are placed by `setup`, not npm);
+// `npm` is the install package (null for the bridges — placed by `setup`, and once placed refreshed
+// by `init`/`upgrade` from the kit's bundled copies, never npm);
 // `wrapperCmds` is the deduped roles[].cmd set the `setup` linker creates on PATH (bridges only).
 // Kept in lockstep with the 5 in-repo capability.json by the drift-guard test. The two release skills
 // (release-engineering / release-marketing) are deliberately NOT here — they are not family members

package/tools/family-registry.mjs

@@ -17,10 +17,13 @@
 // side effects on import (the isDirectRun idiom) — tests import the helpers with nothing run.
 
 import { existsSync, statSync, readFileSync, lstatSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve, dirname } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
+// The ONE dependency-free semver (shared with bin/install.mjs) — the bridge freshness probe compares
+// the placed version against the kit-bundled mirror; null-on-unparseable maps to 'unknown' (INV-B).
+import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
 import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
@@ -57,6 +60,10 @@ import {
   VISIBILITY_PUBLIC,
   DISPLAY_NAMES,
   displayOf,
+  FRESH_CURRENT,
+  FRESH_BEHIND,
+  FRESH_UNKNOWN,
+  FRESH_NOT_CHECKED,
 } from './labels.mjs';
 // The capability-adaptive direct-CLI presenter (Plan §4.2/§4.5): the surface detector, the
 // envelope→ViewModel transform, and the plain/ansi renderers. main() composes them; the agent-mediated
@@ -135,7 +142,18 @@ export const classifyMember = (member, deps = {}) => {
   const report = markerPresent ? validate(skillDir) : { result: NOT_INSTALLED };
   const manifestState = classifyState(markerPresent, report, member);
   const installed = manifestState !== NOT_INSTALLED;
-  const version = manifestState === OK ? readVersion(skillDir).version ?? null : null;
+  // Crash-safe version read: readAuthoritativeVersion THROWS on a present-but-unreadable SKILL.md
+  // (stat needs no read permission, readFileSync does — a TOCTOU/EACCES window after validate).
+  // The read-only survey must never crash on it: degrade to null, which the bridge freshness probe
+  // then reports as 'unknown' (INV-B), never as a throw and never as a silent claim.
+  const version = (() => {
+    if (manifestState !== OK) return null;
+    try {
+      return readVersion(skillDir).version ?? null;
+    } catch {
+      return null;
+    }
+  })();
 
   return { name: member.name, kind: member.kind, installed, skillDir: installed ? skillDir : null, manifestState, version };
 };
@@ -165,6 +183,51 @@ export const MEMORY_ORCH_TEMPLATE_REL = 'references/templates/orchestration.json
 const MEMORY_BEHIND_NOTE =
   "the memory installed here doesn't include the current orchestration template — refresh it with `npx @sabaiway/agent-workflow-memory@latest init`, then restart the session.";
 
+// ── the bridge freshness probe (deterministic-first — INV-A / INV-B) ─────────────
+// The bridges are not npm packages: their ONLY delivery channel is the copy bundled inside this kit
+// (`bridges/<name>/`, placed by `/agent-workflow-kit setup`). A placed bridge therefore has exactly
+// one authoritative freshness comparison — its installed version (readAuthoritativeVersion, already
+// on the row) vs the kit-bundled mirror's capability.json. BOTH are local files, so the "never
+// checks npm" invariant holds. The probe sets the internal row field `freshness`
+// ('behind' | 'current' | 'unknown'); refreshOf derives the public refresh block STRUCTURALLY from
+// that field (INV-2 — never parsed from caveat text). INV-B: an unreadable/unparseable version on
+// EITHER side degrades to 'unknown' + a plain-language note — never a false claim in either direction.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// bridges/ ships beside tools/ in both the repo and the installed kit (the setup-backends.mjs
+// resolution), so this resolves in both. Injectable via deps.bundleRoot for tests.
+const BUNDLE_ROOT = resolve(__dirname, '..', 'bridges');
+
+// Crash-safe on the bundled side: an absent / unreadable / malformed bundle manifest → null (INV-B
+// 'unknown'), never a throw — the read-only survey must survive a broken kit install.
+const readBundledBridgeVersion = (name, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const root = deps.bundleRoot ?? BUNDLE_ROOT;
+  try {
+    const manifest = JSON.parse(String(read(join(root, name, 'capability.json'), 'utf8')));
+    return typeof manifest.version === 'string' ? manifest.version : null;
+  } catch {
+    return null;
+  }
+};
+
+const bridgeBehindNote = (display, placed, bundled) =>
+  `the ${display} installed here (v${placed}) is older than the copy bundled with this kit (v${bundled}) — refresh it with \`/agent-workflow-kit setup\`.`;
+// The recovery differs per failing SIDE: `setup` re-places FROM the bundle, so it can repair an
+// unreadable INSTALLED copy but can never repair an unreadable BUNDLED copy — that needs a kit
+// refresh first (the npx installer), then `setup`.
+const bridgeUnknownNote = (display, side, recovery) =>
+  `couldn't compare the ${display} installed here with the copy bundled with this kit (${side}), so its freshness is unknown — ${recovery}.`;
+const UNKNOWN_SIDES = Object.freeze({
+  placed: {
+    side: 'the installed copy has no readable version',
+    recovery: '`/agent-workflow-kit setup` re-places the bundled copy',
+  },
+  bundled: {
+    side: "the kit's bundled copy has no readable version",
+    recovery: 'refresh the kit first (`npx @sabaiway/agent-workflow-kit@latest init`), then `/agent-workflow-kit setup`',
+  },
+});
+
 export const surveyFamily = (deps = {}) =>
   FAMILY_MEMBERS.map((member) => {
     const row = classifyMember(member, deps);
@@ -184,8 +247,30 @@ export const surveyFamily = (deps = {}) =>
     // Only attach when it is provably ABSENT (a non-ENOENT probe error → 'unknown' → skip, never a
     // false "missing" claim). Mirrors the engine-caveat SHAPE; keyed on the Step-2.4 required asset.
     if (row.kind === 'memory-substrate' && row.manifestState === OK && row.skillDir) {
-      if (probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps) === 'absent') {
+      const templateProbe = probeMarker(join(row.skillDir, MEMORY_ORCH_TEMPLATE_REL), deps);
+      if (templateProbe === 'absent') {
         row.caveats = [...(row.caveats ?? []), MEMORY_BEHIND_NOTE];
+      } else if (templateProbe === 'unknown') {
+        // Could not verify → this row must not be counted "checked, current" by the verdict (INV-B).
+        row.freshness = FRESH_UNKNOWN;
+      }
+    }
+    // Bridge freshness probe (INV-A / INV-B): only for a provably-OURS placed bridge (manifestState
+    // OK). Compares two LOCAL files; a non-OK / absent bridge is out of scope ('not-checked').
+    if (row.kind === 'execution-backend' && row.manifestState === OK && row.skillDir) {
+      const bundled = readBundledBridgeVersion(row.name, deps);
+      const cmp = compareSemver(row.version, bundled);
+      if (cmp === null) {
+        const { side, recovery } = parseSemver(row.version) === null ? UNKNOWN_SIDES.placed : UNKNOWN_SIDES.bundled;
+        row.freshness = FRESH_UNKNOWN;
+        row.caveats = [...(row.caveats ?? []), bridgeUnknownNote(displayOf(row.name), side, recovery)];
+      } else if (cmp < 0) {
+        row.freshness = FRESH_BEHIND;
+        row.caveats = [...(row.caveats ?? []), bridgeBehindNote(displayOf(row.name), row.version, bundled)];
+      } else {
+        // Equal OR newer-than-bundled → not behind. A newer placed bridge is a Phase-2 concern for
+        // the refresh DRIVER (INV-D never-downgrade skip); the read-only status axis never flags it.
+        row.freshness = FRESH_CURRENT;
       }
     }
     return row;
@@ -376,18 +461,31 @@ export const surveyBridges = (deps = {}) => {
   });
 };
 
-// INV-2 (structural refresh — additive, derived, never parsed from a caveat string). A member is
-// `behind` when it is a refreshable CORE member (memory / engine) carrying a refresh-recommending
-// caveat — surveyFamily attaches caveats ONLY to those two kinds, and today every such caveat is
-// refresh-recommending. `recommend` is composed from the member's npm package in the ONE registry
-// (FAMILY_MEMBERS[].npm), never extracted from the caveat text. The kit (composition-root) + the two
-// bridges (execution-backend) never carry such a caveat, so they derive { behind:false, recommend:null }
-// — gated by the CAVEAT, not by npm-nullness (the kit's npm is non-null; only the bridges are null).
+// INV-2 (structural refresh — additive, derived, never parsed from a caveat string), per KIND:
+//   • memory / engine (REFRESHABLE_KINDS): `behind` ⟷ an OK row carrying a refresh-recommending
+//     caveat (surveyFamily attaches caveats to those kinds only then, and every such caveat is
+//     refresh-recommending); `recommend` is composed from FAMILY_MEMBERS[].npm — never the caveat text.
+//   • execution-backend: `behind` ⟷ the bridge freshness probe's row field (freshness === 'behind');
+//     `recommend` is composed PER-KIND — bridges have npm:null (placed by `setup`, never npx), so the
+//     runnable recovery is `/agent-workflow-kit setup`, never an npx composition.
+//   • composition-root (the kit): no freshness probe exists on this surface (the two-axes doctrine —
+//     kit freshness is the npx installer's axis) → never behind, 'not-checked'.
+// `freshness` is the checked-vs-unknown signal the zero-behind verdict scopes itself with (INV-C):
+// behind:false alone cannot distinguish "checked, current" from "could not be checked".
 const REFRESHABLE_KINDS = new Set(['memory-substrate', 'methodology-engine']);
 const npmOf = (name) => FAMILY_MEMBERS.find((m) => m.name === name)?.npm ?? null;
+export const BRIDGE_REFRESH_RECOMMEND = '/agent-workflow-kit setup';
 const refreshOf = (m) => {
+  if (m.kind === 'execution-backend') {
+    const freshness = m.freshness ?? FRESH_NOT_CHECKED;
+    const behind = freshness === FRESH_BEHIND;
+    return { behind, recommend: behind ? BRIDGE_REFRESH_RECOMMEND : null, freshness };
+  }
   const behind = REFRESHABLE_KINDS.has(m.kind) && Boolean(m.caveats?.length);
-  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null };
+  const freshness = REFRESHABLE_KINDS.has(m.kind) && m.manifestState === OK
+    ? m.freshness ?? (behind ? FRESH_BEHIND : FRESH_CURRENT)
+    : FRESH_NOT_CHECKED;
+  return { behind, recommend: behind ? `npx ${npmOf(m.name)}@latest init` : null, freshness };
 };
 
 export const buildEnvelope = (family, project = null, extras = {}) => {
@@ -399,7 +497,7 @@ export const buildEnvelope = (family, project = null, extras = {}) => {
       state: STATE_PUBLIC[m.manifestState] ?? STATE_PUBLIC[UNKNOWN],
     };
     if (m.caveats?.length) entry.notes = m.caveats; // plain-language observations (Steps 2.2 / engine)
-    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend } (INV-2)
+    entry.refresh = refreshOf(m); // additive (INV-1): always present; { behind, recommend, freshness } (INV-2)
     return entry;
   });
   const envelope = { deploymentHead: EXPECTED_WORKFLOW_VERSION, installed };

package/tools/labels.mjs

@@ -41,6 +41,19 @@ export const STATE_PUBLIC = Object.freeze({
 // "hidden fence" / marker terms. ('hidden' here is the PUBLIC visibility word, not the internal fence.)
 export const VISIBILITY_PUBLIC = Object.freeze({ visible: 'visible', hidden: 'hidden', ambiguous: 'unclear' });
 
+// ── refresh freshness tokens (PUBLIC — the envelope's installed[].refresh.freshness) ────────────────
+// The checked-vs-unknown signal the zero-behind verdict scopes itself with (INV-C): `behind:false`
+// alone cannot distinguish "checked, current" from "could not be checked".
+//   'current' / 'behind' — a freshness probe RAN and concluded (these two are the "checked" scope);
+//   'unknown'            — a probe ran but could not conclude (INV-B: never collapsed to a claim
+//                          in either direction);
+//   'not-checked'        — no freshness probe exists for this member/state (e.g. the kit itself:
+//                          its freshness is the npx installer's axis, never checked here).
+export const FRESH_CURRENT = 'current';
+export const FRESH_BEHIND = 'behind';
+export const FRESH_UNKNOWN = 'unknown';
+export const FRESH_NOT_CHECKED = 'not-checked';
+
 // Short, user-facing labels for the version block (kit · memory · engine · codex-bridge · …), so the
 // render is deterministic and the agent never invents a label.
 export const DISPLAY_NAMES = Object.freeze({

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,