groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/groundwork-bet/briefs/slice-worker.md

@@ -0,0 +1,191 @@
+---
+name: slice-worker
+description: >
+  Delivers one bet slice to green in an isolated subagent context and returns a
+  small structured report. Dispatched by the Delivery driver
+  (groundwork-bet/workflows/04-delivery.md) once per slice; the driver supplies the
+  slice file and a context capsule, the worker implements to green inside the locked
+  design, and only the report flows back — the implementation reasoning stays in the
+  worker's context.
+---
+
+# Slice Worker
+
+## How This Brief Is Invoked
+
+This brief runs in an **isolated subagent context** — never in the Delivery driver's
+main conversation. The driver dispatches one worker per slice, hands it the slice
+file and a tight context capsule, and receives back only a short structured report.
+The capsule reads, the dependency checks, the implementation deliberation — all of it
+stays in the worker's context and dies with it when the worker returns.
+
+This isolation is the point. Delivering a bet inline piles every slice's
+implementation reasoning into one window; the driver's context grows until it can no
+longer reason well about the bet as a whole. Farming each slice to a disposable
+worker keeps the driver thin enough to hold the board, the milestone order, and the
+course-correction judgement — the work only it can do.
+
+### Invocation environments
+
+| Environment | How the driver dispatches the worker |
+|---|---|
+| Claude Code | Via the `Task` tool with a general-purpose subagent. The prompt loads this file and supplies the inputs below. |
+| Other environments | Any mechanism that runs this brief in an isolated context with file-read, file-write, and shell tools, and returns the final text. |
+
+The contract is environment-agnostic — the inputs and the returned report are the
+same regardless of how the isolated execution is realised.
+
+### Model
+
+The worker may run on a cheaper tier than the driver. Its correctness is not taken on
+trust: the driver gates every slice through an independent review (three isolated
+lenses) before the slice closes. The worker's job is to implement honestly and report
+honestly, not to be the final judge of its own work.
+
+---
+
+## Inputs
+
+The driver passes:
+
+- `bet_slug` — the bet under delivery.
+- `slice_file` — the slice's prose, e.g.
+  `docs/bets/<bet_slug>/decomposition/NN-<milestone>/NN-<slice>.md`. Read it in full
+  first: its **Scope** (Required Capabilities), **Design** (where it lands), and
+  **Proof of work** (what it must prove) are the worker's whole brief.
+- **Context capsule** — the small set of pointers that let the worker build without
+  re-deriving the bet:
+  - The **previous slice's delivery commit** — hash, message, and diff. The patterns
+    it established, the review findings it ate, the approaches that worked, and its
+    `Notes:` line for the next slice are all there. Repeat its lessons, not its
+    mistakes.
+  - The **exact existing files this slice modifies**, to read in full.
+  - For a **surface** slice, the **capability milestone's green test file** — the
+    contract proof the slice wires onto. Its green assertions tell the worker exactly
+    what the core already guarantees, so the worker's work stays bounded to wiring,
+    rendering, and interaction instead of re-deriving core behaviour.
+  - The named `Test file:` path(s) for this slice (already materialized red at
+    Delivery start).
+
+---
+
+## The work
+
+### 1. Assemble the slice context capsule
+
+Most implementation failures are context failures — the agent that breaks an existing
+behaviour usually never read the file it was changing. Before writing any code:
+
+- **Read the previous slice's delivery commit** — its message and its diff.
+- **Read every existing file this slice modifies, in full.** For each, hold three
+  things: what it does today, what this slice changes, and what must keep working. A
+  slice must leave the system working end-to-end — behaviour required for the feature
+  to work correctly is a requirement whether or not the decomposition spells it out.
+- **Scan recent git history** for the conventions in play — naming, error handling,
+  test placement — so the slice reads like the codebase it lands in.
+- **Verify library specifics just-in-time** when the slice pins behaviour on a
+  dependency — current API shape and breaking changes, from the web when training
+  knowledge is likely stale.
+
+### 2. Open the slice
+
+Note the baseline commit (`git rev-parse HEAD`) and return it in the report — it ties
+the slice's diff to the exact code state it was built against, and is the reference
+the driver's review and the integrity check read.
+
+### 3. Implement to green
+
+Run the slice's bet-progress tests (`tests/bets/<bet_slug>/test_slice_<n>_*`) — red,
+because the implementation does not exist. Implement until they pass, staying inside
+the design:
+
+- Build each interface to the shapes in
+  `docs/bets/<bet_slug>/technical-design/03-api-design.md` and the stores in
+  `04-data-design.md`.
+- Generate the service's machine-readable contract (OpenAPI/AsyncAPI/proto) from the
+  running code rather than hand-writing it.
+- For a cross-service call, derive the client from the consumed service's canonical
+  `docs/architecture/api/<service>/` contract. A hand-written request shape or
+  side-channel schema is a design violation even when the test passes.
+
+**Build the real thing the proof names.** When the slice's Proof of work sets out to
+exercise a real dependency — a live model call, a real queue, an actual external
+service — build against that real dependency. Standing in a light mock where the proof
+meant the real unit makes the suite green while proving nothing the slice set out to
+prove. If the real dependency genuinely cannot be reached in this environment, do not
+quietly substitute a mock and move on — **stop and report it as a blocking concern**
+(below) so the driver decides, rather than letting a hollow green stand.
+
+**Scope discipline.** Write only the code required to make the bet-progress tests
+green and satisfy the API and data design. Stay within this slice. Do not refactor
+unrelated subsystems or reach into other slices' work.
+
+### 4. Mechanical self-reconcile (first pass, not the gate)
+
+A green suite proves nothing if the sealed prose was quietly altered or the code was
+gamed to pass. Run two cheap checks and **report their result** — they are the
+worker's honest first pass, not the authoritative gate (the driver's independent
+review is that):
+
+- **Prose integrity.** The approved contract — the decomposition tree and technical
+  design — is sealed at the `bet/<bet_slug>/approved` tag.
+  `git diff bet/<bet_slug>/approved.. -- docs/bets/<bet_slug>/decomposition/ docs/bets/<bet_slug>/technical-design/`
+  must show no change. The worker never edits that prose; if a proof looks wrong, that
+  is a blocking concern, not an edit.
+- **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
+  defect even though the suite is green — *a weak suite that generated code passes is
+  worse than no suite* (`docs/principles/foundations/testing.md`). Flag any of these
+  in the report rather than leaving them for the review to find.
+
+### 5. Do not commit
+
+The worker implements to green and stops. It does **not** commit, roll out permanent
+best-practice tests, or close the slice — those are the driver's, after its
+independent review and triage. Leave the working tree with the slice's changes
+unstaged; return the report.
+
+---
+
+## The report
+
+Return a short structured report and nothing else — no narration of the
+implementation, no replay of files read. Keep it to what the driver needs to review,
+triage, and close the slice:
+
+```
+SLICE: <n> <slice-slug>  (service: <owner-service>, surface: <core|slug>)
+BASELINE: <git rev-parse HEAD at open>
+SUITE: green | red — <one line: which slice tests pass; if still red, why>
+
+FILES:
+- added: <path>, ...
+- modified: <path>, ...
+- deleted: <path>, ...
+
+NOTES: <one or two sentences for the next slice — a pattern established, a deviation
+taken and why, a struggle worth not repeating>
+
+SELF-RECONCILE:
+- prose-integrity: clean | <what diff appeared>
+- honest-green: clean | <any hardcode / special-case / mock-of-real-work, named>
+
+BLOCKING CONCERN: none | <the case>
+```
+
+Set **BLOCKING CONCERN** when the slice cannot be honestly delivered as specified:
+
+- A **Proof of work proof that looks wrong** — it describes a shape the design never
+  defined, encodes a misread capability, or demands an outcome no implementation can
+  reach. The driver routes this through the Amendment Protocol; the worker never edits
+  the approved prose.
+- **Reality contradicting the locked design** — the design committed to something the
+  implementation reveals is wrong. The driver routes this through Change Navigation.
+- A **real dependency the proof names cannot be reached here** — so a faithful green
+  is impossible without the driver's decision (defer the slice, provision the
+  dependency, or amend the proof). Report it; do not substitute a mock and call it
+  green.
+
+The report is the worker's entire output. Keep it tight: if it runs long, it is
+explaining instead of reporting — cut the explanation.

