@ikon85/agent-workflow-kit 0.33.0 → 0.34.0

package/docs/agents/skills/local-ci.md

@@ -0,0 +1,89 @@
+<!-- setup-workflow: state=filled -->
+# Project layer — local-ci
+
+This repo is a Node + stdlib-Python repo with no database, no dev server and no
+typecheck step, so the two generic profiles map onto a short command set. Run the
+two commands below; do not infer others.
+
+Prerequisite once per clone (worktrees inherit it):
+
+```sh
+git config core.hooksPath .githooks
+```
+
+## Fast static guards
+
+The skill/manifest lints, ~3s, no network, no DB. This is exactly what
+`.githooks/pre-commit` runs, so a normal commit already covers it:
+
+```sh
+python3 -m unittest discover -s scripts -p 'test_skill_*.py' -q
+```
+
+## Full gate
+
+Mirrors the `test` job in `.github/workflows/ci.yml` step for step. Run it from
+the branch's worktree root before opening a PR:
+
+```sh
+npm test
+npm run kit:staleness
+npm run release:guard -- --base "$(git merge-base origin/main HEAD)"
+npm pack --dry-run
+```
+
+Notes on the individual steps:
+
+- `npm test` is `test:node` (`node --test`) plus `test:python`
+  (`python3 -m unittest discover -s scripts -p 'test_*.py'`). Several negative-path
+  tests print `[FAIL] …` lines by design; only the runner's own summary and exit
+  code decide red or green.
+- CI runs `npm install --ignore-scripts` first. Locally that is only needed after
+  a dependency change.
+- `release:guard` runs in CI on `pull_request` only, against
+  `github.event.pull_request.base.sha`. `git merge-base origin/main HEAD` is the
+  local equivalent; `git fetch origin main` first if `origin/main` is stale.
+- `npm pack --dry-run` catches packaging drift (a file added outside the
+  published set) without publishing anything.
+
+## Enforcement
+
+Since #220 the host **does** enforce: the `main protection` ruleset makes the CI
+job `test` a required status check on `main`, with no bypass actor. So the
+generic skill's "When the host CAN enforce" branch applies to this repo — the
+local gate is a pre-flight that shortens the feedback loop, not the only thing
+standing between a red branch and `main`.
+
+Layered, from cheapest to strongest:
+
+| Layer | Runs | Scope |
+| --- | --- | --- |
+| `pre-commit` | automatic, every commit | fast skill/manifest lints |
+| `pre-push` | automatic, every push | full `npm test` |
+| this full gate | explicit, before a PR | `npm test` + staleness + release guard + pack |
+| CI `test` | automatic, on the PR | the same set, machine-enforced at merge |
+
+Never bypass a hook with `--no-verify`.
+
+**Drift rule.** The full gate above and `.github/workflows/ci.yml` are two copies
+of one list. Change one, change the other in the same PR — otherwise the local
+gate goes green on a set the required check does not accept.
+
+## Contention
+
+Not applicable here. This repo has no dev server and the suites are process-level
+(`node --test`, `unittest`), so the generic boot-contention false-red guidance has
+no target. A red is a real red until an isolated re-run of that one test proves
+otherwise.
+
+## On a red
+
+1. Read the failing assertion — the guards print the exact drift (`file:line`,
+   the offending token, the missing manifest key).
+2. Fix the source. A guard that legitimately cannot be satisfied yet gets a
+   documented allowlist entry with a reason; never widen a guard silently.
+3. Re-run the single failing suite, then the full gate for sign-off.
+
+`kit:staleness` red almost always means the generated kit artefacts lag the
+skill sources — run `npm run kit:build` and commit the result rather than
+editing the generated output by hand.

package/docs/agents/wave-anchor-template.md

