docs(ship): define orchestrator-composed ship units

[coreplane-switchboard]

Adds proposed record 0073: the guarded ship unit stays deterministic while an LLM orchestrator chooses each bounded act from fresh facts. The generated index now uses public vocabulary so the consistency gate can pass.

Why: The failed consistency check exposed the internal “runner” noun after F1’s record correction. Recovery failures in #2134, #2154, and #2153 need one authoritative boundary.

Where to look

1. Decision and success criteria Defines the guarded unit machine as the atom, the orchestrator as composer, and graph recovery as retired. ⚠ A blurred boundary could let model judgement bypass deterministic guards.
2. Atom and orchestrator loop Separates machine-owned transitions from judgement between bounded acts and preserves the reviewer wall. ⚠ Approval, gates, admission, and merge must remain deterministic.
3. Reconciliation rules and fixtures States parent cardinality, parked questions, in-unit conflicts, pushed-tree gates, thread resume, and durable adoption. ⚠ Duplicate resume or a missing retained head would recreate lost or rival work.
4. Preserved decision boundaries Attributes one-thread-per-unit to record 0055 and keeps ownership, admission, vocabulary, transcript, and merge guards unchanged.
5. Three-cut rollout and pending gate Flags reconciliation, turns incidents into fixtures, then retires the rival composer while acceptance stays gated.
6. Adversarial correctness amendment Records eight objections, distinguishes accepted authority from implementation, and leaves independent evidence pending.
7. Generated decision index Publishes record 0073 with user-facing “pipeline graph” wording and the truthful proposed status.

Feedback wanted: Judge whether the atom/composer boundary is mechanically enforceable and whether each conflict, question, re-issue, and rolled parent has one truthful next state.

Risk: Docs-only proposal. A wrong boundary could direct implementation toward dual ownership or model-controlled guards; rollback is reverting the record and generated index before acceptance.

Verified: Local gates pass; CI bot, workers, image, docs, web, and package checks pass. CodeQL and the independent cold-reader gate remain pending.

Decisions (3)

• Translate at the published index boundary. The decision record needs the precise internal mechanism, but its generated index is a user surface. Replacing “plan runner” in the record title with “pipeline graph” preserves the distinction while satisfying the vocabulary contract.
• Distinguish accepted authority from implementation. Rebasing brought record 0072's acceptance onto the branch, but its implementation is still pending. The record now names it as accepted while retaining the durable projection as a rollout dependency.
• Keep acceptance separate from author review. The dated amendment is an author-side adversarial pass, not independent evidence. Status remains proposed until the maintainer records a cold reader's quoted restatement, hardest part, and first objection.

Validation (6 criteria)

Criterion	Proof
The formerly failing CI checks succeed	ci / bot and ci / bot / check:consistency completed successfully at pushed head 5e3f14e.
The local consistency command succeeds	npm run check:consistency passed at rebased head 5e3f14e, including docs, decisions, hygiene, specs, and vocabulary checks.
Changed documentation is formatted	npx prettier --check <record> docs/explanation/design-decisions.md passed after the final rebase.
The PR title is an accepted changelog line	npm run check:pr-title -- "docs(ship): define orchestrator-composed ship units" passed.
The pushed range has no whitespace errors	git diff --check origin/main...HEAD passed at pushed head 5e3f14e.
Independent acceptance evidence remains human-gated	No independent cold-reader receipt was produced in this run; record 0073 remains proposed.

For agents

Rebased onto origin/main at 4bcc7f07; the generated index conflict was resolved by rerunning npm run docs:gen, not hand-editing. Main accepted record 0072 during the rebase, so record 0073 now distinguishes accepted authority from unimplemented state. F1 remains fixed at lines 15 and 130 through record 0055. The single coherent commit is 5e3f14e0; no tests or TypeScript checks apply because only Markdown changed.
Requested by @justinhelmer in slack:C0BRRHKFLCB

🤖 Generated with Claude Code

[coreplane-switchboard]

