The delivery constitution — sibling of ARCHITECTURE.md. That book governs how the software is built; this one governs how work is chosen, prepared, proven, and shipped — roadmap, issues, PRs, release. Same discipline: every principle names the practice it comes from and the gate that enforces it. A process rule that isn’t enforced is a comment, not a rule (D1). Gates not yet built are marked TO BUILD — honestly, the same way the architecture book ships green-on-empty gates — and tracked in the enforcement map.

​

0. The axiom

​

1. The Loop — the shape of the whole system

        ┌──────────────────────── THE WORLD ────────────────────────┐
        │  reports · incidents · Discord · support · probe results  │
        └───────────────────────────┬────────────────────────────────┘
                                    │  raw signal
                    ┌───────────────▼───────────────┐
                    │  1. INTAKE            (D2b)   │  ≤3 days: no signal dead-ends
                    └───────────────┬───────────────┘
                    ┌───────────────▼───────────────┐
                    │  2. PREPARE  (D-R1/2 · D5/6 · │  isolate → a ready, harnessed,
                    │     D10 acceptance floor)     │  merge-guaranteed issue
                    └───────────────┬───────────────┘
                                    │  seeded, in priority order
                    ┌───────────────▼───────────────┐
                    │  3. ROADMAP   (D2 · D3 · D-R3)│  one ordered queue, three tiers
                    └───────────────┬───────────────┘
                                    │  pick from the top / self-propose
                    ┌───────────────▼───────────────┐
                    │  4. CLAIM     (D14b)          │  heartbeat lease: 4h, renew or release
                    └───────────────┬───────────────┘
                    ┌───────────────▼───────────────┐
                    │  5. DELIVER (D-A · D6b · D-A2 │  human + agent: debug the hot loop,
                    │     · D-L the two loops)      │  package only the proven diff
                    └───────────────┬───────────────┘
                                    │  a PR: value bundle + diff
                    ┌───────────────▼───────────────┐
                    │  6. PROVE (D8 · D9 · D10 · D12│  non-author witnesses value; channels
                    │     ) + SECURE (D-S)          │  corroborate; diff passes review+security
                    └───────────────┬───────────────┘
                                    │  value-signed + acceptance floor met
                    ┌───────────────▼───────────────┐
                    │  7. RELEASE   (D15)           │  batch signed PRs → ship → credit signers
                    └───────────────┬───────────────┘
                                    │  shipped value
        ┌───────────────────────────▼────────────────────────────────┐
        │  8. CLOSE BACK (D16): your report → this fix → this        │
        │     release; come validate                                  │
        └───────────────────────────┬────────────────────────────────┘
                                    └──► back to THE WORLD

   Off-loop but first-class: INVALIDATED (D11) — honest-negative of a delivery ·
   DECLINE (D17) — honest-negative of a proposal or stale item · both are results, recorded.

​

2. Meta

​

3. The bridge to architecture

​

4. Roles and phases

​

5. The roadmap

​

6. The issue

​

7. The two loops — debug before you package

• #689 (the pre-tag real-spawn leg, so the packaging loop never has to be the debugger). [TO BUILD: #689, #690]