@@ -25,7 +25,7 @@ The **candidate stub** (Stage 1) has no cluster/Wave. On **`to-issues` promotion
 - **Source:** <board-to-waves | external-prd | raw-issue | plan | grill> *(provenance-neutral — the shape is the same regardless of origin; fill the following lines where they apply, delete where they don't)*
 - **Member issues:** #<a> #<b> #<c> … *(listed; linked via `to-issues` promotion, To-Do below)*
 - **Why together (firing criteria):** Gate=<Outcome> · <B1 code proximity / B2 type homogeneity / B3 dependency / B4 verify surface, where applicable>
-- **Size + risk:** ~<N> slices · Backend: <yes/no> · Model mix: <Model [Effort], e.g. Sonnet [medium] / Opus [high] / gpt-5.5 [medium]> · Risk: <low/medium/high — reason, e.g. race/cache/forecast/migration>
+- **Size + risk:** ~<N> slices · Backend: <yes/no> · Routing-intent mix: <judgment/development/mechanical + deep/balanced/light> · Risk: <low/medium/high — reason, e.g. race/cache/forecast/migration>
 - **`grill-needed`:** <no> | <yes — this session> | <yes — own session (too big/fuzzy)>
 
 ### To-Do (maturation: grill → to-prd → to-issues) — *(Stage 1/1p only; at promotion this whole checklist collapses to ONE line: `Maturation: grill <✓/–> · to-prd ✓ · to-issues ✓ (<Date>) — Wave gate + tracking open`)*
@@ -53,7 +53,7 @@ Order (WSJF-lite): visible + low-risk first → logic/backend → cleanup. Depen
 | 1 | ⬜ | <Slice title> | #<sub> | <—/🧭/🔬/📐/📝> | <closes #x / refs #y> |
 <!-- slice-table:end -->
 
-Status legend: ⬜ open · 🔄 in progress · ✅ merged #<PR>. **Every slice = one sub-issue** (`#<sub>`). **The volatile Status column is generated by `board-sync.py anchor-sync <anchor#>` from the board** (between the `<!-- slice-table:start/end -->` markers; `wrapup` Step 5e.1 calls it on merge) — monotone (never flips a `✅`/`🔄` back), drift-free idempotent; **stable plan columns (Slice/Gate/refs) stay hand-maintained** and survive verbatim. It appends missing sub-issue rows (gen-b split). **Don't delete the markers** — without them `anchor-sync` can't locate the table (the first run locates it via the `Status`+`Sub-Issue` header row and sets the markers itself). The native "Sub-issues progress" rollup is the secondary %-view. *(Slimmed in: Branch is derivable from the `feat/<#>-<slug>` convention, the model recommendation lives in the leaf's handoff, Backend? carried no navigation value — legacy anchors that still have those columns keep working, `anchor-sync` matches columns by header name and refreshes Branch/Blocked-by only where the column exists.)*
+Status legend: ⬜ open · 🔄 in progress · ✅ merged #<PR>. **Every slice = one sub-issue** (`#<sub>`). **The volatile Status column is generated by `board-sync.py anchor-sync <anchor#>` from the board** (between the `<!-- slice-table:start/end -->` markers; `wrapup` Step 5e.1 calls it on merge) — monotone (never flips a `✅`/`🔄` back), drift-free idempotent; **stable plan columns (Slice/Gate/refs) stay hand-maintained** and survive verbatim. It appends missing sub-issue rows (gen-b split). **Don't delete the markers** — without them `anchor-sync` can't locate the table (the first run locates it via the `Status`+`Sub-Issue` header row and sets the markers itself). The native "Sub-issues progress" rollup is the secondary %-view. *(Slimmed in: Branch is derivable from the `feat/<#>-<slug>` convention, provider-neutral routing intent lives in the leaf's handoff, Backend? carried no navigation value — legacy anchors that still have those columns keep working, `anchor-sync` matches columns by header name and refreshes Branch/Blocked-by only where the column exists.)*
 
 **Gate legend (retro):** `—` AFK build (`/implement`) · 🧭 design grill (`grill-with-docs-codex`, ADR) · 🔬 verify spike (read-only fact question) · 📐 trade-off/research (read-only, below grill threshold) · 📝 review note (not a build slice). A gate slice (🧭/🔬/📐) sits **before** its dependent build slice (gate-before-build) and blocks it.
 

package/docs/methodology.html

@@ -324,7 +324,7 @@
           <span class="station st-program">grill</span><span class="arrow">→</span>
           <span class="station st-program">Program document</span><span class="arrow">→</span>
           <span class="station st-gate">preview gate</span><span class="arrow">→</span>
-          <span class="station st-wave">to-waves</span><span class="arrow">→</span>
+          <span class="station st-wave">to-issues · Program mode</span><span class="arrow">→</span>
           <span class="station st-phase">phases stamped</span><span class="arrow">+</span>
           <span class="station st-wave">Wave 1…n + slices</span>
         </div>

package/docs/methodology.svg

@@ -49,7 +49,7 @@
 
   <!-- top branch: planned top-down -->
   <rect x="350" y="350" width="260" height="40" rx="7" fill="#2E3850" stroke="B2" stroke-width="1.2"/>
-  <text x="480" y="375" font-size="12.5" fill="#8FA9C4" text-anchor="middle">scale-check → grill → to-waves</text>
+  <text x="480" y="375" font-size="12.5" fill="#8FA9C4" text-anchor="middle">scale-check → grill → to-issues</text>
   <line x1="480" y1="390" x2="553" y2="430" stroke="#8A95A6" stroke-width="1.4" marker-end="url(#arrow)"/>
 
   <!-- main spine -->

package/docs/workflow.html

@@ -181,8 +181,8 @@
       <div class="sw-track" style="--lbg: var(--plan-bg);">
         <span class="station st-plan">scale-check</span><span class="arrow">→</span>
         <span class="station st-gate">grill</span><span class="arrow">→</span>
-        <span class="station st-plan">to-waves</span>
-        <span class="decision">preview gate · zero board writes until yes</span><span class="arrow">→</span>
+        <span class="station st-plan">to-issues</span>
+        <span class="decision">Program identity · preview gate · zero writes until yes</span><span class="arrow">→</span>
         <span class="station st-exec">orchestrate-wave</span>
         <span class="decision">per wave, often AFK</span><span class="arrow">→</span>
         <span class="station st-land">wrapup</span><span class="arrow">→</span>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/codex-exec.sh

@@ -4,6 +4,7 @@ set -u
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 PROC_HELPER="$SCRIPT_DIR/codex_proc.py"
 TESTED_VERSIONS=("0.137.0" "0.144.6")
+SUPPORTED_EFFORTS=("low" "medium" "high" "xhigh" "max" "ultra")
 STATE_ROOT=${CODEX_EXEC_STATE_ROOT:-${TMPDIR:-/tmp}/codex-exec-state}
 
 emit_json() {
@@ -118,10 +119,10 @@ preflight() {
 }
 
 parse_options() {
-  CODEX_BIN=codex PROFILE= MODE= SANDBOX= PROMPT= PROMPT_FILE= RUN_ID= TIMEOUT= PROBE_TIMEOUT= DEBUG_RETAIN=false
+  CODEX_BIN=codex PROFILE= MODE= SANDBOX= PROMPT= PROMPT_FILE= RUN_ID= TIMEOUT= PROBE_TIMEOUT= MODEL= EFFORT= DEBUG_RETAIN=false
   while (($#)); do
     case $1 in
-      --codex-bin|--profile|--mode|--prompt|--prompt-file|--run-id|--timeout|--probe-timeout)
+      --codex-bin|--profile|--mode|--prompt|--prompt-file|--run-id|--timeout|--probe-timeout|--model|--effort)
         (($# >= 2)) || { fail INVALID_ARGUMENT "Missing value for $1"; return 1; }
         case $1 in
           --codex-bin) CODEX_BIN=$2 ;;
@@ -132,6 +133,8 @@ parse_options() {
           --run-id) RUN_ID=$2 ;;
           --timeout) TIMEOUT=$2 ;;
           --probe-timeout) PROBE_TIMEOUT=$2 ;;
+          --model) MODEL=$2 ;;
+          --effort) EFFORT=$2 ;;
         esac
         shift 2 ;;
       --debug-retain) DEBUG_RETAIN=true; shift ;;
