@ikon85/agent-workflow-kit 0.32.0 → 0.33.0

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.32.0",
+  "kitVersion": "0.33.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -47,7 +47,7 @@
       "ownerSkill": "census-update",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "sha256": "b122fe2eb46c070696e38660b021411458b455b7a4e977174f943f2ce4c00819",
       "mode": 420,
       "origin": "kit"
     },
@@ -377,7 +377,7 @@
       "ownerSkill": "kit-update",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "880766b7aef88760f6d79dd31c3333356eef060623fc053fc61f5d5611765bb8",
+      "sha256": "249a45761bcb95148b1567d1bc4d1b622b9b8c41519de4e67b1ef4e33c9ee9fd",
       "mode": 420,
       "origin": "kit"
     },
@@ -407,7 +407,37 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "a3c3dc04411372f509b07e67f82217eb9656933f7ce5101beb5c123c2272d0bb",
+      "sha256": "9f8012a21441a0faff31845f38338078134c11ac60417f0db50b2ee65f0cc6af",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".agents/skills/orchestrate-wave/references/dispatch-subagents.md",
+      "kind": "skill",
+      "ownerSkill": "orchestrate-wave",
+      "surface": "codex",
+      "installRole": "consumer",
+      "sha256": "38247cadf15179e6f916674118fed6f0a19eb1097f123183a91bb18802113943",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".agents/skills/orchestrate-wave/references/dispatch-workflow.md",
+      "kind": "skill",
+      "ownerSkill": "orchestrate-wave",
+      "surface": "codex",
+      "installRole": "consumer",
+      "sha256": "2e2be2fb931147cf232b33c9c23379bcce47558a25756d54f89c6ef2e8a365c3",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".agents/skills/orchestrate-wave/references/report-contracts.md",
+      "kind": "skill",
+      "ownerSkill": "orchestrate-wave",
+      "surface": "codex",
+      "installRole": "consumer",
+      "sha256": "4ecd45229e6558d7b47918616ed199682767f2fd7ff209f6ae97258cbf8aec24",
       "mode": 420,
       "origin": "kit"
     },
@@ -417,7 +447,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "7a94293b7db49f42497d34e6ae0fe9992ab1c770ae0766557618818d6d671c50",
+      "sha256": "bfb547225c6950d4566f87a0da42e85c4c5803236d5adc0787aba265d5c91a53",
       "mode": 420,
       "origin": "kit"
     },
@@ -567,7 +597,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "ec80f4ad36073e0c7c903434fa098d24f31b9d9a46ce55623782173ddba2e5f9",
+      "sha256": "d495758ae52bebd11c81bbe28fc5a1f9b614f972afdba55d1b728630d12cfee8",
       "mode": 420,
       "origin": "kit"
     },
@@ -1209,7 +1239,7 @@
       "ownerSkill": "census-update",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "3a04a2667005cae51cfad7952ff85fe43ba1ae390458b4ce746e23f6e872b3fb",
+      "sha256": "b122fe2eb46c070696e38660b021411458b455b7a4e977174f943f2ce4c00819",
       "mode": 420,
       "origin": "kit"
     },
@@ -1659,7 +1689,7 @@
       "ownerSkill": "kit-update",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "880766b7aef88760f6d79dd31c3333356eef060623fc053fc61f5d5611765bb8",
+      "sha256": "249a45761bcb95148b1567d1bc4d1b622b9b8c41519de4e67b1ef4e33c9ee9fd",
       "mode": 420,
       "origin": "kit"
     },
