@ikon85/agent-workflow-kit 0.32.1 → 0.33.0

package/.claude/skills/orchestrate-wave/references/dispatch-subagents.md

@@ -0,0 +1,79 @@
+# Path B — Native subagent dispatch
+
+Load this recipe only when the capability selector returns Path B. That result
+requires proven native spawn, wait, and aggregate primitives plus effective
+concurrency and thread capacity ≥2. Route from proven capabilities only, never
+from a surface name, and do not emulate a missing primitive.
+
+This recipe is **dormant on the current Codex host.** A verify spike against
+codex-cli 0.144.6 (2026-07-21) proved native start plus bounded wait, and an
+effective concurrency of 4, but the host exposes tool entries carrying only a
+name and a description: no tool schema, no callable or permitted flags, no
+thread capacity. The adapter therefore emits `unknown` for those fields and the
+selector fails closed to Path C. Only a future host that supplies the complete
+normalized inventory selects this path.
+
+## Main-thread preparation
+
+1. Read the canonical `RECON_REPORT_SCHEMA` and `BUILDER_REPORT_SCHEMA` values
+   from `src/lib/reportValidator.mjs`. They are the same contract every
+   orchestration path reports against.
+2. Embed the relevant schema verbatim in each subagent prompt, together with the
+   instruction to return **exactly ONE JSON object** and nothing else — no
+   prose, no fences, no second object. The host does not enforce output shape,
+   so the contract lives in the prompt and the check lives in the main thread.
+3. Acquire the wave claim and create every worktree from the integrated base
+   through `claimWave` in `src/lib/waveClaim.mjs` before any spawn. Claim and
+   worktree creation stay serial in the main thread; only the agents fan out.
+
+## Round 1 — Recon
+
+Spawn **one read-only explorer per slice**, all in one batch so they run
+concurrently, then join them with an **explicit wait** on the spawned set —
+never a sleep, a poll loop, or an implicit continue. Aggregate only after the
+wait returns.
+
+Each explorer returns one recon report. Validate every returned payload against
+the recon schema in the main thread: a payload that does not parse, carries
+extra top-level keys, or fails the schema **is not a PASS** — it is a missing
+report. Re-spawn that single explorer with the failure quoted back to it; never
+accept a prose summary in place of the object.
+
+## Main-thread reconcile boundary
+
+Pass the complete, validated recon set to `reconcileReconReports`. A
+reconciliation failure stops the wave. A successful result is the only boundary
+that permits builders to start; use its overlap graph and dependency edges to
+cut safe dispatch batches. Multiple editors are safe only when dependency
+reachability totally orders them; shared-mutable files still require exactly one
+edit owner.
+
+Every orchestration path crosses this same main-thread reconciliation boundary.
+Reconciliation is never delegated to a subagent.
+
+## Round 2 — Build
+
+For the current reconciled batch, spawn **one builder per slice**, again as one
+concurrent batch joined by an explicit wait. Give each builder the verbatim
+builder contract, its reconciled allowlist, and its required commands. The host
+exposes no per-agent role, model, or reasoning selector, so routing falls back
+to the parent session configuration — record the tier you intended in the
+prompt itself rather than assuming the host honoured it.
+
+Each builder returns exactly one builder report. Validate it against the builder
+schema and then run `semanticVerify` on it in the main thread. A subagent's own
+claim of success is a hypothesis, never the gate.
+
+## B1 fan-out is out of scope
+
+The **B1** shape — a single fan-out over a work list (`spawn_agents_on_csv`)
+plus a host-enforced per-agent `output_schema` — is explicitly excluded. The
+same spike found the callable spawn schema exposes only `task_name`, `message`,
+and `fork_turns`: no work-list fan-out and no output-schema parameter. This
+recipe therefore documents the **B2** shape only: explicit per-slice spawns
+joined by an explicit wait, with validation owned by the main thread.
+
+Re-opening B1 requires its own version-pinned verify spike — tracked as an open
+spike issue on the kit's own tracker — before any recipe or adapter change.
+Never infer the capability from a release note; prove it against the pinned
+runtime first.

package/.claude/skills/orchestrate-wave/references/dispatch-workflow.md