package/src/hidden-skills/groundwork-bet/instructions.md

@@ -0,0 +1,88 @@
+---
+name: groundwork-bet
+description: >
+  Orchestrates the GroundWork bet lifecycle — Discovery, Design Foundations,
+  Decomposition, Delivery, Validation — moving one scoped slice of the product
+  vision from concept to validated delivery. Routes each phase to its workflow
+  file and tracks progress through the pitch's status frontmatter.
+---
+
+# groundwork-bet
+
+You are the orchestrator of the GroundWork bet lifecycle — Discovery, Design Foundations, Decomposition, Delivery, Validation. A bet is one scoped slice of the product vision, moved from concept to validated delivery through five phases that each produce a specific artifact.
+
+Apply the `groundwork-writer` skill when producing any artifact this lifecycle commits. Declarative, assertive, zero-hedging.
+
+---
+
+## Mental Model
+
+Each phase establishes one thing the next phase depends on:
+
+- **Discovery** establishes the *what* and the *why*. It produces the pitch — the problem, the appetite, the solution sketch, the success signal, and the explicit no-gos. Without it, design has nothing to anchor against.
+- **Design Foundations** establishes the *contract*. It produces the technical design — UI design first (one subsection per in-scope surface), then the headless core beneath it: data flows and business logic, API design, and schema & data design, surface-neutral. Without a locked design, decomposition produces milestones and tests that contradict each other.
+- **Decomposition** establishes *the order of work and the proof*. With the design locked, it authors the full **milestone ladder** — demonstrable states ordered to front-load risk, each carrying an **un-mockable** headline Proof-of-work proof (a stub or double cannot satisfy it; this is the success signal made executable) — but slices only the **first milestone**; later rungs are sliced on arrival in Delivery, from what the milestones before them taught. Capability milestones prove at the contract, surface milestones in each surface's medium; every shape traces to the prose API/data design. No test code is written here. The user reviews proof by proof and approves; the approved prose is committed and **tagged** (`bet/<slug>/approved`) — a **ratchet seal**, not a one-time freeze: it covers the ladder plus the first milestone's slices now, and advances additively as Delivery opens (or adds) each later milestone. The tests are generated red at Delivery start from this approved prose. Without this Proof of Work, delivery has no proof to satisfy and no sequence to follow.
+- **Delivery** materializes the red board from the approved prose, then drives it green as an orchestration. The agent is the *driver* — it holds the thin spine (the board, the milestone order, the granularity the user chose, the triage judgement) and dispatches a fresh slice-worker subagent per slice (`briefs/slice-worker.md`) so the heavy implementation context stays disposable. It reviews each worker's diff through independent lenses, commits the slice, and at every milestone boundary runs a postmortem that confirms the milestone honestly proved its intent, re-checks the remaining ladder, and authors the next milestone's slices from what this one taught (introducing a new rung when the ladder is missing one, within appetite) — the seal ratcheting forward as it goes, course-correcting through the Amendment Protocol or Change Navigation when a sealed proof or the design is wrong, never editing sealed prose around. Delivery is offered at three cadences — slice by slice, milestone by milestone (default), or whole bet — which set where the driver pauses; hard stops pause regardless. The suite is the board (`./dev bet status`, derived not stored) and each slice's commit is its record, so progress is visible and resumable. As each slice completes, permanent best-practice tests are rolled out, and a per-slice reconciliation checks that the sealed prose has not silently moved. Without the Decomposition contract, every design question becomes a mid-implementation conversation made under coding pressure.
+- **Validation** confirms the delivered bet behaves as designed, captures each touched service's served contract into the canonical `docs/architecture/api/` record, writes the bet's capability-ledger rows (when the project keeps a surface registry), archives the **whole bet** (docs and tests), runs the bet retrospective, and folds what the bet learned back into upstream documents for every subsequent bet.
+
+The lifecycle is sequential because each phase's output is the next phase's input. The order is structural, not procedural — gating design before decomposition is not a rule to follow but the only way the artifacts compose.
+
+Each phase runs in its own workflow file because each demands a different mode. Loading only the current phase's workflow keeps the conversation in one mode at a time; mixing modes produces shallow work in all of them.
+
+---
+
+## Lifecycle Overview
+
+| Phase | Workflow | Status | Output |
+|---|---|---|---|
+| 1. Discovery | `workflows/01-discovery.md` | `discovery` | `docs/bets/<slug>/pitch.md` |
+| 2. Design Foundations | `workflows/02-design.md` | `design` | `docs/bets/<slug>/technical-design/` (`01-ui-design.md`, `02-data-flows.md`, `03-api-design.md`, `04-data-design.md`) |
+| 3. Decomposition | `workflows/03-decomposition.md` | `decomposition` | `docs/bets/<slug>/decomposition/` prose tree — full milestone ladder + first milestone sliced, approved and sealed (ratchet tag `bet/<slug>/approved`) |
+| 4. Delivery | `workflows/04-delivery.md` (driver) + `briefs/slice-worker.md` (per-slice subagent) | `delivery` | Red board materialized from the approved prose, then driven green milestone by milestone — slice-workers implement, the driver reviews/commits, and at each milestone boundary a postmortem course-corrects and opens the next milestone (authoring its slices, ratcheting the seal); each slice committed as its record |
+| 5. Validation | `workflows/05-validation.md` | `validation` → `delivered` | Canonical `docs/architecture/api/` captured from running code; retrospective; whole bet archived |
+
+The pitch's frontmatter `status` field tracks where the bet sits in the lifecycle. Status transitions on entry to each phase and is the routing signal that lets a fresh context pick up the bet at the right place.
+
+---
+
+## Operating Contract
+
+Standard assistant behaviour — covering too much ground per turn, rushing to draft before the conversation has earned its conclusions, and treating documents as static after committing them — undermines collaborative design. These are the failure modes this process is built to prevent.
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) defines how to manage conversational pacing, discovery notes, living documents, and phase lifecycles. Read it before taking any other action — the protocols there govern how this entire skill operates.
+
+---
+
+## Activation
+
+Check `docs/bets/` for pitches (`<slug>/pitch.md`) and route on the pitch's `status` frontmatter.
+
+`docs/bets/` accumulates one pitch per bet, so several may exist. When the user names a bet — a slug or an unambiguous description — route on that pitch. Otherwise, a single pitch with an active status (anything other than `delivered`) is the bet to pick up; when more than one is active, list the candidates with their statuses and ask the user which to resume. Delivered pitches are the project's history, never resume candidates.
+
+- **`status: discovery`** — the pitch is committed but the bet has not entered Design Foundations. Read the pitch and proceed to Design Foundations.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/02-design.md`
+
+- **`status: design`** — the MVP handoff just completed; discovery is done. Read the pitch and proceed directly to Design Foundations.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/02-design.md`
+
+- **`status: decomposition`** — design is locked; proceed to Decomposition.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/03-decomposition.md`
+
+- **`status: delivery`** — decomposition is done; proceed to Delivery.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/04-delivery.md`
+
+- **`status: validation`** — delivery is done; proceed to Validation.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/05-validation.md`
+
+- **`status: delivered`** — the bet is complete; validation closed it. Tell the user this bet shipped and ask what they want to bet on next — follow-up work is a new bet with its own slug starting at discovery, never a reopened pitch.
+
+- **No pitch / new feature request** — ask the user what feature or problem they want to work on. Ensure the user provides a slug (e.g., `meeting-recording`) to use as the directory name for this bet. Then load and execute discovery.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/01-discovery.md`
+
+If activating in a fresh context against an existing pitch, briefly summarise the pitch's scope so the user can confirm the right bet was picked up before proceeding.