@@ -1689,7 +1719,37 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "a3c3dc04411372f509b07e67f82217eb9656933f7ce5101beb5c123c2272d0bb",
+      "sha256": "9f8012a21441a0faff31845f38338078134c11ac60417f0db50b2ee65f0cc6af",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/skills/orchestrate-wave/references/dispatch-subagents.md",
+      "kind": "skill",
+      "ownerSkill": "orchestrate-wave",
+      "surface": "claude",
+      "installRole": "consumer",
+      "sha256": "38247cadf15179e6f916674118fed6f0a19eb1097f123183a91bb18802113943",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/skills/orchestrate-wave/references/dispatch-workflow.md",
+      "kind": "skill",
+      "ownerSkill": "orchestrate-wave",
+      "surface": "claude",
+      "installRole": "consumer",
+      "sha256": "2e2be2fb931147cf232b33c9c23379bcce47558a25756d54f89c6ef2e8a365c3",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/skills/orchestrate-wave/references/report-contracts.md",
+      "kind": "skill",
+      "ownerSkill": "orchestrate-wave",
+      "surface": "claude",
+      "installRole": "consumer",
+      "sha256": "4ecd45229e6558d7b47918616ed199682767f2fd7ff209f6ae97258cbf8aec24",
       "mode": 420,
       "origin": "kit"
     },
@@ -1699,7 +1759,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "9690ec772a99131c225037dd4bca884e899c133a8e460c36b26a25d6c6c797e1",
+      "sha256": "c9b4308875d59415b074de8b98130d0c2378fda6a4d1e6ac9c332c74b9a9ea97",
       "mode": 420,
       "origin": "kit"
     },
@@ -1869,7 +1929,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "ec80f4ad36073e0c7c903434fa098d24f31b9d9a46ce55623782173ddba2e5f9",
+      "sha256": "d495758ae52bebd11c81bbe28fc5a1f9b614f972afdba55d1b728630d12cfee8",
       "mode": 420,
       "origin": "kit"
     },
@@ -2587,7 +2647,7 @@
       "path": "scripts/readiness.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "f5e8bc2e724f72d1aa9f94c4f8d87b8f4d3f9843797cd6ae59f48e563dc7c7fb",
+      "sha256": "9e7a9c6882e372f38383fe92d98ff2f818bae0be61a62301b7e9a6a2842dd21b",
       "mode": 493,
       "origin": "kit"
     },
@@ -2731,7 +2791,7 @@
       "path": "scripts/worktree-lifecycle/setup.py",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "c720cbff9123f136a53658671d880b9a73f9da4faa0611e37a2a981fa89cda92",
+      "sha256": "0021c50809373335e9dafe97196f42ad039152418baa49e2004b25ba33d137e2",
       "mode": 493,
       "origin": "kit"
     },
@@ -2751,6 +2811,14 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "src/lib/capabilityMatrix.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "9ea051edad14972281e8d19664eeec7dbd91d57b21e5d97e4eeea7323c5241e1",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "src/lib/manifest.mjs",
       "kind": "script",
@@ -2759,6 +2827,14 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "src/lib/reconcileReconReports.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "d433504b66c62f02e3c909fc8b664a1a2c0373a04138a0da919d3ce7d45ba56a",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "src/lib/release-apply.mjs",
       "kind": "script",
@@ -2775,6 +2851,14 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "src/lib/reportValidator.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "f5b06eecd244ee177f94c9afc9f0f04107493ed1e0d661cadc85cbe251591052",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "src/lib/semver.mjs",
       "kind": "script",
@@ -2790,6 +2874,14 @@
       "sha256": "f99d28d2053d55222650d2ca426509d3f56eec5ef70709bbf8c4a278bf80024e",
       "mode": 420,
       "origin": "kit"
+    },
+    {
+      "path": "src/lib/waveClaim.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "dba4a321283e4f3ac3ab87eb726ce193c7e874c4b5ebd5cd5bbea7d28bb67c97",
+      "mode": 420,
+      "origin": "kit"
     }
   ]
 }

package/docs/adr/0002-capability-gated-orchestration.md