@@ -0,0 +1,58 @@
+# Path A — Scripted Workflow dispatch
+
+Load this recipe only when the capability selector returns Path A. That result
+requires the literal `Workflow` tool and every required primitive. Route from
+proven capabilities only, never from a surface name, and do not emulate
+Workflow. The current Codex host lacks complete capability evidence and selects
+Path C; a future host selects whichever path its evidence proves.
+
+## Main-thread preparation
+
+1. Read the canonical `RECON_REPORT_SCHEMA` and `BUILDER_REPORT_SCHEMA` values
+   from `src/lib/reportValidator.mjs`.
+2. Serialize each value as an inline schema literal in its generated Workflow
+   script. Workflow scripts cannot import modules, so never put an `import()`,
+   `require`, `process`, or `fetch` workaround in them.
+3. Build deterministic run arguments. Pass run identity, slice IDs, prompts,
+   models, effort levels, and timestamps through `args`; never call
+   `Date.now()` or `Math.random()` in a script.
+
+## Run 1 — Recon
+
+Declare the named recon phase in `meta.phases`. Within it, make one `agent()`
+call per slice, with explicit `model`, `effort`, and `phase` options. Give every
+call the inline recon schema so the Workflow runtime rejects prose or malformed
+output before aggregation.
+
+Use the run identity supplied in `args` and retain the Workflow-managed
+`journal.jsonl`. The main thread waits for the Recon run to finish and collects
+its schema-valid reports. It must not dispatch a builder yet.
+
+## Main-thread reconcile boundary
+
+Pass the complete Recon-run result to `reconcileReconReports`. A reconciliation
+failure stops the wave. A successful result is the only boundary that permits
+the Build run to start; use its overlap graph and dependency edges to cut safe
+dispatch batches. Multiple editors are safe only when dependency reachability
+totally orders them; shared-mutable files still require exactly one edit owner.
+
+Every orchestration path, including Paths B and C, must cross this same
+main-thread reconciliation boundary. Reconciliation is not Workflow-script
+logic.
+
+## Run 2 — Build
+
+Generate a separate Build run with its own named entry in `meta.phases`. For the
+current reconciled batch, make one `agent()` call per slice with explicit
+`model`, `effort`, and `phase` options and the inline builder schema. Preserve
+the reconciled allowlist and required commands in each verbatim builder prompt;
+the main thread still performs `semanticVerify` on every returned report.
+
+## Resume exactly once
+
+Resume an interrupted Recon or Build run with its recorded `resumeFromRunId`
+and the same deterministic `args`. Workflow returns cached results for completed
+agents: accept those results and dispatch only unfinished calls. Never create a
+replacement run for completed work, and never replay a completed builder. This
+makes each builder phase execute exactly once while the retained
+`journal.jsonl` remains the recovery and progress record.

package/.claude/skills/orchestrate-wave/references/report-contracts.md

@@ -0,0 +1,42 @@
+# Wave Report Contracts
+
+`src/lib/reportValidator.mjs` is the source of truth. The JSON blocks below are
+machine-checked mirrors for hosts that must inline a schema and cannot import the
+module. Do not edit a block without changing the exported constant first.
+
+## Recon report
+
+Required fields: <!-- fields:recon -->sliceId, plannedFiles, dependencyEdges
+
+`plannedFiles[].role` is `edit`, `consume`, or `sharedMutable`.
+`dependencyEdges` records directed slice dependencies as `from`/`to` IDs.
+
+<!-- schema:recon:start -->
+```json
+{"type":"object","required":["sliceId","plannedFiles","dependencyEdges"],"additionalProperties":false,"properties":{"sliceId":{"type":"string","pattern":"^[0-9]+$"},"plannedFiles":{"type":"array","items":{"type":"object","required":["path","role"],"additionalProperties":false,"properties":{"path":{"type":"string"},"role":{"type":"string","enum":["edit","consume","sharedMutable"]}}}},"dependencyEdges":{"type":"array","items":{"type":"object","required":["from","to"],"additionalProperties":false,"properties":{"from":{"type":"string","pattern":"^[0-9]+$"},"to":{"type":"string","pattern":"^[0-9]+$"}}}}}}
+```
+<!-- schema:recon:end -->
+
+## Builder report
+
+Required fields: <!-- fields:builder -->status, filesTouched, testDecisions, commands, commitSha, stopItems, visualVerify
+
+`status` discriminates the `oneOf`: PASS requires a full Git object ID and an
+empty `stopItems`; STOP requires at least one stop item and permits a null SHA.
+Schema validation intentionally accepts nonzero command exits. The orchestrator
+must additionally call `semanticVerify` before accepting PASS.
+
+<!-- schema:builder:start -->
+```json
+{"type":"object","required":["status","filesTouched","testDecisions","commands","commitSha","stopItems","visualVerify"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["pass","stop"]},"filesTouched":{"type":"array","items":{"type":"string"}},"testDecisions":{"type":"array","items":{"type":"string"}},"commands":{"type":"array","items":{"type":"object","required":["command","exitCode","summary"],"additionalProperties":false,"properties":{"command":{"type":"string"},"exitCode":{"type":"integer"},"summary":{"type":"string"}}}},"commitSha":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{40}$|^[0-9a-f]{64}$"},{"type":"null"}]},"stopItems":{"type":"array","items":{"type":"string"}},"visualVerify":{"type":"string"}},"oneOf":[{"required":["status","commitSha","stopItems"],"properties":{"status":{"const":"pass"},"commitSha":{"type":"string","pattern":"^[0-9a-f]{40}$|^[0-9a-f]{64}$"},"stopItems":{"type":"array","maxItems":0}}},{"required":["status","commitSha","stopItems"],"properties":{"status":{"const":"stop"},"commitSha":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{40}$|^[0-9a-f]{64}$"},{"type":"null"}]},"stopItems":{"type":"array","minItems":1}}}]}
+```
+<!-- schema:builder:end -->
+
+## Semantic facts
+
+Call `semanticVerify(report, { gitFacts, allowlist, requiredCommands })` with
+independently collected Git facts: `objectFormat` (`sha1` or `sha256`), the
+resolved `commitSha`, `baseIsAncestorOfCommit`, and `changedFiles`. The ancestry
+fact means the integration base is an ancestor of the builder commit. The helper
+verifies the full SHA against the repository object format and resolved commit, diff subset,
+required command presence, command exits for PASS, and PASS/STOP exclusivity.

