groundwork-method 0.0.1 → 0.11.0

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

@@ -0,0 +1,242 @@
+# 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. A **milestone** is a thin, user-visible step proven by driving the real product the way its consumer would — through the real front door, on the real pipeline. A **slice** is a vertical cut through one service, the unit of work that builds toward a milestone; slices run in sequence, each built on the one before. 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 state the consumer observes at their real surface, 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 thin, user-visible step the product reaches — a state its consumer observes at their real surface, proven by driving the shipping build the way that consumer would. The consumer is whoever the step serves: a person at a screen, a developer calling an SDK, an operator reading a dashboard or trace, another system calling the API. A pure-API product has a front door like any other — its surface is the API and its consumer is the caller. The test of a milestone is simple: name who sees the outcome and what they see. If you cannot, it is not a milestone — it is horizontal scaffolding to fold into the milestone that consumes it, or an unknown to retire as a proof of concept in design.
+
+**Decomposition constraints the agent must hold:**
+- Order by integration value *and risk*: the first milestone is the thinnest user-visible flow that proves the architecture works **through the bet's riskiest real path** — the 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.
+- The **first user-visible milestone lands the design system in the running app** — the shell, the theme and tokens wired in, the base components, and the first real screen built on them. Every later screen is built on that foundation; "make it look right later" is the mistake this whole process exists to stop.
+- Dependencies flow forward only — each milestone builds on the proven state of the ones before it.
+- Milestones are never horizontal. "Build all the schemas" is not a milestone; it is invisible to every consumer and produces no observable state. Proving a backend contract end-to-end is real work, but it is a *slice* on the way to a front door, never a milestone that stops there.
+- The ladder must **sum to a complete, well-rounded experience** — each milestone works, looks right, and is genuinely good to use. A missing rung (the way back from a screen, the progress an operation needs, the information a view requires to be usable) is an incomplete plan, not a smaller scope. The dead-end navigation and the silent progress screen that a real bet shipped were each a *missing milestone* — a rung the ladder should have had.
+- 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 proof Milestone 1 provides, why Milestone 2 can only follow it, and so on, and which consumer observes each. The review focuses on **ordering, whether each milestone names a real outcome a named consumer observes at their surface, and whether the ladder sums to a complete experience** — 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 describes what its consumer observes when they drive the real product: the action they take at their surface, what they see in return, and the real data and pipeline behind it. Write it in the consumer'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 — so a reader understands exactly what becomes true for the consumer when the milestone lands.
+
+**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 the slice-worker rolls out per slice in Delivery (`workflows/04-delivery.md`, the Slice Loop), not the headline proof the user reviews. Include an error case here only when the milestone's demonstrable outcome depends on it. These headline cases are the milestone's **agreed front-door test cases** — the integrity anchor the user signs at planning; they live in the milestone's acceptance criteria and Proof of work.
+
+**The headline proof drives the real product through the real front door.** Each rung's proof must be falsifiable by *reality*: the consumer's action runs the shipping build end to end, on the real pipeline, the way it actually travels — never a test harness driving a scripted stand-in for the work. A proof that a stub, a mock, or a hardcoded return could satisfy is proving plumbing, and plumbing is never a milestone's success signal. The dependency that makes the milestone meaningful runs for real — the live model, the real external service, the actual store — not a placeholder standing in for it. Seeded inputs are fine (handing the real pipeline a known fixture folder tests it on controlled data); replacing the pipeline with a script that emits the expected output is the violation. And **any fake a proof leans on needs a real test behind it**: if a test stands in a fixture for work a real stage should do, some other proof must exercise the real stage that produces it — a fixture nothing real ever generates is a green light wired to nothing. 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.
+
+**Slices build toward the front door, in sequence.** Lay the slices out so they compose coherently into the milestone — what each one solves for and how they stack — and order them so each builds on the proven state of the one before it. They are delivered in that order, integrating continuously, and the milestone's front-door proof is what the last of them closes. This is a plan to steer, not a sealed breakdown: hold what each slice must achieve and how they sum to the milestone, and adjust the how as each slice teaches you something.
+
+**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`)
+- **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, when it builds a screen, the view it wires in `01-ui-design.md` and the pattern it implements in full.
+- **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 — consumer, demonstrable goal, sequencing rationale, acceptance criteria (the agreed front-door cases), **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 slice proves the behaviour at its service edge; when a slice builds a screen, it proves the screen renders and behaves through the pattern it implements in full. 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 real outcome a named consumer observes at their surface, traceable to `technical-design/`: the user-visible step traces to its surface's subsection in `01-ui-design.md`, and the data and interfaces beneath it to `02-data-flows.md` / `03-api-design.md` / `04-data-design.md`. Name who sees it and what they see, or it is not a milestone.
+- The first user-visible milestone lands the design system in the running app — shell, tokens, base components, and a real screen built on them — not a bare-bones screen with styling deferred.
+- The ladder sums to a complete, well-rounded experience: no missing rung (a way back from every screen, the progress and state information each view needs to be usable). A dead-end or a silent-progress screen is a missing milestone, caught here.
+- Every milestone's headline Proof of work **drives the real product through the real front door** — the consumer's action runs the shipping build on the real pipeline, falsifiable by reality, not satisfiable by a stub, mock, or hardcoded return; the milestone that retires the bet's central risk engages the real thing; and any fake the proof leans on has a real test behind it that exercises the real producer.
+- 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>`.
+- 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 a real outcome a named consumer observes at their surface, 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 thin user-visible step the product reaches for a named consumer — a state they observe at their real surface — not a layer of the stack, not a phase of implementation. A slice is a vertical column through one service that builds toward it, not a horizontal pass. If the milestone does not name a consumer and what they see, 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: A user sees their notifications update live in the web app
+
+**Consumer:** the person using the `web-app` — they open the notifications panel and watch
+it reflect real operations as they happen.
+
+**Demonstrable goal:** With the web app running on the real notification service, a user
+opens the notifications panel and sees a real operation appear as a notification, then sees
+its status change in place when the operation completes — on the real pipeline, in the
+shipped design system, with an empty state before anything arrives and a clear way back to
+where they came from.
+
+**Sequencing rationale:** This is the thinnest user-visible flow that proves the whole path
+end to end — event intake, persistence, the read API, and the panel that renders it — on
+the design system that every later screen builds on. It retires the bet's riskiest unknown
+(does the live event path actually reach the screen) at Milestone 1, not last.
+
+**Acceptance criteria (agreed front-door cases):**
+- [ ] With the app open on the notifications panel and no notifications yet, the user sees
+  the empty state; when a real operation starts, its notification appears within 2 seconds.
+- [ ] When that operation completes, the same notification updates its status in place — the
+  user sees one entry change, not a duplicate appear.
+- [ ] The panel renders in the design system (tokens, components), and the user can close it
+  and return to where they were.
+
+## Proof of work
+
+**Proves:** A user driving the running web app sees a real operation surface as a live
+notification and update in place, on the design system, with its empty state and a way back.
+
+**How we prove it:** Drive the shipping web build against the real notification service —
+open the panel and see the empty state; trigger a real operation through the system and see
+its notification appear within 2 seconds; complete the operation and see the one entry's
+status change in place with no duplicate; confirm the panel renders the design-system
+components and that closing it returns to the prior view.
+
+**Test file:** `tests/bets/notifications/test_milestone_1_notifications_panel_live.py` —
+generated red at Delivery start; drives the web surface in `01-ui-design.md` over 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)
+- [Slice 1.2 — web-app: Live notifications panel on the design system](./02-notifications-panel.md)
+```
+
+The shallow version has horizontal milestones invisible to every consumer, no acceptance criteria, no sequencing rationale, and no proof — "Backend" names a build activity, not a state anyone observes. The deep version is a thin user-visible step proven by driving the real product through the front door: the backend slice and the panel slice stack into one flow a user actually sees, on the design system, with its states and its way back.
+
+**Deep (required standard) — a slice file:**
+
+```markdown
+# Slice 1.1 — notification-service: Operation event intake
+
+**Owner service:** notification-service
+**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, who observes each milestone, 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 agreed front-door test cases that become 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 as the recorded 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`). That commit is the user's signature on the agreed front-door cases — the integrity anchor the rest of the bet keeps honest.
+
+The anchor leaves a trail, and the trail is lightweight. **Steering how slices break down is free and needs no record** — adjusting the path to a milestone as delivery teaches you is the plan working as intended. **Changing what a milestone proves** — editing or dropping an agreed front-door case — is an owner-approved move recorded beside the prose: amend the affected `index.md` or slice file and commit it with a message that says what changed and why (`bet(<bet-slug>): amend milestone <N> proof — <reason>`), so a later context (a resumed delivery, a validator) can see it. Authoring a later milestone's slices on arrival, and adding a new rung when a postmortem reveals the ladder is missing one, are the same kind of recorded, additive event. There is no seal to break and no ceremony to run — the record is the commit history of the decomposition tree, and Delivery's prose-integrity check reconciles each built test against the current approved prose it traces to. (This holds whether or not the project is under git: the standing rule is that every built test still proves what its slice's Proof-of-work prose describes, and a change to that prose is a recorded amendment, not a quiet edit.)
+
+➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/04-delivery.md`

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

