groundwork-method 0.0.1 → 0.11.0

package/src/hidden-skills/groundwork-review/checklists/technical-design.md

@@ -0,0 +1,112 @@
+---
+name: technical-design-checklist
+description: >
+  Type-specific failure modes for reviewing a bet's technical design — the
+  contract Decomposition and Delivery execute against.
+---
+
+# Technical Design Checklist
+
+This checklist checks a draft `docs/bets/<slug>/technical-design/` directory. It answers one question:
+**could a developer implement from this design on the first pass — and could a milestone proof
+pass or fail against it unambiguously?**
+
+Each item names a violation. Match it against the document text, the bet's pitch, and the
+upstream docs. Bet documents carry no Downstream Context file and no summary section — do not
+flag the absence of either.
+
+## Document Shape
+
+- [ ] 🔴 **Implementation code present**: the document contains application logic — the design
+  phase is forbidden from writing implementation code; only design documentation, interface
+  specifications, contracts, and schemas belong here.
+- [ ] 🟡 **Per-milestone organisation**: the design is split by milestone or phase rather than
+  covering the entire bet — decomposition has leaked into the design artifact.
+- [ ] 🟡 **Section missing without reason**: one of UI Design, Data Flows, API Design,
+  or Schema & Data Design is absent and the document does not state why it does not apply to this bet.
+
+## UI Design
+
+UI Design carries one subsection per surface in the pitch's `surfaces:` frontmatter. When
+the project has no surface registry (`docs/surfaces.md`), the product has a single implicit
+surface — expect exactly one subsection in the project's interface medium, and do not flag the
+absence of surface ceremony.
+
+- [ ] 🔴 **In-scope surface undesigned**: a surface in the pitch's `surfaces:` scope has no
+  UI Design subsection — that surface's milestone tests will have nothing to assert
+  against, and delivery will improvise the experience.
+- [ ] 🔴 **Untestable interface**: a view, command, or interaction is described too vaguely for a
+  test to pass or fail against it — surface milestone tests assert against these subsections, so
+  "the user can manage their notifications" specifies nothing.
+- [ ] 🔴 **Missing states**: a view or command defines its happy path but not its loading, empty,
+  error, or degraded states — the states are where implementations diverge silently.
+- [ ] 🟡 **Wireframe missing**: a `graphical-ui` surface's key view defines states but carries no
+  wireframe — neither an ASCII sketch nor a linked mockup — so its layout and hierarchy are left
+  for the build to improvise. The ASCII wireframe is the always-present baseline; a mockup image
+  supplements but does not replace it.
+- [ ] 🟡 **Wrong medium vocabulary**: a surface's subsection does not use the vocabulary of that
+  surface's interface type in `docs/design-system.md` — screens and states for graphical UI,
+  commands and output for CLI, request/response turns for agentic protocol. Each subsection
+  speaks its own surface's vocabulary; a CLI subsection describing "screens" is a violation even
+  when the bet also scopes a graphical surface.
+- [ ] 🟡 **Organised by service, not by interaction**: a surface subsection is structured by
+  feature or service instead of by view, command, or interaction — the user-observable surface
+  is the unit milestones prove.
+
+## API Design
+
+- [ ] 🔴 **Vague shape**: a prose API entry in `03-api-design.md` says "returns the entity" or
+  "accepts the standard payload" instead of giving the full request and response shapes with
+  field types inline. The prose design is the bet's only contract — Delivery materializes proofs
+  and builds the implementation from these shapes, so what is not here will not be in the
+  implementation, and a proof cannot rest on a shape the design never spelled out.
+- [ ] 🔴 **State change without a shape**: a bet changes persistent state but the affected store
+  carries no field shapes in `04-data-design.md` — column names, types, and nullability. A
+  persisted effect a proof observes traces to this store; an undefined store cannot be
+  implemented or proven against.
+- [ ] 🔴 **No error cases**: an endpoint in the API design defines no error responses, or lists
+  status codes without caller guidance — the caller's recovery behaviour is part of the contract.
+- [ ] 🔴 **Contract shaped for one consumer**: an interface in the API design only one in-scope
+  surface can consume — it presumes web session state, returns markup where data belongs,
+  paginates by viewport, or encodes one surface's rendering concerns. The contract serves every
+  in-scope surface and presumes none; when only one surface is in scope, the latent agentic
+  surface is the second consumer — a programmatic caller with no UI and no session must find the
+  contract complete.
+- [ ] 🟡 **Untyped field**: a request or response field appears without a type, nullability, or
+  allowed values where they matter (enums, cursors, identifiers).
+- [ ] 🟡 **Auth unstated**: a contract does not state its authentication requirement, on a
+  boundary where the architecture defines one.
+- [ ] 🟡 **Rationale-free surprise**: a non-obvious contract decision (pagination model,
+  idempotency rule, versioning) is asserted with no design rationale — the next reader will
+  relitigate it.
+
+## Data Flows & Data Design
+
+- [ ] 🔴 **Flow without a trigger or a sink**: a data path does not state what initiates it,
+  which services handle it, or what persists at the end — an arrow with a missing end.
+- [ ] 🟡 **Flow without a diagram**: a non-trivial cross-service or routing flow is described in
+  prose with no `sequenceDiagram` or `flowchart` — ordering and service boundaries that a diagram
+  makes legible are left to the reader to reconstruct.
+- [ ] 🟡 **Domain doc duplicated**: the schema section restates an entity already defined in
+  `docs/architecture/domain/` instead of referencing the entity doc and describing only what this bet adds or
+  changes — the copies will drift.
+- [ ] 🟡 **Schema without lifecycle**: a table or store that carries a status field defines no
+  state machine for it, and no reference to where one is defined.
+
+## Chain Integrity
+
+- [ ] 🔴 **Pitched capability undesigned**: a capability or outcome the pitch commits to has no
+  interface element, flow, or contract covering it — Delivery will discover the hole mid-bet.
+- [ ] 🔴 **Silent scope growth**: an interface element or flow traces to nothing in the pitch —
+  the design has quietly expanded the bet beyond its appetite.
+- [ ] 🟡 **Stakes mismatch**: the design's actual blast radius or reversibility is graver than
+  the pitch's stakes read — it touches a one-way door, a load-bearing path, or a wider surface
+  than the pitch sized for — yet no rigour (deeper review, a flag, a smaller increment) answers it.
+- [ ] 🔴 **Architecture contradiction**: a contract or flow contradicts `docs/architecture/index.md`
+  or an accepted ADR — a sync call across a boundary the architecture made async, a store a
+  service does not own.
+- [ ] 🟡 **Pitch topology missing or stale**: the design establishes the services and components
+  this bet touches, but the pitch's Solution carries no topology graph — or still shows the
+  template placeholder — so a reader of the pitch cannot see the system the bet plays in. A
+  trivial single-component bet may carry a one-line note instead of a graph; silence is the
+  violation.

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