@@ -140,6 +143,22 @@ parse_options() {
   done
 }
 
+validate_route_controls() {
+  if [[ -z $MODEL && -z $EFFORT ]]; then
+    return 0
+  fi
+  local effort_supported=false supported
+  for supported in "${SUPPORTED_EFFORTS[@]}"; do
+    [[ $EFFORT == "$supported" ]] && effort_supported=true
+  done
+  if [[ -z $MODEL || -z $EFFORT \
+    || ! $MODEL =~ ^[A-Za-z0-9._:-]+$ \
+    || $effort_supported != true ]]; then
+    fail INVALID_ROUTE_CONTROL "Model and effort must be supplied together from the exact safe vocabulary"
+    return 1
+  fi
+}
+
 prepare_prompt() {
   local state_dir=$1
   TEMP_PROMPT="$state_dir/.prompt-input"
@@ -160,10 +179,14 @@ launch_round() {
   prepare_prompt "$state_dir" || return 1
   local command
   if [[ -z $thread_id ]]; then
-    command=("$CODEX_BIN" exec --json --sandbox "$SANDBOX" -)
+    command=("$CODEX_BIN" exec --json --sandbox "$SANDBOX")
   else
-    command=("$CODEX_BIN" exec resume "$thread_id" -c "sandbox_mode=$SANDBOX" --json -)
+    command=("$CODEX_BIN" exec resume "$thread_id" -c "sandbox_mode=$SANDBOX")
   fi
+  if [[ -n $MODEL ]]; then
+    command+=(-c "model=$MODEL" -c "model_reasoning_effort=$EFFORT")
+  fi
+  command+=(--json -)
   python3 "$PROC_HELPER" run --state-dir "$state_dir" --round "$round" \
     --profile "$PROFILE" --sandbox "$SANDBOX" --timeout "$TIMEOUT" \
     --probe-timeout "$PROBE_TIMEOUT" --prompt-file "$TEMP_PROMPT" \
@@ -252,6 +275,7 @@ PY
 
 new_run() {
   parse_options "$@" || return 1
+  validate_route_controls || return 1
   PROFILE=${PROFILE:-review}
   MODE=${MODE:-read-only}
   [[ $PROFILE == review || $PROFILE == build ]] || { fail INVALID_PROFILE "Profile must be review or build"; return 1; }
@@ -285,15 +309,18 @@ new_run() {
   state_dir=$(mktemp -d "$STATE_ROOT/codex-exec.XXXXXXXX") || return 1
   chmod 700 "$state_dir"
   run_id=${state_dir##*.}
-  printf '%s\n' "$run_id" >"$state_dir/run-id"
   printf '%s\n' "$PROFILE" >"$state_dir/profile"
   printf '%s\n' "$SANDBOX" >"$state_dir/sandbox"
+  printf '%s\n' "$MODEL" >"$state_dir/model"
+  printf '%s\n' "$EFFORT" >"$state_dir/effort"
   printf '1\n' >"$state_dir/next-round"
   chmod 600 "$state_dir"/*
   lease_token=$(acquire_lease "$state_dir") || {
     fail ACTIVE_RUN "Run state is already owned by another lifecycle action"
     return 1
   }
+  printf '%s\n' "$run_id" >"$state_dir/run-id"
+  chmod 600 "$state_dir/run-id"
   output=$(launch_round "$state_dir" 1 "$lease_token")
   rc=$?
   release_or_fail "$state_dir" "$lease_token" "$run_id" "$output" || return 1
@@ -307,16 +334,20 @@ new_run() {
 }
 
 resume_run_locked() {
-  local state_dir=$1 lease_token=$2 stored_profile stored_sandbox thread_id round
+  local state_dir=$1 lease_token=$2 stored_profile stored_sandbox stored_model stored_effort thread_id round
   [[ ! -f $state_dir/debug-retain ]] || {
     fail RUN_FINALIZED "Run was finalized with debug retention"; return 1;
   }
   [[ -f $state_dir/profile && ! -L $state_dir/profile \
-    && -f $state_dir/sandbox && ! -L $state_dir/sandbox ]] || {
-    fail INVALID_STATE "Persisted profile or sandbox state is missing or unsafe"; return 1;
+    && -f $state_dir/sandbox && ! -L $state_dir/sandbox \
+    && -f $state_dir/model && ! -L $state_dir/model \
+    && -f $state_dir/effort && ! -L $state_dir/effort ]] || {
+    fail INVALID_STATE "Persisted profile, sandbox, or route controls are missing or unsafe"; return 1;
   }
   stored_profile=$(<"$state_dir/profile")
   stored_sandbox=$(<"$state_dir/sandbox")
+  stored_model=$(<"$state_dir/model")
+  stored_effort=$(<"$state_dir/effort")
   [[ $stored_profile == review || $stored_profile == build ]] || {
     fail INVALID_STATE "Persisted profile is not in the exact allowlist"; return 1;
   }
@@ -328,6 +359,13 @@ resume_run_locked() {
     fail MODE_MISMATCH "Resume mode differs from persisted mode"
     return 1
   fi
+  if [[ -n $MODEL && $MODEL != "$stored_model" ]] || [[ -n $EFFORT && $EFFORT != "$stored_effort" ]]; then
+    fail ROUTE_CONTROL_MISMATCH "Resume model or effort differs from the persisted applied route"
+    return 1
+  fi
+  MODEL=$stored_model
+  EFFORT=$stored_effort
+  validate_route_controls || return 1
   SANDBOX=$stored_sandbox
   [[ -f $state_dir/thread-id ]] || { fail NO_THREAD "Run has no resumable thread" NO-THREAD; return 1; }
   thread_id=$(<"$state_dir/thread-id")
@@ -346,6 +384,7 @@ resume_run_locked() {
 
 resume_run() {
   parse_options "$@" || return 1
+  validate_route_controls || return 1
   [[ -n $RUN_ID ]] || { fail RUN_ID_REQUIRED "Resume requires --run-id"; return 1; }
   local state_dir lease_token rc output
   state_dir=$(find_state "$RUN_ID") || { fail RUN_NOT_FOUND "Run state does not exist"; return 1; }

package/scripts/codex-exec.test.mjs

@@ -143,6 +143,62 @@ test('invalid timeout and mode inputs fail before launch', () => {
   assert.equal(exists(fx.launchLog), false);
 });
 
+test('approved route passes explicit model and effort controls to Codex', () => {
+  const fx = fixture();
+  const result = invoke(fx, [
+    ...launchArgs(),
+    '--model', 'coding-model',
+    '--effort', 'high',
+  ]);
+  assert.equal(result.output.status, 'OK');
+  const command = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim());
+  assert.ok(command.includes('model=coding-model'));
+  assert.ok(command.includes('model_reasoning_effort=high'));
+
+  const resumed = invoke(fx, [
+    'resume', result.output.runId, '--codex-bin', fake,
+    '--prompt', 'Again', '--timeout', '2',
+  ]);
+  assert.equal(resumed.output.status, 'OK');
+  const resumeCommand = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim().split('\n').at(-1));
+  assert.ok(resumeCommand.includes('model=coding-model'));
+  assert.ok(resumeCommand.includes('model_reasoning_effort=high'));
+
+  const mismatch = invoke(fx, [
+    'resume', result.output.runId, '--codex-bin', fake,
+    '--model', 'other-model', '--effort', 'high', '--prompt', 'No',
+  ]);
+  assert.equal(mismatch.output.error, 'ROUTE_CONTROL_MISMATCH');
+});
+
+test('route controls fail closed when incomplete or unsafe', () => {
+  for (const args of [
+    [...launchArgs(), '--model', 'coding-model'],
+    [...launchArgs(), '--effort', 'high'],
+    [...launchArgs(), '--model', 'unsafe value', '--effort', 'high'],
+    [...launchArgs(), '--model', 'coding-model', '--effort', 'unknown'],
+  ]) {
+    const fx = fixture();
+    const result = invoke(fx, args);
+    assert.equal(result.output.error, 'INVALID_ROUTE_CONTROL');
+    assert.equal(exists(fx.launchLog), false);
+  }
+});
+
+test('current extended reasoning efforts are passed through explicitly', () => {
+  for (const effort of ['max', 'ultra']) {
+    const fx = fixture();
+    const result = invoke(fx, [
+      ...launchArgs(),
+      '--model', 'coding-model',
+      '--effort', effort,
+    ]);
+    assert.equal(result.output.status, 'OK', effort);
+    const command = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim());
+    assert.ok(command.includes(`model_reasoning_effort=${effort}`));
+  }
+});
+
 test('finalize deletes state, debug-retain preserves diagnostics, and finalized resume fails', () => {
   const fx = fixture();
   const run = invoke(fx, launchArgs()).output;

package/scripts/test_codex_adapter_sync_contract.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 ADAPTER = REPO_ROOT / ".agents/skills/codex-adapter-sync/SKILL.md"
+AGENTS_README = REPO_ROOT / ".codex/agents/README.md"
 _FRONTMATTER_SPEC = importlib.util.spec_from_file_location(
     "skill_frontmatter_lint", REPO_ROOT / "scripts/test_skill_frontmatter_lint.py")
 frontmatter = importlib.util.module_from_spec(_FRONTMATTER_SPEC)
@@ -39,27 +40,24 @@ class AdapterModesContract(unittest.TestCase):
         self.assertNotIn("before inventory or edits", self.body)
 
 
-class AdapterModelContract(unittest.TestCase):
+class AdapterRoutingContract(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         cls.body = ADAPTER.read_text(encoding="utf-8")
 
-    def test_current_models_inherit_by_default_and_route_by_task_shape(self):
-        routing = " ".join(section(self.body, "Model routing").split())
-
-        self.assertIn("inherited parent model configuration", routing)
-        self.assertIn("`gpt-5.6-sol`", routing)
-        self.assertIn("complex, open-ended judgment work", routing)
-        self.assertIn("`gpt-5.6-terra`", routing)
-        self.assertIn("everyday tool-using development", routing)
-        self.assertIn("`gpt-5.6-luna`", routing)
-        self.assertIn("clear, repeatable, high-volume work", routing)
-        self.assertIn("`model_reasoning_effort`", routing)
+    def test_durable_routing_is_provider_neutral_and_resolved_at_dispatch(self):
+        routing = " ".join(section(self.body, "Routing intent").split())
+
+        self.assertIn("`routing-intent`", routing)
+        self.assertIn("`reasoning-intent`", routing)
+        self.assertIn("Evidence catalog", routing)
+        self.assertIn("Access graph", routing)
+        self.assertIn("Routing policy", routing)
+        self.assertIn("dispatch time", routing)
+        self.assertIn("explicit `inherit`", routing)
+        self.assertIn("Dispatch receipt", routing)
         self.assertIn("`default`, `worker`, and `explorer`", routing)
-        self.assertIn("not a fourth concrete variant", routing)
 
-        for stale in ("gpt-5.4-mini", "gpt-5.5"):
-            self.assertNotIn(stale, self.body)
         self.assertNotRegex(self.body, r"(?<!model_)\breasoning_effort\b")
         self.assertNotRegex(self.body, r"\bagent_type\b")
 
@@ -104,6 +102,23 @@ class AdapterAgentContract(unittest.TestCase):
         self.assertIn("Parse every `.codex/agents/*.toml`", agents)
         self.assertIn("Reject a file", agents)
 
+    def test_codex_host_inventory_is_dated_and_does_not_invent_spawn_selectors(self):
+        inventory = " ".join(
+            AGENTS_README.read_text(encoding="utf-8").split()
+        )
+        for fragment in (
+            "2026-07-23",
+            "`task_name`",
+            "`message`",
+            "`fork_turns`",
+            "no per-spawn `model`",
+            "no per-spawn effort selector",
+            "`src/lib/routingAdapters/codex.mjs`",
+            "blocks differentiated AFK",
+            "Dispatch receipt v2",
+        ):
+            self.assertIn(fragment, inventory)
+
 
 class AdapterValidationContract(unittest.TestCase):
     @classmethod

package/scripts/test_orchestrate_wave_contract.py

@@ -34,6 +34,25 @@ CODEX_SUBAGENTS = (
     REPO / ".agents/skills/orchestrate-wave/references/dispatch-subagents.md"
 )
 CODEX_SURFACE = REPO / ".agents/skills/orchestrate-wave"
+EXPECTED_DIRECT_SPAWN_CONTRACTS = (
+    "audit-skills/SKILL.md",
+    "code-review/SKILL.md",
+    "codebase-design/DESIGN-IT-TWICE.md",
+    "improve-codebase-architecture/INTERFACE-DESIGN.md",
+    "improve-codebase-architecture/SKILL.md",
+    "research/SKILL.md",
+)
+DIRECT_SPAWN_PATTERN = re.compile(
+    r"Run \*\*one read-only research subagent|"
+    r"Run both axes as \*\*parallel sub-agents|"
+    r"Spawn 3\+ sub-agents|"
+    r"spawn 3\+ sub-agents|"
+    r"make 3\+ parallel\s+`spawn_agent` calls|"
+    r"Then use the Agent tool|"
+    r"use `spawn_agent` with `agent_type: explorer`|"
+    r"use `spawn_agent` with only|"
+    r"Spin up a \*\*background agent",
+)
 
 
 # Outcome -> fragments whose conjunction proves that portable behavior.
@@ -86,6 +105,15 @@ def markdown_body(text: str) -> str:
     return text.split("\n---\n", 1)[1]
 
 
+def direct_spawn_contracts(surface: str) -> tuple[str, ...]:
+    root = REPO / surface
+    return tuple(sorted(
+        str(path.relative_to(root))
+        for path in root.rglob("*.md")
+        if DIRECT_SPAWN_PATTERN.search(path.read_text(encoding="utf-8"))
+    ))
+
+
 class OrchestrateWaveContract(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
@@ -176,6 +204,47 @@ class OrchestrateWaveContract(unittest.TestCase):
         self.assertIn("(b) tier + effort", prose)
         self.assertIn("Standing rules", prose)
 
+    def test_every_surface_dispatch_crosses_resolver_and_spawn_guard(self):
+        prose = " ".join(self.skill.split())
+        for fragment in (
+            "provider-neutral Routing intent",
+            "shared resolver",
+            "spawn guard",
+            "Claude or Codex adapter",
+            "routingAdapters/codex.mjs",
+            "Dispatch receipt",
+            "requested and applied route",
+            "environment precedence",
+            "detected transport is not authorization",
+            "AFK",
+        ):
+            self.assertIn(fragment, prose)
+
+    def test_every_direct_spawn_contract_routes_through_the_shared_guard(self):
+        required = (
+            "provider-neutral Routing intent",
+            "routeDispatcher.mjs",
+            "shared spawn guard",
+            "Dispatch receipt",
+        )
+        claude_actual = direct_spawn_contracts(".claude/skills")
+        codex_actual = direct_spawn_contracts(".agents/skills")
+        self.assertEqual(claude_actual, EXPECTED_DIRECT_SPAWN_CONTRACTS)
+        self.assertEqual(codex_actual, EXPECTED_DIRECT_SPAWN_CONTRACTS)
+        for relative in claude_actual:
+            claude = " ".join(
+                (REPO / ".claude/skills" / relative).read_text(encoding="utf-8").split()
+            )
+            codex = " ".join(
+                (REPO / ".agents/skills" / relative).read_text(encoding="utf-8").split()
+            )
+            with self.subTest(contract=relative):
+                for fragment in required:
+                    self.assertIn(fragment, claude)
+                    self.assertIn(fragment, codex)
+                for unsupported in ("Agent tool", "subagent_type", "agent_type"):
+                    self.assertNotIn(unsupported, codex)
+
     def test_path_a_reference_locks_the_two_run_dispatch_contract(self):
         workflow = CLAUDE_WORKFLOW.read_text(encoding="utf-8")
         for fragment in (
@@ -214,6 +283,10 @@ class OrchestrateWaveContract(unittest.TestCase):
             "spawn_agents_on_csv",
             "output_schema",
             "dormant",
+            "task_name`, `message`, and `fork_turns",
+            "no model or effort selector",
+            "blocks differentiated AFK",
+            "routingAdapters/codex.mjs",
         ):
             self.assertIn(" ".join(fragment.split()), prose)
 

package/scripts/test_program_planning_contract.py

@@ -11,6 +11,76 @@ class ProgramPlanningContractTest(unittest.TestCase):
     def skill(self, name: str) -> str:
         return (ROOT / ".claude" / "skills" / name / "SKILL.md").read_text()
 
+    def file(self, path: str) -> str:
+        return (ROOT / path).read_text()
+
+    def test_to_issues_is_the_public_planning_facade(self):
+        text = self.skill("to-issues")
+        self.assertIn("single public Planning facade", text)
+        self.assertIn("planning-mode=feature", text)
+        self.assertIn("planning-mode=program", text)
+        self.assertIn("Missing or contradictory identity", text)
+        self.assertIn("Size, prose, and model judgment never select the mode", text)
+
+    def test_program_identity_delegates_to_the_internal_graph_engine(self):
+        issues = self.skill("to-issues")
+        waves = self.skill("to-waves")
+        self.assertIn("delegate to the internal", issues)
+        self.assertIn("`to-waves` graph engine", issues)
+        self.assertIn("complete Program preview", issues)
+        self.assertIn("Internal Program graph engine", waves)
+        self.assertIn("compatibility entrypoint", waves)
+        self.assertIn("carries both", waves)
+        self.assertIn("never infer Program mode", waves)
+
+    def test_feature_identity_keeps_the_existing_decomposition_path(self):
+        text = self.skill("to-issues")
+        self.assertIn("Feature identity", text)
+        self.assertIn("PROMOTE", text)
+        self.assertIn("ATOMIC", text)
+
+    def test_normal_routes_name_only_the_planning_facade(self):
+        route_files = (
+            ".claude/skills/ask-matt/SKILL.md",
+            ".claude/skills/scale-check/SKILL.md",
+            ".claude/skills/setup-workflow/workflow-overview.md",
+            ".claude/skills/board-to-waves/SKILL.md",
+            "CLAUDE.md",
+            "README.md",
+            "docs/workflow.html",
+            "docs/methodology.html",
+            "docs/methodology.svg",
+        )
+        for path in route_files:
+            with self.subTest(path=path):
+                text = self.file(path)
+                self.assertIn("to-issues", text)
+                self.assertNotIn("→ `to-waves`", text)
+                self.assertNotIn("→ to-waves", text)
+
+    def test_dual_surface_planning_skills_are_coherent(self):
+        skill_snippets = (
+            ("to-issues", "single public Planning facade"),
+            ("to-waves", "Internal Program graph engine"),
+            ("ask-matt", "the user never chooses that engine"),
+            ("scale-check", "explicit Program identity selects the internal graph path"),
+            ("setup-workflow", "explicit Program identity"),
+            ("board-to-waves", "not directly to a hidden engine"),
+        )
+        for skill, snippet in skill_snippets:
+            with self.subTest(skill=skill):
+                claude = self.file(f".claude/skills/{skill}/SKILL.md")
+                codex = self.file(f".agents/skills/{skill}/SKILL.md")
+                self.assertIn(snippet, claude)
+                self.assertIn(snippet, codex)
+
+        support_files = ("workflow-overview.md", "board-sync.md")
+        for name in support_files:
+            with self.subTest(support=name):
+                claude = self.file(f".claude/skills/setup-workflow/{name}")
+                codex = self.file(f".agents/skills/setup-workflow/{name}")
+                self.assertEqual(claude, codex)
+
     def test_to_waves_finishes_with_every_wave_execute_ready_by_default(self):
         text = self.skill("to-waves")
         self.assertIn("## 7. Program completion contract", text)