groundwork-method 0.0.1 → 0.11.0

package/src/hidden-skills/groundwork-review/checklists/decomposition.md

@@ -0,0 +1,135 @@
+---
+name: decomposition-checklist
+description: >
+  Type-specific failure modes for reviewing a bet's decomposition — the
+  milestone map, slice specs, and prose proofs the bet executes against.
+---
+
+# Decomposition Checklist
+
+This checklist checks a bet's decomposition tree under `docs/bets/<slug>/decomposition/`. It
+answers one question: **does every milestone name consumer-visible value — proven once at the
+contract, then per surface — every slice cut vertically, and every capability trace to the
+technical design with a falsifiable prose proof?**
+
+Each item names a violation. Match it against the tree's milestone `index.md` and slice files and
+the design under `docs/bets/<slug>/technical-design/`. Bet documents carry no Downstream Context
+file and no summary section — do not flag the absence of either.
+
+## Milestone Shape
+
+- [ ] 🔴 **Horizontal milestone**: a milestone names a layer of the stack ("Backend", "Build all
+  the schemas", "Integration") rather than a demonstrable state in the product's interface — it
+  is invisible to the user and proves nothing end-to-end.
+- [ ] 🔴 **Goal not traceable to the design**: a milestone's goal corresponds to nothing in
+  `technical-design/` — a surface milestone's user-visible goal traces to no UI Design
+  subsection, or a capability milestone's contract state traces to no API Design interface or
+  Schema & Data Design store. The milestone proves something the design never committed to.
+- [ ] 🔴 **No acceptance criteria**: a milestone carries no concrete, observable acceptance
+  criteria a reviewer could check against the running product.
+- [ ] 🟡 **No sequencing rationale**: a milestone does not state why it sits where it does — what
+  the first milestone proves architecturally, why the next can only follow it.
+- [ ] 🟡 **Milestone count outside 2–5**: one milestone suggests the bet is not scoped in
+  user-visible increments; six or more suggests it is a roadmap, not a bet. Exception: a
+  headless delivery legitimately carries a single capability milestone with every surface
+  milestone deferred — when the pitch's surface no-gos say so, do not flag it.
+
+## Milestone and Slice Typing
+
+These items apply only when the project carries a surface registry (`docs/surfaces.md`). A
+project with no registry decomposes against its single implicit surface — untyped milestones,
+no slice `Surface` field — and none of these items fire.
+
+- [ ] 🔴 **Milestone untyped or mistyped**: a milestone carries no `Type:`, or its type
+  contradicts its content — a milestone whose demonstrable state is a contract exercised
+  headless is a capability milestone; one asserting in a surface's medium is a surface
+  milestone, and the surface slug it names must exist in the registry.
+- [ ] 🔴 **Capability proof not first**: the bet introduces new capability but does not open
+  with the capability milestone proving it at the contract — surface milestones are sequenced
+  before the contract proof they depend on.
+- [ ] 🔴 **Surface milestone asserting business outcomes**: a surface milestone's goal or
+  acceptance criteria assert business rules rather than wiring, rendering, and interaction —
+  the milestone is re-litigating what the capability milestone proves at the contract.
+- [ ] 🟡 **Consumer unnamed**: a capability milestone does not record who its consumer is — the
+  in-scope surfaces that build on it, or the latent agentic surface for a headless delivery.
+- [ ] 🔴 **Slice surface missing or invalid**: a slice file carries no `Surface` field, or its
+  value is neither `core` nor a registry slug — delivery cannot sequence core-before-surface, and
+  the slice's test discipline is undeclared.
+
+## Slice Verticality
+
+- [ ] 🔴 **Horizontal slice**: a slice is a horizontal pass ("all schemas", "all APIs", "all UI")
+  rather than a vertical column delivering a testable capability end-to-end.
+- [ ] 🔴 **Slice that needs the future**: a slice cannot be deployed and verified without a later
+  slice existing — it fails the vertical-slice test and must be merged up or reframed.
+- [ ] 🟡 **Orphan slice or empty milestone**: a slice belongs to no milestone, or a milestone
+  decomposes into no slices.
+- [ ] 🟡 **Anatomy incomplete**: a slice file is missing one of its parts — Owner service,
+  Surface (`core` or a registry slug; registry projects only), Complexity (S/M/L),
+  Prerequisite, Scope (one-paragraph intro plus Required Capabilities), Design, Proof of work.
+- [ ] 🟡 **Vague prerequisite**: a prerequisite does not name the exact prior merge gate (e.g.
+  "Slice 1.2 merged") — "after the backend work" sequences nothing.
+
+## Capabilities and Proofs
+
+- [ ] 🔴 **Unfalsifiable capability**: a Required Capability cannot fail — "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.
+- [ ] 🔴 **Capability without a design anchor**: a Required Capability traces to no interface in
+  `technical-design/03-api-design.md` or store in `04-data-design.md` — the slice commits to
+  behaviour the design never specified.
+- [ ] 🔴 **Missing test file link**: a milestone `index.md` or slice file names no `Test file:`
+  path in its Proof of work at `tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.<ext>`
+  or `tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.<ext>`. The path is named at
+  decomposition; Delivery materializes the red stub from it.
+- [ ] 🟡 **Proof without an observable condition**: a Proof of work's `How we prove it` states no
+  specific, falsifiable observation — "verify it works" gives the reviewer nothing to check
+  against the milestone's acceptance criteria.
+- [ ] 🔴 **Decomposition tree incomplete**: the tree is missing a piece — `meta.json`, a milestone
+  `index.md`, or a slice file the milestone links — so the bet has no complete plan to execute
+  against.
+
+## Proof Semantics
+
+Tests do not exist at decomposition — they are materialized red at Delivery start (Step 0.5)
+from this approved prose. So these checks read the **Proof of work** prose, not test code: a
+proof that describes the wrong thing sends Delivery to the wrong destination with a green light.
+The purely code-level failures are enforced at Delivery — Step 0.5 confirms each materialized
+stub is red for the feature's absence, and Step 4's honest-green reconciliation catches
+white-box assertions and gamed implementations — so here the review checks the prose.
+
+- [ ] 🔴 **Proof does not match the capability**: a Proof of work proves something other than the
+  Required Capability it rests on — the capability says 202-and-idempotent, the proof shows
+  200-and-exists. Delivery will satisfy the proof and miss the capability.
+- [ ] 🔴 **Shape not in the prose design**: a proof references a request body, response field, or
+  table shape that `technical-design/03-api-design.md` / `04-data-design.md` does not define — the
+  proof rests on a contract that does not exist.
+- [ ] 🔴 **Tautological proof**: a Proof of work that cannot fail once any implementation exists —
+  observing that a response is received without observing its content, or describing the failure
+  it should surface as the success it checks for.
+- [ ] 🔴 **Core logic re-proven at a surface**: a surface milestone's or surface slice's Proof of
+  work re-asserts a business rule the capability milestone already proves at the contract —
+  prove-once is the principle that keeps surface count from multiplying the test pyramid; surface
+  proofs cover wiring, rendering, and interaction only. (Registry projects only; an untyped
+  decomposition pairs interface and API layers per milestone as before.)
+- [ ] 🟡 **Headline error case missing**: a milestone whose demonstrable outcome depends on an
+  error case (e.g. the dependency being unavailable) proves only the happy path. Exhaustive
+  error-matrix coverage is not expected here — it lands in Delivery's permanent tests — but an
+  error the milestone's proof rests on belongs in the headline Proof of work.
+- [ ] 🟡 **Proof of work missing or stale**: a milestone `index.md` or slice file in
+  `decomposition/` lacks its Proof of work, or its proof no longer matches the design or the
+  Required Capability it rests on — the user would approve a definition of done that drifted from
+  what the bet builds.
+
+## Chain Integrity
+
+The Document Chain Integrity table in the decomposition workflow defines the full chain; these
+are its decomposition-side checks.
+
+- [ ] 🔴 **Design not covered**: a contract, flow, or interface element in `technical-design/`
+  maps to no milestone or slice and is not explicitly cut — the bet will end with designed
+  behaviour nobody built.
+- [ ] 🔴 **Scope beyond the design**: a milestone or slice delivers behaviour the
+  `technical-design/` never specified — decomposition has silently grown the bet.
+- [ ] 🟡 **Proof outside the acceptance criteria**: a slice's Proof of work proves behaviour that
+  traces to no milestone acceptance criterion — proof of work the milestone never asked for.

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

@@ -0,0 +1,85 @@
+---
+name: design-system-checklist
+description: >
+  Type-specific failure modes for reviewing a draft design system — the
+  implementation-ready specification that eliminates downstream design decisions.
+---
+
+# Design System Checklist
+
+This checklist checks a draft `docs/design-system.md`. It answers one question: **could a
+developer or generative UI tool implement this specification without making a single design
+decision of their own?**
+
+Each item names a violation. Match it against the document text; answer yes/no. The items apply
+across all interface tracks (graphical UI, CLI, agentic protocol) — read "value" as the track's
+unit of commitment: a CSS token, a terminal colour role, a protocol field.
+
+A design system legitimately carries one titled section per interface type in use (`# Graphical
+UI`, `# CLI`, `# Agentic Protocol`), plus a shared foundation when several types are active.
+Multiple type sections — and the multi-block brand-tokens file they project to — are the
+contract for multi-type products, never duplication or contradiction findings in themselves.
+
+## Document Hygiene
+
+- [ ] 🟡 **Leftover downstream summary**: the published doc still carries a `## Summary for
+  Downstream` section. The cross-phase contract now lives in `.groundwork/context/design-system.md`,
+  not in the published doc; an old-template summary section is residue and should be removed.
+
+## Translation Depth
+
+- [ ] 🔴 **Direction instead of value**: a section states intent ("warm colours", "generous
+  whitespace", "snappy feedback") without committing to implementable values. The user's words
+  echoed back are not a specification.
+- [ ] 🔴 **Decision left to the implementer**: any instruction of the form "choose an appropriate
+  X", "use a suitable Y", or a value range with no committed default — the implementer is being
+  asked to make a design call this document exists to eliminate.
+- [ ] 🟡 **Single-property definition**: a design concept defined by one property (just a
+  background colour, just a radius) where the standard requires the full set — surface, border,
+  depth, state, and variant coverage.
+- [ ] 🟡 **Hedged specification**: "should", "could", "consider", "typically" attached to a value
+  — a spec either commits or stays silent.
+
+## Coverage and Coherence
+
+- [ ] 🔴 **Promised variant missing**: the document commits to a mode in one section (a second
+  theme, a no-colour fallback, a responsive breakpoint, a degraded state) and another section
+  defines values for only one mode.
+- [ ] 🔴 **Undefined token referenced**: a token, class, or named value is used in one section
+  but defined nowhere in the document.
+- [ ] 🔴 **Incomplete interaction states**: an interactive element defines some states but not
+  the full set its own constraints require — e.g. hover specified but focus-visible or disabled
+  absent.
+- [ ] 🟡 **Target-structure gap**: a section the track's target structure requires (constraints,
+  shell, error choreography, empty states, or the track equivalent) is absent with no stated
+  reason.
+- [ ] 🟡 **Token contradicts token**: two sections within the same interface-type section (or
+  the shared foundation) commit to different values for the same concept — a spacing step, a
+  duration, a colour role — leaving the implementer to pick a winner. Different types
+  legitimately express the same brand decision differently.
+
+## Constraints
+
+- [ ] 🔴 **Constraints section without numbers**: performance budgets, accessibility baselines,
+  or platform targets are named but carry no measurable value ("the app must be fast",
+  "accessible to all users").
+- [ ] 🔴 **Accessibility floor unverifiable**: an accessibility commitment with no testable
+  criterion — no contrast ratio, no keyboard path, no equivalent for the track's medium.
+- [ ] 🟡 **Rationale-free opinionated default**: a non-obvious technical default (colour space,
+  grid base, easing model) asserted with no one-line reasoning — the next person to touch it
+  will relitigate or silently abandon it.
+
+## Upstream Contract
+
+- [ ] 🔴 **Brief commitment contradicted**: a value or pattern in this document conflicts with a
+  decision or hard rule in `docs/product-brief.md` — e.g. a brief that
+  commits to a terminal medium answered with screen-design sections.
+- [ ] 🔴 **Type section unbacked or missing**: when `docs/product-brief.md` carries a surface set,
+  the document's titled type sections disagree with it — a type section with no MVP-horizon
+  surface of that type behind it, or an MVP-horizon interface type with no section (and no
+  stated deferral).
+- [ ] 🔴 **User type unserved**: a user type the product brief commits to has no design answer —
+  no journey, shell state, or interaction pattern accounts for them.
+- [ ] 🟡 **Silently introduced product decision**: the document commits to a product-level
+  behaviour (a capability, a flow, an exclusion) that the brief neither states nor implies —
+  design has quietly extended the product.

package/src/hidden-skills/groundwork-review/checklists/domain-entity.md

@@ -0,0 +1,66 @@
+---
+name: domain-entity-checklist
+description: >
+  Type-specific failure modes for reviewing a domain entity doc — checked
+  against the current architecture doc and the accepted (non-superseded) ADRs.
+---
+
+# Domain Entity Checklist
+
+This checklist checks a draft `docs/architecture/domain/<entity>.md`. It answers one question: **does this
+entity describe the system currently being built — agreeing with `docs/architecture/index.md`
+and the accepted ADRs — and is every state, event, and invariant
+mechanically enforceable?**
+
+Each item names a violation. Match it against the document text, `docs/architecture/index.md`, and
+the ADRs under `docs/architecture/decisions/` (skip any ADR whose `status` is `superseded`). Domain entity
+docs carry no Downstream Context file and no summary section — do not flag the absence of either.
+
+## Identity and Ownership
+
+- [ ] 🔴 **Owner from a superseded design**: the `Owner:` line names a service, vendor, or
+  mechanism an accepted ADR moved away from — e.g. `Owner: web (via Supabase Auth)` after an ADR
+  moved auth to another provider. The doc describes a system no longer being built.
+- [ ] 🔴 **Owner not in the architecture**: the `Owner:` service does not exist in the current
+  architecture's service topology.
+- [ ] 🟡 **No invariant to enforce**: the "What it is" paragraph describes the entity without
+  stating the invariant the entity exists to enforce.
+
+## Lifecycle Mechanics
+
+- [ ] 🔴 **Undetectable trigger**: a lifecycle state's transition trigger is backed by no field
+  in the Fields table and no emitted event — a state that cannot be mechanically detected cannot
+  be enforced and is invalid.
+- [ ] 🔴 **Time-based state without its field**: a state reached by the passage of time or
+  inactivity ("dormant", "expired") with no timestamp field (e.g. `last_active_at`,
+  `expires_at`) that makes it detectable.
+- [ ] 🟡 **Phantom field**: the Lifecycle or Invariants section references a field that does not
+  appear in the Fields table.
+- [ ] 🟡 **Stateless entity with a state table**: the entity is described as immutable or having
+  no meaningful state machine, yet a lifecycle table is present anyway — the template requires
+  saying so explicitly and removing the table.
+
+## Domain Events
+
+- [ ] 🔴 **Event implies an unprovisioned mechanism**: a domain event is listed as published when
+  the architecture provisions no message broker or event bus — it implies a publish channel that
+  does not exist. Without a broker, events are in-process domain concepts only, and the doc must
+  not suggest otherwise.
+- [ ] 🟡 **Event naming drift**: an event does not follow the `<entity>.<verb>` naming form, or
+  names a different entity than the one this doc defines.
+- [ ] 🟡 **Event without a lifecycle anchor**: an event's trigger corresponds to no state
+  transition or field change defined elsewhere in the doc.
+
+## Invariants vs the ADRs
+
+- [ ] 🔴 **Overstated guarantee**: an invariant 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. The invariant must state the weaker guarantee the
+  system actually enforces.
+- [ ] 🔴 **Invariant against a superseded mechanism**: an invariant depends on a vendor,
+  persistence model, or data-isolation strategy that an accepted ADR replaced.
+- [ ] 🟡 **Untestable invariant**: an invariant phrased so that no test or boundary check could
+  detect its violation ("bookings are always handled correctly").
+- [ ] 🟡 **Invariant duplicating the lifecycle**: an invariant that restates a transition rule
+  already in the Lifecycle table rather than constraining validity — noise that will drift from
+  its twin.

package/src/hidden-skills/groundwork-review/checklists/implementation-readiness.md

@@ -0,0 +1,47 @@
+---
+name: implementation-readiness-checklist
+description: >
+  Pre-flight gate between decomposition and delivery: verifies the artifacts the
+  delivery phase is about to execute against actually exist, agree with each other,
+  and are still current. Applied inline by the delivery workflow — these are
+  mechanical existence and consistency checks, not authorship review.
+---
+
+# Implementation Readiness Checklist
+
+Checked against the bet's committed artifacts immediately before the first slice is implemented. The one question this answers: **if delivery starts now, will it execute against complete, current, mutually consistent instructions — or improvise?** Any 🔴 item blocks delivery and routes back to the owning phase.
+
+## The document chain
+
+- [ ] 🔴 **Missing link**: `docs/bets/<slug>/pitch.md`, the `technical-design/` directory, or the `decomposition/` tree does not exist — delivery has no executable plan.
+- [ ] 🔴 **Status out of sequence**: the pitch frontmatter `status` is not `delivery` (or `decomposition` about to transition) — a fresh context picked up the wrong bet or a phase was skipped.
+- [ ] 🔴 **Unreviewed artifact**: the technical design or the decomposition tree was committed without its review gate reaching `VERDICT: PRESENT` (visible in conversation history or flagged in the doc) — an ungated plan is a draft, not a contract.
+
+## Surface scope
+
+These items apply only when the project carries a surface registry (`docs/surfaces.md`). A project with no registry has a single implicit surface; none of these items fire. The ledger itself is gated at validation — a bet cannot reach `delivered` with an empty ledger cell — so readiness checks the scope agreement that makes that gate satisfiable.
+
+- [ ] 🔴 **Pitch ↔ design surface disagreement**: the pitch's `surfaces:` frontmatter and the technical design's UI Design subsections name different surface sets — delivery would build for surfaces the bet never scoped, or skip ones it committed to, and validation's ledger row would have no honest state for the mismatched column.
+- [ ] 🔴 **Slice surface unmapped**: a slice's `Surface` value in the decomposition tree is missing, or is neither `core` nor a registry slug — core-before-surface sequencing cannot run, and the slice's outcome has no ledger column to land in.
+
+## Contracts
+
+- [ ] 🔴 **Slice without a contract**: a slice in the decomposition tree introduces or changes a service API whose shapes are absent from the prose design (`technical-design/03-api-design.md`, or the store in `04-data-design.md`) — that slice will be implemented against guesswork.
+- [ ] 🟡 **Contract orphan**: a designed interface in `technical-design/03-api-design.md` that no slice implements — either scope was silently cut in decomposition or the design carries dead weight. The interface is what the implementation's generated contract (canonical `docs/architecture/api/<service>/`, captured at validation) must eventually carry.
+
+## Proof of work
+
+Tests do not exist at this gate — Delivery materializes the red board from this approved prose at Step 0.5, and confirms there that every materialized stub is red for the feature's absence. Readiness checks the prose and the approval tag, not test code.
+
+- [ ] 🔴 **Missing Proof of work**: a milestone `index.md` or slice file in `docs/bets/<slug>/decomposition/` lacks its Proof-of-work prose, or names no `Test file:` path in it — there is nothing for Delivery to materialize into a red stub, so "done" has no definition.
+- [ ] 🔴 **Approval tag absent**: under git, the `bet/<slug>/approved` tag does not exist — the approved decomposition tree and technical design were never sealed, so there is no sealed baseline (the ratchet's initial point) the delivery prose-integrity reconciliation can hold the prose to. An unsealed contract is a draft, not a definition of done. (Not under git: confirm the bet record names the approval baseline the reconciliation falls back to.)
+- [ ] 🔴 **Ladder or first milestone incomplete**: the `decomposition/` tree is missing a piece it must carry at delivery start — `meta.json`, any milestone `index.md` (the full ladder of headline proofs), or a slice file the **first milestone** links — so delivery would execute against a partial plan. A *later* milestone with no slice files is expected (it is sliced on arrival, not up front), not incomplete; but a slice link that resolves to nothing is a dangling reference and fails this check.
+- [ ] 🟡 **Capability ↔ proof drift**: a Required Capability with no Proof of work covering it, or a Proof of work that rests on no Required Capability — the proof and the plan disagree about what is being proven.
+- [ ] 🟡 **Proof-of-work prose stale**: a milestone `index.md` or slice file's Proof of work describes a shape, an interface, or an outcome the current `technical-design/` no longer carries — the sealed prose drifted from the design, so the user approved something other than what delivery will build against.
+- [ ] 🟡 **Testing strategy unresolved**: a slice's stack does not resolve to a promoted engineer-skill testing strategy (`.agents/skills/groundwork-<stack>-engineer/references/testing.md`) — the slice-worker has no authority to roll the permanent best-practice tests out against, and the coverage-auditor lens no baseline to hold them to. Scaffolded services always carry one; a hand-added or non-standard service may not. Name the gap so delivery rolls out coverage deliberately rather than improvising it.
+
+## Currency
+
+- [ ] 🔴 **Open contradiction in discovery notes**: an entry under `## Design Details` or `## Bets` in `.groundwork/cache/discovery-notes.md` contradicts the committed design or decomposition — a captured signal was never reconciled, and delivery would build against the stale half.
+- [ ] 🟡 **Stale upstream**: `groundwork check` (or its git-log baseline) reports a canonical doc this bet depends on as stale — the design may rest on a map that no longer matches the territory. Assess whether the drift touches this bet before proceeding.
+- [ ] 🟡 **Maturity blocker unacknowledged**: `docs/maturity.md` carries an `open` `blocks-delivery` row that this bet neither closes nor consciously deferred during discovery — delivery is about to run into the documented obstacle.

package/src/hidden-skills/groundwork-review/checklists/infrastructure.md

@@ -0,0 +1,68 @@
+---
+name: infrastructure-checklist
+description: >
+  Type-specific failure modes for reviewing a draft infrastructure document —
+  the verified description of the running local environment.
+---
+
+# Infrastructure Checklist
+
+This checklist checks a draft `docs/architecture/infrastructure.md`. It answers one question: **could any
+developer run the local environment from this document alone — boot it, test it, and verify it
+is healthy — without asking a question?**
+
+Each item names a violation. Match it against the document text plus `docs/architecture/index.md`;
+answer yes/no.
+
+## Document Hygiene
+
+- [ ] 🟡 **Leftover downstream summary**: the published doc still carries a `## Summary for
+  Downstream` section. The cross-phase contract now lives in `.groundwork/context/infrastructure.md`,
+  not in the published doc; an old-template summary section is residue and should be removed.
+
+## Runnability
+
+- [ ] 🔴 **Port without a boot command**: services and ports are listed but the document never
+  states how to start them — an inventory is not an environment.
+- [ ] 🔴 **Test path unstated**: the document does not say how to run the test suite, or names a
+  test command without saying what it runs against (running stack vs self-booting).
+- [ ] 🟡 **Health unverifiable**: a service is listed with no health endpoint or equivalent check
+  — a developer cannot tell a booted service from a hung one.
+- [ ] 🟡 **Raw commands beside a managed surface**: the environment has a single management
+  surface (a `./dev` CLI or equivalent) but the document instructs raw per-service commands that
+  bypass it — two run paths rot independently.
+- [ ] 🟡 **Migration path missing**: a service includes a database but the document never states
+  how migrations are run.
+
+## Verification Honesty
+
+- [ ] 🔴 **Unverified fact stated as verified**: the document presents ports, commands, or test
+  results as confirmed while also recording (or omitting) that the system was never booted — a
+  verification section is mandatory, and "pending" must be flagged, not papered over.
+- [ ] 🔴 **Verification without results**: a verification section exists but cites no outcome —
+  no test counts, no health responses, no named checks. "Everything works" is a claim, not
+  evidence.
+- [ ] 🟡 **Stale specificity**: the document hedges concrete facts it is responsible for
+  ("typically port 4000", "the test command should be...") — this doc records the actual system,
+  not the theoretical one.
+
+## Service Inventory
+
+- [ ] 🔴 **Architecture service missing**: a service named in `docs/architecture/index.md`
+  does not appear in this document's inventory, with no explicit note that it is not yet
+  scaffolded.
+- [ ] 🔴 **Orphan service**: a service appears here that the architecture does not define —
+  infrastructure has silently extended the system.
+- [ ] 🟡 **Inventory row incomplete**: a service row lacks its language/generator, port, or base
+  path — a developer cannot locate or address it.
+- [ ] 🟡 **Shared infrastructure unlisted**: a dependency the services plainly use (database,
+  broker, tracing backend) is absent from the infrastructure table — it will fail to exist on a
+  fresh machine.
+
+## Environment Requirements
+
+- [ ] 🔴 **Secret or env var requirement unstated**: a service needs credentials or environment
+  variables to boot (auth keys, provider tokens) and the document neither lists them nor points
+  to where they are configured — the first fresh boot fails opaquely.
+- [ ] 🟡 **Implicit tool dependency**: the boot path assumes a tool (Docker, a language runtime,
+  a CLI) the document never names as a prerequisite.

package/src/hidden-skills/groundwork-review/checklists/maturity.md

@@ -0,0 +1,71 @@
+---
+name: maturity-checklist
+description: >
+  Type-specific failure modes for reviewing a maturity doc — the evidenced
+  assessment and roadmap against the nine-dimension maturity model.
+---
+
+# Maturity Checklist
+
+This checklist checks a draft `docs/maturity.md`. It answers one question: **is every assessment
+evidenced, every roadmap row parseable, and every claim consistent with the committed doc set?**
+
+Read the model at `.groundwork/skills/maturity-model.md` first — it defines the
+dimensions (D1–D9), the assessment states (including the `n/a` state reserved for the
+conditional dimensions D8 and D9), and the allowed severity, recommendation, and status
+values. Match each item against the document text and the canonical doc set.
+
+## Document Hygiene
+
+- [ ] 🟡 **Leftover downstream summary**: the published doc still carries a `## Summary for
+  Downstream` section. The cross-phase contract now lives in `.groundwork/context/maturity.md`,
+  not in the published doc; an old-template summary section is residue and should be removed.
+
+## Assessment Rows
+
+- [ ] 🔴 **State without evidence**: an assessment row carries a state (✅/🟡/🔴) but cites no file,
+  command output, or absence that justifies it — an assessment row without evidence is an
+  opinion.
+- [ ] 🔴 **Partial without specifics**: a 🟡 partial assessment does not name exactly which part
+  of the dimension fails — "partially done" with no specifics steers no one.
+- [ ] 🔴 **Dimension missing**: one of the nine dimensions (D1–D9) has no assessment row —
+  a conditional dimension whose precondition does not hold still gets a row, with state `n/a`
+  and the precondition as evidence.
+- [ ] 🟡 **Assessment stamp missing**: the assessment carries no date or no record of which phase
+  or skill ran it.
+- [ ] 🟡 **Evidence that proves nothing**: the cited evidence does not bear on the dimension's
+  signal — a doc path offered as proof of D3 (one-command operations), say, instead of the
+  `./dev` surface.
+
+## Roadmap Vocabulary
+
+Downstream skills parse these strings exactly; a near-miss is a silent orphan.
+
+- [ ] 🔴 **Out-of-vocabulary severity**: a severity other than `blocks-delivery`,
+  `standard-divergence`, or `cosmetic`.
+- [ ] 🔴 **Out-of-vocabulary recommendation**: a recommendation other than `fix-now`, `defer`, or
+  `blocks-delivery`.
+- [ ] 🔴 **Out-of-vocabulary status**: a status other than `open`, `in-bet (<slug>)`,
+  `closed (<slug>)`, or `accepted`.
+- [ ] 🔴 **Row without a dimension**: a roadmap row names no dimension (D1–D9) — the gap cannot
+  be tied to what it blocks.
+- [ ] 🟡 **Gap without a cost**: a roadmap row does not state what leaving the gap open costs —
+  the model exists to let the user weigh maturity work against product work with full
+  information.
+
+## Attribution
+
+- [ ] 🔴 **Unattributed closure**: a row marked `closed` does not name the closing bet slug — an
+  unattributed closure cannot be audited later.
+- [ ] 🔴 **Unattributed acceptance**: a row marked `accepted` does not record who accepted it and
+  why in its notes.
+- [ ] 🟡 **History silent**: the `## History` log carries no line for the assessment or status
+  change this draft records — the append-only audit trail has a hole.
+
+## Consistency with the Doc Set
+
+- [ ] 🔴 **Assessment contradicts a committed doc**: a state or roadmap row contradicts the
+  canonical doc set — claiming D3 ✅ while `docs/architecture/infrastructure.md` records no `./dev` surface,
+  or naming a service `docs/architecture/index.md` does not have.
+- [ ] 🟡 **Status contradicts the roadmap's own evidence**: a row's notes describe the gap as
+  resolved while its status reads `open`, or vice versa — the row disagrees with itself.

package/src/hidden-skills/groundwork-review/checklists/product-brief.md

@@ -0,0 +1,69 @@
+---
+name: product-brief-checklist
+description: >
+  Type-specific failure modes for reviewing a draft product brief — the vision
+  document every downstream phase reads first.
+---
+
+# Product Brief Checklist
+
+This checklist checks a draft `docs/product-brief.md`. It answers one question: **can a
+designer, architect, and MVP planner each start their work from this document without asking
+"but what is this product, exactly?"**
+
+Each item names a violation. Match it against the document text; answer yes/no. A matched 🔴 item
+means downstream phases start from wrong foundations; a matched 🟡 item is advisory.
+
+## Document Hygiene
+
+- [ ] 🟡 **Leftover downstream summary**: the published doc still carries a `## Summary for
+  Downstream` section. The cross-phase contract now lives in `.groundwork/context/product-brief.md`,
+  not in the published doc; an old-template summary section is residue and should be removed.
+
+## Users
+
+- [ ] 🔴 **Label without a person**: a user type is named but carries no job-to-be-done or
+  success definition — a designer could not design a journey for them. "Busy professionals" is a
+  label; a mental model of why they hire the system is the standard.
+- [ ] 🔴 **Success without an observable**: a user type's "success looks like" cannot be observed
+  in practice — sentiment ("they feel confident") with no behaviour attached.
+- [ ] 🟡 **Phantom user**: a user type appears in the Capabilities or Experience sections but is
+  absent from Target Users, or vice versa.
+
+## Capabilities and Experience
+
+- [ ] 🔴 **Feature name without function**: a capability is a noun phrase ("smart scheduling",
+  "unified inbox") with no statement of what it does for the user, why it matters to the vision,
+  or how it connects to other capabilities.
+- [ ] 🔴 **Experience without a medium**: the Experience section describes what happens without
+  naming the interaction medium — screen-based app, command-line tool, API/protocol, voice, or
+  physical device. Downstream design and infrastructure decisions depend on it.
+- [ ] 🟡 **Steps without texture**: the Experience is a bare step list ("sign up, create a
+  booking, get a confirmation") that a reader cannot picture the shape of — no entry point, no
+  outcome, no sense of pacing.
+- [ ] 🟡 **MVP masquerading as vision**: the Capabilities section reads as a first-release scope
+  rather than the full vision — scoping belongs to MVP planning, and a pre-shrunk brief starves
+  it.
+
+## Altitude and Boundaries
+
+- [ ] 🔴 **Technology in the brief**: the document names databases, frameworks, vendors, or
+  hosting choices. Technology decisions belong to architecture; a brief that pre-commits them
+  contaminates that conversation.
+- [ ] 🟡 **Design-depth leakage**: the brief specifies interaction mechanics, edge-case handling,
+  or permission rules — "what happens when two users edit the same booking" is a later phase's
+  question.
+- [ ] 🔴 **Ungrounded constraint**: a Domain Constraint reads as a generic disclaimer ("the
+  system must be secure", "data must be handled responsibly") rather than a specific rule
+  grounded in this product's context.
+- [ ] 🟡 **Marketing voice**: the System Purpose paragraph pitches ("revolutionary", "seamless",
+  "delightful") instead of declaring what the system is, who it serves, and what it enables.
+
+## Success Indicators
+
+- [ ] 🔴 **Unobservable indicator**: a success indicator no designer or engineer could observe in
+  practice — "users find it valuable" instead of a concrete signal like "a user completes a
+  booking within their first session".
+- [ ] 🟡 **Indicator without a tie to the problem**: an indicator that could be satisfied while
+  the stated Problem remains unsolved — it measures activity, not the value the brief claims to
+  deliver.