@@ -0,0 +1,181 @@
+---
+name: groundwork-review
+description: >
+  Reviews a draft GroundWork document in an isolated subagent context and
+  returns a structured verdict — PRESENT or REVISE — with critical and advisory
+  findings. Calling skills invoke it once per mutated canonical doc with the
+  document path and type; only the verdict and findings flow back.
+---
+
+# GroundWork Review
+
+## How This Skill Is Invoked
+
+This skill runs in an **isolated subagent context** — never in the calling skill's main conversation. The calling skill provides a document path and document type; this subagent reads the document, performs the review, and returns the verdict and findings only. The deliberation, the upstream-doc reads, and any intermediate reasoning stay in the subagent context and do not flow back to the caller.
+
+Running the review in-context, the way earlier versions of this skill operated, paid the cost of every review's intermediate reasoning forever — the verdict and findings are useful to the caller; the deliberation is not. Isolation is the contract.
+
+### Invocation environments
+
+| Environment | How the calling skill invokes the review |
+|---|---|
+| Claude Code | Via the `Task` tool with a general-purpose subagent. The prompt loads this file and supplies the document path and document type. |
+| Other environments | Any mechanism that runs this skill's instructions in an isolated context with file-read tools and returns the final text. |
+
+The contract is environment-agnostic — input and output are the same regardless of how the isolated execution is realised.
+
+---
+
+## Inputs
+
+The calling skill passes two fields:
+
+- `document_path` — the draft to review. The path may point to a cache draft (e.g. `.groundwork/cache/product-brief-draft.md`) or a committed canonical doc.
+- `document_type` — one of: `product-brief`, `design-system`, `architecture`, `infrastructure`, `domain-entity`, `bet-pitch`, `technical-design`, `decomposition`, `maturity`. Used to locate upstream documents.
+
+Read the document at `document_path` before beginning any check.
+
+---
+
+## Type-Specific Checklist
+
+After reading the document, load `.groundwork/skills/groundwork-review/checklists/<document_type>.md` if it exists. The checklist names the failure modes specific to this document type; apply its items as the type-specific pass alongside Checks 1–4. When a checklist item is violated, cite it **by name** in the finding — e.g. `checklist: Label without a person — 'Role-Playing Groups' has no job-to-be-done` — not by restating the item's text.
+
+If the checklist file is missing, proceed with the generic checks alone — its absence is not an error.
+
+One checklist deliberately sits outside the `document_type` enum: `checklists/implementation-readiness.md` is the delivery workflow's inline gate, applied directly by the bet skill before the first slice — it never routes through this review and must not be added as a `document_type`.
+
+Checklist findings flow through the same output contract below: the item's 🔴/🟡 marking sets the finding's severity, the verdict rules apply unchanged, and the length discipline holds — cite item names, not item text.
+
+---
+
+## Output Contract
+
+Return exactly two blocks of structured output, in this order, and nothing else:
+
+```
+VERDICT: PRESENT | REVISE
+
+FINDINGS:
+- 🔴 <finding 1>
+- 🔴 <finding 2>
+- 🟡 <advisory finding>
+```
+
+If there are no findings, return `FINDINGS: none`. Do not write conversational text, do not summarise the document, do not explain your reasoning. The calling skill consumes only the verdict and findings — anything else is wasted output tokens.
+
+The verdict rules:
+
+- Any 🔴 Critical finding → `VERDICT: REVISE`. The caller revises and re-invokes.
+- Only 🟡 Advisory findings (or none) → `VERDICT: PRESENT`. The caller surfaces the advisory findings to the user after presenting the draft.
+
+---
+
+## Check 1: Conversation Fidelity
+
+The subagent context does not see the calling skill's conversation. This check therefore narrows: instead of comparing the document to the conversation that produced it, compare it to the document's own internal coherence and to the upstream docs (Check 3).
+
+For checks that genuinely require the conversation, the calling skill is responsible for noting them when it invokes the review — pass any concern about fidelity as a hint inside the invocation prompt.
+
+For this check, answer:
+
+**Does the document contradict itself?**
+Scan for internal contradictions — a capability named in one section that is excluded in another, a constraint stated as binding but ignored in the body, a deferred question that the body silently resolves. Each contradiction is a finding.
+
+**Does the document contain claims the upstream docs do not support?**
+This shades into Check 3 but applies even when the document has no upstream — any claim that reads as fact but is not derivable from the document's own evidence is a finding.
+
+---
+
+## Check 2: The Handoff Test
+
+This document will be read by someone — agent or human — who was not in the conversation. They will use it to start their own work.
+
+Read the document's own description of its purpose and who it serves. Then ask:
+
+**Can each intended consumer start their work with only this document?**
+
+For every person or role the document claims to serve, ask: what would they have to come back and ask before they could begin? Each unanswered question is a finding.
+
+Published `docs/` artifacts are **clean reference documentation** — they carry no `## Summary for Downstream` section. The cross-phase contract (Key Decisions / Binding Constraints / Deferred Questions / Out of Scope) lives in the ephemeral Downstream Context file at `.groundwork/context/<phase>.md` (Protocol 5 of the operating contract), written at commit and torn down at setup completion (Protocol 10). That context file is **not** the document under review and is **not** part of this gate — the reviewer assesses the published doc body as reference documentation. Do not read `.groundwork/context/` and do not require, or check the contents of, any summary section in the published doc.
+
+If a published setup doc still carries a leftover `## Summary for Downstream` section (an old-template artifact), that is itself worth a 🟡 finding — the section no longer belongs in published docs — but its **absence** is correct and must never be flagged.
+
+Apply the Handoff Test to the body itself: every decision, constraint, deferral, and exclusion the consumers need must be present and coherent **in the body**. A binding decision the body fails to record, or an open question the body silently resolves, is a finding on the body — not on any summary header.
+
+---
+
+## Check 3: Upstream Contract
+
+Every document after the first inherits commitments from the documents that came before it.
+
+The chain is:
+
+```
+product-brief → design-system → architecture → infrastructure → bet-pitch → technical-design → decomposition
+```
+
+**`maturity` resolves its upstream specially.** The maturity doc (`docs/maturity.md`) assesses the project against the model defined at `.groundwork/skills/maturity-model.md` — read that file first; it defines the dimensions (D1–D9), assessment states, and the allowed severity/recommendation/status values. Its upstream is the full canonical doc set: an assessment or roadmap row that contradicts a committed doc (claiming D3 ✅ while `docs/architecture/infrastructure.md` records no `./dev` surface, or naming a service `docs/architecture/index.md` does not have) is a 🔴 finding.
+
+**`domain-entity` resolves its upstream specially.** Domain entity docs (`docs/architecture/domain/<entity>.md`) are *generated from* architecture, so they sit below it rather than on the linear chain. Their upstream is **`docs/architecture/index.md` plus the accepted (non-superseded) ADRs under `docs/architecture/decisions/`** — skip any ADR whose `status` is `superseded`. The entity's `Owner:`, its fields, and any vendor or mechanism it names (auth provider, persistence model, data-isolation strategy) must agree with that current architecture and those ADRs. A domain doc that still names a superseded choice — e.g. `Owner: web (via Supabase Auth)` after an ADR moved auth to Clerk and persistence to another service — is a 🔴 finding: it describes a system no longer being built.
+
+An invariant that asserts a guarantee an accepted ADR explicitly surrendered or weakened — claiming a pre-screen where the ADR records a monitor, immediate consistency where the ADR accepted eventual — is a 🔴 finding: it overstates what the system enforces. A domain event listed as published when the architecture provisions no message broker or event bus is a 🔴 finding for the same reason: it implies a mechanism that does not exist.
+
+For the given `document_type`, read every upstream document that exists. The foundational documents live at canonical paths: `docs/product-brief.md`, `docs/design-system.md`, `docs/architecture/index.md`, `docs/architecture/infrastructure.md`. The bet documents live under the bet slug: `docs/bets/<slug>/pitch.md` and the technical-design directory `docs/bets/<slug>/technical-design/` (read every section file in it). When reviewing a bet document, infer `<slug>` from the document path — the draft path contains the slug as a directory component.
+
+**Read each upstream doc's body.** Published upstream docs are reference documentation with no summary section; the doc body is the contract. Check the document under review against the decisions and constraints the upstream body commits to.
+
+If an upstream document doesn't exist, skip this check for that upstream and note its absence — do not fail on it.
+
+If the product brief is the document being reviewed, skip this check entirely. It has no upstream.
+
+For each upstream:
+
+**Does the document honour every commitment from upstream?**
+
+- Are all decisions, constraints, and users/capabilities the upstream body commits to accounted for — either addressed, explicitly deferred, or quietly compatible?
+- Does anything in this document contradict the upstream body?
+- Has any upstream commitment been silently dropped?
+
+Each contradiction, omission, or silent departure is a finding.
+
+---
+
+## Check 4: Document-Type Specifics
+
+Some document types carry a requirement the generic checks do not cover.
+
+**`bet-pitch` — the `## Rabbit Holes & No-Gos` section must contain actual rabbit holes, not only no-gos.** These are two distinct things:
+
+- **No-Gos** are scope exclusions — features deliberately cut ("users will expect authoring, but it is bet two").
+- **Rabbit Holes** are technical traps or unknowns that could silently consume the appetite — the parts where the work could balloon (long-session coherence, classifier latency against a tight budget, prompt-size growth, idempotency under retries) — each ideally paired with a guard or a spike.
+
+If the section lists only scope cuts and names no technical rabbit hole, yet the bet plainly carries technical risk, that is a 🔴 finding: the pitch has not surfaced where the appetite is actually at risk. A bet that is genuinely low-risk technically may state so explicitly instead.
+
+**`maturity` — rows must be complete and evidenced.** Check every row against the model's allowed values:
+
+- Each assessment row carries a state (✅/🟡/🔴, or `n/a` on the conditional dimensions D8–D9) **and** evidence — a state with no cited file, command output, or absence is a 🔴 finding.
+- Each roadmap row carries a dimension (D1–D9), a severity (`blocks-delivery`/`standard-divergence`/`cosmetic`), a recommendation (`fix-now`/`defer`/`blocks-delivery`), and a status (`open`/`in-bet (<slug>)`/`closed (<slug>)`/`accepted`). A missing or out-of-vocabulary value is a 🔴 finding — downstream skills parse these strings.
+- A row marked `closed` must name the closing bet slug; a row marked `accepted` must record who accepted it and why in its notes. Either absence is a 🔴 finding: an unattributed closure or acceptance cannot be audited later.
+- A 🟡 partial assessment that does not name exactly which part of the dimension fails is a 🔴 finding — "partially done" with no specifics steers no one.
+
+---
+
+## Findings
+
+A finding is a specific, quotable problem. Not a general observation. Not advice. A finding identifies exact text (or exact absence of text) and states what is wrong.
+
+Bad finding: "The users section could be stronger."
+Good finding: "'Role-Playing Groups' is listed as a user type but has no job-to-be-done or success definition — a designer couldn't design a journey for them."
+
+Classify each finding:
+- 🔴 **Critical** — Would cause someone downstream to start from wrong or incomplete foundations.
+- 🟡 **Advisory** — Worth surfacing to the user, but a reasonable consumer could work past it.
+
+Keep each finding to one or two short sentences. The calling skill is going to apply them in revisions — long findings are harder to act on, not more useful.
+
+---
+
+## Length Discipline
+
+The entire return payload — verdict + findings — should fit in ≤500 tokens. The skill loads roughly 200 lines into the subagent's context; the subagent reads a draft and a handful of upstream sections; the output is short. If the output is running long, you are explaining instead of finding — cut the explanation.

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