package/README.md

@@ -349,8 +349,55 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 `--force` (overwrite pre-existing untracked files on `init`), `--yes` / `-y`
 (accept non-interactive update decisions).
 
+## Upgrade notes
+
+### 0.33.0 — capability-gated orchestration
+
+`kit-update` reconciles this release for you. These notes matter only if you
+maintain a **local fork of `orchestrate-wave`**: the blocks below changed
+behaviour, so a forked copy must re-apply them by hand or it keeps orchestrating
+the old way. Decision record:
+[`docs/adr/0002-capability-gated-orchestration.md`](docs/adr/0002-capability-gated-orchestration.md).
+
+- **Capability matrix, fail-closed.** The dispatch mechanic is selected from
+  host-supplied capability evidence, degrading A → B → C. Missing or `unknown`
+  evidence never proves a capability, and Path C (direct, serial) is always
+  available.
+- **No emulation of a missing primitive.** A host without a scripted workflow
+  runtime gets the simpler recipe, never a hand-rolled imitation of one.
+- **Codex Path B is native subagents.** Explicit per-slice spawns joined by an
+  explicit wait — dormant until a host supplies the complete normalized
+  inventory.
+- **JSON-schema reports plus independent verification.** Every path returns
+  schema-valid recon and builder reports and crosses the same main-thread
+  boundary; a builder's own PASS is a hypothesis until `semanticVerify` confirms
+  it against independently collected Git facts.
+- **Per-batch, post-hub worktree provisioning.** Worktrees are created serially
+  in the main thread from the integrated base after the hub lands, under an
+  atomic compare-and-set wave claim; reuse on a stale base now STOPs.
+- **Heartbeat during long gates.** Long-running gates report status rather than
+  waiting silently.
+
 ## Release notes
 
+### 0.33.0
+
+- added: `.agents/skills/orchestrate-wave/references/dispatch-subagents.md`
+- added: `.agents/skills/orchestrate-wave/references/dispatch-workflow.md`
+- added: `.agents/skills/orchestrate-wave/references/report-contracts.md`
+- added: `.claude/skills/orchestrate-wave/references/dispatch-subagents.md`
+- added: `.claude/skills/orchestrate-wave/references/dispatch-workflow.md`
+- added: `.claude/skills/orchestrate-wave/references/report-contracts.md`
+- added: `src/lib/capabilityMatrix.mjs`
+- added: `src/lib/reconcileReconReports.mjs`
+- added: `src/lib/reportValidator.mjs`
+- added: `src/lib/waveClaim.mjs`
+- changed: `.agents/skills/orchestrate-wave/SKILL.md`
+- changed: `.agents/skills/orchestrate-wave/references/builder-contract.md`
+- changed: `.claude/skills/orchestrate-wave/SKILL.md`
+- changed: `.claude/skills/orchestrate-wave/references/builder-contract.md`
+- changed: `scripts/worktree-lifecycle/setup.py`
+
 ### 0.32.1
 
 - changed: `.agents/skills/census-update/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.32.1",
+  "kitVersion": "0.33.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -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"
     },
@@ -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"
     },
@@ -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.1",
+  "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/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),