Epic: contract-edge gates — planner wire-surface checklist, contracts registry, mock parity, assembly stage (from the 2026-07-10 one-CP retro)

[sawy3r]

Finding

A 17-slice release ran under full Baton discipline (per-slice fresh-context adversarial verification, all PASS) and every build halt was a planner-owned cross-slice contract seam — an agreement between two specs that no single spec owned and no per-slice verifier could grade:

1. Unpinned request-body shape — one spec said an endpoint "accepts the payload" without pinning the body shape against the handler's pre-existing validation gate; the consumer's body could never persist. Found three slices downstream.
2. Mock encoding the spec author's wrong assumption — a consumer slice passed legitimate adversarial verification with a latently-400 PUT because its mock and its spec shared the same wrong body-shape assumption. Implementer, tests, and verifier had a structurally shared blind spot.
3. New wire artefact with no owning slice — an If-Match header specced client-side and handler-side, but the CORS AllowHeaders between them was owned by nobody; every real-browser preflight failed. Invisible to every per-slice gate; caught only by an improvised live-browser assembly phase.

With strong models the failure class has moved up a level: gates now catch bad contracts, not bad implementations. Node-level gates verify slices against specs; every failure lived on an edge between two specs.

Full retro + evidence: fired repo, docs/captures/2026-07-10-baton-sworn-edge-contracts-proposal.md.

Recommendations (baton-side)

• Rec 5 — wire-surface enumeration in role-prompts/planner.md (Layer 4) + interim guard in the Phase 4 self-contained-spec checklist ("any AC satisfiable by a mocked boundary names the live-transport test that pins it"). Prompt-only, agreed do-first. Landed with this issue.
• Rec 1 — contract registry: contracts-v1.json schema (planner-emitted contracts.json, sibling to board.json: kind / surface / owner / consumers / live_test / fixtures), planner.md Phase 3b "build the contract registry" + Phase 4 "every wire artefact this spec names has a registry entry". Grading gate (sworn lint contracts) lands sworn-side after the schema is stable.
• Rec 2 — mock parity rule: a consumer slice may mock a registered boundary only with fixtures recorded by the owner's live contract test (file-based pact, inside the existing artefact model). Rule 2 extension / Rule 10 no-mock sub-rule + proof-schema fixture support.
• Rec 3 — first-class assembly stage: release state machine gains tracks-merged → assembled → journey-validated → merged; /merge-release hard-gates on assembled; Rule 10 wording becomes "journeys re-walked after assemble passes". Machine half (sworn assemble) lands sworn-side.

(Rec 4 — BLOCKED short-circuits the retry loop — is sworn-only and tracked in swornagent/sworn.)

Ordering ruling (Brad + orchestrator, 2026-07-10)

Baton-first, Sworn-second: Baton owns artefact shapes and rule semantics; sworn grades them. A gate cannot grade a record with no defined shape.

1. Pure-prompt items (Rec 5) — done.
2. Baton record/rule definitions (contracts-v1.json, mock-parity rule text, assembled state + Rule 10 wording) — governance changes, human-ratified.
3. Sworn implementations against the stable target.

Skew-window management (binding): every new Baton record lands optional-with-advisory (planner emits it; nothing hard-fails on absence) and flips to required only when the corresponding sworn gate ships. Fold in a version handshake: sworn declares which baton schema versions it grades (natural home: sworn doctor --sync-baton).

Validation set

The 2026-07-10 release folder is the test corpus: reconstruct the pre-fix state and assert each gate fires (lint contracts on the seam-1 specs → FAIL; mock-parity on the seam-2 test file → FAIL; assemble on the pre-fix tree → preflight failure surfaces).

Explicitly not proposed

No change to effort/complexity tiering (delegated slices were clean all day), no loosening of per-slice fresh-context verification (the gap was scope, not rigor), no new agent roles — gates and artefacts only, keeping the "records over roles" bias.

[sawy3r]

Rec 5 landed on main: c65c848 (baton/role-prompts/planner.md — Layer 4 wire-surface enumeration + Phase 4 live-transport-pin checklist item). Proof bundle: docs/captures/2026-07-10-rec5-wire-surface-checklist-proof.md. Installed copies synced to ~/.claude/baton/ and ~/.codex/baton/ role-prompt paths. Next per ordering ruling: step 2 governance items (contracts-v1 schema, mock-parity rule text, assembled state + Rule 10 wording) — human-ratified before any sworn implementation. Rec 4 tracked at swornagent/sworn#88.

[sawy3r]

Step 2 merged (#60, main 41c5797) and post-merge checklist complete: installed trees synced (~/.claude/baton + ~/.codex/baton, Codex path-rewrite applied; baton-merge-release skill regenerated), Rule 10 paragraph re-spliced into the user-level CLAUDE.md, and contracts-v1 published to baton.sawy3r.net/schemas/. Publishing also fixed a pre-existing gap: SIX record schemas (board-v1, spec-v1, proof-v1, journeys-v1, attestations-v1, verifier-verdict-v1) had $ids that 404'd in production — all 12 schemas now resolve 200, and the site's /schemas manifest lists them. Baton-side Recs 1/2/3 are done (advisory until graded); step 3 (sworn: lint contracts, fixture checks, assemble, doctor --sync-baton handshake) is unblocked — swornagent/sworn#88 remains the independent Rec 4 item.

[sawy3r]

assembly-proof-v1 ratified + published (main 0a75b02; https://baton.sawy3r.net/schemas/assembly-proof-v1.json). This was the last artefact shape blocking a fully mechanical tracks-merged → assembled → journey-validated → merged chain — the assembly stage was ratified in step 2 but assembled had no proof schema, so sworn's assemble gate couldn't be built without inventing the shape (which the ordering ruling forbids). Grounded in the fired 2026-07-10 improvised run: per-suite results with a product-regression/spec-defect/by-design-excepted/environment-blocked disposition axis, boundary/preflight observations (the CORS class), and a required ss-verified teardown block (Rule 11). Structurally fail-closed — non-pass needs a disposition, excepted needs tracking (Rule 2). 13 schemas now hosted. All baton-side step-2/step-3 artefacts are now shipped; the sworn work list (W1–W4) is handed off (swornagent/sworn, docs/captures/2026-07-11-contract-edge-step3-handoff.md), with W4's only remaining blocker being fired#1168 (derive_ports).