Changes requested: The record’s boundary section cites the wrong decision for the one-thread-per-unit rule.

Warning

Changes requested · head e43f3b7 · 1 finding: 1 minor

Severity	Finding	Where
minor	F1 Boundary attributes one-thread-per-unit to the wrong record	docs/decisions/0073-the-ship-pipeline-dissolves-into-the-orchestrator-the-unit-machine-is-the-deterministic-atom-and-judgement-composes-units.md:130

Full review

F1 — Record 0056 governs dashboard navigation, not one-thread-per-unit. That rule belongs to record 0055, which this record correctly cites at line 15. Change the boundary reference to 0055 so readers reach the authoritative decision.

[justinhelmer]

Cold-reader receipt for record 0073 (the acceptance gate). Run 2026-09-21 19:47Z by the maintainer's operator session: a fresh agent session that was handed only the record as it stands at e43f3b7c (no repository, no other files, no other context) and asked to restate the bet, name the hardest part, and state its first objection and whether the document already answers it. Its answer, verbatim:

1. Restate the bet. The record decides that the smallest deterministic thing in the system is one unit's machine — coding → review → fix → checks → merge, with its leases, single owner, admission, reviewed-head and fast-gate guards, rebase-before-push and merge door — and that everything above that atom becomes judgement: an LLM orchestrator reads each unit's named ending plus fresh repository and plane facts, then picks the next bounded act. What it replaces is the second orchestration system, the plan runner: the DAG walk with depends-on columns, the sequential cursor, the plan:merge versus merge: person column, attempts numbered by re-issue, the typed contract's stop rules, and the person-driven recovery vocabulary (agent:ship, agent:coding, pulls rebase). Plans survive as evidence the orchestrator reads and must cite when it departs from them, not as a program anyone executes. Authority is explicitly not part of the trade: where the effective grant says a person merges, a person still merges.

2. The hardest part. The parent cardinality invariant — that a live parent declares exactly one of a live child, a bounded wait, or an ending — is the part I judge hardest to get right, and the record agrees by ranking it first in the difficulty map. It is hard because the writers of those three facts can sit on different generations of the process, so the replacement has to be durable, atomic and idempotent across a roll that can kill the writer mid-transition; anything less and the orchestrator merely observes the same owner gap that #2134 produced instead of closing it. It is also the one rule that cannot be delegated to the model, since the model can roll too, so the plane must own the zero-or-many detection and the repair trigger in deterministic code. And its correctness currently rests on a dependency that does not exist yet: record 0072's state field is still proposed, which the document concedes blocks the claim that the rule shipped.

3. First objection. My first objection was that replacing a DAG with an LLM's choice makes scheduling unreviewable — if plan order is only "context", the orchestrator can quietly run a consumer before the schema change that feeds it and nobody can audit why. The document answers it in two places. Difficulty map item 7 states the requirement directly: "The orchestrator must cite why it departed from a written order, or 'judgement' becomes unreviewable scheduling by vibe." The "Why not keep depends-on as a hard guard?" section and amendment 6 add the safety half — the guards that must never soften live inside the unit machine and the merge door, while plan dependencies stay reasons the orchestrator should normally honor and must justify leaving, so a departure lands as cited fresh facts in the thread.

Verdict: passes

This is the independent receipt the record's cold-reader gate asks for. The acceptance ask that follows this PR carries it into a dated amendment note; this PR stays proposed as asked.

[coreplane-switchboard]

LGTM: The prior attribution finding is fixed, and no findings remain at the current head.

Note

Approved · head c9e82a6 · no findings

Full review

F1 is resolved: the boundary now correctly attributes one-thread-per-unit to record 0055. No findings remain.

[coreplane-switchboard]

LGTM: The rebase resolves the old-head consistency failures, and no findings remain in the full change.

Note

Approved · head 5e3f14e · no findings

Full review

The rebase updates the record and generated index consistently with record 0072’s accepted status. No findings remain.

[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.