groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/groundwork-bet/workflows/05-validation.md

@@ -0,0 +1,199 @@
+# Phase 5: Validation (Testing & Handoff)
+
+**Goal:** Verify the implementation, capture each touched service's served contract into the canonical `docs/architecture/api/` record, archive the whole bet, fold what the bet learned back into the upstream documents, and seed the next bet with any signals that surfaced during delivery.
+
+A bet that ships without updating upstream docs leaves the next bet operating against a stale map. The Validation phase exists to close the loop — the test suite proves the implementation works, the Living Documents scan proves the rest of the system still describes reality.
+
+## Operating Contract
+
+This workflow operates under the protocols defined in `.groundwork/skills/operating-contract.md` (contract v1; Continuous Bet mode: Protocols 1, 2, 4, 8, and 9 apply). This phase is the back-feed mechanism for the entire GroundWork lifecycle — Living Documents and Discovery Notes updates here are what keep the upstream `docs/` artifacts useful for every bet that follows.
+
+## Instructions
+
+### Step 1: Mark validation status
+
+Update `docs/bets/<bet-slug>/pitch.md` frontmatter to `status: validation`.
+
+### Step 2: Run the test suite
+
+Execute the full bet-progress test suite: `./dev test bet <bet-slug>` (or `pytest tests/bets/<bet-slug>/` directly). Every test must pass before advancing — and run the **prose-integrity reconciliation once over the whole bet**. By now the `bet/<bet-slug>/approved` tag has **ratcheted forward** through delivery — advancing additively as each milestone was opened-and-sliced or added — so it sits at the final rung's authoring commit. `git diff bet/<bet-slug>/approved.. -- docs/bets/<bet-slug>/decomposition/ docs/bets/<bet-slug>/technical-design/` shows no change except approved amendments (the Amendment Protocol's commit trail), and every built test still proves what its slice's Proof-of-work prose describes. (The per-slice reconciliation already guarded each ratchet step during delivery; this is the whole-bet confirmation.) The sealed contract is the prose; the tests and implementation were built this phase and are supposed to have changed. A suite that drifted from the sealed prose without a recorded amendment is not what the user approved — flag it and revert.
+
+**Contract verification:** Confirm that no manual schema definitions or rogue HTTP calls were introduced during Delivery — cross-service calls use clients derived from the canonical `docs/architecture/api/<service>/` contract, and no endpoint, field, or table exists that the prose design and the captured contract do not define. A bet that delivered against side-channel contracts has compromised the architecture's integrity; flag it and revert.
+
+### Step 2.5: Capture the canonical contract
+
+The bet's API and data design were prose; the real machine-readable contract is what the running service serves. Now that the implementation satisfies the design, snapshot it. For each service this bet touched, capture the service's **served** OpenAPI — `GET /openapi.json` from the running service, or the framework's spec export (FastAPI and Huma generate it from the code) — into `docs/architecture/api/<service>/openapi.yaml` (creating it for a new service), and likewise `asyncapi.yaml` where the service serves events. It is captured from running code, never promoted from a bet spec — the prose design is the design commitment, the running service is the source of truth. The canonical per-service spec is what the generated contract-conformance tests and `groundwork-check` read — a bet that never captures leaves the canonical record describing the system before this bet existed.
+
+### Step 2.6: Visual verification gate
+
+**Conditional — graphical surfaces only.** Skip this step entirely, and say so in one line, when the bet touched no `graphical-ui` surface: a backend, CLI, or agentic bet pays nothing. For a bet that delivered a graphical surface, confirm the visual ladder before the bet can reach `delivered`:
+
+1. **Tier 1 — the deterministic floor is green.** Step 2 already ran the suite; confirm `tests/system/test_render_smoke.py`, `test_a11y_smoke.py`, and `test_token_conformance.py` passed across the viewport × theme matrix. Render-smoke catches a blank/throwing/unstyled page; token-conformance asserts the specified atmosphere actually *landed* — the surface treatments render with their backdrop blur and multi-layer elevation rather than degrading to a flat default. A red layer is a real defect and blocks the bet — it is not a flaky test to wave through.
+2. **Tier 2 — spec-conformance inspection happened.** Confirm each graphical milestone recorded its per-screen spec-conformance verdict during delivery (the `Visual:` line in the closing slice's delivery commit, from `04-delivery.md` Milestone close). That verdict is the designer-judged check: does the rendered surface match the written micro-polish spec, including the dimensions computation cannot assert — optical alignment, restraint, and whether the composition reads as considered. A milestone that closed with no verdict did not run the inspection — route it back.
+
+Report which tiers ran in one line, so the run/skip is auditable. There is no separate multimodal "is it as good as the references" grading pass: the craft bar is set as the concrete micro-polish spec at design time (a screenshot cannot see motion or state, and a vision grade of static frames is a weak signal), enforced deterministically by Tier 1 and by the designer's spec-conformance judgement in Tier 2.
+
+### Step 2.7: Record the bet in the capability ledger
+
+Skip this step entirely when the project has no `docs/surfaces.md` — a project without a registry has a single implicit surface and no ledger to maintain.
+
+The capability ledger (in `docs/surfaces.md`) is where surface divergence becomes a recorded decision instead of silent drift, and validation is the one writer that appends capability rows. For each capability this bet delivered — user-meaningful, typically 1–3 per bet, coarse enough to stay readable, never per-endpoint — write its ledger row:
+
+- **Row key:** `<bet-slug>/<capability-slug>` — stable, greppable, collision-free.
+- **Every surface column filled** with exactly one state and its payload: `delivered` (this bet's slug), `planned` (a bet ref or discovery-notes pointer), `omitted` (one-line rationale), or `n/a` (no payload). The pitch's `surfaces:` scope and surface no-gos are the source: in-scope surfaces whose surface milestones went green are `delivered`; deferred no-gos and deferred surface milestones are `planned`; omitted no-gos are `omitted`, carrying the pitch's rationale; structurally meaningless columns are `n/a`. A retired surface's column fills `n/a` automatically.
+- **Cross-post every `planned` cell** as a bullet under `## Bets` in `.groundwork/cache/discovery-notes.md`, naming the capability key and the target surface — the next bet's Discovery reads that section, so the deferral becomes backlog instead of memory.
+- **Update `.groundwork/surfaces.json` in the same change:** append the capability entries with the same keys, states, and payloads. The prose ledger and its machine twin are projections of the same decisions; they never drift.
+
+**The gate:** a bet cannot reach `delivered` status with an empty ledger cell. An unfilled column is an undecided divergence — decide it with the user (`planned`, `omitted`, or `n/a`) before Step 8.
+
+**Shallow ledger update (insufficient):**
+
+```markdown
+| `notifications/status` | delivered | planned | planned |
+```
+
+States without payloads, `planned` cells pointing nowhere, nothing cross-posted to discovery notes, the JSON twin untouched — a deferral recorded where no future bet will find it is silent drift wearing a ledger row.
+
+**Deep ledger update (required standard):**
+
+```markdown
+| Capability | web-app | admin-cli | mcp-server |
+|---|---|---|---|
+| `notification-delivery/in-app-status` | delivered (`notification-delivery`) | planned (discovery-notes — operators asked for failure visibility during the Step 4 review) | omitted — agents query operation status directly via the contract; a push feed duplicates it |
+```
+
+Plus, in the same change: the `planned` cell cross-posted under `## Bets` in discovery notes ("`notification-delivery/in-app-status` → `admin-cli`: operators need failure visibility; deferred from `notification-delivery`"), and `.groundwork/surfaces.json` gaining the matching capability entry with identical states and payloads. Every column decided, every decision findable.
+
+### Step 3: Archive the whole bet
+
+Move the whole bet out of the active tree: `docs/bets/<bet-slug>/` → `docs/bets/_archive/<bet-slug>/` **and** `tests/bets/<bet-slug>/` → `tests/bets/_archive/<bet-slug>/`. Run `./dev archive bet <bet-slug>` if the CLI is available — it now moves both; otherwise `git mv docs/bets/<bet-slug> docs/bets/_archive/<bet-slug>` and `git mv tests/bets/<bet-slug> tests/bets/_archive/<bet-slug>`. The active docsite Bets section then shows only in-flight bets.
+
+The permanent best-practice tests rolled out during Delivery (in service repos and `tests/system/`) remain in place — they are the ongoing coverage for this feature going forward. The bet's prose and its bet-progress suite served their purpose as the definition of done and the proof-of-work scaffolding; they are now archived as the bet's record.
+
+### Step 4: Review with the user
+
+Summarise what was delivered. Walk through the user-facing changes, the new contracts, and any constraints the implementation revealed. Capture the user's reactions — corrections, requests for follow-up bets, or observations about what surprised them all belong in the next step's scan.
+
+### Step 5: Apply the Living Documents protocol
+
+The architecture of the system has changed. Every upstream document that describes the changed surface must be updated to match — surgically, in place, without asking permission. This is the single most important step of the phase, and the one most likely to be skipped under deadline pressure.
+
+For each `docs/` artifact, scan the bet conversation and the delivered code for what now contradicts the document. Apply targeted updates. Report what changed. When the update to `docs/architecture/index.md` is structural — a new boundary, a changed data flow, a new service-level requirement — adopt the architect persona (`.groundwork/skills/groundwork-architect/SKILL.md`) so the refinement carries the same reasoning standard the document was built to.
+
+Documents to scan, in order:
+
+1. **`docs/architecture/index.md`** — new services, new boundaries, refined data flows, new technology choices, new service-level requirements. The Service-Level Requirements table is the most common update target.
+2. **`docs/design-system.md`** — new design patterns, new component variants, new interaction states, refined accessibility commitments. Update only when the bet introduced something the design system did not anticipate. When the refinement is a design change — a new pattern or component variant, an interaction state, or an accessibility commitment — adopt the designer persona (`.groundwork/skills/groundwork-designer/SKILL.md`) so the update carries the same reasoning standard the design system was built to.
+3. **`docs/product-brief.md`** — new user types, refined success criteria, capabilities that turned out to be load-bearing in ways the brief did not capture. Vision-level refinements only; the brief is not a changelog. When the refinement is a vision-level product change — a new user type, a reframed success criterion, a capability that shifted the product's scope — adopt the product persona (`.groundwork/skills/groundwork-product/SKILL.md`) so the update carries the same reasoning standard the brief was built to.
+4. **`docs/architecture/infrastructure.md`** — new services in the local topology, new ports, new health endpoints, new commands. The infrastructure document must continue to describe a system that actually runs.
+5. **`docs/surfaces.md`** — when it exists: registry entries whose reality changed (a `planned` surface this bet activated, a changed core-access path or test medium), and confirm Step 2.7's ledger rows landed with their `.groundwork/surfaces.json` twin in lockstep. Skip when the project has no registry.
+6. **`docs/maturity.md`** — the maturity roadmap. Mark every row this bet closed as `closed (<bet-slug>)`, re-assess the dimensions the bet touched (a bet that captured a service's OpenAPI contract into `docs/architecture/api/` may move D2 from 🟡 to ✅ — cite the new evidence), open new rows for gaps the bet revealed or introduced (a new service shipped without a contract is a new `standard-divergence` row), and append one line to `## History`. Re-stamp `last_reviewed`. On a registry project, re-assess D8 (surface parity discipline) against the ledger state Step 2.7 just wrote — a `planned` cell aging past three closed bets with no referencing pitch is what moves it off ✅. If this bet activated a second independently-deployed surface or changed a published contract, re-assess D9 (contract compatibility): the stance must stand under architecture's Binding Constraints and the contract-conformance tests must show no breaking drift.
+
+For each document updated, report the change in one line: "Updated `docs/architecture/index.md` — added `notification-service` to service map and SLR row for at-least-once delivery."
+
+**Distinguish refinements from reversals (Protocol 2).** Most bet updates are refinements — new rows, new boundaries, additive detail. But if the bet *overturned* a prior Key Decision or Binding Constraint, or you are about to write a superseding ADR in Step 7, that update is a **reversal**, and the Reversal Protocol applies even in Continuous Bet mode (Protocols 1, 2, 4, 8, and 9 apply to the bet). For each reversal: reconcile the *full body* of the affected doc and every dependent doc it touches, write the superseding ADR (Step 7), and **re-invoke `groundwork-review` on each mutated doc** (Protocol 9), with the matching `document_type`. The re-gate is fail-closed and the revise cap applies (Protocol 8): proceed only on a parseable `VERDICT: PRESENT` per doc. Because the reversal supersedes an ADR, also re-review **every** `docs/architecture/domain/*.md` unconditionally (`document_type: domain-entity`) — their `Owner:`/fields go stale silently since they carry no summary to flag the drift, and they are the dependents most often missed. A bet that mutates four setup docs is exactly where contradictory canonical docs creep in — the re-gate is the guard.
+
+If a scan finds nothing to update, say so explicitly. Silence is ambiguous — the user cannot tell whether you scanned and found nothing or skipped the scan.
+
+### Step 6: Update discovery notes
+
+Scan the bet conversation for signals that belong to a future bet — sequencing instincts ("we should do notifications next"), parking-lot ideas ("the search experience needs its own bet"), constraints the user surfaced about subsequent work. Append these as bullets under `## Bets` in `.groundwork/cache/discovery-notes.md` so the next bet's Discovery phase finds them.
+
+Remove any discovery-notes entries that were incorporated into the artifacts updated in Step 5. A signal that has been promoted into a permanent document does not belong in the parking lot.
+
+### Step 7: Write ADRs for significant decisions
+
+Review the technical decisions made during this bet. If any decision was significant enough to warrant a permanent record — a stance future bets should not relitigate without a new ADR — write an ADR to `docs/architecture/decisions/NNNN-<slug>.md` using the template at `.groundwork/skills/templates/adr.md`.
+
+Significance test: would a new engineer joining the project six months from now need to know this decision to avoid revisiting it? If yes, record it. If no, skip. Not every bet produces an ADR.
+
+Number sequentially: read the existing `docs/architecture/decisions/` directory and use the next available integer (zero-padded to four digits). Create the `docs/architecture/decisions/` directory if it does not exist.
+
+### Step 7.5: Run the bet retrospective
+
+A bet that ships without extracting its lessons leaves the next bet to rediscover them at delivery prices. The retrospective is one facilitated pass over four mechanics — checklist items in a single conversation, not a ceremony — and its output is `docs/bets/<bet-slug>/retrospective.md` plus action items the next bet reads.
+
+1. **Mine the slice records.** Read the bet's delivery commits — `git log` of the `bet(<bet-slug>): slice ...` commits, their changed files and their `Notes:` lines — plus any change proposals or amendments in the bet directory. Surface *patterns*, not anecdotes: a finding type that appeared in two or more slice reviews, a struggle that recurred, a proof that needed amending. One-off issues are noise; repeats are process signal.
+2. **Audit the previous bet's action items.** Read the previous bet's `retrospective.md` (if one exists). For each action item: done, in progress, or ignored — and if ignored, did it cost us this bet? An item that was ignored *and* costly escalates to a `docs/maturity.md` row so it stops depending on anyone's memory.
+3. **Detect significant discoveries.** Check whether this bet invalidated anything queued bets depend on: an architectural assumption broken, a dependency the next pitch does not account for, debt that changes the appetite math, user behaviour different from what the brief assumed. On detection, recommend re-pitching the affected bets before the next one starts — never start a bet on premises this one just disproved. Whether a discovery overturns a queued bet's premise — changed user behaviour, shifted appetite math, or resequenced priorities — is a product judgement; adopt the product persona (`.groundwork/skills/groundwork-product/SKILL.md`) when weighing a re-pitch.
+4. **Explore readiness.** Green is not live. Confirm with the user where the delivered work actually stands — deployed, accepted, observed in use — and carry anything unresolved forward as an explicit item rather than an assumption.
+
+Write `docs/bets/<bet-slug>/retrospective.md`: the patterns found, the follow-through audit results, any discovery alerts, the readiness state, and the action items — each with a stable ID (`<bet-slug>-R1`, `-R2`, …) so the next retrospective can audit them mechanically. Append the action items as bullets under `## Bets` in `.groundwork/cache/discovery-notes.md`, each carrying its ID — the next bet's Discovery phase already reads that section.
+
+### Step 8: Mark the bet delivered
+
+Update `docs/bets/<bet-slug>/pitch.md` frontmatter to `status: delivered`. On a registry project, Step 2.7's gate applies: do not write `delivered` while any ledger cell for this bet's capabilities is empty — fill the column or the bet does not close.
+
+### Step 9: Hand off
+
+Confirm the bet is complete. Summarise what was delivered, what was updated upstream, and what was parked for the next bet. Recommend a fresh context for the next bet — the rich delivery context has been compressed into doc updates and discovery notes, so the next bet does not need it.
+
+## Quality Standard: What "Deep Enough" Looks Like
+
+The handoff fails when the Living Documents scan is a checkbox instead of a surgical update. A handoff that says "no changes needed" without naming what was scanned is indistinguishable from a handoff that skipped the scan entirely. The standard is concrete: state what you read, name what changed, and quote the change.
+
+**Shallow output (insufficient):**
+
+```
+Validation complete. Tests pass. Handing off to groundwork-doc-sync to refresh
+the docs.
+```
+
+**Deep output (required standard):**
+
+```
+Validation complete.
+
+Test suite: 47/47 passing. Contract verification: all cross-service calls
+use the generated `notification_client`; no rogue HTTP found.
+
+Whole bet archived: docs/bets/_archive/notification-delivery/ and
+tests/bets/_archive/notification-delivery/.
+
+Living Documents scan:
+
+- `docs/architecture/index.md` — added `notification-service` to the service map
+  (Phase 3 — Service Design). Added two rows to the Service-Level
+  Requirements table: at-least-once delivery for outbound notifications,
+  idempotent webhook handler on the receiving side. Tech stack updated to
+  reference NATS JetStream as the chosen async transport with the same
+  reasoning attached to existing entries.
+- `docs/design-system.md` — added `Toast` component variant for delivery-status
+  notifications. Updated interaction states to include the dismissable
+  state with focus-trap behaviour.
+- `docs/product-brief.md` — no changes; the bet implemented capabilities
+  already described.
+- `docs/architecture/infrastructure.md` — added `notification-service` (port 4002,
+  health endpoint `GET /health`) to the services table. Added NATS to
+  the infrastructure components table (port 4222, container
+  `<app>-nats`). Updated `./dev start` verification footnote to include
+  notification flow.
+- `docs/surfaces.md` — ledger row `notification-delivery/in-app-status`
+  written: web-app delivered (`notification-delivery`), admin-cli planned
+  (cross-posted to discovery notes), mcp-server omitted (agents query
+  operation status via the contract). `.groundwork/surfaces.json` updated
+  in the same change; no empty cells.
+
+Discovery notes:
+
+- Removed two `## Design Details` entries that were incorporated into the
+  notification service's contract.
+- Appended one `## Bets` entry: "Search experience parked — the user
+  raised it three times during this bet, and the architecture's search
+  capability is currently unmapped. Next bet candidate."
+
+Bet status: delivered.
+```
+
+The shallow version tells the user nothing. The deep version proves the scan happened, names what changed and why, and surfaces the discovery-note delta so the next bet starts with a clear inheritance.
+
+The same standard applies across every scan target:
+- **Architecture updates** must name the section, the change, and the reasoning — not just "added a service."
+- **Design System updates** must name the component or pattern that changed and whether existing patterns are affected.
+- **Brief updates** must justify the vision-level change against what the user actually said during delivery.
+- **Infrastructure updates** must include the concrete observable changes — ports, commands, health endpoints — not a summary.
+- **Ledger updates** must carry every cell's state with its payload and name where each `planned` deferral was cross-posted — a state without its payload is a decision without its record.
+
+## Congratulations
+
+Once Steps 1 through 9 are complete and the user has seen the handoff summary, congratulate them on a successful bet. The cycle returns to the orchestrator for the next bet or anytime skill.

package/src/hidden-skills/groundwork-design-system/instructions.md

@@ -0,0 +1,125 @@
+---
+name: groundwork-design-system
+description: >
+  Translates the user's aesthetic intent — mood, personality, interaction
+  philosophy — into an implementation-ready `docs/design-system.md` that
+  eliminates all downstream design decisions. The brand conversation runs once;
+  a translation track runs per interface type in use. Taste conversation in,
+  precision specification out, reviewed with the user section by section.
+---
+
+# GroundWork Design System
+
+You are an opinionated, technical design systems architect collaborating with a domain expert. The user knows their product deeply — your role is to codify their vision into an implementation-ready design system that eliminates all downstream design decisions. Your output is `docs/design-system.md`: a precision specification that a developer or generative UI tool can implement without making any choices that belong to design.
+
+**Adopt the designer persona.** Load `.groundwork/skills/groundwork-designer/SKILL.md` and operate as it for this entire workflow. It carries the design principles you apply — visual craft, layout and space, interaction and motion, usability, the token contract, accessibility — in a self-contained `references/` library routed by decision shape. This workflow choreographs the *conversation* (phases, gates, the per-interface-type tracks); the persona supplies the *design expertise*. When a phase reaches a decision the persona holds a reference for — perceptual colour and type in `visual-craft.md`, spacing and grid in `layout-and-space.md`, states and motion in `interaction-and-motion.md`, the token tiers in `design-systems-and-tokens.md` — load that reference and apply its reasoning rather than re-deriving it here.
+
+Lead with curiosity and discovery before leading with proposals. Understand how the user wants their product to *feel* — the mood, the personality, the interaction philosophy — before committing to any specification values. When you can articulate their aesthetic intent clearly enough to explain it back to them, you are ready to translate it into a rigorous design system. Assumptions left unexamined here become CSS values nobody questioned and nobody likes.
+
+Education is part of this role. Most users have a clear sense of taste and instinct; fewer understand why OKLCH matters over HEX, why spring physics feel different from linear easing, or how an 8-point spatial grid creates visual rhythm. When a design area has a well-understood technical foundation, surface it. Closing that gap is part of what makes this conversation valuable.
+
+Apply the `groundwork-writer` skill when producing the final output document. Declarative, assertive, zero-hedging.
+
+---
+
+## Core Contract: Intent In, Specification Out
+
+The user is not a designer or specification writer. They speak in taste, instinct, analogy, and feeling. That is the correct level of input.
+
+The process has three beats:
+
+1. **High-level conversation** (Phases 1–4): The agent and user talk about how the product should *feel* — its mood, its personality, its interaction philosophy. No implementation details, no spec-level values, no technical formatting. This conversation runs **once, at brand level** — a product has one personality no matter how many interface types express it.
+2. **Expert translation** (Phase 5a): The agent autonomously converts the approved direction into a rigorous, implementation-ready specification. This is the agent's core contribution, and it runs **once per interface type in use** — the same brand direction becomes CSS tokens for a screen, ANSI roles for a terminal, protocol semantics for an agent surface.
+
+   When entering Phase 5a, announce the shift from collaborative conversation to autonomous translation — the user should understand the interaction pattern is changing and that the agent will return with a complete design system for review. Cache updates during this phase are preparation steps, not interruptions of the conversation.
+
+3. **Specific review** (Phase 5b): The agent presents each type's design system as a proposal. The user and agent walk through the specifics together — reacting to concrete choices, adjusting values, and refining until the spec is right.
+
+This separation is non-negotiable. A user who is asked to approve OKLCH values during the taste conversation disengages. An agent who skips the translation and echoes the user's words back as a "design system" has done no useful work.
+
+---
+
+## How This Conversation Works
+
+Building a design system is a multi-phase collaborative session, not a questionnaire. Each phase has a distinct goal. You drive the conversation — knowing which phase you are in, what you are trying to establish, and when you have enough to move forward.
+
+- **Discover before proposing.** In each phase, explore the user's intent and preferences before presenting a recommendation. The proposal should feel like a natural conclusion to the conversation, not an interruption of it.
+- **Use the user's language.** Never assume the user recognises acronyms or jargon they did not introduce themselves. When you bring technical concepts into the conversation, teach them — don't drop them.
+- **Orient the user.** When starting a new phase, explain where the user is in the process and how the phase will be run.
+
+---
+
+## 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.
+
+---
+
+## Initialization & Resume Protocol
+
+### Step 1: Cache Check
+
+Check if `.groundwork/cache/design-system-cache.md` exists.
+
+- If it **does not exist**, copy the template from `.groundwork/skills/groundwork-design-system/templates/design-system-cache.md` to `.groundwork/cache/design-system-cache.md`. 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. If `interface_types` is already recorded and phases are in progress, summarise what has been completed and ask whether the user wants to resume or start fresh. If they choose to start fresh, reset the cache file from the template. If they choose to resume, skip to Step 3.
+
+### Step 1.5: Discovery Notes Check
+
+Apply the Discovery Notes check from the Operating Contract. Check `.groundwork/cache/discovery-notes.md` for entries under `## Design System` and carry them as pre-discovered context into the track.
+
+The capture half of Protocol 1 applies through every phase of the track: when the user voices an out-of-phase signal — an architecture instinct, a delivery priority, an implementation specific — append it under its header (`## Architecture`, `## Bets`, `## Design Details`) in `.groundwork/cache/discovery-notes.md` and steer back to the design conversation. Create the file from the template at `.groundwork/skills/templates/discovery-notes.md` if it does not exist.
+
+### Step 1.6: Hand-off Cache Check
+
+Check if `.groundwork/cache/handoff/product-brief.md` exists. If it does, read it in full — it carries the previous phase's post-commit context: rejected user-type framings, deferred design decisions, user aesthetic instincts not yet formalised. Treat this as pre-discovered context the same way as discovery notes. This is the Hand-off Cache contract from Protocol 6 of the Operating Contract.
+
+If the file does not exist, skip this step. The Operating Contract's Cache Isolation rule (Protocol 7) forbids reading any other phase's cache.
+
+### Step 2: Interface Type Detection
+
+Read the product brief's Downstream Context file `.groundwork/context/product-brief.md` first (Protocol 5) — that file carries the Key Decisions, Binding Constraints, and Deferred Questions the product brief committed to. Only read the body of `docs/product-brief.md` if the context file does not name the interaction surfaces clearly enough to classify.
+
+Design tracks run once per **interface type** in use, not per surface — a web app and a mobile app are both `graphical-ui` and share one track run. When the context file's Key Decisions carry the surface set with horizon markers (MVP / later / aspirational), classify each surface into a type using the table below; the distinct types of the **MVP-horizon** surfaces are this session's active set. Types appearing only at later or aspirational horizons are deferred — record them in the cache, but do not run their tracks now: they run lazily when `groundwork-surface-activation` births the first surface of that type, appending its section to the existing design system.
+
+When the context file carries no surface set (a brief written before surfaces were enumerated), fall back to single-type detection: determine the product's primary interface type and treat it as an active set of one.
+
+The interface type describes what the end-user interacts with, not what the backend does. An AI-powered product with a visual frontend is `graphical-ui` regardless of backend complexity.
+
+| Type | Signals | Examples |
+|---|---|---|
+| `graphical-ui` | Web app, mobile app, desktop app, dashboard, any product whose target users are end-consumers interacting through a screen | SaaS products, consumer apps, interactive fiction, e-commerce storefronts, admin panels, data visualisation tools, AI-powered products with a visual frontend |
+| `cli` | Command-line tool, terminal application, shell utility — a human sits at a terminal and interacts through typed commands and rendered output, whether the tool runs one-shot or as an interactive session | Developer tools, build systems, package managers, infrastructure CLI, interactive coding assistants and agentic terminal apps (Claude Code, Gemini CLI, Aider) |
+| `agentic-protocol` | Agent framework, skill system, MCP server, developer methodology, protocol — the consumer is another program or agent integrating via API, with no human terminal surface | GroundWork itself, LangChain, agent orchestrators, MCP servers |
+
+If `docs/product-brief.md` does not exist or cannot be read, ask the user what kind of interface their product has — visual app, command-line tool, or agent/protocol system, or a combination. Use their answer to determine the types. Do not proceed without a confirmed active set in `interface_types`.
+
+If the product brief describes end-consumers (players, readers, shoppers, viewers) as target users but uses backend or engine language, the product is `graphical-ui`. The `agentic-protocol` type applies only when the primary users are developers or other agents integrating via API.
+
+Disambiguate `cli` from `agentic-protocol` by **who consumes the output**: a human watching a terminal, or a program integrating via API. A product where a human sits at a terminal interacting with an embedded agent is `cli`, even when an LLM drives the experience underneath — the design problem is terminal rendering, streaming, and interaction. `agentic-protocol` is for the framework or protocol consumed via API with no human terminal surface. A coding assistant a developer runs in their shell routes to `cli`; the MCP server or agent framework it talks to routes to `agentic-protocol`.
+
+If the product brief contains explicit interface vocabulary (web app, CLI tool, agent framework), record the types. If the brief describes the system without naming any interaction surface, treat it as ambiguous and ask the user a single, direct question to determine which of the three types applies.
+
+Write the active set to the `interface_types` field in `.groundwork/cache/design-system-cache.md`, and any deferred types to its `deferred_types` field.
+
+### Step 3: Load Foundation and Tracks
+
+Load and execute `.groundwork/skills/groundwork-design-system/tracks/_foundation.md` — the shared foundation flow. It owns the session spine: the brand-level Phases 1–4 run once, each active type's Phase 5 translation and walkthrough run from its track file, and one commit closes the phase. The foundation draws each type's contributions from the corresponding track file:
+
+| Interface Type | Track File |
+|---|---|
+| `graphical-ui` | `.groundwork/skills/groundwork-design-system/tracks/graphical-ui.md` |
+| `cli` | `.groundwork/skills/groundwork-design-system/tracks/cli.md` |
+| `agentic-protocol` | `.groundwork/skills/groundwork-design-system/tracks/agentic-protocol.md` |
+
+Read the foundation file and the active tracks, then execute from the foundation's Phase 1 (or the appropriate resume point if resuming). DO NOT retain these initialization instructions in context once the foundation is loaded. The foundation file is the single source of truth for the session spine; each track is the single source of truth for its type's design content.
+
+The output, `docs/design-system.md`, carries the shared brand foundation plus one titled section per active type (`# Graphical UI`, `# CLI`, `# Agentic Protocol`) — the section `docs/surfaces.md` design-track references resolve to. A deferred type gets its section later: `groundwork-surface-activation` runs that type's track lazily against the existing foundation, without re-running the brand conversation.
+
+### Commit Contract
+
+The commit runs once, in the foundation flow's Phase 6, after every active type's walkthrough completes. It must follow Protocol 3.4 of the Operating Contract — including writing the Downstream Context file to `.groundwork/context/design-system.md` (Protocol 5, enforced by `groundwork-writer`) while keeping `docs/design-system.md` a clean spec with no summary section, and writing the hand-off file to `.groundwork/cache/handoff/design-system.md` (Protocol 6, template at `.groundwork/skills/templates/handoff.md`). The hand-off captures rejected aesthetic directions, deferred design decisions, user instincts about interaction patterns or motion that did not make it into the spec, and any other context the architecture phase needs. The previous phase's hand-off at `.groundwork/cache/handoff/product-brief.md` is deleted at the same commit — this phase has now consumed it.
+
+**Brand tokens.** The commit also writes `.groundwork/config/brand-tokens.json` — the machine-readable projection of the branding decisions, following the contract at `.groundwork/skills/groundwork-design-system/templates/brand-tokens.md`. Every product gets the **Tier 1** `identity` block (name, wordmark, primary/accent colour, voice), projected mechanically from the brand's palette and the product brief — not a new design conversation — because scaffolding reads it to brand the `./dev` CLI regardless of interface type. Each active type that defines a **Tier 2** block adds it alongside: the `cli` track emits the `terminal` block (colour role table, symbol vocabulary, splash, typography) and the `graphical-ui` track emits the `visual` block (semantic palette, typography, shape, density, motion), each carrying the same values as its type's section in `docs/design-system.md`. A product with both types in use carries both blocks. This file lives in persistent config and is not deleted at cache cleanup.

package/src/hidden-skills/groundwork-design-system/templates/brand-tokens.md

@@ -0,0 +1,182 @@
+# Brand Tokens Contract
+
+`brand-tokens.json` is the machine-readable projection of the design system's branding decisions. The prose in `docs/design-system.md` is the human source of truth; this file is what automation reads. Both are written at the Design System commit; they never disagree because the tokens are derived from the same approved decisions.
+
+**Location:** `.groundwork/config/brand-tokens.json` — the persistent config home, alongside `config.toml` and `state.json`. It is not a draft and it is not deleted on cache cleanup.
+
+**Why it exists:** one brand, many renderers. The scaffolded `./dev` control plane reads these tokens to brand itself; a CLI product's own starter reads the same tokens through the same render layer; a graphical product's app generator reads them to seed its theme. The framework wears the brand it helps design.
+
+---
+
+## Tier 1 plus per-type Tier 2 blocks
+
+Every project gets a `./dev` CLI regardless of what it is building, so **every product emits Tier 1** — the singular `identity` block, because identity is brand-level. **Tier 2 is a set of per-type blocks**, keyed by name at the top level of the JSON: each interface type whose design track produces a machine-projectable treatment contributes one block, so a product with several types in use carries several blocks side by side.
+
+| Block | Emitted by | Carries | Read by |
+|---|---|---|---|
+| `identity` (Tier 1) | every product, exactly once | name, wordmark glyph, primary/accent colour, voice | `./dev`, lightly — and every Tier 2 consumer as the fallback root |
+| `terminal` (Tier 2) | the `cli` track | colour role table, symbol vocabulary, splash, typography | `./dev` richly + the product CLI, via the shared render layer |
+| `visual` (Tier 2) | the `graphical-ui` track | semantic palette (both themes), typography (with per-role micro), shape, density, motion (with interaction profiles), elevation, blur, gradients, surface treatments, optional `platform` ergonomics | graphical app generators, to seed the surface theme (Tailwind today; other theme projections as surface generators land) |
+
+The `agentic-protocol` track contributes no Tier 2 block — a protocol has no terminal or visual treatment to project.
+
+Tier 2 blocks are **additive** over Tier 1 and over each other. Consumers read the block they need **by key**, tolerate its absence (falling back to a theme derived from `identity`), and ignore blocks they do not know. Never reshape Tier-1 fields to add a block; only append.
+
+The `tier` field reads as a capability summary: `1` means identity only; `2` means the file carries at least one Tier 2 block. Consumers must not branch on `tier` to locate blocks — presence of the block key is the only reliable signal, and existing consumers already work this way.
+
+---
+
+## Field reference
+
+### Tier 1 — `identity` (required, every product)
+
+| Field | Type | Meaning |
+|---|---|---|
+| `appName` | string | Product name as shown in CLI headers and help. |
+| `wordmark` | string | A short glyph or mark rendered before the name (e.g. `◢◤`). One to three characters. Empty string for none. |
+| `primary` | string `#rrggbb` | The brand's primary accent colour. Drives the CLI's primary chrome (logo, active markers, step headers). |
+| `accent` | string `#rrggbb` | A secondary accent for emphasis and selection. |
+| `voice` | string | A short descriptor of the product's tone (e.g. `"terse, Unix-traditional"`). Informs default verbosity and microcopy. |
+
+### Tier 2 — `terminal` (cli track)
+
+- `colorRoles` — a map of semantic role → resolution across colour depths. Roles: `success`, `error`, `warning`, `info`, `muted`, `accent`, `header`, `key`, `value`. Each role carries `truecolor` (`#rrggbb` or `null`), `ansi256` (0–255 or `null`), and `noColor` (the bold/dim/underline/case treatment used when colour is stripped). The render layer resolves truecolor → ansi256 → noColor → plain by terminal capability. Roles with `null` colour fields (e.g. `header`) are expressed by `noColor` treatment at every depth.
+- `symbols` — a map of marker → `{ unicode, ascii }`. The render layer uses `unicode` on capable terminals and `ascii` otherwise. Markers: `success`, `error`, `warning`, `info`, `step`, `substep`, `active`.
+- `splash` — `{ style, tagline }`. `style` is one of `wordmark-line` (the mark + name on one line), `banner` (a multi-line header), or `none`. `tagline` is optional.
+- `typography` — treatment per content tier: `header`, `title`, `body`, `muted`. Values are treatment descriptors (`"bold + UPPERCASE"`, `"bold + primary"`, `"plain"`, `"dim"`).
+
+### Tier 2 — `visual` (graphical-ui track)
+
+- `palette` — a map of semantic role → `{ light, dark }` CSS colour strings (OKLCH or `#rrggbb`), the machine form of the colour architecture in `docs/design-system.md`. Roles: `primary`, `accent`, `surface`, `surfaceAlt`, `textBody`, `success`, `error`, `warning`, `info`. Both theme values are required for every role — the design system commits to dual-theme palettes, so the projection carries both.
+- `typography` — `{ display, body, scale }`. `display` and `body` are `{ family, weight }` for the heading and body families. `scale` is a short descriptor of the type-scale treatment (e.g. `"1.25 modular from 16px, fluid clamp"`), enough for a generator to reconstruct the scale's character without re-deriving every step — the full scale lives in the document. Optionally carries `roles` — a map of type role (`display`, `title`, `body`, `caption`, `label`) → `{ size, lineHeight, weight, tracking }`, the concrete per-role micro (line-height and tracking) that separates considered type from framework defaults — and `numeric` (e.g. `"tabular-nums"`) where columns of figures must align.
+- `shape` — `{ radiusBase, character }`. `radiusBase` is the base corner radius (e.g. `"8px"`); `character` is a one-line descriptor of the shape language (e.g. `"soft, concentric nesting"`).
+- `density` — a one-line spacing/density descriptor carrying the grid base (e.g. `"comfortable, 8pt grid"`).
+- `motion` — `{ easeStandard, durationBaseMs, personality }`. `easeStandard` is the standard easing curve (`"cubic-bezier(0.2, 0, 0, 1)"`), `durationBaseMs` the base duration, `personality` a one-word register (`"snappy"`, `"weighted"`, `"restrained"`). Optionally carries `interactions` — a map of context (`hover`, `press`, `enter`, `exit`, `stagger`) → `{ durationMs, ease, transform }`, the per-context motion profiles a surface spec references so feedback timing is a token rather than an ad-hoc value invented per component.
+- `elevation` — optional; a map of level name → an ordered array of shadow layers, each `{ y, blur, spread?, color }` (CSS length plus an OKLCH/`#rrggbb` colour, alpha tapering as the layer widens). The machine form of the design system's depth model: a level is a *stack* — several layers reading as one modelled shadow — not a single drop shadow. Name levels by role (`low`, `mid`, `high`) or by the product's own vocabulary. The geometry serves both themes; carry theme-specific tinting in the layer colour where the design system calls for it.
+- `blur` — optional; a map of level name → CSS length (e.g. `"subtle": "8px"`, `"standard": "12px"`, `"heavy": "20px"`), the backdrop-blur radii the surface treatments draw on.
+- `gradients` — optional; a map of name → a CSS gradient string (the mesh/aurora recipe, e.g. a layered `radial-gradient`), or `{ light, dark }` when the recipe differs by theme. The machine form of the design system's ambient-texture decisions.
+- `surface` — optional; a map of named surface treatment → a composition of the tokens above: `{ blur?, tint?, border?, elevation?, gradient?, noise? }`, where `blur`/`elevation`/`gradient` name an entry in those maps (or carry a literal value) and `tint`/`border` are CSS colours with alpha. This is the per-app surface vocabulary — the glass/elevated/hero treatments a product composes once and reuses — and it is the home for surface recipes that must never be baked into an engineer skill. A generator projects each treatment into one utility class.
+- `references` — optional; the machine-readable form of the design system's `## Design References` record. An array of `{ name, admired }` objects (e.g. `{ "name": "Linear", "admired": "command-palette density, backdrop blur, restraint with colour" }`), naming the market-leading products the design drew from and the specific qualities admired. It is the machine index of the technique library — it informs the atmosphere and motion tokens and the per-surface micro-polish spec at bet design; present when the design system committed a reference record. Sub-objects keyed by platform dimension; each theme projection reads the sub-object it serves and ignores the rest. Web needs no sub-object — the fields above are the web baseline, and one visual block serves every platform.
+  - `platform.touch` (mobile surfaces) — `{ targetMin, durationScale }`. `targetMin` is the minimum interactive dimension (e.g. `"48dp"`); the mobile theme projection enforces it in tap-target sizing. `durationScale` (optional, default 1) multiplies `durationBaseMs` for touch surfaces, where full-screen transitions span more distance than pointer micro-interactions.
+  - `platform.desktop` (desktop surfaces) — `{ titleBar, menuStyle, density }`. `titleBar` is the window-chrome treatment: `"native"`, `"hidden-inset"` (content extends beneath the platform's window controls), or `"custom"`. `menuStyle` is `"native"` (OS menu bar) or `"in-window"`. `density` (optional) overrides the top-level `density` descriptor for pointer-precision layouts. The desktop shell owns these fields; its renderer reads the shared fields unchanged.
+
+---
+
+## Annotated example — a product carrying both Tier 2 blocks
+
+A web app, a mobile app, and a desktop shell plus an admin CLI: the graphical-ui track emitted one `visual` block for all three graphical surfaces — with `platform` ergonomics for mobile and desktop — the cli track emitted `terminal`, and every projection carries the same brand.
+
+```json
+{
+  "schema": "groundwork.brand-tokens",
+  "version": 1,
+  "tier": 2,
+  "identity": {
+    "appName": "Acme",
+    "wordmark": "◢◤",
+    "primary": "#5fafff",
+    "accent": "#d7afff",
+    "voice": "terse, Unix-traditional"
+  },
+  "visual": {
+    "palette": {
+      "primary":    { "light": "oklch(55% 0.18 250)", "dark": "oklch(70% 0.15 250)" },
+      "accent":     { "light": "oklch(70% 0.15 300)", "dark": "oklch(75% 0.13 300)" },
+      "surface":    { "light": "oklch(98% 0.005 250)", "dark": "oklch(18% 0.01 250)" },
+      "surfaceAlt": { "light": "oklch(95% 0.008 250)", "dark": "oklch(22% 0.012 250)" },
+      "textBody":   { "light": "oklch(25% 0.01 250)", "dark": "oklch(90% 0.005 250)" },
+      "success":    { "light": "oklch(60% 0.13 160)", "dark": "oklch(70% 0.12 160)" },
+      "error":      { "light": "oklch(55% 0.18 25)",  "dark": "oklch(68% 0.16 25)" },
+      "warning":    { "light": "oklch(70% 0.14 85)",  "dark": "oklch(78% 0.13 85)" },
+      "info":       { "light": "oklch(60% 0.14 250)", "dark": "oklch(72% 0.12 250)" }
+    },
+    "typography": {
+      "display": { "family": "Instrument Sans", "weight": 600 },
+      "body":    { "family": "Inter", "weight": 400 },
+      "scale":   "1.25 modular from 16px, fluid clamp",
+      "roles": {
+        "display": { "size": "2.5rem",   "lineHeight": 1.1,  "weight": 600, "tracking": "-0.02em" },
+        "title":   { "size": "1.5rem",   "lineHeight": 1.25, "weight": 600, "tracking": "-0.01em" },
+        "body":    { "size": "1rem",     "lineHeight": 1.6,  "weight": 400, "tracking": "0" },
+        "caption": { "size": "0.875rem", "lineHeight": 1.5,  "weight": 400, "tracking": "0.01em" }
+      },
+      "numeric": "tabular-nums"
+    },
+    "shape": { "radiusBase": "8px", "character": "soft, concentric nesting" },
+    "density": "comfortable, 8pt grid",
+    "motion": {
+      "easeStandard": "cubic-bezier(0.2, 0, 0, 1)",
+      "durationBaseMs": 150,
+      "personality": "snappy",
+      "interactions": {
+        "hover":   { "durationMs": 150, "ease": "cubic-bezier(0, 0, 0.2, 1)", "transform": "translateY(-1px)" },
+        "press":   { "durationMs": 100, "ease": "cubic-bezier(0.4, 0, 1, 1)", "transform": "scale(0.97)" },
+        "enter":   { "durationMs": 200, "ease": "cubic-bezier(0, 0, 0.2, 1)", "transform": "scale(0.98)" },
+        "stagger": { "durationMs": 30,  "ease": "linear",                     "transform": "none" }
+      }
+    },
+    "elevation": {
+      "low":  [ { "y": "1px", "blur": "2px", "color": "oklch(0% 0 0 / 0.06)" } ],
+      "mid":  [ { "y": "1px", "blur": "2px", "color": "oklch(0% 0 0 / 0.06)" },
+                { "y": "4px", "blur": "8px", "color": "oklch(0% 0 0 / 0.04)" } ],
+      "high": [ { "y": "1px",  "blur": "2px",  "color": "oklch(0% 0 0 / 0.06)" },
+                { "y": "4px",  "blur": "8px",  "color": "oklch(0% 0 0 / 0.04)" },
+                { "y": "12px", "blur": "24px", "color": "oklch(0% 0 0 / 0.03)" } ]
+    },
+    "blur": { "subtle": "8px", "standard": "12px", "heavy": "20px" },
+    "gradients": {
+      "aurora": "radial-gradient(60% 60% at 30% 20%, oklch(70% 0.15 300 / 0.18), transparent 70%)"
+    },
+    "surface": {
+      "glass":    { "blur": "standard", "tint": "oklch(98% 0.005 250 / 0.72)", "border": "oklch(100% 0 0 / 0.08)", "elevation": "mid" },
+      "elevated": { "blur": "heavy",    "tint": "oklch(98% 0.005 250 / 0.82)", "border": "oklch(100% 0 0 / 0.12)", "elevation": "high" },
+      "hero":     { "blur": "standard", "tint": "oklch(98% 0.005 250 / 0.65)", "border": "oklch(100% 0 0 / 0.10)", "elevation": "high", "gradient": "aurora" }
+    },
+    "platform": {
+      "touch":   { "targetMin": "48dp", "durationScale": 1.25 },
+      "desktop": { "titleBar": "hidden-inset", "menuStyle": "native", "density": "compact, 8pt grid" }
+    }
+  },
+  "terminal": {
+    "colorRoles": {
+      "success": { "truecolor": "#5faf87", "ansi256": 72,  "noColor": "bold" },
+      "error":   { "truecolor": "#d75f5f", "ansi256": 167, "noColor": "bold" },
+      "warning": { "truecolor": "#d7af5f", "ansi256": 179, "noColor": "bold" },
+      "info":    { "truecolor": "#5fafff", "ansi256": 75,  "noColor": "dim" },
+      "muted":   { "truecolor": "#8a8a8a", "ansi256": 245, "noColor": "dim" },
+      "accent":  { "truecolor": "#d7afff", "ansi256": 183, "noColor": "underline" },
+      "header":  { "truecolor": null,      "ansi256": null, "noColor": "bold+upper" },
+      "key":     { "truecolor": "#5fafff", "ansi256": 75,  "noColor": "plain" },
+      "value":   { "truecolor": "#d0d0d0", "ansi256": 252, "noColor": "plain" }
+    },
+    "symbols": {
+      "success": { "unicode": "✔", "ascii": "OK" },
+      "error":   { "unicode": "✖", "ascii": "x" },
+      "warning": { "unicode": "⚠", "ascii": "!" },
+      "info":    { "unicode": "●", "ascii": "*" },
+      "step":    { "unicode": "▶", "ascii": ">" },
+      "substep": { "unicode": "↳", "ascii": "-" },
+      "active":  { "unicode": "❯", "ascii": ">" }
+    },
+    "splash": { "style": "wordmark-line", "tagline": "" },
+    "typography": {
+      "header": "bold + UPPERCASE",
+      "title":  "bold + primary",
+      "body":   "plain",
+      "muted":  "dim"
+    }
+  }
+}
+```
+
+A CLI-only product is the same object without the `visual` block; a web-only product, without the `terminal` block — and without `platform`, which appears only when a mobile or desktop surface shares the visual block. A Tier-1 file (`"tier": 1`) carries neither block — `identity` only.
+
+---
+
+## Rules
+
+- **Derive, never invent.** Every value traces to an approved Design System decision. `terminal.colorRoles` is the machine form of the CLI section's colour architecture; `visual.palette` is the machine form of the graphical section's colour architecture — block and document must carry the same values.
+- **Tier 1 is always derivable.** For products with no cli track, project the brand's primary palette colour to `identity.primary`, pick a secondary as `accent`, and take the product name and voice from the brief. This is a mechanical projection, not a new design conversation.
+- **One block per type, one writer per block.** Each type's track emits its own block at the single Design System commit (or at lazy activation, when a type's track runs later). Blocks never share or override each other's fields.
+- **Versioned contract.** `version` is bumped only when the shape of an existing field changes. Adding a block kind, or an optional field or sub-object within a block (e.g. `visual.platform`), is additive — `version` stays 1. Consumers ignore unknown fields and unknown blocks, and tolerate any missing Tier 2 block or optional field.
+- **Many readers, by key.** The `workspace-dev-cli` generator, the shared CLI render layer, and the `cli-app` product generator read `terminal`; graphical app generators read `visual`; none of them write, and none locate a block through the `tier` field.

package/src/hidden-skills/groundwork-design-system/templates/design-system-cache.md

@@ -0,0 +1,64 @@
+# Design System Cache
+
+> This file captures approved outputs from each phase of the Design System process. It is used to resume work and to compile the final `docs/design-system.md`. Do not edit manually.
+
+**Interface Types:** pending
+**Deferred Types:** none
+
+---
+
+## Phase 1: Non-Functional Requirements
+
+**Status:** pending
+
+<!-- Replace this section with the agreed NFRs once the user approves them. -->
+
+---
+
+## Phase 2: Inspiration Library
+
+**Status:** pending
+
+<!-- Replace this section with the agreed inspiration library once the user confirms the direction. -->
+
+---
+
+## Phase 3: Structure
+
+**Status:** pending
+
+<!-- One subsection per active interface type. Replace with each type's agreed structure definition once the user approves it. -->
+
+---
+
+## Phase 4: Design Language
+
+**Status:** pending
+
+### Cluster Coverage
+
+Language clusters group aesthetic decisions for user reaction. The brand-level core is defined in the foundation flow; each active track's Type language contribution folds into the same clusters. Skip a cluster only when irrelevant to the product.
+
+- [ ] Cluster 1: Identity
+- [ ] Cluster 2: Feel
+- [ ] Cluster 3: Craft
+
+### Synthesis
+
+<!-- Replace with the Phase 4 Synthesis Gate output once the user approves the direction. -->
+
+---
+
+## Phase 5: Expert Translation & Review
+
+**Status:** pending
+
+**Draft Location:** `.groundwork/cache/design-system-draft/` — a directory of per-section files shared by all active types. See each track's file table and the foundation flow's Draft Layout rule. Concatenated into `docs/design-system.md` at commit.
+
+### Walkthrough Progress
+
+Spec clusters group implementation specifics for the Phase 5b walkthrough. Names are deliberately distinct from Phase 4's language clusters. Phase 5 runs once per active type — duplicate this checklist under a heading per type.
+
+- [ ] Cluster 1: Foundation (base tokens — colour, type scale, spacing equivalents)
+- [ ] Cluster 2: Interaction (depth, motion, interaction states, behaviour under load)
+- [ ] Cluster 3: Surface (everything else — refer to the active track for the full list)