@@ -0,0 +1,70 @@
+# Capability-gated orchestration: scripted-workflow / native-subagents / direct, fail-closed, no emulation
+
+Status: accepted (2026-07-22, issue #167)
+
+`orchestrate-wave` fans out recon and building across agents. The mechanic that
+performs that fan-out is not the same on every host: one host exposes a scripted
+workflow runtime, another exposes native subagent spawn/wait primitives, a third
+exposes neither. The skill ships from one body for both surfaces, so the mechanic
+cannot be baked into the prose — and a wrong guess is expensive, because a wave
+that half-dispatches leaves worktrees and branches behind.
+
+We decided to select the mechanic from **proven, host-supplied capability
+evidence**, never from a surface name and never from the model's own belief
+about what it can call.
+
+1. **A capability matrix over normalized tool entries.** The host supplies an
+   inventory; `capabilityAdapter.claude` / `.codex` only normalize what was
+   handed to them and perform no ambient discovery. Each entry carries
+   `callable`, `permitted`, a schema, and `capabilities: string[] | "unknown"`.
+   `classifyCapabilities` returns exactly one of three paths, and
+   `selectOrchestrationReference` returns one discriminated target: a reference
+   path for A and B, the inline marker for C.
+2. **Fail closed, A → B → C.** Missing or `unknown` evidence never proves a
+   capability. Path A additionally requires the *literal* tool name plus every
+   named primitive individually proven; Path B requires proven spawn, wait, and
+   aggregate plus effective concurrency and thread capacity ≥2. Anything short
+   of that degrades to Path C — direct, serial, in the main thread — which is
+   always available.
+3. **Never emulate a missing primitive.** A host without a scripted workflow
+   runtime does not get a hand-rolled imitation of one. The degraded path is a
+   different, simpler recipe, not the same recipe with the primitive faked.
+4. **The report contract is path-independent.** Every path produces the same
+   schema-valid recon and builder reports (`src/lib/reportValidator.mjs`, mirrored
+   in `references/report-contracts.md`), and every path crosses the same
+   main-thread boundary: schema validation, then `reconcileReconReports`, then
+   `semanticVerify` on builder reports. A subagent's own PASS is a hypothesis.
+5. **Progressive disclosure.** `SKILL.md` carries only the selector, the
+   invariants, Path C, and pointers; each path's recipe lives in `references/`
+   and is loaded only when selected.
+
+## Considered options
+
+- **Route by surface name** (Claude → workflow, Codex → subagents): rejected —
+  it is a claim, not evidence. A verify spike against codex-cli 0.144.6 found
+  native spawn and wait callable and concurrency ≥2, yet the host exposed tool
+  entries with only a name and a description: no schema, no callable/permitted
+  flags, no thread capacity. Name-based routing would have selected Path B on a
+  host that cannot prove it.
+- **Emulate the missing primitive** (hand-rolled fan-out where no workflow
+  runtime exists): rejected — it reproduces the failure modes the runtime exists
+  to prevent (run identity, resume-exactly-once, runtime output validation)
+  without any of its guarantees, and it fails at the worst moment, mid-wave.
+- **Fail open on unknown evidence** (assume a capability when the host is
+  silent): rejected — the cost asymmetry is severe. A false Path C is slower; a
+  false Path A or B strands a partially dispatched wave.
+- **One monolithic SKILL.md carrying all three recipes**: rejected — every
+  session would pay for two recipes it will never run.
+
+## Consequences
+
+- The current Codex host selects Path C. `references/dispatch-subagents.md` is
+  written and tested but **dormant** until a host supplies the complete
+  normalized inventory; that dormancy is pinned from both sides by tests.
+- Adding a path means adding evidence requirements and a reference, not
+  branching the skill body.
+- Hosts that improve their inventory reporting gain a faster path with no skill
+  change — the selector picks it up as soon as the evidence arrives.
+- The B1 fan-out shape (`spawn_agents_on_csv` plus a host-enforced per-agent
+  `output_schema`) stays out of scope until its own version-pinned verify spike
+  returns a positive verdict.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.32.0",
+  "version": "0.33.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/readiness.mjs

@@ -99,22 +99,53 @@ function section(text, heading) {
   return body.join('\n').trim();
 }
 
-async function prodVerdict(root, paths) {
-  const bodies = [];
+export async function inspectProdSections(root, paths) {
+  const sections = [];
   for (const path of paths) {
     const text = await readText(root, path);
-    if (text === null) continue;
     const body = section(text, '## Prod');
-    bodies.push(body);
+    const problem = text === null ? 'missing-file'
+      : (body === null ? 'missing-section' : (body ? null : 'empty-section'));
+    sections.push({
+      path,
+      state: body === null ? 'missing' : (body ? 'valid' : 'invalid'),
+      body,
+      problem,
+    });
+  }
+  return sections;
+}
+
+async function prodEvidence(root, paths) {
+  const sections = await inspectProdSections(root, paths);
+  const present = sections.filter(({ problem }) => problem !== 'missing-file');
+  const valid = present.filter(({ state }) => state === 'valid');
+  const empty = present.filter(({ problem }) => problem === 'empty-section');
+  if (!valid.length && !empty.length) {
+    return {
+      verdict: 'absent',
+      diagnostics: sections.map(({ path, problem }) => ({ path, problem })),
+    };
+  }
+  const malformed = present.filter(({ state }) => state !== 'valid');
+  if (malformed.length) {
+    return {
+      verdict: 'invalid',
+      diagnostics: malformed.map(({ path, problem }) => ({ path, problem })),
+    };
+  }
+  const bodies = [...new Set(present.map(({ body }) => body))];
+  if (bodies.length > 1) {
+    return {
+      verdict: 'invalid',
+      diagnostics: present.map(({ path }) => ({ path, problem: 'divergent-section' })),
+    };
   }
-  if (!bodies.length) return 'absent';
-  if (bodies.every((body) => body === null)) return 'absent';
-  if (bodies.some((body) => !body)) return 'invalid';
-  return bodies.every((body) => body === bodies[0]) ? 'valid' : 'invalid';
+  return { verdict: 'valid', diagnostics: [] };
 }
 
 async function evidenceVerdict(root, evidence) {
-  if (evidence.type === 'prod-section') return prodVerdict(root, evidence.paths);
+  if (evidence.type === 'prod-section') return (await prodEvidence(root, evidence.paths)).verdict;
   if (evidence.type === 'runbook-reference') return runbookVerdict(root, evidence);
   const verdicts = await Promise.all((evidence.paths ?? []).map(async (path) => {
     const text = await readText(root, path);
@@ -129,14 +160,17 @@ async function evidenceVerdict(root, evidence) {
 }
 
 export async function evaluateCapability({ root, capability, decision }) {
-  const evidence = await evidenceVerdict(root, capability.evidence);
-  if (evidence === 'invalid') return { state: 'invalid', clearDecision: false };
+  const prod = capability.evidence.type === 'prod-section'
+    ? await prodEvidence(root, capability.evidence.paths) : null;
+  const evidence = prod?.verdict ?? await evidenceVerdict(root, capability.evidence);
+  const diagnostics = prod?.diagnostics?.length ? { diagnostics: prod.diagnostics } : {};
+  if (evidence === 'invalid') return { state: 'invalid', clearDecision: false, ...diagnostics };
   if (evidence === 'valid') return { state: 'ready', clearDecision: Boolean(decision) };
-  if (decision === 'pending') return { state: 'pending', clearDecision: false };
+  if (decision === 'pending') return { state: 'pending', clearDecision: false, ...diagnostics };
   if (decision === 'not-applicable' && capability.allowNotApplicable) {
-    return { state: 'not-applicable', clearDecision: false };
+    return { state: 'not-applicable', clearDecision: false, ...diagnostics };
   }
-  return { state: 'missing', clearDecision: false };
+  return { state: 'missing', clearDecision: false, ...diagnostics };
 }
 
 async function loadManifest(root) {

package/scripts/test_census_update_contract.test.mjs

@@ -169,6 +169,20 @@ test('census-update coordinates the stable foundation API without a second engin
   assert.match(skill, /\.census\/profile\.json/);
   assert.match(skill, /\.census\/active\.json/);
   assert.match(skill, /schemaVersion/);
+  assert.match(skill, /every `localScanners\[\]\.test`/);
+  assert.match(skill, /shared project-local census check entry point/i);
+  assert.match(
+    skill,
+    /It must execute every declared focused test,\s+and both local CI and pre-push must transitively reach that same entry point\./i,
+  );
+  assert.match(skill, /executable wiring test/i);
+  assert.match(skill, /missing or partial[\s\S]*failed/i);
+  assert.match(skill, /previous active\s+census bytes are unchanged/i);
+  assert.match(skill, /idempotent/i);
+
+  const setupCensus = await text('.claude/skills/setup-workflow/census.md');
+  assert.match(setupCensus, /activation[\s\S]*durable[\s\S]*local CI[\s\S]*pre-push/i);
+  assert.match(setupCensus, /remove only[\s\S]*kit-owned census wiring/i);
 });
 
 test('brownfield bootstrap activates real surface coverage with a separate behavior overview', async () => {

package/scripts/test_orchestrate_wave_contract.py

@@ -21,6 +21,19 @@ CLAUDE_BUILDER = (
 CODEX_BUILDER = (
     REPO / ".agents/skills/orchestrate-wave/references/builder-contract.md"
 )
+CLAUDE_WORKFLOW = (
+    REPO / ".claude/skills/orchestrate-wave/references/dispatch-workflow.md"
+)
+CODEX_WORKFLOW = (
+    REPO / ".agents/skills/orchestrate-wave/references/dispatch-workflow.md"
+)
+CLAUDE_SUBAGENTS = (
+    REPO / ".claude/skills/orchestrate-wave/references/dispatch-subagents.md"
+)
+CODEX_SUBAGENTS = (
+    REPO / ".agents/skills/orchestrate-wave/references/dispatch-subagents.md"
+)
+CODEX_SURFACE = REPO / ".agents/skills/orchestrate-wave"
 
 
 # Outcome -> fragments whose conjunction proves that portable behavior.
@@ -32,10 +45,17 @@ BEHAVIORAL_PARITY = {
         "LOCAL annotated tag",
         "never push",
     ),
+    "compare-and-set claim protocol": (
+        "src/lib/waveClaim.mjs",
+        "claimWave",
+        "compare-and-set",
+        "acquired",
+    ),
     "owner-safe abort cleanup": (
         "this run planted",
         "On ANY wave STOP/abort",
         "Never delete a claim marker observed during a preflight collision",
+        "releaseWaveClaim",
     ),
     "dependency-aware retirement": (
         "topological",
@@ -91,6 +111,18 @@ class OrchestrateWaveContract(unittest.TestCase):
         ):
             self.assertIn(" ".join(fragment.split()), prose)
 
+    def test_builder_report_contract_is_identical_on_every_path(self):
+        """One report contract, whichever mechanic dispatched the builder."""
+        prose = " ".join(self.builder.split())
+        for fragment in (
+            "identical on every orchestration path",
+            "references/report-contracts.md",
+            "exactly ONE JSON object",
+            "src/lib/reportValidator.mjs",
+            "semanticVerify",
+        ):
+            self.assertIn(" ".join(fragment.split()), prose)
+
     def test_current_portable_contracts_survive_the_port(self):
         for fragment in (
             "project layer",
@@ -101,6 +133,110 @@ class OrchestrateWaveContract(unittest.TestCase):
         ):
             self.assertIn(fragment, self.skill)
 
+    def test_capability_selector_routes_exactly_one_orchestration_mechanic(self):
+        for fragment in (
+            "## Orchestration mechanics",
+            "literal `Workflow`",
+            "do not emulate",
+            "returns exactly one",
+            "references/dispatch-workflow.md",
+            "references/dispatch-subagents.md",
+            "Path C",
+            "Phase 1 uses the selected orchestration mechanics",
+            "Phase 2 uses the selected orchestration mechanics",
+        ):
+            self.assertIn(fragment, self.skill)
+
+        self.assertLessEqual(len(self.skill.splitlines()), 345)
+
+    def test_registry_ownership_distinguishes_safe_from_eager_registries(self):
+        prose = " ".join(self.skill.split())
+        for fragment in (
+            "declaration-only registries",
+            "may be predeclared by one hub",
+            "eager/validated registries",
+            "each appending only its own existing artifact after creation",
+            "dependency edges",
+        ):
+            self.assertIn(fragment, prose)
+
+        phase_one = prose.split("## Phase 1", 1)[1].split("## Phase 2", 1)[0]
+        done = phase_one.split("**Done when:**", 1)[1]
+        for fragment in (
+            "either one declaration-only owner",
+            "verbatim consume-only dependents",
+            "or an explicit serialized owner sequence",
+            "each owner appends only its own existing artifact",
+        ):
+            self.assertIn(fragment, done)
+
+    def test_phase_two_keeps_per_slice_routing_decisions(self):
+        prose = " ".join(self.skill.split())
+        self.assertIn("(a) inline vs delegate", prose)
+        self.assertIn("(b) tier + effort", prose)
+        self.assertIn("Standing rules", prose)
+
+    def test_path_a_reference_locks_the_two_run_dispatch_contract(self):
+        workflow = CLAUDE_WORKFLOW.read_text(encoding="utf-8")
+        for fragment in (
+            "meta.phases",
+            "one `agent()` call per slice",
+            "model`, `effort`, and `phase`",
+            "inline schema literal",
+            "Recon run",
+            "reconcileReconReports",
+            "Build run",
+            "resumeFromRunId",
+            "exactly once",
+            "journal.jsonl",
+            "timestamps through `args`",
+            "Date.now()",
+            "Math.random()",
+            "Every orchestration path",
+        ):
+            self.assertIn(fragment, workflow)
+
+        self.assertEqual(workflow, CODEX_WORKFLOW.read_text(encoding="utf-8"))
+
+    def test_path_b_reference_locks_the_native_subagent_contract(self):
+        subagents = CLAUDE_SUBAGENTS.read_text(encoding="utf-8")
+        prose = " ".join(subagents.split())
+        for fragment in (
+            "one read-only explorer per slice",
+            "one builder per slice",
+            "explicit wait",
+            "exactly ONE JSON object",
+            "reportValidator.mjs",
+            "reconcileReconReports",
+            "main thread",
+            "is not a PASS",
+            "waveClaim",
+            "spawn_agents_on_csv",
+            "output_schema",
+            "dormant",
+        ):
+            self.assertIn(" ".join(fragment.split()), prose)
+
+        self.assertEqual(subagents, CODEX_SUBAGENTS.read_text(encoding="utf-8"))
+
+    def test_codex_surface_carries_no_path_a_primitive_outside_its_pointer_target(self):
+        """B-surface prose must not require Workflow-only primitives."""
+        offenders = {}
+        for path in sorted(CODEX_SURFACE.rglob("*.md")):
+            if path.name == "dispatch-workflow.md":
+                continue
+            body = path.read_text(encoding="utf-8")
+            hits = [term for term in ("journal.jsonl", "resumeFromRunId") if term in body]
+            # The literal tool name is admissible ONLY inside the capability gate.
+            if "`Workflow`" in body:
+                gate = body.split("## Orchestration mechanics", 1)
+                remainder = gate[0] + (gate[1].split("\n## ", 1)[1] if len(gate) > 1 and "\n## " in gate[1] else "")
+                if "`Workflow`" in remainder:
+                    hits.append("`Workflow`")
+            if hits:
+                offenders[str(path.relative_to(REPO))] = hits
+        self.assertEqual(offenders, {})
+
     def test_claude_and_codex_surfaces_match(self):
         self.assertEqual(
             markdown_body(self.skill),