docs: one design document, written against the code

[thedancingdeveloper]

Consolidates the design documentation into one file, docs/DESIGN.md.

ARCHITECTURE.md, INTERNALS.md and COORDINATION-PLANE.md total ~1,480 lines, overlap by roughly half, and disagree with each other and with the code in several places. This adds a single document that says how the harness works and why it is shaped that way, current design only. Status, phasing, what is built and what has been proven belong to docs/STATUS.md, which is being written in parallel; nothing here duplicates it.

Shape

Organised around what a reader needs, not around how the code grew:

1. what this is, and the one idea — the gates are the product
2. the execution pipeline, and what each stage guarantees
3. the invariants, each paired with the failure that produced it — a claim is a lease; checks before the reviewer; never retry a spend cap; no global state in the retry path; checkpoint before the expensive gate; the reviewer fails closed twice; a policy refusal is terminal; unknown is never zero
4. model routing — roles, presets, chains, parking, classification
5. the dependency graph — an unresolvable required target is a blocker, not an assumption
6. state and durability — two databases, rollup-then-thin, redaction at the write boundary, the outcome vocabularies, attempts, holds, budgets, the coordination plane
7. project isolation
8. the API, and why there is no GUI
9. extension points — how a vendor is added without editing core

Where a document and the code disagreed, the code won

Each of these is named in the text rather than quietly corrected:

Older documents say	The code does
the implementer produces a unified diff; edits.py unmentioned	the implementer is asked for edit blocks and the harness computes the line numbers (D10, reopened 2026-08-05); a diff is still read
five dispositions, twelve reason kinds	six dispositions and nineteen reason kinds
the ledger, rooms, command service and oversight actor are "proposed, not built"	all four are built and tested — and unwired: nothing in the API or CLI constructs a ledger
a worktree per item	that is the session executor; the direct executor branches inside one checkout
LIMIT 200 on the claim scan	a keyset page over (attempts, item_id); the scan walks pages
events live in the audit database	there are two event tables — a live one sharing the queue's file, and the durable one with cost columns in its own database
"full jitter", random() * min(base * 2**attempt, cap)	the cap bounds the curve and the delay never falls below it; the doc's principle holds, its formula does not, so no formula is quoted
parking is per endpoint	per (endpoint, role), with the reviewer and planner ringfenced from endpoint-wide parks

Deliberately dropped

Phase orders, stage histories, "what is not built yet" lists, acceptance criteria, implementation programmes, the coordination plane's issue cross-references, and AUDIT-PLAN.md's metric catalogue — all of it is either status (STATUS.md) or process, and none of it is design. The audit rules that keep the numbers defensible are kept; the list of metrics to compute is not.

Adds only this file. The older documents are untouched — the deprecation banners and link fixes belong to the pass that owns them.

uv run ruff check ., uv run ruff format --check . and uv run mypy . all pass.

🤖 Generated with Claude Code