docs(ship): accept orchestrator-composed ship units

[coreplane-switchboard]

Accepts decision record 0073 with its independent reader receipt and a tree-backed correctness amendment. Adds a three-unit plan that can replace the plan runner without losing work, duplicating ownership, or weakening unit and merge guards.

Why: The acceptance request supplied the independent receipt, but record 0073 still needed a total, rollback-safe implementation contract over record 0072.

Where to look

1. Acceptance gates Records the cold-reader quote verbatim, including all three requested answers and the passing verdict.
2. Total reconcile rules Closes outcome coverage across unit endings, round outcomes, and approved-but-not-ready standing. ⚠ A missing class could strand work or admit the wrong next act.
3. Generation and fallback fences Requires atomic cardinality, composer epochs, lossless flag transfer, and unchanged machine and door guards. ⚠ Incorrect fencing could create two owners across a roll.
4. Rollout contract Names the flag, prerequisite, stop conditions, three cuts, and current plan runner's safe tail ownership.
5. Judgement fixture unit Makes each ending, two-generation race, question, conflict, salvage, and ended-thread adoption scenario executable. ⚠ This is the main correctness surface for work preservation.
6. Retirement unit Deletes the graph walk and recovery copy only after differential and zero-dual-owner gates pass.

Feedback wanted: Please judge the composer-transfer boundary during a mid-round flag flip and whether the eight-class reconcile projection is complete without softening a unit-machine guard.

Risk: Documentation only; incorrect requirements could guide a later unsafe ownership migration. Roll back by reverting the commit and leaving record 0073 proposed. No runtime or deploy change.

Verified: Focused links test and all scoped gates pass; full CI is green at 584e6e4. The post-merge main-file receipt remains human-gated.

Decisions (3)

• Transfer composer ownership only at durable act boundaries. Reading the flag per event was rejected because old and new generations could both act on one unit. A desired composer plus compare-and-swapped epoch lets an in-flight deterministic act finish once, then transfers all durable facts while fencing the old writer.
• Normalize endings, rounds, and standing together. A switch over UnitEnding alone was rejected: checks_failed is a ShipRoundOutcome, while approved-not-merge-ready is assembled from approval plus fresh pull-request facts. The plan requires a closed projection over all three sources and fails when a variant is added.
• Depend on record 0072's field, not an equivalent projection. A parallel durable projection was rejected because it would recreate competing state owners. Cardinality and the hosted parent's live-state transition must share one fenced mutation after record 0072 U1 lands.

Validation (10 criteria)

Criterion	Proof
The CI-reported documentation link failure is fixed	npx vitest run src/docs/links.test.ts — PASS, 1 file and 7 tests at rebased head 584e6e4.
Changed Markdown is formatted	npx prettier --check <3 changed Markdown files> — PASS after rebase.
Public tree gains no private imprint	npm run hygiene:check — PASS; 9 files and 37 listed hits remain, 138 lines allowed.
Spec proof references remain valid	npm run specs:check — PASS; 51 specs and 5656 proof references checked.
Decision and plan records remain valid	npm run decisions:check — PASS; 112 records valid against merge-base 2d6dd17.
Generated documentation matches its sources	npm run docs:check — PASS; all 12 generated files match.
PR title is an accepted changelog line	npm run check:pr-title -- "docs(ship): accept orchestrator-composed ship units" — PASS.
Full hosted verification passes	CI at 584e6e4 — 28 successful checks and 1 expected skipped docs deploy; bot aggregate and all four test shards passed.
Changed-set TypeScript	Not run locally: this documentation-only change touches no tsconfig or TypeScript source; hosted typecheck passed.
Acceptance receipt after merge	Human-gated: confirm main carries record 0073 as accepted and the new plan path; no deploy is required.

For agents

Rebased onto origin/main at 2d6dd17 and force-pushed coherent head 584e6e4. The failed CI shard was reproduced until src/docs/links.test.ts identified the repository-external relative link; that diagnostic shard command timed out after exposing the failure, so the full shard is not claimed locally. The focused links suite passes 7/7, and hosted shard 2 plus the aggregate bot gate are green. The receipt now links the exact public GitHub API comment URL by immutable repository and comment ids, preserving the public-hygiene baseline. docs/explanation/design-decisions.md is generated.
Requested by @justinhelmer in slack:C0BRRHKFLCB

🤖 Generated with Claude Code

[coreplane-switchboard]

LGTM: The acceptance amendments and three-unit plan satisfy the decision's gates and preserve the existing machine and merge-door guards.

Note

Approved · head 758b77a · no findings

Full review

No findings. The acceptance amendments and implementation plan satisfy the unit contract without weakening existing guards.

[github-actions]

Auto-approved: coreplane-switchboard[bot] reviewed this PR and posted an LGTM verdict (see its review). This repository opted in through its REVIEW_BOT_LOGIN and REVIEW_BOT_ID variables.

[coreplane-switchboard]

LGTM: The receipt-link fix is valid, and both prior CI findings are resolved at the current head.

Note

Approved · head 584e6e4 · no findings

Full review

No findings. The receipt link is valid, and both previously failing CI checks now pass at the reviewed head.

[github-actions]

Auto-approved: coreplane-switchboard[bot] reviewed this PR and posted an LGTM verdict (see its review). This repository opted in through its REVIEW_BOT_LOGIN and REVIEW_BOT_ID variables.