• choke point 2. have (receipt-level delivered-deployment gate; choke point 2 named) / [TO BUILD: #690 rehearsal probe]

​

8. Proof — PRs and validation

​

9. People

​

9b. The tags — the state machine’s alphabet

​

10. Release and closure

​

11. How this document changes

​

Part II — Operating the loop

​

The roadmap

• Lane — the business value: match it to what the contributor actually uses.
• Milestone — the version it gates (v0.12.x is the current patch stream; its progress bar is the roadmap-at-a-glance).
• Human bar — what validation costs in human terms: Desk check (read the bundle, eyeball the logs) · Operator run · Solo meeting · Small group (2–4) · Crowd 5+ · In-the-loop UX (walk the flow, judge the experience itself).
• Setup — the infrastructure floor: None · Lite (one laptop) · Compose · k8s/helm.

​

The state machine

​

PREPARE protocol

​

The prompt

​

Step 0 — Read the law

​

Step 1 — Gather the signal (D4: symptoms only)

​

Step 2 — Ground in the code as it is (D4, D-A)

​

Step 3 — The D5b split/bundle verdict (explicit, first)

• Would splitting force the same diff into two issues? → bundle: one issue, one value sentence PER value, one acceptance row + preferred validator per value.
• Would bundling staple independent diffs into one PR? → split: emit a split recommendation (two prepared issues) instead of one bloated issue.
• Adjacent-but-different-diff work → a same-setup: note naming the batch, never a merge.
• Platform rule (the perceiver bounds the atom): in-meeting behavior prepares ONE issue per platform, even when the engine diff is shared — a Meet user won’t debug Teams, and a validator signs only the platform they sit on. The first platform issue claimed carries the shared-engine change; siblings reference it and validate their own platform’s fixtures + live leg.

​

Step 4 — Write the body (template sections, in order)

1. Title — name the bug and explain it, plainly (D3: named by the problem): for fixes, component: the defect — its consequence (house example: “api-gateway: shared HTTP pool starves token validation under load — valid API keys mass-401”); for probes, the question being measured; for features, the capability. Never an aspirational state-sentence (“The API answers while…”) — the title states what is wrong, not the world after the fix.
2. Value this issue delivers — one witnessable sentence per value (D5/D5b), FIRST: the reader decides whether to care before anything else, so the value leads the body.
3. Why this matters — dry, factual stakes: what a user loses, what depends on it, what was observed and where (D3).
4. Where we are (honest) — current-code facts, file:line for every claim. Unknowns stated as unknowns. The era note is mandatory when the report predates the current tree: state the report’s version/era vs today’s code explicitly — an old-era report means we are validating new code against a known failure mode of the old code, and the body must say so in those words, so nobody mistakes an inherited symptom for a confirmed present-tense bug.
5. Components — each exactly ONE module or seam, Target: a real path (D5, D-A); each a business-named waypoint with early validation in that module’s own harness lane and a named fixture range — deterministic producer / captured live output / hand-authored edge case (D-A2). A solution needing two modules is two components.
6. Prepared solution + along-the-way forks — mechanism, files, steps, and the branches a contributor may actually hit (D6). Alternates welcome, never required.
7. Acceptance table — the floor that guarantees merge (D10). Every row: discriminating (red→green pair), controlled (negative control shown red), anchored (sha/id/timestamp), complete (no-regression rows). One discriminating row per stated value (D5b). Floor, never ceiling — extending value is welcome and credited.
8. Deployments to validate (D12b) — which of Lite compose / full compose / k8s-helm / hosted the table runs against, which are explicitly out of scope, and whether Lite needs its own run (say so either way — Lite takes the most divergent path). State that every attestation must name its setup + build provenance (sha, compose/values file, fresh-clone vs long-lived, env deltas).
9. Docs surface (D6c) — the pages this change must touch and at what altitude: quickstart step / how-to / reference / concept, each for its reader. Usually several files. “No docs impact” must be argued, never assumed.
10. Live bar (D12) — scaled to the observation: speaker behavior 2–5 people, join/API one operator, a parser none. Never more humans than the observation requires.
11. Validation request (D9) — the preferred signer is the originating reporter(s), named; any competent non-author qualifies. Multichannel: what the bot did, what the human saw, what the instruments recorded — channels must corroborate.
12. Principle check (D7, fix-requests only) — the architecture principle this defect indicts (verbatim) and the gate that should have caught it; if none covers it, say so — that is a constitution finding.

​

Step 5 — Labels, board, closures

• Labels: state: prepared (only a maintainer flips to ready) · kind: fix-request | evaluation-request | probe · legacy type:* kept · area:* · P0 only if production-critical.
• Board: where it sits in the one ordered queue, and its same-setup: batch note.
• Supersede list: which raw issues close into this one, each with a drafted closing comment that links here and invites the reporter to validate when it ships (D16).

​

Step 6 — Self-audit, then emit

1. the D5b verdict, 2. the full issue body, 3. the label set, 4. the supersede/close list with drafted comments, 5. open questions for the maintainer — anything you could not ground in code or signal. Never guess to fill a section; an honest open question beats a confident invention.

​

Honesty rules (override everything)

​

TAKE protocol

​

The prompt

​

Step 0 — Read the law and the claim

​

Step 1 — The bundle gate (before reading a line of the diff)

​

Step 2 — Floor mapping, in the issue’s own numbering

• presented — red→green pair shown, negative control shown red, anchors present (base+head shas, ids, timestamps); a green pr-value/gates run on the head sha is presented for every row those legs carry — link the run, don’t re-demand the row;
• partial — claimed but missing its control, its anchor, or its red side;
• missing — including the rows only a live leg can carry. The live row exists precisely because unit greens can lie; never waive it for a plausible diff — but route it to the cheapest rung that carries it (the ladder, §Validation) before routing it to a human.

​

Step 3 — The diff on its own axis

1. Does the change hold at the altitude of the claim (P19) — is user-facing behavior proven by a live leg, or only by unit green?
2. Do the negative controls actually discriminate — would the test stay green if the fix were reverted?

​

Step 4 — The plan-bug rule (own our half)

​

Step 5 — Tone (first contributions are load-bearing)

​

Step 6 — The verdict (exactly one)

• Floor met + diff sound → arrange the value validation: a non-author runs it live (preferred signer: the originating reporter, D16/D9), multichannel evidence corroborating, attestation naming setup + build provenance (D12b). On the signature: merge, label state: value-signed, credit author AND validator.
• Floor not met → CHANGES_REQUESTED with the row-by-row map from step 2 and the exact, finite path to merge — then restate the promise: present the table and this merges. Nothing beyond the floor may be demanded (value beyond it is welcomed and credited, never required).
• Diff unsound → CHANGES_REQUESTED with the grounded findings; pair every 🔴 with the fix direction the issue’s prepared solution already implies.
• Wrong work entirely (doesn’t deliver the claimed issue) → decline honestly: what it would take, what would reopen it, and whether the diff carries value worth its own issue.

​

Step 7 — After merge: close the loop

​

Honesty rules (override everything)

​

Debugging — the hot loop

​

Validation

​

The ladder — machine first, human last

• The machine presents what the machine can prove. A green pr-value run on the PR’s head sha is the live-leg evidence row for backend-visible behavior — TAKE step 2 consumes it directly. Contributors hand-assemble only the rows above the automation line: platform-specific behavior, UX, real external services. Never ask a contributor or a human validator to re-witness a rung the harness already witnessed on their exact sha.
• Claim only your rung (P19/D12 restated for the ladder). pr-value green does not claim audio→words; L3.5 green does not claim real-Meet admission. Every rung’s report names what it proved AND the rungs it explicitly does not reach — an over-claimed rung is a false green, treated as an incident (the v0.12.1 lesson: a machinery-green release was published as if value-witnessed; the witness was still unsigned).

​

The human signature

​

Integration — the merge bar

​

Release — the ship bar

1. Batch — the value-signed merges since the last release, cut on the version milestone.
2. Validate together — the release machinery proves the batch as a whole (the compose stack bot-ready end-to-end, L4 evidence); individually-proven changes can still interfere.
3. Publish — images built and pushed; tags move per the declared tag policy (:v012 moves every release; :latest only by explicit, policy-conformant promotion) — artifact pointers are part of the release’s truth surface.
4. Credit + coverage — release notes name authors and validators, per change (D11/D15), and carry the coverage statement: which deployments/platforms each change was validated on and which stay honestly unclaimed (D12b). A release is proven on what we name — never a bare “works”.
5. Close back — every issue in the batch closes with the release; its reporter is invited to validate on the shipped artifact (D16). An issue closed without its reporter hearing about it is an unclosed loop.
6. The milestone ticks — the public progress bar is the release ledger.

• PR-level value is machine-witnessed. A PR’s value rows are proven by the harness on its own sha (pr-value, path-aware legs); no human eyeballs individual PRs. A PR reaches the human only as proven value + reviewed diff — or when it needs a genuine ruling.
• Every release carries ONE combined-value witness pass. The release generates a witness script from the batch: a single live session (one real meeting on the release candidate + one product walkthrough) in which every user-visible value shipped in the batch is experienced once. The autonomous legs surround it; the human contributes the irreducible minimum — admit the bot, speak, walk the script (~10 min). Backend-invisible changes are listed under the script with their machine evidence, witnessed by proxy and named as such.
• Publish and promote are the same act for witness purposes: neither happens before the witness pass is signed. A release published unwitnessed is retracted to pre-release until the pass is met.

• Re-verdict in ≤10 minutes, no rebuild. The release verdict (the validate legs) must be re-obtainable against already-published artifacts without rebuilding anything unchanged. Build+publish and validate+promote are separate machinery; a harness fix re-runs only the second. · Gate: release-validate is independently dispatchable with a version input.
• Harness fixes iterate off-main. A validation-harness change is testable from its branch against the published set before it merges — a smoke-script fix must never cost a PR→merge→full-pipeline round trip per attempt (the v0.12.1 maiden run paid 3 × ~20–50 min for two one-line harness fixes; this law is that bill, paid once).
• Silence is an incident signal. A triggered release run that has produced no first job within 10 minutes is stuck, not slow — check the runner queue instead of waiting (the same maiden run lost 50 minutes to an unwatched queue stall).

​

The guarantee — what every release promises, and what proves each line

1. Every artifact users pull is the artifact we proved. All images — services, agents, workers, bot — published, and validation ran against those published bytes, never a local build. · Proof: release-validate pulls-only; the install digest audit (#569).
2. The product works end-to-end on every documented install path. Compose, lite, Kubernetes: up from scratch, product FSM green. · Proof: the deployment-shape matrix.
3. Real audio becomes correct, speaker-attributed words. Fixture audio → real pipeline → real STT, exact-words oracle, both pipelines. · Proof: the wav→words leg (#560); until it ships, this line reads “proven at the witness pass only” — and the notes say so.
4. A fresh machine with nothing on it succeeds. Clean cloud VM, documented install, working bots. · Proof: the fresh-VM leg, born and destroyed per release.
5. Nothing that worked before broke. Prior-release behavior holds; 0.10 clients still function; deliberate breaks recorded by name. · Proof: v010-compat + no-regression rows.
6. Every image contains what its name promises. · Proof: image-identity leg.
7. A human witnessed the assembled value. One live pass on the release candidate — real meeting, real words, every user-visible batch change walked once — signed by the human who did it. No signature, no release. · Proof: the witness pass.
8. Every change in the batch was individually proven before it entered. Machine-validated on its own tree, diff-reviewed, merged through the card. · Proof: pr-value + gates green on each merged head.
9. The notes tell the truth about coverage. Proven-on-what-we-name, per path, per leg; the honestly-unclaimed list explicit; every author and validator credited; the loop closed to every reporter. · Proof: the guarantee block is machine-generated from run results.
10. Pointers moved honestly. :v012 only after all of the above; :latest only by explicit ruling; the 0.10 line never touched. · Proof: promote’s constitutional guards.

​

The two choke points

1. What you get — the value in one or two sentences, in user terms.
2. Is it real? — the proof, honestly: which machine legs ran green on this PR’s sha (linked), what the contributor witnessed themselves, and — never omitted — what is NOT yet proven and which later gate carries it.
3. The change — the diff in plain words: what was touched, how big, where the risk sits, what the review found (fixed or outstanding).
4. Your decision — the exact ask, one sentence, and what changes on each answer.

​

Asking the human

• One concern per ask, one ask at a time. Never a wall of parallel questions; the queue is ours to hold, not theirs to untangle. The next ask waits for the verdict on this one.
• The full bundle in one shot. Everything the decision needs arrives together: the value at stake, the reasoning, the architecture implications, the recommendation with its trade-off — no follow-up round-trip to assemble context the asker already had.
• No jargon — readable at both altitudes in the same text. The CEO reading (what value, what risk, what it costs) and the CTO reading (which module, which principle, which gate) must both land without translation. Codenames and session shorthand never survive into an ask.
• Say exactly what the verdict changes. An ask is a decision with consequences, never an FYI; if nothing changes on their answer, don’t ask.
• One eyeball request at a time (the validation form of the same rule): a human validation ask names one flow, fully instructed, earned by a green instrument first — never “try again” as a probe (D9’s human-red rule).

​

The maintenance cycle

​

The prompt

• No linked issue (pre-constitution or drive-by) → the era rule: a PR is signal + a candidate diff. Map it: delivers a now-prepared issue → invite adoption (author claims the issue; their diff meets its floor); valuable but unprepared → run PREPARE seeded by the PR; era-superseded → decline with credit and what would reopen it.
• Bundle missing → request it warmly (TAKE step 1) and stop there — never review a diff on vibes.
• Awaiting triage → run TAKE → one verdict.
• Changes requested → heartbeat check: active → wait; silent days → one nudge (issue + Discord); silent past the lease → release the claim, mark the PR draft, thank the author, requeue the issue.
• Floor met, awaiting validation → drive it: ping the preferred signer (the reporter); no signer in reach → recruit any competent non-author (the lane names the species); an owner-only leg → surface it to the owner explicitly per Asking the human, never let it wait silently.
• Value-signed → merge same-day (the promise, honored), label, credit in the thread.

​

Enforcement map