package/src/hidden-skills/groundwork-bet/templates/bet-progress-test.md

@@ -0,0 +1,126 @@
+# Bet-Progress Test Guidance
+
+*This document explains how to write bet-progress tests — the red proof-of-work suite generated at Delivery start from the bet's approved prose decomposition. It is guidance for the agent materializing the stubs, not a runnable test file. The actual test stubs live under `tests/bets/<bet-slug>/`.*
+
+---
+
+## What bet-progress tests are
+
+Bet-progress tests are **temporary, black-box proof-of-work** materialized from the approved prose before any implementation exists. Each one renders the Proof-of-work prose of a milestone or slice — the proof the user already reviewed and approved in the decomposition tree — into a runnable red stub. At Delivery start the board is materialized for the whole **milestone ladder** plus the **first milestone's slices**; each later milestone's slice stubs are added when Delivery opens that milestone (its slices are authored then). So the board shows progress at milestone granularity before the later rungs are sliced. They assert what the milestone's consumer would observe if the feature were complete. Red means the work is not done. Green means it is proven. Running the suite is the bet's live progress board.
+
+A milestone's proof follows its type:
+
+**Capability-level tests** prove a capability milestone — they hit the contract directly, end-to-end against the running services over HTTP (or against the embedded core's public API), with no surface in the loop. Every business rule the bet introduces is proven here, exactly once.
+
+**Interface-level tests** prove a surface milestone — they assert what that surface's users observe, in that surface's medium:
+- `graphical-ui` — a browser-driven test that navigates to the feature and verifies what the user sees
+- `cli` — a test that invokes the command and verifies the output, exit code, or side-effect
+- `agentic-protocol` — a test that sends a protocol request and verifies the response structure
+
+Interface-level tests resolve their target surface through the surfaces fixture (slug → entry point) and are bounded to wiring, rendering, and interaction. **They never re-prove core logic** — a business rule already proven at the contract re-asserted in a surface test is a review finding, because it multiplies the test pyramid by the surface count for nothing. When an interface test goes red against green capability tests, the failure is in the surface's adapter layer by elimination.
+
+When the project has no surface registry, the two layers pair up per milestone exactly as they always have: an interface-level test in the project's single medium, plus an API-level system test that localizes failures.
+
+Slice tests prove the vertical capability a slice contributes toward its parent milestone. They are **informed by and bounded by** the parent milestone's tests — a slice test proves a specific capability; the milestone test proves the consumer-visible outcome those capabilities enable. A slice's `surface` field names the discipline that applies: `core` slices prove contract behaviour; surface slices prove wiring in their surface's medium.
+
+---
+
+## The target-state principle
+
+Write every test as if the feature already exists. The test describes the desired reality, not the current state. A test that asserts "endpoint returns 501" is not a bet-progress test — it describes the absence of implementation. Assert the presence of the delivered capability.
+
+---
+
+## System-level only
+
+Bet-progress tests hit the running services from the outside. They:
+- Do not import application code
+- Do not mock services or fake data layers
+- Do not depend on implementation details (database schemas, internal module structure)
+
+If a test requires knowledge of an internal module, it is not a bet-progress test — it belongs in the permanent per-service test suite.
+
+---
+
+## File naming convention
+
+All bet-progress tests live under `tests/bets/<bet-slug>/`. The `<bet-slug>` is the kebab-case slug of the bet (the `docs/bets/<bet-slug>/` directory name).
+
+**Milestone test files:**
+```
+tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.<ext>
+```
+Where `<N>` is the milestone number (1, 2, 3...), `<milestone-slug>` is the kebab-case milestone name, and `<ext>` is the project's test language extension (`.py`, `.go`, `.ts`) — discovered from the scaffold, never assumed.
+
+**Slice test files:**
+```
+tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.<ext>
+```
+Where `<N>` is the slice number within the milestone, `<service>` is the owning service name (from `docs/architecture/infrastructure.md`), and `<slice-slug>` is the kebab-case slice name.
+
+**Archive path (Phase 5 — after delivery):**
+```
+tests/bets/_archive/<bet-slug>/
+```
+
+---
+
+## Fixtures and service discovery
+
+Bet-progress tests reuse the shared fixtures from `tests/conftest.py`:
+- `cluster` — boots and health-checks all services; provides the running topology
+- `api_client` — an HTTP client configured with the discovered service base URLs; capability-level tests use this to hit the contract directly
+- `pure_state_reset` — truncates all service data stores before each test (autouse)
+- `surfaces` — the mapping from registry slug to that surface's entry point (base URL for a web surface, binary path for a CLI, protocol endpoint for an agentic surface); interface-level tests resolve their target surface here
+- `frontend_base_url` — the legacy alias for the single graphical surface's base URL; present when exactly one graphical surface exists, for suites written before the surfaces fixture
+
+Declare the fixtures you need as test-function parameters; pytest resolves them from the parent conftest automatically.
+
+For interface-level tests against a `graphical-ui` surface, the `page` fixture (from pytest-playwright) drives a real browser. For `cli` surfaces, use `subprocess` or `pexpect` to invoke the binary directly.
+
+## Capturing screenshots for the visual verification loop
+
+For `graphical-ui` interface tests, capture a screenshot of each key state of the screen under test — default, hover, focus, empty, loading, error — written to `.groundwork/cache/visual/<bet-slug>/<surface>/<state>.png` (create the directory first). These are the states where "renders broken" and "looks unfinished" both live, and the captures are what the delivery agent reads (Tier 2 inspection) and the validation fidelity critique grades (Tier 3). Capture after the state is reached and assertions pass — the screenshot records the proven state, it does not replace the assertion. Capture nothing for `cli` and `agentic-protocol` surfaces; their observable output is text, asserted directly.
+
+**What capture sees, and what it does not.** A static screenshot verifies render correctness, coherence, and composition. It does *not* see motion (easing, durations, press physics) or perceived latency — both committed in the design system — so those stay behaviour-tested, asserted on timing and state, never on a frame. Do not treat a captured screen as proof of an animation or a latency budget.
+
+**Declare the routes the bet touched.** The permanent route-driven gates (render-smoke, geometry, visual-regression) sweep the screens listed in `tests/system/routes.json` (a JSON array of paths), defaulting to the app root when absent. When a bet adds or changes a `graphical-ui` route, add it to that manifest so the permanent suite covers it — the same promotion shape as the bet's other best-practice tests.
+
+---
+
+## Placeholder structure for red tests
+
+When the implementation does not exist yet, a test stub must be **explicitly red** — it must fail, not skip. Use the pattern appropriate to the test language:
+
+- Python: `pytest.fail("bet-progress test not yet implemented — <describe target state>")`
+- Go: `t.Fatal("bet-progress test not yet implemented — <describe target state>")`
+- TypeScript: `throw new Error("bet-progress test not yet implemented — <describe target state>")`
+
+Comment the stub with what it will eventually assert, so the Delivery agent knows exactly what to implement. For a capability milestone stub:
+```
+# Contract: [the end-to-end behaviour the core should prove — request, response, persisted effect]
+```
+For a surface milestone stub:
+```
+# Surface <slug>: [what the user should observe in this surface's medium — wiring and rendering only]
+```
+For an untyped milestone (no surface registry), comment both layers:
+```
+# Layer 1 — interface: [what the user should observe in the product]
+# Layer 2 — API: [what the service should return end-to-end over HTTP]
+```
+
+---
+
+## What makes a good bet-progress test
+
+A bet-progress test is good when:
+- It asserts a **falsifiable, consumer-visible outcome** — at the contract or in a surface's medium, never an internal state
+- It would fail if the feature shipped incomplete
+- For a **milestone headline**, it is **un-mockable** — it exercises the real dependency that makes the milestone meaningful (the live model, the real service, the actual store), so a stub, mock, or hardcoded return cannot turn it green. A milestone proof a double can satisfy proves plumbing, not the milestone (`workflows/03-decomposition.md`)
+- It would pass without any special knowledge of how the feature is implemented internally
+- It proves each business rule exactly once — at the contract; surface tests assert only wiring, rendering, and interaction
+- It is a **headline proof, not a permutation** — it proves the milestone's outcome or the slice's capability, not every input variant or error code
+- A reviewer can read it and confirm it matches the milestone's acceptance criteria and Proof-of-work prose in its `decomposition/NN-<milestone-slug>/index.md`
+
+**Keep the suite lean.** Bet-progress tests render the high-impact proofs the user reviewed and signed as prose — a milestone's consumer-visible outcome and each slice's vertical capability, typically one to three assertions apiece. If an assertion is an edge case, a permutation, or an error variant rather than the headline outcome, it does not belong here; it is part of the slice's permanent best-practice tests, written when the slice is built in Delivery (`workflows/04-delivery.md` Step 5). A wall of assertions is unreviewable upstream and front-loads coverage the delivery suite is meant to carry.

package/src/hidden-skills/groundwork-bet/templates/change-proposal.md

@@ -0,0 +1,38 @@
+# Change Proposal [N]: [Bet Name]
+
+*Written when mid-delivery reality contradicts the locked design. The proposal is the decision record the user approves before any locked artifact moves — and the audit trail Validation's retrospective reads afterward.*
+
+**Severity:** [minor — contracts and milestones survive; specific tests/design sections need correction | structural — a contract, milestone, or the appetite is wrong]
+
+---
+
+## Discovery
+
+[What implementation revealed, stated as evidence — the failing behaviour, the incompatible dependency, the contract that cannot be satisfied. Quote the error, the doc, or the code that proves it.]
+
+## Impact
+
+| Artifact | Affected section | Why |
+|---|---|---|
+| `pitch.md` | [section or none] | [how the discovery touches it] |
+| `technical-design/` | [section file — `01-ui-design.md` / `02-data-flows.md` / `03-api-design.md` (shapes) / `04-data-design.md`] | |
+| `decomposition/` | [milestone `index.md` / slice file] | |
+| Built artifacts | [test stub(s) under `tests/bets/<slug>/`, the served contract] | |
+
+## Proposed changes
+
+*(One entry per edit. Before/after, not descriptions of edits.)*
+
+### [artifact → section]
+
+**Before:**
+> [current text / spec fragment / assertion]
+
+**After:**
+> [proposed text / spec fragment / assertion]
+
+**Rationale:** [why this is the right correction, in one or two sentences]
+
+## Routing
+
+[Minor: edits applied on approval, mutated docs re-reviewed, affected proofs amended through the Amendment Protocol (edit the slice/milestone prose, re-tag `bet/<slug>/approved`, then change the code), slice resumed. Structural: bet reverts to Design Foundations with this proposal as input; delivered slices that survive the change are listed here.]

package/src/hidden-skills/groundwork-bet/templates/decomposition/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Decomposition",
+  "pages": ["..."]
+}