@@ -0,0 +1,226 @@
+# 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, rolls out the slice's permanent best-practice tests, 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.
+
+**A note on voice.** This phase is dense with reading — the board, the git log, the approved prose, the previous slice's commit — and it is tempting to narrate each read as a discovery ("now I understand the protocol," "key finding: the slices are approved"). Don't: you are guiding the user through *their* delivery, not reporting your way through this file. Tell them where the bet stands and what is next, and state routine checks as plain fact (groundwork-persona, *Speak as the Guide, Not the Tourist*).
+
+## Restrictions
+
+⚠️ **CRITICAL CONSTRAINT — the approved prose is the definition of done; changing what it proves is a recorded amendment.** The decomposition (`docs/bets/<bet-slug>/decomposition/`) and the technical design were reviewed proof by proof, at assertion-grade scrutiny, and approved by the user — recorded at the `bet(<bet-slug>): approve decomposition` commit, which at delivery start covers the full milestone ladder (every rung's headline proof) plus the first milestone's slices. That approved **prose** is the definition of done — Delivery builds *against* it. Three things are expected and need no special ceremony: (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; (2) each later milestone's slices are **authored on arrival** (and a missing rung may be **added**), recorded by committing the new slice files and gated by the same decomposition review; (3) the slice **breakdown is steered freely** as delivery teaches you — adjusting the path to a milestone needs no record. What is *not* free is **changing what a milestone proves** — editing or dropping an agreed front-door case, weakening a Proof-of-work proof, loosening an API shape: that is an owner-approved **Amendment** (below), recorded as a commit beside the prose with a reason, so a later context can see it. The prose lives under git, so `git log -- docs/bets/<bet-slug>/decomposition/ docs/bets/<bet-slug>/technical-design/` shows the trail, and the prose-integrity reconciliation in the slice review confirms each built test still proves what its current approved prose describes.
+
+⚠️ **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.
+
+## Git workflow: a branch per bet, a commit per slice
+
+Delivery's unit of git isolation is the **bet**, not the slice. The bet rides one short-lived branch — `bet/<bet-slug>`, the line of history the approved decomposition commit already sits on — worked inside one **worktree** isolated from `main` and from any other bet in flight. Every slice-worker for this bet operates in that one worktree, in order; you commit each slice onto the branch as you close it. The branch merges to trunk once, at bet close (Validation, `05-validation.md`).
+
+Slices are sequential by construction — a slice reads the previous slice's delivery commit, and a slice wires onto a prior slice's contract already proven green — so there is no parallelism to win by giving each slice its own worktree, and real hazard in trying: worktrees share one object store, and a second writer racing `.git/index.lock` or silently falling back to the main checkout is how agent runs lose work undetected. Keep parallelism where it belongs — across bets (each its own worktree and branch) and across the review lenses (read-only; they read the diff and need no worktree). The worker-leaves-it-unstaged, driver-reviews-then-commits handoff (Slice Loop below) works *because* worker and driver share this one serial worktree: the worker hands you a working-tree diff, not a branch to merge.
+
+**Open the isolation before the red board.** The worktree and branch must exist before Step 0.5 commits the red board into them. If the bet is not already on its own branch and worktree from its earlier phases, open them now: branch `bet/<bet-slug>` from a clean `origin/<trunk>`, in a worktree under a gitignored path (the host's convention — e.g. `.worktrees/<bet-slug>/`). One branch lives in one worktree — never check the same branch out twice.
+
+**Bootstrap the worktree once, before the first worker.** A fresh worktree shares the object store but not the working tree — dependencies, gitignored env and secrets, and submodule contents are all absent until you put them there. Before dispatching slice one: install dependencies, copy in the gitignored env/secret files the services need, run `git submodule update --init --recursive` if the project uses submodules, assign isolated ports / a scratch database if the bet boots services, and **build the code map for the worktree** (`npx groundwork-method repo-map` — deterministic, incremental, no network) so each worker's Step-1 orientation has a current map to read. This is the working-directory contract every worker capsule then points at (Slice Loop §1). One caveat on code intelligence in a worktree: Serena is registered in the tracked `.mcp.json` with `--project .`, which resolves to the *session* root, not the worktree path — so treat Serena as best-effort here and rely on the freshly-built repo map plus the graceful-degradation contract (`.groundwork/skills/code-intelligence.md`) rather than assuming the symbol tools are live in the worktree.
+
+**Slice = one commit on the branch; milestone = a checkpoint, not a merge.** You commit each slice as you close it (Slice Loop §4) — one Conventional Commit per slice, history preserved, never squashed: the per-slice commits are the record the next slice's capsule and Validation's retrospective both read. A milestone closing is a green, reviewed, postmortem'd checkpoint *on the branch* — nothing merges to trunk yet. Slices integrating onto the bet branch continuously is the integration that catches slice-to-slice breakage; merging to trunk is a separate, later event.
+
+**Push the bet branch as you go — off-machine backup.** The bet's worktree lives on one machine; until something leaves it, a single disk failure loses the whole delivery. So as delivery proceeds, push the branch to its own remote — `git push -u origin bet/<bet-slug>` on the first push, plain `git push` after — so every closed slice is backed up off the machine. This is **backup, not integration**: an isolated `bet/<bet-slug>` branch publishes nothing into trunk or anyone's path, so it does not carry the user gate the bet-close trunk merge does — it is the safety net the per-slice commit discipline assumes, run routinely without asking. Push right after each slice's delivery commit (Slice Loop §4), or at a minimum at every milestone close. During delivery the branch only grows — the single rebase happens at bet close — so these are fast-forward pushes, never forced; the backup branch is torn down with the local branch once the bet merges to trunk (Validation Step 8.5). On a project with no remote this is a no-op — and keep the project's CI scoped to pull requests and trunk so a routine backup push does not fire the full pipeline on every slice.
+
+**Bet close = the single merge to trunk.** When Validation is green and the bet is done, integrate it to trunk in one user-gated step (merging to a shared branch is a push-class action — the user's call, never the driver's alone): rebase `bet/<bet-slug>` onto current `origin/<trunk>` to absorb drift, fast-forward merge, then remove the worktree (`git worktree remove`, then `git worktree prune` — never `rm -rf`) and delete the branch. Trunk only ever receives a complete, validated bet, so there is nothing half-built on it and no feature flag is required to keep it releasable. (A team may still flag a risky rollout in its own code; the delivery contract does not mandate it.) An appetite-bounded bet is a *short-lived* branch — the days-long feature branch trunk-based development permits, not the weeks-long drift it warns against. The mechanical merge step runs at the end of Validation (`05-validation.md`, Step 8.5).
+
+### Recording a cross-service slice, by repository topology
+
+A slice can span more than one service; how it commits depends on how the project's repositories are laid out. The scaffold produces a **monorepo**, and that is the path the rest of this workflow assumes; the other two topologies are supported with the deltas below.
+
+- **Monorepo** *(scaffold default — friendliest)*. All services and the bet's artifacts (`docs/bets/`, `tests/bets/`) live at one workspace root under one branch. A cross-service slice is **one atomic commit** spanning the service directories — the slice *is* the unit of record, exactly as Slice Loop §4 writes it. The "derive the client from the producer's canonical contract" rule is satisfied in-tree: the consumer's generated client and the producer's contract land in the same commit. A backwards-incompatible cross-service change is not one mega-commit — slice it expand → migrate → contract (add the new shape beside the old, migrate each consumer, then remove the old) so each step is independently green and revertible.
+
+- **Submodules** *(if the project nests each service as a submodule of a superrepo)*. The worktree is the superrepo's; each affected service is a submodule. For each service the slice touches: the worker edits inside the submodule **on a real branch — never a detached HEAD**, or the commit is silently lost on the next submodule update; you commit there and **push the submodule first**, then record a **gitlink-bump commit in the superrepo** — that superrepo commit, referencing the child SHAs, is the slice of record. The worktree bootstrap must have run `submodule update --init`. This topology costs a two-step, two-repo commit per service and is hostile to automated workers; prefer the monorepo unless the project is already committed to submodules.
+
+- **Polyrepo** *(if each service is its own repository)*. There is no single commit that spans the slice. Carry a **change-set id** across the N repositories' branches, record the slice as a **manifest binding the N commits** in the bet's home repo (where `docs/bets/<bet-slug>/` lives), and gate integration on producer-before-consumer ordering — or backward-compatibility plus a contract check (e.g. Pact `can-i-deploy`, `buf breaking`) — rather than a shared green build. This is the most expensive topology for the per-slice-commit model; reach for it only when the services genuinely must ship from separate repos.
+
+## 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 approved decomposition commit, 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 unapproved 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 approved prose and free to change.
+
+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 and record its slices (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 approved 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.
+
+Slices run in sequence, each built on the proven state of the one before it. A slice that wires onto a contract another slice established consumes one already proven green, not one being built beneath it in parallel — the slice order encodes this. When a slice builds on a prior slice's proven contract, the slice-worker capsule includes that prior slice's green test file — the proof it builds on.
+
+### Opening a milestone — authoring the next rung
+
+Every milestone after the first is *unsliced* until Delivery reaches it: decomposition approved 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 approved 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 approved 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. **Record the authored slices** — on the user's approval (the postmortem already pauses for them in slice and milestone modes), commit the new slice files (`bet(<bet-slug>): author milestone <N>`). This is additive authoring, recorded in history — it adds this rung's slices and changes no existing 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 a **front-door headline proof** (a real outcome a named consumer observes, driven through the real product), 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. **Record the new rung** additively (commit the new `index.md`, `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. Adding a rung changes no existing 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`). The capsule is **pointers and slice-specifics, not a paraphrase of the brief** — the worker reads the brief for the process (build the real thing, self-reconcile, do not commit, the report format); restating that here only bloats the capsule and drifts from the brief when it changes. Pass:
+
+- `bet_slug` and the slice's `slice_file` path under `docs/bets/<bet-slug>/decomposition/`.
+- The **working directory & isolation contract** — the bet's worktree path (the bootstrapped one from the Git workflow above), the instruction to run every command from it, leave all changes **unstaged**, and **not** re-isolate (no new worktree, branch, or `EnterWorktree`). The worker builds in the worktree you prepared; it does not manage its own.
+- 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.
+- When the slice **builds on a prior slice's proven contract**, that slice's **green test file** — the proof it wires onto.
+- The slice's materialized red `Test file:` path(s).
+- The **stack's testing strategy** — the promoted engineer skill for the slice's stack (`.agents/skills/groundwork-<stack>-engineer/references/testing.md`), whose **Bet Slice Rollout** section defines the permanent best-practice tests this slice owes. The worker rolls out against it and the coverage-auditor lens reviews against it, so name the right stack when a slice spans more than one.
+- Any **slice-specific constraints** the brief cannot know — a frozen signature it must not change, a subsystem it must not touch, a safety or content guardrail, the fixtures it must prove on. State them as hard constraints, not suggestions.
+- Any **prior spike or proven recipe** that de-risks this slice — a working invocation, a validated config, a dependency already on disk. If it lives in an ephemeral location (a job-temp or scratch path), instruct the worker to relocate what it needs into a durable path in the repo or the project cache **and never depend on the ephemeral path at runtime**.
+- If the slice should leave specific facts for the next slice, name them so the worker's `NOTES:` captures them (a transport chosen, a model id, a durable location, a command to rebuild an artifact).
+
+The worker implements to green inside the locked design, rolls out the slice's permanent best-practice tests per its stack's testing strategy, runs its mechanical self-reconcile, and returns a short report (files touched, `COVERAGE:`, `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 fixed is the approved 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. Confirm it has not silently moved: `git log --oneline -- docs/bets/<bet-slug>/decomposition/ docs/bets/<bet-slug>/technical-design/` since the approval commit shows only recorded amendments (each an Amendment commit carrying a reason). A Proof-of-work proof, an acceptance criterion, or an API shape changed without that recorded amendment — 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, against the real product. A return value hardcoded to the test's expected output, an input special-cased to the fixture, a `if TEST_MODE`-style branch, a mocked-out unit of real work, or a fixture standing in for a real pipeline stage that nothing else produces 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`). Two extensions make this bite at delivery: **a fake needs a real test behind it** — if this slice leans on a fixture or stub for work a real stage should do, confirm some test exercises the real producer, or the fixture is a green light wired to nothing; and **the proof runs against the shipping build** — the artifact a user actually launches (the packaged app, the embedded worker), not a test target that runs code the shipping build never includes. 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 four parallel, independent lenses (Protocol 9 mechanics — isolated subagents, each loading its brief under `.groundwork/skills/groundwork-bet/briefs/`; the four 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** (`briefs/blind-reviewer.md`) — receives only the diff, no bet context. Familiarity hides bugs; this lens has none.
+- **Edge-case tracer** (`briefs/edge-case-tracer.md`) — 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** (`briefs/acceptance-auditor.md`) — 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.
+- **Coverage auditor** (`briefs/coverage-auditor.md`) — receives the diff, the slice's Required Capabilities, and the stack's testing strategy (`.agents/skills/groundwork-<stack>-engineer/references/testing.md`). Judges the permanent best-practice tests the worker rolled out — they are in this diff now, so they are reviewable here — against that strategy: are the error and boundary cases covered to the rigour of the happy path, does the complex logic the slice introduced carry a unit test, did an observable path get its critical-path trace assertion, and for a `graphical-ui` slice are the named component states present. A sociable test that executes a branch without asserting on it is a gap even on a green board, and a surviving mutant on changed high-risk code is the evidence to cite. This is the lens that makes comprehensive coverage a reviewed obligation rather than a hope — the seam the honest-green check and the acceptance auditor both leave open.
+
+**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. 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. Then push the branch (`git push`) so the closed slice is backed up off the machine — backup, not integration (Git workflow above); skip it only on a project with no remote.
+
+**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 — prove it at the front door
+
+A milestone is done when its **agreed front-door test cases pass against the real product** — the shipping build, on real data, in conditions as close to real as the environment allows — not when its slices are each individually green. Run the milestone's bet-progress tests (`test_milestone_<n>_*`); the milestone shows green on the board (`./dev bet status`) once its proof passes. But green at the suite is the floor, not the finish: closing the milestone is confirming the consumer's outcome actually holds at their surface.
+
+**Prove it in the consumer's medium.** 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. For a milestone whose consumer is at a screen (`graphical-ui`), drive the *running* app and verify what they see; a `cli` or `agentic-protocol` milestone proves at its own front door (the command's real output, the response structure) and pays nothing for the pixel tiers below.
+
+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 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. When the surface's platform has no check that can run, that is a fail-closed block, not a skip (the test tooling emits a failing placeholder naming the gap, never silently passes — Test tooling, area G of the change plan).
+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: 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.
+3. **Tier 3 — the polish pass.** Now there is a running milestone to look at, run a deliberate pass over what was actually delivered, against the design and the agreed cases. Ask two questions: what does the consumer still need that is missing — a screen that works but shows no progress, a view with no empty state, a flow with no way back — and what considered touches would make this genuinely good to use. Build those in. The boundary is concrete: elevate what *this milestone* delivers to match its own design and complete its own flows; a net-new capability is its own milestone (route it as a ladder amendment), and the no-gos hold. AI-assisted coding makes this cheap, so the bar is high — "it renders" is not the finish line; "it is a pleasure to use" is.
+
+**Then the experience-auditor reviews the milestone.** Dispatch the experience-auditor lens (`briefs/experience-auditor.md`, the designer persona) over the assembled, running milestone — distinct from the per-slice coverage review, because design fidelity and flow completeness need the whole surface, not one slice. It judges, against `01-ui-design.md`, the design system, and the design-phase reference apps: best-in-class patterns implemented in full, no dead-end flows, the named states present, design-system match, and the joy-to-use bar. Its findings triage like any other review — a dead-end flow or a design-system miss is `decision-needed` and blocks the milestone.
+
+A coherence or experience defect the review 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. There is no "done for function now, polish later" split — a milestone tested only through fakes, or shipped as a bare shell, has not closed.
+
+### 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, at the front door?** 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, driven through the real product? The failure this catches is the *quietly hollowed proof*: a milestone whose intent was a consumer observing a real outcome — a live model call surfacing on screen, a real external service, an actual queue — delivered instead against a light mock, a stub, a scripted driver, or a fixture nothing real produces, so the suite passes while the consumer's outcome was never proven. 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 through the shipping build 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) an approved *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 *what the plan proves* (a milestone's or slice's Proof of work, an acceptance criterion) is an **Amendment** (below): on the user's approval, edit the prose and commit it beside the decomposition with a reason (`bet(<bet-slug>): amend milestone <N> proof — <reason>`), 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 — the recorded amendment commit, 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 record the authored slices. (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 committed with a reason) 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 and **commit it beside the decomposition with a reason** (`bet(<bet-slug>): amend milestone <N> proof — <reason>`), then change the built test and code to match. That recorded amendment commit is the trail the reconciliation reads. Editing an *unopened* milestone's headline proof is the cheapest amendment of all — correct the ladder rung and commit; 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, commit it with a reason, 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, record the new rung), 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`