groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/groundwork-bet/workflows/03-decomposition.md

@@ -0,0 +1,246 @@
+# Phase 3: Decomposition (Milestones, Slices, Proof of Work)
+
+**Goal:** With the design locked, break the bet into the order of work and write — in prose — the proof each step must pass. Plan *just enough* to start building coherently: author the full **milestone ladder** — every rung's headline proof — but only the **first milestone's slices**. Each later milestone is sliced when its turn comes, in Delivery, re-derived from what the milestones before it actually taught — not guessed now and defended later. Agent-led, then reviewed: the agent proposes the breakdown and authors the proofs; the user reviews sequencing and the proofs. This phase produces **prose only** — the decomposition tree. No test code, no implementation code. The prose proofs are the contract; Delivery materializes them into a red suite and turns it green.
+
+This phase is where the bet becomes executable. Milestones define the demonstrable checkpoints — capability proofs at the contract, surface proofs in each surface's medium. Slices define the vertical units of work. Each milestone and each slice carries a **Proof of work** written in plain language: what it proves and how the suite will prove it. The milestone ladder is the bet's success signal made executable — each rung is a demonstrable state that must be **un-mockable** (a stub or double cannot satisfy it), and the rungs are ordered to retire the bet's biggest risk earliest. That prose is the definition of done the user approves — turning it green is Delivery's job, and the red board is generated from this approved prose at Delivery start (`workflows/04-delivery.md` Step 0).
+
+## Restrictions
+⚠️ **CRITICAL CONSTRAINT:** This phase produces **prose only** — the decomposition tree. You are FORBIDDEN from writing implementation code, and equally from writing test code: both belong to Delivery. The Proof-of-work sections describe each proof in plain language; the runnable red stubs are generated from them at Delivery start. Nothing a compiler or interpreter would run is authored in this phase.
+
+## Operating Contract
+
+This workflow operates under the protocols defined in `.groundwork/skills/operating-contract.md` (contract v1; Continuous Bet mode: Protocols 1, 2, 4, 8, and 9 apply). Read it before taking any other action.
+
+Protocol 1 applies throughout: milestone and slice discussions surface signals that belong elsewhere — future-bet instincts (`## Bets`), implementation details worth preserving (`## Design Details`). Capture them in `.groundwork/cache/discovery-notes.md` as they occur, then steer back to sequencing.
+
+## Step 1: Update pitch status
+
+Update `docs/bets/<bet-slug>/pitch.md` frontmatter to `status: decomposition`.
+
+## Step 2: Propose milestones
+
+Read every file in `docs/bets/<bet-slug>/technical-design/` in full — `01-ui-design.md` for the UI design subsections, `02-data-flows.md` for the business logic and data flows, `03-api-design.md` for the interfaces and their shapes, and `04-data-design.md` for the schema and data model. From these, decompose the bet into milestones — then present the breakdown for review before writing a single proof.
+
+**What a milestone is:** a demonstrable state the product reaches, ordered so each one is independently shippable. Its consumer gets value from Milestone 1 even if Milestone 2 never ships. Milestones come in two types:
+
+- **Capability milestone** — proves core behaviour headless. Its demonstrable state is a contract exercised end-to-end against the running services (or the embedded core's public API): curl-able, scriptable, observable, with no surface running. This amends the user-visible rule honestly rather than bending it: a capability milestone is *consumer-visible at the contract*, and the decomposition records who that consumer is — the bet's in-scope surfaces, whose milestones build on it; or, when the bet delivers headless, the latent agentic surface (the programmatic caller the promoted contract serves).
+- **Surface milestone** — proves a named surface delivers the capability to its users. Its demonstrable state is asserted in that surface's medium and bounded to wiring, rendering, and interaction — the business behaviour beneath it was already proven at the contract.
+
+**Degrade rule:** a project with no `docs/surfaces.md` has a single implicit surface — skip milestone typing and the slice `surface` field entirely; milestones are user-visible states in the product's interface medium, exactly as before this distinction existed. A single-surface registry types its milestones (one capability milestone, then surface milestones for the lone surface) with no extra questions to the user — the typing falls out of the design, not a conversation.
+
+**Decomposition constraints the agent must hold:**
+- A bet introducing new capability **opens with its capability milestone**; surface milestones follow and depend on it. The contract proof comes first because every surface milestone consumes it.
+- A bet may legitimately **end at the capability milestone** with every surface milestone deferred — a headless delivery. The pitch's surface no-gos predicted this, and validation records the deferral in the capability ledger.
+- Order by integration value *and risk*: the first milestone is the thinnest end-to-end flow that proves the architecture works **through the bet's riskiest real path** — the un-mockable proof that retires the biggest unknown comes early, not last. Later milestones add richness to that proven foundation. Front-loading risk is the point of laddering: a bet that proves its plumbing for three milestones and only meets its hard dependency at the end has surfaced its risk too late to act on cheaply.
+- Each milestone is independently shippable — dependencies flow forward only.
+- Milestones are never horizontal. "Build all the schemas" is not a milestone; it is invisible to every consumer and produces no demonstrable state. A capability milestone is not horizontal — its contract is demonstrable end-to-end, just at the API rather than on a screen.
+- 2–5 milestones is the healthy range. Fewer means the bet is probably not scoped in demonstrable increments. More means it is probably not a bet — it is a roadmap.
+
+Present the milestone list with the **sequencing rationale** for each: what architectural proof Milestone 1 provides, why Milestone 2 can only follow it, and so on. The review focuses on **ordering, typing, and whether each milestone names a demonstrable outcome for a named consumer** — not implementation detail. Revise the ordering until the user is satisfied before proceeding.
+
+## Step 3: Write each milestone's Proof of work (prose)
+
+For each approved milestone, write its **Proof of work** prose before moving to slices — the proof the user reviews and signs, in plain language, with no assertion code. A milestone's proof follows its type:
+
+**Capability milestone proofs** describe what is exercised against the contract directly — end-to-end against the running services (or the embedded core's public API): the request made, the response and persisted effect observed, the error case the milestone's outcome rests on. No surface is in the loop. Write it so a reader understands exactly what becomes true at the contract.
+
+**Surface milestone proofs** describe what that surface's users observe, in that surface's medium — `graphical-ui` what renders and how the user interacts, `cli` the command and its output, `agentic-protocol` the request and the response structure. **A surface proof never re-proves core logic** — the capability milestone already proved every business rule at the contract, and re-asserting one at a surface multiplies the test pyramid by the surface count for nothing. Surface proofs cover wiring, rendering, and interaction.
+
+**Degrade rule:** with no surface registry, write each milestone's proof as the two familiar layers — an interface-level proof in the project's single medium plus an API-level proof that localizes failures — exactly as before milestone typing existed.
+
+**Keep it to the headline proof.** A milestone's Proof of work is the small set of outcomes that prove its consumer-visible state — typically one to three. It does not enumerate every permutation, error code, or boundary; that granular coverage is the permanent best-practice tests rolled out per slice in Delivery (`workflows/04-delivery.md` Step 5), not the headline proof the user reviews. Include an error case here only when the milestone's demonstrable outcome depends on it.
+
+**The headline proof must be un-mockable.** The milestone ladder is the success signal made executable, so each rung's proof must be falsifiable by *reality*, not satisfiable by a *double*. If a stub, a mock, or a hardcoded return could make the proof pass, it is not proving the milestone — it is proving plumbing, and plumbing is never a milestone's success signal. A capability milestone's proof exercises the real dependency that makes the capability meaningful (the live model, the real external service, the actual store) — not a placeholder standing in for it. You may not defer the bet's central risk to a stub across the *whole* ladder: the milestone that retires that risk must engage the real thing. (If a real dependency genuinely cannot be reached in the test environment, name that constraint here and route it as a `BLOCKING CONCERN` in Delivery — never quietly redefine the proof down to what a stub can pass.) This is the decomposition-time complement to Delivery's *honest green*: honest green stops a proof that *named* real work from being hollowed during implementation; this stops a proof from being *authored* hollow in the first place.
+
+**The proof's shapes come from the prose design.** Every request, response field, and name a proof references traces to `docs/bets/<bet-slug>/technical-design/03-api-design.md` (or a store in `04-data-design.md`) — the prose design carries the shapes at design fidelity, and the proof rests on them. A proof that invents a shape the design does not define is describing a contract that does not exist; the review blocks it.
+
+Write the milestone's `Proves` / `How we prove it` / `Test file` into its `index.md` (Step 5) — the test file path is named here but the stub is not written until Delivery.
+
+## Step 4: Decompose milestones into slices
+
+Break the **first milestone** into **vertical slices** — the smallest units that are independently buildable, deployable, and verifiable. Author slices for the first rung only; the later milestones keep their headline proof but are *not* sliced yet. Each later milestone is sliced when its turn comes, at the prior milestone's postmortem in Delivery (`workflows/04-delivery.md`), so its slices are derived from what the milestones before it actually taught. The slicing discipline below is identical wherever it runs, whether now for the first milestone or on arrival for a later one.
+
+**The vertical-slice test:** *Can this slice be deployed and verified without any future slice existing?* If yes, it is vertical. If it requires a downstream slice to be useful, it is too thin or horizontal — merge it up or reframe it as a capability of a larger slice.
+
+Never slice horizontally: "all schemas, then all APIs, then all UI" is three horizontal passes. Each slice must cross whatever service boundaries are needed to deliver a testable capability end-to-end.
+
+Each slice spec must contain:
+- **Owner service** — the primary service this slice lives in (from `docs/architecture/infrastructure.md`)
+- **Surface** — `core` for a slice implementing capability-core behaviour, or the registry slug of the surface it wires (omit the field entirely when the project has no surface registry). The field drives delivery sequencing — core slices merge before the surface slices that consume them — and tells the reviewer which test discipline applies: contract proof for `core`, wiring-only for a surface.
+- **Complexity** — S / M / L
+- **Prerequisite** — the exact prior merge gate (e.g. "Slice 1.2 merged"), or none
+- **Scope** — a one-paragraph intro linking the slice to its parent milestone and stating what vertical capability it contributes, plus **Required Capabilities**: falsifiable behaviour statements, each tracing to an interface in `technical-design/03-api-design.md` or a store in `technical-design/04-data-design.md`. "The endpoint exists" is not falsifiable. "POST `/api/sessions` returns 201 with a `session_id` field when given a valid request body matching the API design" is.
+- **Design** — where the slice lands in the design: the interface it implements, the data flow it realizes in `02-data-flows.md`, and (for a surface slice) the view it wires in `01-ui-design.md`.
+- **Proof of work** — the slice's prose proof (Step 5): what it proves and how, the handful of outcomes that show its capability is present.
+
+## Step 5: Write the decomposition tree
+
+Write the reviewable artifact as a **browsable tree** at `docs/bets/<bet-slug>/decomposition/`, using the templates under `.groundwork/skills/groundwork-bet/templates/decomposition/` (the tool creates parent directories automatically):
+
+| Path | Content | Template |
+|---|---|---|
+| `decomposition/meta.json` | Sidebar order + the "Decomposition" title. | `decomposition/meta.json` |
+| `decomposition/NN-<milestone-slug>/index.md` | One folder per milestone; `index.md` is its landing page — type, consumer, demonstrable goal, sequencing rationale, acceptance criteria, **Proof of work** (Step 3), and links to its slices. | `decomposition/milestone-index.md` |
+| `decomposition/NN-<milestone-slug>/NN-<slice-slug>.md` | One file per slice — header, **Scope** (intro + Required Capabilities), **Design**, **Proof of work** (Step 4 / Step 5). | `decomposition/slice.md` |
+
+**The full ladder, the first rung sliced.** Write every milestone's `index.md` now — the complete ladder of headline proofs the user approves. Write slice files only for the **first milestone**. A later milestone's folder holds its `index.md` with the headline proof and its slice list deferred (the `milestone-index.md` template's *authored on arrival* affordance) until Delivery opens it; its slice files are written then. This is *plan just enough* on disk: the whole ladder is visible and reviewable, but only the rung you are about to climb is detailed.
+
+The `NN-` numeric prefixes order the milestone folders and the slices within each, so the tree reads top to bottom on the docs site as the order of work. Discover the project's test language and service names from the scaffold (`docs/architecture/infrastructure.md` and the generated `docker-compose.yml`) so each `Test file:` path names the right extension and owning service — do not hardcode a language or service name. The path is named; the stub is generated at Delivery start.
+
+**The slice's Proof of work is the prose proof.** Write each `Proves` / `How we prove it` from the slice's target-state intent — what becomes true and the observable condition that shows it — never assertion code. A `core` slice proves contract behaviour; a surface slice proves wiring, rendering, and interaction only. This is the headline proof, not every assertion: the granular edge-case and permutation coverage is added when the slice is built in Delivery.
+
+Apply `groundwork-writer` when drafting the tree — declarative, assertive, zero-hedging.
+
+## Step 6: Independent review
+
+The decomposition is the sequencing commitment this bet executes against. A milestone no consumer can observe, a slice that is horizontal, or a proof that does not trace to the design compounds into every delivery decision. The review pass catches these before the plan hardens.
+
+1. **Announce** the shift — the agent is moving from authoring into an independent review of the decomposition before presenting Proof of Work.
+2. **Assemble the tree for review.** The decomposition lives as a tree of files, so concatenate them into one document for the reviewer — a shell operation that consumes no output tokens regardless of size: `run_command("find docs/bets/<bet-slug>/decomposition -name '*.md' | sort | xargs cat > /tmp/<bet-slug>-decomposition.md")` (sorted so milestone and slice order is preserved). Then **invoke the review subagent** (Protocol 9) with `document_path: /tmp/<bet-slug>-decomposition.md` and `document_type: decomposition`. The gate is fail-closed (Protocol 8): proceed only on a parseable `VERDICT: PRESENT`; a review that errors, hangs, or returns no verdict follows Protocol 9's failure path.
+3. **Revise loop.** If the verdict is **REVISE**, apply every 🔴 Critical finding directly to the affected milestone `index.md` or slice file. Rewrite sections rather than annotating them. Re-assemble (`find docs/bets/<bet-slug>/decomposition -name '*.md' | sort | xargs cat > /tmp/<bet-slug>-decomposition.md`) and run the review again. The revise cap is a hard stop, not a target to push past: after 3 REVISE verdicts, stop, surface remaining 🔴 findings as 🟡 Advisory, and disclose that the review did not reach **PRESENT** (Protocol 8). Clean up the assembled file once the review settles: `run_command("rm /tmp/<bet-slug>-decomposition.md")`.
+4. **Carry advisory findings forward.** When the verdict is PRESENT, hold any 🟡 Advisory findings — they surface during the Proof of Work transition so the user can decide whether to act on them.
+
+The review verifies document-chain integrity — see the **Document Chain Integrity** section below for the exact checks the reviewer applies.
+
+## Decomposition Gate
+
+Before presenting Proof of Work, verify every item. This gate runs at initial decomposition over **the full ladder and the first milestone's slices**, and runs again — scoped to a single milestone's slices — each time Delivery opens a later milestone or introduces a new one (`workflows/04-delivery.md`):
+
+- Every milestone names a demonstrable goal a reviewer can trace to `technical-design/`: a surface milestone's user-visible goal traces to its surface's subsection in `01-ui-design.md`; a capability milestone's contract state traces to `03-api-design.md` / `04-data-design.md` (and the data flows in `02-data-flows.md`), with its consumer named.
+- Every milestone's headline Proof of work is **un-mockable** — falsifiable by the real dependency it names, not satisfiable by a stub, mock, or hardcoded return; the milestone that retires the bet's central risk engages the real thing.
+- When the project has a surface registry: every milestone is typed (`capability` or `surface (<slug>)`), the bet's new capability opens with its capability milestone, and every slice carries a `surface` value (`core` or a registry slug). With no registry, none of this applies — untyped milestones, no surface fields.
+- Every milestone has a **Proof of work** in its `index.md` — `Proves`, `How we prove it`, and a named `Test file:` path at `tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.<ext>`.
+- No surface milestone proof re-asserts a business rule the capability milestone proves at the contract — surface proofs are bounded to wiring, rendering, and interaction.
+- Every **authored** slice (the first milestone's at initial decomposition; the opened or introduced milestone's on arrival) is vertical — it can be deployed and verified without any future slice existing.
+- Every authored slice has falsifiable Required Capabilities, each tracing to an interface in `technical-design/03-api-design.md` or a store in `technical-design/04-data-design.md`.
+- Every authored slice has a **Proof of work** and a named `Test file:` path at `tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.<ext>`.
+- Every request shape, response field, and name a proof references traces to `technical-design/03-api-design.md` / `04-data-design.md` — no shapes the prose design does not define.
+- The `decomposition/` tree carries `meta.json`, **every** milestone `index.md` (the full ladder of headline proofs), and the slice files for **every milestone authored so far** — the first milestone at initial decomposition, the current milestone on arrival — with those slice links resolving. A later, unopened milestone legitimately has no slice files yet.
+
+A *missing rung* is not Proof of Work — the full ladder of headline proofs must be present and approved. But an unsliced *later* milestone is not a partial decomposition; it is the plan-just-enough design. What must be complete is the ladder plus the slices for the milestone now being authored.
+
+## Document Chain Integrity
+
+The review subagent applies these checks. The agent authoring the decomposition should apply them during Step 6 as well — they catch drift before it reaches the reviewer.
+
+| Document | Upstream check | Downstream check |
+|----------|---------------|-----------------|
+| Pitch | Solves the stated problem within appetite | Design covers the pitched solution |
+| Technical Design | Every surface element/flow traces to the pitch | Milestones can be derived from it |
+| Milestones | Each goal is consumer-visible value — at the contract for capability milestones, in the surface's medium for surface milestones — traceable to the design | Every slice belongs to exactly one milestone |
+| Slices | Required Capabilities trace to interfaces/stores in `technical-design/03-api-design.md` / `04-data-design.md` | Proof of work traces to milestone acceptance criteria |
+
+## Quality Standard: What Good Milestones and Slices Look Like
+
+A milestone is a demonstrable state the product reaches for a named consumer — at the contract for a capability milestone, in a surface's medium for a surface milestone — not a layer of the stack, not a phase of implementation. A slice is a vertical column through one component, not a horizontal pass. If neither description produces a name that means something to its consumer, the decomposition is wrong.
+
+**Shallow (insufficient):**
+
+```markdown
+## Milestones
+
+1. **Backend** — Build the database schema and notification service
+2. **Frontend** — Add notification UI components
+3. **Integration** — Connect frontend to backend and end-to-end test
+```
+
+**Deep (required standard) — a milestone `index.md`:**
+
+```markdown
+# Milestone 1: Notification lifecycle proven at the contract
+
+**Type:** capability
+**Consumer:** the `web-app` and `admin-cli` surfaces — Milestones 2 and 3 build on
+this contract.
+
+**Demonstrable goal:** An operation lifecycle event posted to the notification service
+produces a queryable notification record, and subsequent events update its status in
+place — provable end-to-end against the running services with nothing but an HTTP client.
+
+**Sequencing rationale:** This contract is what every surface consumes. Proving it
+headless first makes Milestones 2 and 3 wiring exercises against a known-good core —
+a red surface test can only mean a surface problem.
+
+**Acceptance criteria:**
+- [ ] `POST /internal/events` with a valid operation lifecycle event returns `202`, and
+  `GET /api/notifications` returns the corresponding record within 2 seconds.
+- [ ] A `completed` event for the same operation updates the existing record's status in
+  place — no duplicate record.
+
+## Proof of work
+
+**Proves:** A lifecycle event becomes a queryable notification, and a later event for the
+same operation updates that record rather than creating a second one.
+
+**How we prove it:** Against the running services with an HTTP client only — POST a valid
+event, then GET the feed and see the record within 2 seconds; POST a `completed` event for
+the same operation and see the one record's status change in place, with no duplicate.
+
+**Test file:** `tests/bets/notifications/test_milestone_1_notification_contract.py` —
+generated red at Delivery start; traces to the `POST /internal/events` and
+`GET /api/notifications` interfaces in `03-api-design.md`.
+
+## Slices
+- [Slice 1.1 — notification-service: Operation event intake](./01-event-intake.md)
+```
+
+The shallow version has horizontal milestones invisible to every consumer, no acceptance criteria, no sequencing rationale, and no proof. Its "Backend" milestone names a build activity, not a contract state anyone can exercise. The deep version opens with the capability milestone that proves the contract headless for named consumers; surface milestones follow, bounded to wiring in each surface's medium.
+
+**Deep (required standard) — a slice file:**
+
+```markdown
+# Slice 1.1 — notification-service: Operation event intake
+
+**Owner service:** notification-service
+**Surface:** core
+**Complexity:** M
+**Prerequisite:** none
+
+## Scope
+
+Wires the notification service to receive operation lifecycle events from the operations
+service and persist them as notification records. This is the notification-service's data
+foundation — every other slice depends on this record existing.
+
+**Required Capabilities:**
+- `POST /internal/events` accepts an operation lifecycle event matching the `OperationEvent`
+  shape in `03-api-design.md`; returns `202 Accepted`.
+- A notification record is created in the `notifications` table with status, message, and
+  operation_id populated from the event payload.
+- Duplicate events for the same operation_id + status are idempotent; a second identical
+  event produces no additional record.
+
+## Design
+
+Implements `POST /internal/events` from `03-api-design.md`, realizing the intake flow in
+`02-data-flows.md`, and writes the `notifications` store defined in `04-data-design.md`.
+
+## Proof of work
+
+**Proves:** An operation event sent to the service becomes exactly one notification record,
+and a repeat of the same event changes nothing.
+
+**How we prove it:** POST a valid event and confirm `202`, then query the `notifications`
+table and see one matching row; POST the identical event again and confirm the row count is
+unchanged; POST an event missing a required field and confirm `422` with no row written.
+
+**Test file:** `tests/bets/notifications/test_slice_1_notification_service_event_intake.py` —
+generated red at Delivery start; traces to `POST /internal/events` and the `notifications`
+store.
+```
+
+The slice's Proof of work is the headline proof of its vertical capability — not every permutation. The exhaustive edge-case and error-matrix coverage lands in Delivery's permanent best-practice tests, written when the slice is built.
+
+## Transition
+
+Present the decomposition tree as Proof of Work:
+
+- `docs/bets/<bet-slug>/decomposition/` — the sequencing commitment and the prose proofs, browsable milestone by milestone, slice by slice.
+
+Walk the milestone map first — ordering rationale, milestone types, demonstrable goals. Then walk the **Proof of work** sections **proof by proof**: for each milestone and slice, what it proves, where that traces in the design, and why it is the right proof. The proof is prose, but the scrutiny is assertion-grade — the user is approving the definition of done, so pace this walkthrough like the design decision it is (Protocol 4), not a confirmation formality. Where the user challenges a proof, fix the prose and continue.
+
+On approval, **commit the decomposition and tag the baseline**: commit `docs/bets/<bet-slug>/decomposition/` (the full milestone ladder plus the first milestone's slices) together with the finalized `technical-design/` (e.g. `bet(<bet-slug>): approve decomposition`), then tag that commit `git tag bet/<bet-slug>/approved`. The tag is the user's signature on the prose — but it is a **ratchet, not a one-time freeze**. What it seals at this point is the full ladder of headline proofs *and* the first milestone's slices. Each later milestone's slices are sealed when Delivery opens that milestone: the agent authors them, they pass this same gate (scoped to that milestone) and the Protocol 9 review, and on approval the tag **advances** to the commit that adds them (`git tag -f bet/<bet-slug>/approved`, message `bet(<bet-slug>): author milestone <N>`).
+
+The ratchet has **two additive event types**: authoring an existing rung's slices, and **adding a new rung** when a postmortem reveals the ladder is missing a milestone (`bet(<bet-slug>): add milestone <N>` — the *ladder amendment* in `workflows/04-delivery.md`). Both advance the tag additively and never reopen a sealed proof. From any point forward, `git diff bet/<bet-slug>/approved.. -- docs/bets/<bet-slug>/` shows the prose changes since the current seal: a legitimate change is the additive authoring of the milestone just opened, or the additive headline of a milestone just added; any *modification* to an already-sealed headline or slice proof must instead route through the Amendment Protocol in `workflows/04-delivery.md`. The code (tests and implementation) is *built* during Delivery and is free to change; only the prose contract is sealed. (If the project is not under git, there is no tag to anchor to — note that in the bet record; the reconciliation then falls back to checking that each built test still proves what its slice's Proof-of-work prose describes.)
+
+➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/04-delivery.md`

package/src/hidden-skills/groundwork-bet/workflows/04-delivery.md

@@ -0,0 +1,193 @@
+# Phase 4: Delivery
+
+**Goal:** Turn the bet-progress board green, milestone by milestone, by driving a fresh worker through each slice, reviewing its work, and pausing at each milestone to confirm the milestone honestly proved what it set out to prove, that the remaining ladder still holds, and to author the next milestone's slices from what this one taught — leaving a delivery record behind that the next slice, the validation phase, and the next bet can learn from.
+
+## You are the delivery driver
+
+Delivery is an orchestration, not a single linear loop you run in one context. You are the **driver**: you hold the thin spine — the board, the milestone order, the delivery granularity the user chose, and the triage and course-correction judgement — and you keep that context small so you can reason about the bet as a whole.
+
+You do not implement slices in your own context. Each slice is delivered by a **fresh slice-worker subagent** (`briefs/slice-worker.md`) you dispatch with a tight context capsule; it implements to green and returns a short report, and its implementation reasoning dies with its context. You review every worker's diff through independent lenses, triage the findings, commit the slice, and at each milestone boundary you run the postmortem that decides whether the plan needs to change. This division is what keeps the heavy implementation context disposable and your own context clear enough to course-correct.
+
+## Restrictions
+
+⚠️ **CRITICAL CONSTRAINT — sealed prose is the fixed definition of done; the ladder advances by ratchet.** The decomposition (`docs/bets/<bet-slug>/decomposition/`) and the technical design were reviewed proof by proof, at assertion-grade scrutiny, approved by the user, and sealed at the `bet/<bet-slug>/approved` git tag — which at delivery start covers the full milestone ladder (every rung's headline proof) plus the first milestone's slices. That sealed **prose** is the fixed definition of done — Delivery builds *against* it, never edits it. Two things are *not* edits to it and are expected: (1) the tests and the implementation are *built* this phase — Step 0.5 materializes the red board from the approved Proof-of-work prose, and the milestone loop turns it green; and (2) each later milestone's slices are **authored on arrival** (and a missing rung may be **added**), with the tag *ratcheting forward* to add them — additive, recorded (`bet(<bet-slug>): author milestone <N>` / `add milestone <N>`), and gated by the same decomposition review. What is forbidden is *changing an already-sealed proof*: a sealed Proof-of-work proof that looks wrong is a stop-and-escalate through the Amendment Protocol below, not a quiet prose edit. The seal holds because the prose is under git from the tag forward — `git diff bet/<bet-slug>/approved.. -- docs/bets/<bet-slug>/` shows additive next-rung authoring or rung-addition (legitimate) versus a modification to sealed prose (a defect unless it carries an approved amendment trail), and the prose-integrity reconciliation in the slice review tells them apart.
+
+⚠️ **CRITICAL CONSTRAINT — scope.** Each slice writes only the code required to make its bet-progress tests green and satisfy the API and data design in `docs/bets/<bet-slug>/technical-design/`. Stay within the milestones and slices in the decomposition tree. No large refactors, no touching unrelated subsystems. If reality contradicts the locked design, follow Change Navigation below.
+
+## Operating Contract
+
+This workflow operates under the protocols defined in `.groundwork/skills/operating-contract.md` (contract v1; Continuous Bet mode). Implementation rarely surfaces phase-crossing signals — but when it does, capture it under the matching section in `.groundwork/cache/discovery-notes.md` and continue. The full Living Documents scan happens in Validation (Phase 5). Do not interrupt delivery to apply upstream updates mid-flight.
+
+Subagent dispatch follows Protocol 9's mechanics throughout this phase — the slice-worker and every review lens run as isolated subagents (the `Task` tool in Claude Code), and only their reports flow back. A host with no subagent mechanism cannot run this phase as designed; surface that to the user before starting rather than collapsing the workers into your own context.
+
+## Step 0: Implementation Readiness Gate
+
+Before any slice work, verify the bet is actually executable. Load `.groundwork/skills/groundwork-review/checklists/implementation-readiness.md` and check every item against the bet's artifacts — the document chain, the API and data design, the approval tag, and currency. If the checklist file is absent, stop and report it — the install is broken and `npx groundwork-method update` restores it; do not improvise the gate from memory. These are mechanical existence and consistency checks; run them inline (no review subagent — the artifacts were already authorship-gated when their phases committed them, and there is nothing here to be biased about).
+
+The gate is fail-closed: any 🔴 item blocks delivery. Report each failed item by name with what is missing, route back to the owning phase (a missing interface design → Design Foundations; an absent approval tag or incomplete decomposition tree → Decomposition; an unreconciled discovery note → resolve it with the user now), and do not begin implementation until the item passes. 🟡 items are surfaced to the user with your read on whether they touch this bet; the user decides whether to proceed.
+
+When every 🔴 item passes, state so in one line, update `docs/bets/<bet-slug>/pitch.md` frontmatter to `status: delivery`, and inform the user you are entering Developer Mode.
+
+## Step 0.5: Materialize the red board
+
+The approved decomposition is prose; Delivery's first act is to render it into the runnable red board it tracks progress against. From the approved Proof-of-work prose, generate one red stub per **milestone** (the whole ladder) and one per **slice of the first milestone** — the board the rest of this phase turns green. A later milestone's slice stubs are materialized when Delivery opens that milestone and its slices are authored; until then the milestone carries only its headline stub. This is deliberate: the milestone stubs make the ladder legible from the first run — `./dev bet status` shows Milestone 1 going green while Milestones 2+ stay red — so progress is visible at milestone granularity long before the later rungs are sliced.
+
+For each milestone `index.md` (the full ladder) and each slice file of the first milestone under `docs/bets/<bet-slug>/decomposition/`, materialize its named `Test file:` as a red stub that fails explicitly (never skips), commenting the stub with what the Proof-of-work prose says it must eventually assert so the slice worker knows exactly what to implement. Discover the project's test language and service names from the scaffold (`docs/architecture/infrastructure.md`, the generated `docker-compose.yml`) — never assume. Use `./dev new milestone <bet-slug> <milestone-slug>` and `./dev new slice <bet-slug> <milestone-slug> <service> <slice-slug>` when they exist to scaffold the stubs at the correct paths; write the files directly otherwise. Either way the paths match the prose exactly:
+
+```
+tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.<ext>
+tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.<ext>
+```
+
+Consult `.groundwork/skills/groundwork-bet/templates/bet-progress-test.md` for the placeholder pattern and quality criteria. Run the suite once and confirm **every stub is red** — red because the implementation does not exist, not because of an import or fixture error. That red board is the bet's live progress display: `./dev bet status` reads it, and red→green is "see how far we've come." Commit the red board (e.g. `bet(<bet-slug>): materialize red board`) before opening the first slice — it is the build artifact the slice loop fills in, generated *from* the sealed prose and free to change, never the tamper target.
+
+The scaffold and the `./dev` CLI are a starting point you keep shaping as the product grows. When a repeated delivery task earns it, or shipped tooling does not fit the work, adapt the tooling rather than scripting around it — add a project command under `.dev/commands/`, register a runner, or extend the relevant scaffold. Never leave a shipped command inert and never build a parallel tool beside it (the *no empty capabilities* rule, `docs/principles/delivery/day-2-operational-baseline.md`).
+
+## Step 0.7: Choose delivery granularity
+
+Delivery can run at three cadences. The cadence sets where you pause for the user; it never relaxes the gates. Offer the choice in one turn and recommend the default:
+
+| Mode | Runs autonomously | Pauses for the user |
+|---|---|---|
+| **Slice by slice** | one slice | after every slice closes, and at every milestone postmortem |
+| **Milestone by milestone** *(default)* | all of a milestone's slices | at every milestone postmortem |
+| **Whole bet** | all milestones | only on a hard stop, and at a postmortem that flags a course-correction |
+
+**Hard stops pause in every mode, the autonomy choice notwithstanding:** a `decision-needed` review finding, an Amendment Protocol trigger (an approved proof looks wrong), or a Change Navigation trigger (reality contradicts the locked design). Autonomy speeds the path between gates; it never lets the driver decide one of these alone.
+
+Recommend the user pin a top reasoning model for this driver session — the driver carries the triage and course-correction judgement, which is the hardest reasoning in the bet. The slice-workers run as subagents and may use a cheaper tier; their correctness is gated by the independent review, not taken on trust.
+
+State the chosen mode back in one line, then begin the milestone loop. The choice is a session preference, not a stored artifact — on a fresh-context resume (the board and git log tell you where delivery stands), re-confirm the mode before continuing; it is one cheap question.
+
+## The Milestone Loop
+
+Work through the milestone ladder in order. For each milestone: if its slices are not yet authored (every milestone after the first), **open it** — author its slices and ratchet the seal (see *Opening a milestone* below) — then drive its slices to green (the Slice Loop), close the milestone, and run the milestone postmortem before moving to the next. The first milestone's slices were authored and sealed at decomposition, so it opens straight into the Slice Loop. A fresh context resumes by reading the board (`./dev bet status` renders red/green per milestone and slice from the suite) and the git log of delivery commits, not a manifest — the first red slice is where to pick up; a milestone whose headline stub is red but which has no slice files yet is the next one to open.
+
+When the decomposition types its slices (`surface: core` or a surface slug — registry projects), core slices merge before the surface slices that consume them. A surface slice wires a contract that must already be proven green, not one being built beneath it in parallel — the milestone order already encodes this (the capability milestone opens the bet); hold it at slice granularity too. The slice-worker capsule for a surface slice includes the capability milestone's green test file — the contract proof the slice builds on.
+
+### Opening a milestone — authoring the next rung
+
+Every milestone after the first is *unsliced* until Delivery reaches it: decomposition sealed its headline proof in the ladder, not its slices. Opening it is where those slices are authored — and the reason they were deferred is that they are now written from what the milestones before them *actually taught*, not from an up-front guess. This is *plan just enough* in motion: the rung you are about to climb gets detailed using ground truth.
+
+For milestone 1 there is nothing to open — its slices were authored and sealed at decomposition; roll straight into the Slice Loop. For every later milestone, open it at the end of the previous milestone's postmortem (the postmortem is the look-up; this is the act it produces):
+
+1. **Author the milestone's slices** following Decomposition Step 4–5 (`workflows/03-decomposition.md`) — vertical slices, falsifiable Required Capabilities tracing to the design, a headline Proof of work per slice, all consistent with the milestone's sealed headline proof. Apply what the delivered milestones taught: a slice the design foresaw may now be redundant, a boundary may now need a slice the design missed.
+2. **Review them** — run the Decomposition Gate scoped to this milestone, then the Protocol 9 decomposition review on the new slice files (fail-closed, exactly as Decomposition Step 6). Revise to a clean verdict.
+3. **Ratchet the seal** — on the user's approval (the postmortem already pauses for them in slice and milestone modes), commit the new slice files and advance the tag: `git tag -f bet/<bet-slug>/approved`, message `bet(<bet-slug>): author milestone <N>`. The ratchet is additive — it adds this rung's slices and never reopens a sealed proof.
+4. **Materialize this milestone's slice stubs** (Step 0.5's procedure, scoped to the new slices) and commit the extended red board before the Slice Loop opens its first slice.
+
+If opening the milestone reveals the *headline proof itself* is now wrong — not just its slices — that is not authoring: route it through the Amendment Protocol or Change Navigation below.
+
+### Introducing a milestone — a ladder amendment
+
+The ladder is fluid: a postmortem can reveal that a milestone is *missing* — a demonstrable state the bet needs that the up-front ladder did not foresee. Introducing a new rung is a supported, first-class move, not a process failure. Because downstream milestones are unsliced, inserting or re-ordering a rung is cheap — there are no authored slices to unwind.
+
+1. **Appetite check first.** Confirm the new rung fits the bet's **appetite** and is derivable from the locked design. If it would *exceed* the appetite, or needs capability the technical design never covered, stop — that is Change Navigation (re-scope the appetite, or carve the work to a future bet / no-go), not a ladder amendment. Never grow the ladder silently to absorb scope the bet did not bet on. The "2–5 milestones; more is a roadmap" rule (`workflows/03-decomposition.md`) still bounds the grown ladder.
+2. **Author the new milestone's `index.md`** with an **un-mockable headline proof**, placed and numbered at the right rung (re-number unopened downstream milestone folders as needed — cheap, they are unsliced).
+3. **Review it** — the Decomposition Gate scoped to the new milestone, then the Protocol 9 decomposition review (fail-closed). Revise to a clean verdict.
+4. **User approval is a hard stop** — adding a success-signal rung changes the definition of done, so it is the user's call, surfaced at the postmortem.
+5. **Ratchet the seal** additively (`git tag -f bet/<bet-slug>/approved`, message `bet(<bet-slug>): add milestone <N>`) and **materialize the new milestone's headline stub**. Its slices are authored when Delivery reaches it, via *Opening a milestone* above. The new rung never reopens a sealed proof.
+
+### The Slice Loop — the driver's per-slice sequence
+
+For each slice in the milestone, in order:
+
+#### 1. Dispatch the slice-worker
+
+Assemble the context capsule and dispatch a fresh slice-worker subagent (Protocol 9 mechanics — an isolated subagent loading `.groundwork/skills/groundwork-bet/briefs/slice-worker.md`). Pass it:
+
+- `bet_slug` and the slice's `slice_file` path under `docs/bets/<bet-slug>/decomposition/`.
+- The **previous slice's delivery commit** — hash, message, and the instruction to read the diff. Its established patterns, eaten review findings, and `Notes:` line are how this slice repeats lessons instead of mistakes.
+- The **exact existing files this slice modifies**, named, to read in full.
+- For a **surface** slice, the **capability milestone's green test file** — the contract it wires onto.
+- The slice's materialized red `Test file:` path(s).
+
+The worker implements to green inside the locked design, runs its mechanical self-reconcile, and returns a short report (files touched, `NOTES:`, self-reconcile result, and any `BLOCKING CONCERN`). It does not commit. Keeping the capsule tight is what keeps the worker bounded: it reads what it needs to change and the contract it builds on, not the whole bet.
+
+**Act on a `BLOCKING CONCERN` before reviewing.** A worker that reports an approved proof looks wrong, that reality contradicts the locked design, or that a real dependency the proof names cannot be reached has hit a hard stop — route it through the Amendment Protocol or Change Navigation below (and pause for the user) before any further slice work. Do not let a worker that could not honestly reach green be reviewed as if it did.
+
+#### 2. Review the slice
+
+A worker's green report is the author's account of its own work; it is not the gate. Review the slice's uncommitted diff before closing it — and note that the test files are *built* this phase and are *supposed* to change; what is sealed is the prose.
+
+**First, reconcile against the approved prose (mechanical — run it yourself, no subagent).** The worker's self-reconcile is a first pass; confirm it.
+
+- **Prose integrity.** The approved contract is the decomposition tree and the technical design, sealed at the `bet/<bet-slug>/approved` tag. Confirm it has not silently moved: `git diff bet/<bet-slug>/approved.. -- docs/bets/<bet-slug>/decomposition/ docs/bets/<bet-slug>/technical-design/` shows no change except an approved amendment (the Amendment Protocol's commit trail). A Proof-of-work proof, an acceptance criterion, or an API shape changed without that trail — a weakened proof, a dropped case, a loosened shape — is a `decision-needed` finding. (Most slices change no prose at all; then this is a one-line no-op.) The built test must also still honestly prove what its slice's Proof-of-work prose describes — a stub filled in to assert less than the prose promised is the same finding.
+- **Honest green.** The implementation must satisfy the proof for the right reason. A return value hardcoded to the test's expected output, an input special-cased to the fixture, a `if TEST_MODE`-style branch, or a mocked-out unit of real work is a `decision-needed` finding even though the suite is green — *a weak suite that generated code passes is worse than no suite* (`docs/principles/foundations/testing.md`). A worker's `SELF-RECONCILE` flag here is a lead to confirm, not a verdict to trust.
+
+**Then dispatch the slice diff for review** through three parallel, independent lenses (Protocol 9 mechanics — isolated subagents; the three lenses catch different failure classes and none substitutes for another; none is the slice-worker, which authored the diff and cannot judge it):
+
+- **Blind reviewer** — receives only the diff, no bet context. Familiarity hides bugs; this lens has none.
+- **Edge-case tracer** — receives the diff plus repo read access. Walks every branch and boundary the diff introduces and reports only unhandled paths: null/empty inputs, failure timing, races, off-by-ones.
+- **Acceptance auditor** — receives the diff, the slice's Required Capabilities, and the prose API/data design (`technical-design/03-api-design.md`, `04-data-design.md`). Verifies the implementation does what the design says and nothing more — and that it does so honestly: the service's generated contract matches the prose shapes; undeclared endpoints, fields beyond the design, silently skipped error cases, and implementation gamed to the test (hardcoded returns, special-cased inputs, test-only branches) are findings even when tests pass.
+
+**Triage every finding** into exactly one bucket, deduplicating across lenses and the reconciliation:
+
+| Bucket | Meaning | Handling |
+|---|---|---|
+| decision-needed | A real choice the design does not settle | Blocks the slice — put it to the user now (a hard stop) |
+| patch | Unambiguous fix within the slice's scope | Fix before closing the slice |
+| defer | Real, but pre-existing — not caused by this slice | Append as a row to `docs/maturity.md` with severity; do not fix mid-slice |
+| dismiss | False positive or noise | Drop; do not persist |
+
+Apply `patch` fixes yourself when small and bounded, or re-dispatch a worker for a larger one. A slice closes only with zero open decision-needed and patch findings.
+
+#### 3. Roll out permanent tests
+
+Once the slice's bet-progress tests are green and the review is clear, roll out that slice's **permanent best-practice tests** — interface tests, HTTP API system tests, honeycomb service-perimeter tests, and unit tests for complex logic, per the project's testing strategy. For a `graphical-ui` slice, this includes **component render tests** across the states the design system names — default, loading, empty, error, long-content — so a component that throws on a prop or state combination is caught in isolation before any page integrates it (the scaffold ships the pattern at `components/render-smoke.test.tsx`); and adding any new route to `tests/system/routes.json` so the permanent render-smoke, geometry, and a11y gates sweep it. These live in the service repos and `tests/system/`, not in `tests/bets/`, and stay in the codebase after the bet is archived.
+
+#### 4. Record and close the slice
+
+Commit the slice — that commit **is** the record, and the driver writes it (the worker left the changes unstaged). Use a structured message: a `bet(<bet-slug>): slice <N.M> <slice-slug>` subject, then a body listing every file added, modified, or deleted, and a `Notes:` line — one or two sentences on what the next slice should know: a pattern established, a deviation taken and why, a struggle worth not repeating (carry the worker's `NOTES:` forward here). The commit is what makes the next slice's capsule and Validation's retrospective possible; an empty `Notes:` on a slice that fought us is a record that lies. The slice flips green on the board the moment its tests pass — no status field to maintain.
+
+**In slice-by-slice mode, pause here** — show the user the closed slice (what it proved, what the review found, the commit) and confirm before dispatching the next worker. In milestone and whole-bet modes, continue to the next slice without pausing.
+
+### Milestone close
+
+After all of a milestone's slices are delivered, run the milestone's bet-progress tests (`test_milestone_<n>_*`) to confirm the milestone's full demonstrable outcome. The milestone shows green on the board (`./dev bet status`) once its proof passes — the board is derived from the suite, so there is nothing to mark.
+
+**Visual verification — graphical surface milestones only.** A behavioural test asserting a selector exists passes while the rendered page is blank, throwing, unstyled, or showing an error-boundary fallback — the bug class assertion tests cannot see. Before a milestone that closed a `graphical-ui` surface is marked `delivered`, run the ladder against the *running* app; skip this entirely for `core`/`cli`/`agentic-protocol` milestones, which pay nothing.
+
+1. **Tier 1 — the deterministic floor is green.** The permanent `tests/system/test_render_smoke.py`, `test_a11y_smoke.py`, and `test_token_conformance.py` run as part of the suite: navigation returns 2xx/3xx, zero `error`-level console output, zero uncaught exceptions, no failed same-origin requests, no error overlay, a non-blank render across the viewport × theme matrix, the axe gate at the design system's accessibility baseline, and — the new layer — the specified atmosphere actually landed (surface treatments render with backdrop blur and multi-layer elevation, the projected tokens resolve, no degradation to a flat default). A red layer blocks the milestone — it is a real defect, not a flaky test.
+2. **Tier 2 — confirm the build matches the micro-polish spec.** Read the screenshots Tier 1 captured (`.groundwork/cache/visual/_smoke/<surface>/<route>__<viewport>__<theme>.png`, plus any per-state captures written by interface tests to `.groundwork/cache/visual/<bet-slug>/<surface>/<state>.png`). Adopt the designer persona (`.groundwork/skills/groundwork-designer/SKILL.md`, reference `design-review.md`) and judge each screen against the **per-surface micro-polish spec** in `technical-design/01-ui-design.md` and the design system. The question is conformance to the written spec, not "is it as good as a leader": did the specified surface treatment, motion, elevation, and type tokens land; do empty/loading/error states read as designed rather than as a failure; and — the dimensions Tier 1 cannot compute — is alignment optically correct, is the atmosphere restrained, does the composition read as considered? Surface what diverges from the spec; do not recite a fixed checklist. Record a one-line spec-conformance verdict per screen in the closing slice's commit message (a `Visual:` line) — a graphical milestone cannot close without it.
+
+A coherence defect the inspection spots is fixed in this same delivery phase, where it is cheapest. A finding genuinely deferred is logged as a discovery note or a `docs/maturity.md` row, never silently dropped. Tier 1 asserts the tokens landed; this Tier-2 judgement covers what computation cannot — optical alignment, restraint, and whether the whole reads as considered against the spec.
+
+### Milestone postmortem & course-correction
+
+A green milestone is not a finished milestone. The board going green proves the suite passes; it does not prove the milestone proved *what it set out to prove*, and it does not ask whether what the milestone taught us should change the rest of the plan. The retrospective in Validation (Phase 5) is too late for that — by then the whole bet is built against assumptions a mid-bet milestone may already have disproved. This checkpoint is the proactive one: at every milestone boundary, before the next milestone opens, run a focused pass over four questions, then open the next rung. It is a facilitated conversation, not a ceremony — it is where course-correction happens, and where the next milestone is sliced from what this one taught, while it is still cheap.
+
+1. **Did this milestone honestly prove its intent?** Read the milestone's Proof-of-work prose against what was actually built. The board is green — but is it green for the right reason? The failure this catches is the *quietly hollowed proof*: a milestone whose intent was to exercise a real dependency — a live model call, a real external service, an actual queue — delivered instead against a light mock or a stub, so the suite passes while proving nothing the milestone existed to prove. The honest-green check runs per slice, but a milestone-level intent can erode across slices in a way no single slice review sees. When you find it, that is a course-correction: the milestone did not prove its intent, and the fix is to work the real thing in and re-prove it now — not to roll forward and discover at validation that the bet never proved its core premise. Treat a deferred-to-mock-where-the-real-thing-was-meant as a finding, every time, even on a fully green board.
+
+2. **What did building this milestone teach that the remaining plan does not yet know?** Implementation reveals what design could only assume. Re-read the remaining ladder in light of what is now built: an assumption that broke, a downstream slice now redundant because this milestone subsumed it, a slice now missing because a real boundary turned out to need wiring the design did not foresee, a proof downstream that reads wrong now that its premise is concrete, or a whole milestone the ladder is missing. The question is not "is the plan still perfect" — it is "does what we learned change what we should build next." Route the answer by weight: (a) it changes only *how the next rung should be sliced* → carry it straight into *Opening a milestone* (that is exactly the slicing-from-ground-truth this deferral exists to enable); (b) the ladder is *missing a rung* → *Introducing a milestone* (a ladder amendment, within appetite); (c) a sealed *rung, design, or the appetite* is wrong → an Amendment or Change Navigation (Q3).
+
+3. **Route any needed change through the integrity machinery — never a silent edit.** A change to the *plan prose* (a milestone's or slice's Proof of work, an acceptance criterion) is an **Amendment** (below): on the user's approval, edit the prose, move the `bet/<bet-slug>/approved` tag to a commit that includes the edit, then adjust the affected board and code. A change to the *design itself* (an API/data shape, a milestone's existence, the appetite) is **Change Navigation** (below): write the change proposal and route by severity — though a *missing rung that fits the appetite and the locked design* is the lighter **ladder amendment** handled in-delivery (*Introducing a milestone* above), with no revert. Either way the trail — edited prose + re-tag, or a change-proposal file — is what lets the next slice's prose-integrity reconciliation tell an approved change from a silent one. "Adjust as we go" is a feature of this process precisely because it leaves that trail.
+
+4. **Where does the delivered work actually stand?** Note anything the milestone surfaced that the next milestone or the final validation needs — a readiness caveat, a discovery-note signal for a future bet (`.groundwork/cache/discovery-notes.md`), a `docs/maturity.md` row. Capture it now while it is fresh; do not bank on remembering it at validation.
+
+**Pause per the chosen mode.** In slice-by-slice and milestone-by-milestone modes, always pause here: present the postmortem — what the milestone proved, anything that did not hold, and any course-correction you recommend — and get the user's decision before opening the next milestone. In whole-bet mode, surface the postmortem summary and proceed automatically *unless* it found a course-correction (a hollowed proof, a remaining-plan change, an amendment, a new milestone / ladder amendment, or a Change Navigation): a course-correction is the user's call and pauses even in whole-bet mode. Routinely authoring the next rung's slices is *not* a course-correction — in whole-bet mode a clean postmortem rolls straight on, the scoped Protocol 9 review gating the new slices. A clean postmortem in whole-bet mode carries its summary onto the record.
+
+**Then open the next milestone.** With this milestone's lessons in hand, the user's go-ahead (or whole-bet autonomy), and any ladder amendment or Change Navigation already routed, run *Opening a milestone* above and ratchet the seal. (The final milestone has no next rung; its postmortem closes into Validation.)
+
+## Amendment Protocol — when an approved proof is wrong
+
+An approved proof can still be wrong: its Proof-of-work prose can describe a shape the design never defined, encode a misread capability, or demand an outcome no implementation can reach. Approval does not make the prose right — it makes changing it a decision the user takes, not a convenience the implementing worker or driver reaches for. The amendment leaves a trail (the edited prose + a re-tag) precisely so the prose-integrity reconciliation can tell an approved change from a silent one. This protocol fires from three places: a slice-worker's `BLOCKING CONCERN`, a `decision-needed` review finding, or the milestone postmortem.
+
+1. **Stop work on the affected slice or milestone.** Do not edit the prose, and do not implement toward a proof you believe is wrong.
+2. **State the case:** what the Proof-of-work proof (or the API shape behind it) says, what you believe it should say, and which artifact is the source of the error — the proof alone, or the technical design behind it.
+3. **Route by depth.** A wrong proof against a correct design is a proof amendment: on the user's explicit approval, edit the slice's (or milestone's) Proof-of-work prose, **move the `bet/<bet-slug>/approved` tag to a commit that includes the edit** (`git tag -f`, or record the amended commit in the bet record when re-tagging is undesirable), then change the built test and code to match. That edited-prose commit is the amendment trail the reconciliation reads. Editing an *unopened* milestone's headline proof is the cheapest amendment of all — correct the ladder rung and re-tag; because its slices were never authored, nothing downstream unwinds. A wrong API/data design is deeper — follow Change Navigation below.
+4. **Record the amendment** in the slice's delivery commit `Notes:` (and in the postmortem record when it surfaced there) so Validation's retrospective sees how the contract moved after approval.
+
+## Change Navigation — when reality contradicts the locked design
+
+Mid-delivery discoveries that invalidate the design are not failures of the process; pushing through them silently is. When implementation reveals the design committed to something wrong — surfaced by a slice-worker, a review, or the milestone postmortem:
+
+1. **Pause the slice** and write a change proposal at `docs/bets/<bet-slug>/change-proposal-<n>.md` using the template at `.groundwork/skills/groundwork-bet/templates/change-proposal.md`: the discovery and its evidence, the impact across pitch / technical design / decomposition / built artifacts (name each affected section), the before/after of every proposed edit, and the severity.
+2. **Route by severity.** *Minor* — the API/data design and milestones survive; specific proofs and design sections need correction: on user approval, apply the edits, re-review mutated docs (Protocol 9), amend affected proofs through the Amendment Protocol (edit the prose, re-tag, change the built test and code), resume the slice. *Ladder amendment* — the design holds and the ladder is simply missing a rung that fits the appetite and is derivable from the locked design: this is not a design contradiction at all — handle it in-delivery via *Introducing a milestone* above (author the new rung's headline, review, ratchet the seal), no revert. *Structural* — an API/data design, a milestone, or the appetite itself is wrong, or a needed new rung requires capability the design never covered or would exceed the appetite: on user approval, revert to Design Foundations (`status: design`), rework the design with the proposal as input, and re-run Decomposition for the affected scope; unaffected delivered slices stand.
+3. The proposal stays in the bet directory either way — it is the audit trail Validation and the retrospective read.
+
+## Transition
+
+Once all bet-progress tests are green, every slice is committed with its record filled, every milestone postmortem has run, and the permanent best-practice tests for every slice are in place, you are ready for validation.
+
+➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/05-validation.md`