package/src/hidden-skills/groundwork-bet/templates/decomposition/milestone-index.md

@@ -0,0 +1,35 @@
+# Milestone [N]: [Milestone Name]
+
+*This is the landing page for one milestone in the decomposition tree. It renders to `docs/bets/<bet-slug>/decomposition/NN-<milestone-slug>/index.md`. It carries the milestone's demonstrable goal, its sequencing rationale, its acceptance criteria, and the prose proof of work — then links to its slices. The slice files sit beside it in the same folder.*
+
+*`Type:` and `Consumer:` apply only when the project carries a surface registry (`docs/surfaces.md`). With no registry, omit both — milestones are user-visible states in the product's single interface medium, exactly as before.*
+
+**Type:** capability | surface ([surface-slug])
+
+**Consumer:** [who exercises this contract — the bet's in-scope surfaces that build on it in later milestones, or the latent agentic surface for a headless delivery. Capability milestones only.]
+
+**Demonstrable goal:** [the state the product reaches when this milestone is complete. For a capability milestone: the contract behaviour provable end-to-end against the running services (or the embedded core's public API) — curl-able, scriptable, observable. For a surface milestone: what a user of this surface can observe or do, in that surface's medium, bounded to wiring, rendering, and interaction.]
+
+**Sequencing rationale:** [why this milestone sits where it does. A bet introducing new capability opens with its capability milestone, because every surface milestone consumes the contract it proves. A surface milestone states what it wires and never re-proves the rules the capability milestone settled.]
+
+**Acceptance criteria:**
+- [ ] [specific, falsifiable criterion — at the contract for a capability milestone, in the surface's medium for a surface milestone]
+- [ ] [specific, falsifiable criterion]
+
+## Proof of work
+
+*The prose proof the user reviews and approves. This is the milestone's definition of done in plain language — what becomes true about the product and how the suite proves it. No assertion code; the runnable stub is generated from this prose at Delivery start.*
+
+**Proves:** [the consumer-visible outcome this milestone reaches, in one or two sentences. State what becomes true about the product, not how a test is written.]
+
+**How we prove it:** [the shape of the proof in prose — what the suite exercises end to end and the observable condition it passes on. A reader should understand the proof without seeing any code. For a capability milestone this hits the contract directly; for a surface milestone it asserts what that surface's users observe.]
+
+**Test file:** `tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.<ext>` — generated red at Delivery start; traces to [the interface in `technical-design/03-api-design.md` (or store in `04-data-design.md`) for a capability milestone, or the surface subsection in `01-ui-design.md` for a surface milestone].
+
+## Slices
+
+*The first milestone is sliced now, at decomposition; every later milestone is sliced when Delivery opens it (`workflows/04-delivery.md`), from what the milestones before it taught. Until a milestone is opened, leave the placeholder line below; once it is sliced, replace it with ordered links — each slice a vertical capability that moves this milestone forward.*
+
+> *Slices authored on arrival.*
+
+- [Slice [N.1]: [Slice Name]](./NN-<slice-slug>.md)

package/src/hidden-skills/groundwork-bet/templates/decomposition/slice.md

@@ -0,0 +1,35 @@
+# Slice [N.M] — [service]: [Slice Name]
+
+*One vertical slice of a milestone. Renders to `docs/bets/<bet-slug>/decomposition/NN-<milestone-slug>/NN-<slice-slug>.md`. It states the slice's scope, ties it to the design, and carries the prose proof of work the user approves. The slice is vertical — it can be deployed and verified without any future slice existing.*
+
+*`Surface:` applies only when the project carries a surface registry (`docs/surfaces.md`); omit it with no registry.*
+
+**Owner service:** [service name from `docs/architecture/infrastructure.md`]
+
+**Surface:** core | [surface-slug from `docs/surfaces.md`]
+
+**Complexity:** S / M / L
+
+**Prerequisite:** (none, or "Slice [N.K] merged")
+
+## Scope
+
+[One paragraph linking this slice to its milestone — what vertical capability it contributes and how that capability demonstrably moves the milestone forward.]
+
+**Required Capabilities:**
+- [Falsifiable capability statement 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.]
+- [Falsifiable capability statement]
+
+## Design
+
+[Where this slice lands in the design. Name the interface it implements in `technical-design/03-api-design.md` or the store it touches in `technical-design/04-data-design.md`, the data flow it realizes in `technical-design/02-data-flows.md`, and — for a surface slice — the view or interaction in `technical-design/01-ui-design.md` it wires. The shapes the slice builds against live in that prose design at design fidelity; this slice does not restate them.]
+
+## Proof of work
+
+*The prose proof the user reviews and approves — this slice's definition of done in plain language. No assertion code; the runnable stub is generated from this prose at Delivery start.*
+
+**Proves:** [the vertical capability this slice contributes, in one plain-language sentence — what it makes true that the milestone depends on.]
+
+**How we prove it:** [the proof case in prose — the request or interaction exercised and the observable condition it passes on. A `core` slice proves contract behaviour; a surface slice proves wiring, rendering, and interaction only, never re-proving a rule the capability milestone settled.]
+
+**Test file:** `tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.<ext>` — generated red at Delivery start; traces to [the interface, channel, or schema table in `technical-design/` it rests on].

package/src/hidden-skills/groundwork-bet/templates/pitch.md

@@ -0,0 +1,45 @@
+---
+status: discovery
+surfaces: [<registry-slug>, <registry-slug>]
+---
+
+# Bet: [Feature Name]
+
+*`surfaces:` lists the registry slugs (from `docs/surfaces.md`) this bet delivers to — validation fills the capability ledger from this scope. When the project has no surface registry, omit the key entirely: the bet runs against the single implicit surface, exactly as before the registry existed. A single-surface registry means one entry and nothing more.*
+
+## The Pitch
+*Provide a brief explanation of the problem, the proposed solution, the appetite, and the stakes.*
+
+- **Problem:** What user problem are we solving?
+- **Appetite:** How much is solving this worth — judged by opportunity cost, what else this cycle could hold? State worth, not an effort estimate. (Express in calendar time only when human-coordination time is the real constraint.)
+- **Stakes:** What is at risk if we get this wrong — blast radius (surface touched, who feels it), reversibility (one-way door or iterate-behind-a-flag), and review load (how much a human must hold to vouch for it)? Stakes earns the rigour; it is not effort.
+- **Solution:** At a high level, how will we solve this?
+- **Success Signal:** What observable outcome confirms this bet delivered its intended value?
+
+### Topology
+
+*A `graph` of the services and components this bet touches and how they connect — the picture that frames the solution at a glance. Renders on GitHub and the docs site. Leave the placeholder below at discovery; the design phase fills it in once the actual shape is known (`workflows/02-design.md` updates it as a living document), so a reader of the pitch always sees the system the bet plays in.*
+
+```mermaid
+graph TD
+  A[Surface / caller] --> B[Service this bet touches]
+  B --> C[(Store)]
+  B --> D[Downstream service]
+```
+
+## Rabbit Holes & No-Gos
+*Two distinct lists. Rabbit holes protect the appetite from technical surprise; no-gos protect it from scope creep.*
+
+**Rabbit Holes** — the technical traps or unknowns that could silently eat the appetite. Name where the work could balloon, and the guard or spike that keeps it bounded. Skip only if the bet is genuinely low-risk technically — and say so if it is.
+
+- [ ] Risk: <what could balloon> — Guard: <the spike, cap, or decision that bounds it>
+
+**No-Gos** — the things we are explicitly NOT doing, to prevent scope creep. Include natural extensions users would expect but are excluded — "users will expect X, but we are not doing X because…" — so reviewers do not raise them as gaps.
+
+- [ ] Out of scope item 1 — why it is excluded
+- [ ] Out of scope item 2 — why it is excluded
+
+**Surface no-gos** — when the registry holds surfaces beyond this bet's `surfaces:` scope, name each surface the capability will not reach in this bet, with its disposition: **deferred** (will reach it later — state the intent) or **omitted** (deliberately never — state the rationale). Validation writes these dispositions into the capability ledger; a surface left unstated here becomes an empty ledger cell the bet cannot close with. Skip this list when the registry holds one surface or the project has no registry.
+
+- [ ] Surface `<slug>` — deferred: <what brings the capability there, and roughly when>
+- [ ] Surface `<slug>` — omitted: <why this capability deliberately never ships here>

package/src/hidden-skills/groundwork-bet/templates/technical-design/01-ui-design.md

@@ -0,0 +1,51 @@
+## UI Design
+
+*The user-facing design of each surface this bet delivers to — what the user sees, the states it must cover, and how they interact. One subsection per surface in the pitch's `surfaces:` scope, written in the vocabulary of the surface's interface type (from its design track in `docs/design-system.md`):*
+- *`graphical-ui` — screens, views, regions, states (loading, active, empty, error, degraded), with a wireframe per key view*
+- *`cli` — commands, flags, output format, error messages, exit codes (no wireframe — the output sketch stands in)*
+- *`agentic-protocol` — request/response turns, protocol states, expected response structure (no wireframe)*
+
+*Organize each subsection by view, command, or interaction — not by feature or service. Each subsection is the anchor that surface's milestone interface-tests will assert against.*
+
+*When the project has no surface registry (`docs/surfaces.md` absent), the product has a single implicit surface: write one subsection for it in the project's interface medium and skip all other surface ceremony. A single-surface registry likewise produces exactly one subsection.*
+
+### Surface: [surface-slug]
+
+#### [View / Command / Interaction Name]
+
+**Purpose:** [what this interaction accomplishes for the user]
+
+**Wireframe** *(graphical-ui only):*
+
+*An ASCII sketch of the view's layout — the regions, their arrangement, and the key controls. Low-fidelity on purpose: it fixes structure and hierarchy, not pixels. One sketch per key view; annotate the notable states inline or sketch a second frame when a state changes the layout materially (empty vs populated, error). The ASCII is the source of truth and is always present — a reader and an agent both build the layout from it.*
+
+```
+┌─ [View title] ──────────────────┐
+│ [region / control]      [action]│
+├─────────────────────────────────┤
+│ [primary content area]          │
+│                                  │
+│ [secondary panel or list]       │
+└─────────────────────────────────┘
+```
+
+*Optional — when a real mockup exists:* `![<view> — <state>](./wireframes/<surface>-<view>.png)`. *A linked or embedded design image supplements the ASCII; it never replaces it (an image is not diffable and an agent cannot read layout intent from it).*
+
+**States:**
+
+| State | Trigger | What the user observes |
+|-------|---------|------------------------|
+| [state name] | [what causes this state] | [what the user sees, reads, or receives] |
+| [state name] | [what causes this state] | [what the user sees, reads, or receives] |
+
+**Key interactions:**
+- [user action] → [system response and any state transition]
+- [user action] → [system response]
+
+**Micro-polish spec** *(graphical-ui only — token-traceable, not adjectives):*
+- *Motion:* [the motion profile or `{duration, easing, transform}` per interaction/state transition — `hover`, `press`, `enter`/`exit`, `stagger`]
+- *Atmosphere / material:* [surface treatment token — `surface-glass`/`surface-elevated`/`surface-hero`, or an explicit blur/tint/border/elevation/gradient composition — plus any glow or grain]
+- *Static micro:* [elevation token (`shadow-low/mid/high`), spacing steps, type roles with line-height/tracking, colour roles, optical-alignment and crisp-rendering obligations]
+
+---
+*(Add a view/command/interaction block for each significant interaction this bet introduces on this surface; add a `### Surface:` subsection for each in-scope surface)*