@@ -0,0 +1,254 @@
+---
+name: groundwork-scaffold
+description: >
+  Makes the architecture physically real: scaffolds the services through
+  generators, wires the infrastructure, writes per-service developer docs, and
+  verifies the system boots and passes its tests before any product code is
+  written. Produces `docs/architecture/infrastructure.md`, the
+  `docs/getting-started/` developer on-ramp, and a running environment.
+---
+
+# groundwork-scaffold
+
+You are a platform engineer. The architecture document defines the system in the abstract — services, boundaries, communication patterns, and capability decisions. Your job is to make it physically real: scaffold the services, wire the infrastructure, write the developer documentation, and verify that everything boots and passes its tests before the team writes a single line of product code.
+
+This phase is mostly execution, not discovery. The design conversations happened upstream. Read the architecture carefully, translate it into the right generator commands, confirm the plan with the user, and then build. When something doesn't work — a port collision, a misconfigured environment variable, a failed health check — own the debugging and repair. Scaffold defects belong to this phase because the team inheriting the environment should never encounter them.
+
+Apply the `groundwork-writer` skill when producing any output document. Declarative, assertive, zero-hedging.
+
+---
+
+## How This Phase Works
+
+Scaffold has six execution phases that must be completed in order — each phase depends on the integrity of the one before it.
+
+**Phase 1** establishes the generator plan: read the architecture, map every service to a generator with its specific parameters, and get explicit user confirmation before anything runs. A rushed mapping produces a scaffolded environment that doesn't match the architecture — and fixing that mismatch costs more than taking the time to map it correctly.
+
+**Phase 2** is mechanical execution. Once the mapping is confirmed, act autonomously: run each generator command and verify the outputs.
+
+**Phase 3** creates the developer documentation for every service — a service doc and an API stub per service. These are the reference documents the team uses when building bets. Sparse on first pass, but structured to grow without being rewritten.
+
+**Phase 4** is verification. Boot the infrastructure, apply database migrations, and run the pre-baked system tests. Debug and repair anything that fails. The infrastructure document must describe a system that actually runs.
+
+**Phase 5** drafts and reviews `docs/architecture/infrastructure.md`, then authors the `docs/getting-started/` developer on-ramp. Output the final documents and get explicit user approval before proceeding.
+
+**Phase 6** commits — deletes the cache, applies Living Documents and discovery note updates, and hands off to the orchestrator.
+
+Each phase runs from its own file. At the start of each phase, read that phase's file from `.groundwork/skills/groundwork-scaffold/phases/` and follow it. Never preload later phases — a session carrying instructions for work it has not reached spends working memory the current phase needs.
+
+| Phase | File |
+|---|---|
+| 1. Ingestion & Service Mapping | `phases/01-ingestion-service-mapping.md` |
+| 2. Scaffolding Execution | `phases/02-scaffolding-execution.md` |
+| 3. Service Documentation & API Stubs | `phases/03-service-documentation-api-stubs.md` |
+| 4. Infrastructure Verification | `phases/04-infrastructure-verification.md` |
+| 5. Draft & Review | `phases/05-draft-review.md` |
+| 6. Commit | `phases/06-commit.md` |
+
+---
+
+## Operating Contract
+
+Rushing to execution before the mapping is confirmed, skipping verification because the system "should" work, and treating the infrastructure document as a fill-in-the-blanks template are the failure modes this process is built to prevent.
+
+**Before proceeding, load and apply all protocols from `.groundwork/skills/operating-contract.md` (contract v1).** The Discovery Notes, Living Documents, and Phase Lifecycle protocols defined there are mandatory for this skill.
+
+---
+
+## Initialization & Resume Protocol
+
+### Step 1: Cache Check
+
+Check if `.groundwork/cache/scaffold-cache.md` exists.
+
+- If it **does not exist**, copy the template from `.groundwork/skills/groundwork-scaffold/templates/scaffold-cache.md` to `.groundwork/cache/scaffold-cache.md`, then proceed directly to Step 2. Do not re-read the file you just wrote — the in-memory state is authoritative for the rest of this phase.
+- If it **does exist**, read it once. Summarise which phases are complete and ask the user whether to resume or start fresh. If they choose to start fresh, reset the cache file from the template. If they choose to resume, read the file for the first phase the cache does not mark complete — from the phase table in How This Phase Works above — and continue from there.
+
+### Step 2: Discovery Notes Check
+
+Check if `.groundwork/cache/discovery-notes.md` exists and has entries under `## Architecture` or `## Design Details`.
+
+If entries exist, treat them as pre-discovered context — infrastructure preferences, technology opinions, or specific service configuration decisions the user communicated earlier. Carry them into the relevant phases.
+
+If the file does not exist, or exists with no entries under those headings, skip this step and proceed to Step 2.5. Do not re-read the file later in the phase — its absence is final.
+
+### Step 2.5: Hand-off Cache Check
+
+Check if `.groundwork/cache/handoff/architecture.md` exists. If it does, read it in full — it carries the architecture phase's post-commit context: rejected technology choices with rationale, deferred decisions (observability stack, multi-region rollout), user instincts about scaling and vendor preferences not yet committed. Treat as pre-discovered context for Phase 1 mapping. This is the Hand-off Cache contract from Protocol 6.
+
+If the file does not exist, skip this step. Cache Isolation (Protocol 7) forbids reading any other phase's cache.
+
+### Step 3: Workspace CLI
+
+Check whether `./dev` exists at the project root.
+
+- If it **does not exist**, run `workspace-dev-cli` immediately before any other generator runs. Derive the app name from the architecture document or product brief — do not ask the user for it. Command: `npx --yes nx g "$(pwd)/.groundwork/config/generators.json:workspace-dev-cli" --appName <app-name>`.
+- If it **does exist**, the workspace CLI is already in place.
+
+Mark CLI Initialization complete in `scaffold-cache.md` before proceeding.
+
+The `./dev` CLI and `docker-compose.yml` are the entry points for everything that follows — booting, testing, verification. They are infrastructure prerequisites, not services to map.
+
+---
+
+## Adapt the Starting Point — Never Inert, Never Duplicated
+
+The generators and the `./dev` CLI are a high-quality *starting point*, not a fixed artifact to accept or work around. When a shipped affordance does not fit the project — the canonical case is a Docker-shaped `./dev start` in a workspace with no containers — adapt it to do something real. The `./dev` toolkit is built to grow: register a native app as a runner in `.dev/dev.config.json`, or add a project command under `.dev/commands/` (or a `commands` block in `.dev/dev.config.json`) — a verb the project owns that the CLI discovers and lists beside the built-ins, and that can even shadow a built-in for a stack the default lifecycle does not fit. Two outcomes are defects, never ship them: a shipped command left wired to nothing, and a parallel tool built beside the one already there. This is the *no empty capabilities* rule from the Day-2 baseline (`docs/principles/delivery/day-2-operational-baseline.md`) applied to the tooling, and the instinct is welcome at scaffold time and at any bet later.
+
+---
+
+## Quality Standard: What "Deep Enough" Looks Like
+
+The infrastructure document must give any developer everything they need to run the local environment without asking a question. A document that lists services and port numbers without explaining how to start them, how to run tests, or how to verify they are healthy has failed.
+
+When the project has a surface registry (`docs/surfaces.md`), the document lists surfaces as their own group with each surface's core-access path — surfaces are consumer-facing adapters over the capability core, and a reader needs them distinguishable from the core services they call. A `scaffold: manual` surface appears in the group with the operational expectations its implementation must meet.
+
+**Shallow output (insufficient):**
+
+```markdown
+# Infrastructure
+
+## Services
+
+- auth-service (Go): localhost:4000
+- story-service (Go): localhost:4001
+- web-app (Next.js): localhost:3000
+
+## Database
+
+PostgreSQL: localhost:5432
+```
+
+**Deep output (required standard):**
+
+```markdown
+# Infrastructure
+
+## Environment Overview
+
+Three services run natively via `air` (Go) or `next dev` (Next.js). PostgreSQL and
+the Jaeger trace backend run in Docker. All services are managed through the `./dev` CLI.
+
+## Services
+
+| Service | Generator | Language | Local Port | Health Endpoint |
+|---|---|---|---|---|
+| `auth-service` | go-microservice | Go | 4000 | `GET /health` |
+| `story-service` | go-microservice | Go | 4001 | `GET /health` |
+| `web-app` | nextjs-app | TypeScript | 3000 | `GET /api/healthz` |
+
+**auth-service** — handles user authentication and JWT issuance. Scaffolded with
+`--auth clerk` for full Clerk user and service authentication. PostgreSQL database:
+`auth-service`. Base path: `services/auth-service/`.
+
+**story-service** — manages the story lifecycle. Scaffolded with `--auth service`
+for service-to-service auth and `--messaging gcp-pubsub` for the transactional
+outbox pattern. PostgreSQL database: `story-service`. Base path: `services/story-service/`.
+
+**web-app** — Next.js frontend. Scaffolded with `--auth clerk` and `--apiProxy true`
+to proxy API requests to `auth-service`. Base path: `services/web-app/`.
+
+## Surfaces
+
+| Surface | Type | Core Access | Scaffold | Test Medium |
+|---|---|---|---|---|
+| `web-app` | graphical-ui | http-gateway (`/api/proxy` → auth-service) | nextjs-app | playwright |
+| `admin-cli` | cli | http-direct (service tokens) | cli-app | subprocess-cli |
+| `mobile-app` | graphical-ui | http-gateway | manual | flutter-integration |
+
+**mobile-app** is `scaffold: manual` — no generator produced it. Its registration
+here and in the `surfaces` test fixture is a contract the manual implementation
+must meet when it lands: expose a health endpoint, integrate with `./dev`, and
+provide a reach value the fixture can resolve.
+
+## Infrastructure
+
+| Component | Port | Container Name |
+|---|---|---|
+| PostgreSQL | 5432 | `<app-name>-db` |
+| Jaeger (tracing UI + query API) | 16686 | `<app-name>-jaeger` |
+
+Infrastructure is on-demand: a component appears here only because some service or
+provider footprint asked for it. A local-first or desktop-only workspace has none.
+
+## What `./dev start` does
+
+A **managed unit** is anything `./dev` starts, stops, tails, and reports on — the
+union of docker-compose services, native app-services, and registered runners
+(surfaces and sidecars in `.dev/dev.config.json`). The table below is that exact
+set and must equal what `./dev status --json` reports across its `docker`,
+`native`, and `runners` arrays. A unit listed here that `./dev status` does not
+show is documentation drift, not a footnote — reconcile it (Phase 4), do not paper
+over it.
+
+| Managed unit | Run mode | How `./dev` starts it | Why |
+|---|---|---|---|
+| `<app-name>-db` | container (compose) | `docker compose up db` | on-demand: a service uses a relational/vector store |
+| `<app-name>-jaeger` | container (compose) | `docker compose up jaeger` | on-demand: a service exports OTLP telemetry |
+| `auth-service` | native app-service | `air` (Go hot reload) | detected by `.air.toml` |
+| `web-app` | runner (surface) | `npx nx run web-app:serve` | a surface generator self-registered it; autostart |
+| `compute-service` | runner (sidecar) | `uv run python src/main.py` | native because it needs Metal/MPS — cannot be containerized |
+
+When the union is empty, `./dev start` prints an honest "nothing registered" notice
+and exits 0 — it never reports a started environment it did not start.
+
+## Running it
+
+The boot, test, and migration commands a developer needs day to day — and the
+fresh-clone setup walkthrough — live in the getting-started on-ramp
+(`docs/getting-started/`), not here. State the canonical three so this document is
+self-sufficient for a reader checking the running system, and point to the on-ramp
+for the rest:
+
+```bash
+./dev start       # Boot every managed unit (containers, app-services, runners)
+./dev status      # Check service, container, and runner health
+./dev test        # Run the system tests against the running stack
+```
+
+If any service runs a database, also name the migration command (`./dev migrate`).
+See `docs/getting-started/` for prerequisites, dependency install, `./dev doctor`,
+and the full `./dev` command reference.
+
+## Verification
+
+Verified green on initial scaffold:
+- All Go health endpoints returned `{"status": "ok"}` with PostgreSQL connected.
+- Clerk webhook endpoint on `story-service` correctly rejected unverified payloads.
+- System integration tests: 7/7 passed.
+```
+
+---
+
+## The developer on-ramp: `docs/getting-started/`
+
+`infrastructure.md` describes the *shape* of the running system. The getting-started
+section answers a different question — **how does someone who just cloned the repo
+get it running?** — and it is the doc set the docs-site landing page routes a new
+developer to. Author three files under `docs/getting-started/`, each a clean
+published doc under `groundwork-writer`:
+
+- **`index.md`** — the on-ramp overview. Two short paragraphs: what this system is in
+  one line (lift from the product brief), and the two reading paths — set it up here,
+  or understand the product via `docs/product-brief.md`. Link to `setup.md` and
+  `dev-cli-reference.md`. Keep it to a screen; it is a signpost, not a tutorial.
+
+- **`setup.md`** — the fresh-clone walkthrough, in order, with the *actual* values this
+  scaffold produced: **prerequisites** (the runtimes and tools the stack needs —
+  Docker, the language runtimes per service, any CLI like `air`/`uv`/`pnpm` — with
+  versions), then `./dev doctor` to verify the environment, then **install
+  dependencies** (the real per-stack commands), then env configuration (the variables
+  `infrastructure.md` lists as required, and where they go), then `./dev start`, then
+  how to confirm health (`./dev status` / the health endpoints). This is the content
+  `infrastructure.md` never carried — write it from what Phase 4 verification actually
+  did, not from theory. If verification was pending, say so here too.
+
+- **`dev-cli-reference.md`** — the complete `./dev` command catalogue. **Derive it from
+  `./dev help`** (the CLI's registry is the single source of truth — never hand-list
+  commands from memory, or the doc drifts the moment a command is added): one section
+  per command group (Lifecycle, Quality, Bet Workflow, Meta), each command with its
+  summary and flags, plus the "Extending `./dev`" note on project-owned commands
+  (`.dev/commands/` and the `commands` block in `.dev/dev.config.json`).
+
+These are skill-authored, not templated, precisely so they carry this project's real
+prerequisites, install commands, and command set rather than a generic stand-in.