groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/groundwork-scaffold/phases/01-ingestion-service-mapping.md

@@ -0,0 +1,87 @@
+# Phase 1: Ingestion & Service Mapping
+
+Read `docs/architecture/index.md` to identify every service, database, and messaging component the system requires. This document is the source of truth for what needs to be built.
+
+Read `.groundwork/config/generators.json` to discover the available generators. Then read the schema for each generator relevant to the architecture — schemas define the full parameter space (authentication models, messaging integrations, WebSocket support, database inclusion) and understanding them before mapping ensures each generator is configured correctly.
+
+Also read `.groundwork/config/config.toml` if it exists: entries under `[defaults.generators]` (flags keyed by generator name) and `[defaults]` (llm_provider, llm_model) are the user's standing preferences. Fold them into the mapping proposal as the configured starting position — named as coming from their config, never silently applied, and overridden without ceremony when the architecture demands it.
+
+With the architecture and schemas in hand, **propose the full service-to-generator mapping in a single structured pass** — one row per service with the generator choice, key parameters, and a one-line rationale. Proposing everything at once exposes cross-service inconsistencies that per-service interrogation hides, and lets the user react to the complete picture rather than approving one service at a time.
+
+For each service in the proposal:
+- Identify which generator produces this service.
+- Determine the parameters from the architecture's capability decisions: authentication model, messaging integration, WebSocket requirement. Use the Generator Capability Mapping below to translate architectural language into specific flag values — architecture documents are written in vendor-neutral capability terms, and the generators are flag-driven, so an explicit translation table is the contract between the two.
+- Derive a service name that follows the architecture's naming conventions.
+
+Planning ends before execution begins because running generators from a partially-confirmed plan generates services that don't match the architecture — fixing generated code is harder than correcting a mapping. Once every service is confirmed, write the complete execution plan to `scaffold-cache.md` — every generator command in order with all parameters — and get final approval for the full plan before proceeding. Mark the Service Mapping phase complete in `scaffold-cache.md`.
+
+Count the services in `docs/architecture/index.md`, count the confirmed mappings, and verify they match before closing Phase 1.
+
+**Surfaces:** Read the surface registry — `docs/surfaces.md` and its machine twin `.groundwork/surfaces.json` — when it exists. The registry, not the design system, decides what gets scaffolded and how it gets tested, because the architecture phase already settled each surface's scaffold target and test medium there. Each `active` surface drives two mapping decisions:
+
+- **Scaffold target.** A surface whose `scaffold` field names a generator (`nextjs-app`, `cli-app`, `flutter-app`, `electron-app`) gets its own generator invocation in the execution plan, named by its slug. A `scaffold: forged` surface gets no generator invocation either — `groundwork-stack-forge` builds its seed directly (see the unsupported-stack options below) — but it joins the test fixtures via `--surfaces` like any other surface. A `scaffold: manual` surface gets no generator invocation — the registry never blocks on tooling — but the execution plan still records its three obligations: an entry in `docs/architecture/infrastructure.md`'s Surfaces group (Phase 5), registration in the test fixtures via the `--surfaces` entry below, and an operational-expectations note stating what the manual implementation must meet to keep that registration honest — a health endpoint, `./dev` integration, and a reach value the fixtures can use.
+- **Test medium.** Run `system-test-runner` once, passing every active surface in `--surfaces`: a JSON array of `{"slug", "medium", "reach"?}` where `medium` is the surface's registry `testMedium` and `reach` is a static base URL (`playwright`/`protocol-client` surfaces — omit it to discover the docker-compose service named after the slug) or the launch command for a `subprocess-cli` surface (a generated `cli-app` builds to `node services/<slug>/dist/cli.js`); `flutter-integration` and `playwright-electron` surfaces omit it — their reach is the app's own test-harness command, discovered as `npx nx run <slug>:test-integration` / `npx nx run <slug>:smoke` once `services/<slug>` is scaffolded. The generator emits a session `surfaces` fixture keyed by slug plus one runner fixture per surface — `<slug>_page` (`playwright`), `<slug>_runner` (`subprocess-cli`, and `flutter-integration`/`playwright-electron`, where it drives the app's own integration_test or Playwright `_electron` suite as a subprocess through the app's toolchain guard), `<slug>_client` (`protocol-client`) — and includes `pytest-playwright` whenever a `playwright` surface is present. A medium with no fixture family is registered in the `surfaces` fixture and nothing more; its tests arrive with its tooling.
+
+**When no registry exists**, the project predates it — behave exactly as before: read `docs/design-system.md`, identify the single interface track (`graphical-ui`, `cli`, or `agentic-protocol`), and pass it as `--interfaceMedium`, the deprecated single-surface alias. That flag alone determines whether `pytest-playwright` and the `frontend_base_url` fixture are generated. Browser-driven interface proof is fully supported for `graphical-ui`; for `cli` and `agentic-protocol`, bet-progress tests use `subprocess`/HTTP against the running endpoint (no shared fixture is generated — write those tests against bare `subprocess`/HTTP).
+
+**Capability registry:** Read the capability-ports registry — `.groundwork/capability-ports.json` and its prose twin `docs/architecture/index.md` §3 — when it exists. It records each technical capability → provider → footprint the architecture settled, and it is the authority for *which infrastructure exists and why*: infrastructure is a consequence of a provider's footprint, never a scaffold default. Map each entry to an action:
+
+- A provider with an `env` / `compose-service` / `runner` footprint becomes a generator flag on the service that owns the capability (e.g. `python-microservice --llm --llmProvider anthropic`, `--postgres`) — or, when the service is already scaffolded, an `add-capability --service <slug> --capability <c> --provider <p>` invocation in the plan.
+- A provider of `none` is the **bare interface**: scaffold it with `--provider none` (or `add-capability ... --provider none`) so the service gets the interface, a not-yet-implemented stub, and a strict-xfail contract test — the provider is a bet, recorded in the hand-off as the first delivery's work. Add no infrastructure for a `none` capability.
+
+A capability whose provider the available generators cannot produce is the reversal path below, not a silent substitution. When no registry exists, the project predates it — derive capabilities from the architecture prose as before.
+
+**Generator Capability Mapping:**
+
+| Architectural decision | Generator + flag |
+|---|---|
+| End-user authentication via Clerk | `nextjs-app --auth clerk`, `go-microservice --auth clerk` |
+| Service-to-service authentication | `go-microservice --auth service` |
+| No authentication required | `--auth none` (or omit `--auth`) |
+| Transactional outbox via Kafka | `--messaging kafka` |
+| Transactional outbox via GCP Pub/Sub | `--messaging gcp-pubsub` |
+| Lightweight pub/sub via Redis (Python only) | `python-microservice --messaging redis` |
+| WebSocket real-time delivery | `--websockets` |
+| Frontend → backend API proxy | `nextjs-app --apiProxy` |
+| Command-line application as the product (or a CLI surface for a service) | `cli-app --name <name>` (add `--repl` when the design system specified an interactive/REPL paradigm; add `--core` when the CLI fronts workspace services — e.g. its registry access path is http-direct — to scaffold the core-access seam and the `status` wiring-proof command; omit `--core` for a standalone tool) |
+| Mobile surface (registry `platform: mobile`) | `flutter-app --name <slug>` (never joins docker-compose; the Flutter SDK is a runtime prerequisite, not a generation one) |
+| Desktop surface (registry `platform: desktop`) | `electron-app --name <slug>` (never joins docker-compose; the Electron binary downloads at bootstrap, and the boot smoke needs a display — xvfb on Linux CI) |
+| LLM integration (Python service) | `python-microservice --llm --llmProvider <openai\|anthropic\|local\|none>` (default `openai`; `local` = self-hosted OpenAI-compatible endpoint) |
+| LLM as a bare interface / undecided provider (a bet) | `python-microservice --llm --llmProvider none` (interface + stub + strict-xfail contract test; no SDK, no infra) |
+| Add a capability to an already-scaffolded service | `add-capability --service <slug> --capability <c> --provider <p>` (Day-2 / inside a bet; `--provider none` for a bare interface) |
+| GPU inference on RunPod (Python service) | `python-microservice --runpod` |
+| PostgreSQL on a Python service | `python-microservice --postgres` |
+| REST surface on a Python service | `python-microservice --rest` |
+| Docker Compose test topology (surface registry present) | `system-test-runner --surfaces '<JSON array of {slug, medium, reach?} from .groundwork/surfaces.json>'` |
+| Docker Compose test topology (no registry — single interface type) | `system-test-runner --interfaceMedium <graphical-ui\|cli\|agentic-protocol>` |
+| Fumadocs documentation site | `docs-site --name <slug>` |
+
+This table is the one place to update when generator flags evolve. When a new flag ships, add a row here; when a flag is removed, delete the row. The mapping is the contract between architecture's vocabulary and scaffold's execution — keep it current.
+
+**When the generators cannot honour an architecture decision.** This is common and expected: the architecture may have chosen a vendor, language, or topology the available generators do not produce (e.g. a TypeScript backend when only Go/Python exist, a native macOS AppKit app, Supabase auth when only Clerk is wired). Surface the genuine trade-off to the user as a single decision (Protocol 4) with three honest options:
+
+1. **Reverse onto a supported stack.** Adopt the generator's path. This almost always *reverses* an architecture Key Decision or supersedes an ADR — a **reversal** under Protocol 2, not a refinement. At commit (Phase 6) follow the Reversal Protocol in full: reconcile the architecture *body* (not just its summary), reconcile every dependent doc the reversal touches — the domain entity docs (`Owner:`, fields), service docs, infrastructure — write the superseding ADR, and re-invoke `groundwork-review` on each mutated doc. The committed architecture must describe the system you actually scaffolded, with no residue of the abandoned one.
+2. **Forge it.** Keep the chosen stack and build a first-class starting point for it: **load and run `.groundwork/skills/groundwork-stack-forge/instructions.md`.** It researches the stack, authors a self-contained engineer skill, builds a Day-2 seed wired into `./dev`, and writes a Day-2 checklist into the hand-off for MVP. This is the path that keeps GroundWork worth using off the paved road — reach for it when the stack choice is deliberate and the team will keep building in it. The forged seed becomes the service/surface in this mapping; record it in the execution plan like any other unit.
+3. **Hand-roll manually.** Record the surface as `scaffold: manual` with its operational obligations (a health signal, `./dev` integration, a test reach), and leave the implementation to the team with no scaffolding support. Choose this only when the component is throwaway or the team explicitly wants no help — otherwise option 2 serves them better.
+
+Take the user's call; never silently substitute a default the architecture did not choose.
+
+**LLM provider: scaffold the boilerplate, hand the integration to the bet.** When the architecture names an LLM provider, map it to `--llmProvider` (`openai`, `anthropic`, or `local` for a self-hosted OpenAI-compatible endpoint) so the generated LLM client targets the right SDK and a sensible default model from the start. When the provider is genuinely undecided or deferred, use `--llmProvider none`: the **bare interface** — the text-generation interface, a not-yet-implemented stub, and a strict-xfail contract test, with no SDK and no infrastructure. `none` is the honest scaffold of "hand the integration to the bet": the interface is the spec, the provider is the bet, and the xfail test flips red the moment it is implemented. Reach for it instead of picking a provider the product has not committed to. But be precise about what the generator delivers and what it does not. The `--llm` flag produces a *generic LLM client*: a single `generate_text` call behind the text-generation interface, with retries and a circuit breaker. It does **not** implement the provider-specific behaviour an architecture usually depends on — prompt caching a large shared context, streaming responses, structured outputs, a moderation/safety gate, or tool use. Those are **bet/MVP development work**, not scaffold output. Record them in the scaffold hand-off as work the first bet must build, and say so plainly when presenting the scaffold. Never describe the generated client as "provider-agnostic" or imply it already satisfies an architectural capability it only stubs — an honest "the LLM client is scaffolded; prompt caching and streaming are bet work" is worth more than a green checkmark that papers over the gap. If the architecture's provider is a real vendor the flag does not offer, that is the reversal path above, not a silent substitution to whatever the generator defaults to.
+
+**Generator availability:**
+
+| Generator | What it produces | Key parameters |
+|---|---|---|
+| `go-microservice` | Go API with PostgreSQL, optional auth and messaging | `--name`, `--auth` (none/service/clerk), `--messaging` (none/kafka/gcp-pubsub), `--websockets` |
+| `python-microservice` | Python FastAPI service, optional PostgreSQL and messaging | `--name`, `--rest`, `--postgres`, `--messaging` (none/redis/kafka/gcp-pubsub), `--websockets`, `--llm`, `--llmProvider` (openai/anthropic/local/none, default openai), `--runpod`, `--native` |
+| `nextjs-app` | Next.js frontend with App Router | `--name`, `--auth` (none/clerk), `--apiProxy`, `--websockets` |
+| `cli-app` | Branded Node+TypeScript command-line application, themed from `brand-tokens.json`; standalone by default, or a frontend for workspace services with `--core` | `--name`, `--repl` (scaffold the interactive REPL layer), `--core` (wire the workspace core-access seam + `status` wiring proof; `API_BASE_URL` overrides the gateway URL) |
+| `flutter-app` | Flutter mobile app (official MVVM architecture, Riverpod, go_router), themed from `brand-tokens.json`; pubspec-based — wires into Nx via run-commands targets, never joins docker-compose | `--name`, `--org` (reverse-domain bundle id prefix, default `com.example`) |
+| `electron-app` | Electron desktop app (hardened main/preload/renderer split, typed IPC, React + Tailwind renderer), themed from `brand-tokens.json`; wires into Nx via run-commands targets, never joins docker-compose | `--name`, `--org` (reverse-domain app id prefix, default `com.example`) |
+| `system-test-runner` | Docker Compose test topology and system test suite | `--surfaces` (JSON array of `{slug, medium, reach?}` from the surface registry), `--interfaceMedium` (deprecated single-surface alias: graphical-ui/cli/agentic-protocol, default: graphical-ui) |
+| `docs-site` | Fumadocs documentation site that serves the live `docs/` tree (product brief, architecture, bets) with H1-derived titles; registers as a native `./dev` runner (`pnpm dev`, not autostarted), never joins docker-compose | `--name` |
+| `add-capability` | Adds a capability interface + provider implementation (or a bare `none` interface) to an existing service | `--service`, `--capability` (default `llm`), `--provider` (capability default, or `none`), `--stack` (auto-detected) |
+
+`workspace-dev-cli` is handled in initialization and does not appear in service mapping.
+
+**Offer a documentation site (optional, default off).** Independent of the architecture's services, offer the user a browsable site for the project's own `docs/` — product brief, architecture, and the bets as they land. Present it once as a single optional decision (Protocol 4), **default to skipping it**, and frame it plainly: "a local site to browse your docs and bets; not part of the running product." If they accept, add `docs-site --name docs` to the execution plan — it registers as a native `./dev` runner and shows up in `infrastructure.md`'s footprint matrix like any other managed unit (Phase 5). If they decline, add nothing and say nothing further. The docs site is a developer affordance, never inferred from the architecture and never a service the architecture must justify.

package/src/hidden-skills/groundwork-scaffold/phases/02-scaffolding-execution.md

@@ -0,0 +1,15 @@
+# Phase 2: Scaffolding Execution
+
+**If command execution tools are available:** Execute the confirmed generator commands in order. For each command:
+1. Run `npx --yes nx g "$(pwd)/.groundwork/config/generators.json:<generator-name>" <parameters>`. The absolute `$(pwd)` prefix is required because Nx calls `require.resolve` on the collection argument — a relative path resolves against Nx's own `node_modules`, not the workspace root.
+2. Verify the expected output files exist (e.g., `services/<name>/go.mod` for a Go service, `services/<name>/package.json` for a Next.js app).
+
+After all generators have run, verify that `docker-compose.yml` includes entries for every scaffolded service.
+
+Then reconcile against `.groundwork/capability-ports.json`: every capability with a `compose-service` footprint must have its service in `docker-compose.yml`, every `runner` footprint an entry in `.dev/dev.config.json` `runners[]`, and every `none` capability its stub plus a strict-xfail contract test in the service. A declared footprint with no materialization is a mapping or generation error — fix it before advancing, since the generators inject infrastructure only on demand and a missing provider leaves the capability silently unsatisfied.
+
+Go and Python generators automatically install the corresponding `groundwork-go-engineer` or `groundwork-python-engineer` skill into `.agents/skills/`. The Next.js generator installs `groundwork-nextjs-engineer`. Verify each skill file exists after its generator runs — the generator promotes it directly from the framework package, so if any are missing, re-run that service's generator.
+
+Mark the Scaffolding Execution phase complete in `scaffold-cache.md` and proceed to Phase 3.
+
+**If command execution tools are unavailable:** The execution plan is already in `scaffold-cache.md`. Present the full runbook to the user as a single handoff — all commands in order, with the expected output for each. Do not ask them to run one command and report back. Accept their confirmation and mark the Scaffolding Execution phase complete. Note that infrastructure verification (Phase 4) must be done manually.

package/src/hidden-skills/groundwork-scaffold/phases/03-service-documentation-api-stubs.md

@@ -0,0 +1,100 @@
+# Phase 3: Service Documentation & API Stubs
+
+For each scaffolded service, create two files: a service document and an API stub. These give every developer a consistent entry point into each service from day one — before any product code exists.
+
+Create `docs/architecture/services/` and `docs/architecture/api/` if they do not exist.
+
+## Service Document
+
+Write `docs/architecture/services/<service-name>.md` for each service:
+
+```markdown
+# <service-name>
+
+**Generator:** <generator-name>
+**Language:** Go | TypeScript | Python
+**Port:** <port>
+**Base path:** `services/<service-name>/`
+
+## Overview
+
+<One paragraph: what this service does and its role in the system. Derive from the architecture document.>
+
+## Dependencies
+
+| Dependency | Type | Notes |
+|---|---|---|
+| PostgreSQL | Database | `<service-name>` database — DB-backed services only; a stateless frontend owns no database |
+| `<other-service>` | Service | Called via HTTP — URL at `<OTHER_SERVICE_URL>` env var |
+| `<external-provider>` | External | e.g. Clerk, GCP Pub/Sub |
+
+## API
+
+[`docs/architecture/api/<service-name>.md`](../api/<service-name>.md)
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `PORT` | Yes | Service port (default: <port>) |
+| `<database connection vars>` | Yes | Database connection — language-specific names, DB-backed services only (see population rules) |
+
+See `services/<service-name>/.env.example` for the full list.
+
+## Running Locally
+
+```bash
+./dev start <service-name>
+```
+
+## Testing
+
+```bash
+<unit test command for this language>
+```
+```
+
+**Population rules:**
+
+- Derive the port from `docker-compose.yml` or the architecture document after generation. Do not guess.
+- List every inter-service dependency by name with the env var the calling service uses to reach it. If service A calls service B, service A's doc names service B and the env var (e.g. `AUTH_SERVICE_URL`).
+- List every external dependency — databases, auth providers, message brokers. Derive from the generator flags and the architecture document.
+- A stateless frontend owns no database. The `nextjs-app` generator scaffolds no datastore, so its service doc omits the PostgreSQL dependency row and every database environment variable. Only a service scaffolded with a database — a Go microservice, or a Python microservice with `--postgres` — names a database. Naming a database for a frontend describes infrastructure that does not exist.
+- The database connection is exposed through language-specific environment variables, so populate the variables the generated service actually reads. A Go service reads a single `DATABASE_URL` connection string. A Python service reads discrete variables — `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` — and composes the connection internally. The generated `.env.example` is the ground truth; do not assume `DATABASE_URL` for a service that reads discrete variables.
+- Read the generated `.env.example` for each service to populate the environment variables table. If `.env.example` does not exist, list only variables derivable from the generator flags.
+- Derive the unit test command from the language: `go test ./...` for Go, `uv run pytest` for Python, `pnpm test` for Next.js.
+- Do not invent variables, routes, or descriptions. If a value cannot be derived from existing files or the architecture document, leave its cell blank rather than fabricating a placeholder.
+
+**Drift frontmatter.** Open each `docs/architecture/services/<name>.md` and `docs/architecture/api/<name>.md` with YAML frontmatter so `groundwork-check` can detect drift automatically: `generation_mode: generated`, `source_of_truth:` (the canonical code paths for this service — its `services/<name>/` root and any contract files), and `last_reviewed:` (today's date). The `generated` mode routes `groundwork-check`'s recovery to re-running the generator; the brownfield extract phases use `extracted` instead. Both stamp the same three keys, so the check glob reads greenfield and brownfield docs identically.
+
+## API Stub
+
+Write `docs/architecture/api/<service-name>.md` for each service that exposes HTTP endpoints — Go microservices and Python microservices with `--rest`. Skip frontend apps and the system-test-runner.
+
+```markdown
+# <service-name> API
+
+**Base URL:** `http://localhost:<port>`
+**Auth:** <Bearer JWT | Service token (`X-Service-Token` header) | None>
+
+## Health
+
+### GET /health
+
+**Response:** `200 OK`
+```json
+{"status": "ok"}
+```
+
+## Endpoints
+
+<!-- Routes are defined in `services/<service-name>/`. Populate this section as endpoints are implemented. -->
+```
+
+**Population rules:**
+
+- Derive auth from the generator flags: `--auth clerk` → Bearer JWT, `--auth service` → service token header, `--auth none` → no auth.
+- **If the architecture document already specifies this service's contract — an explicit endpoint, an event stream, a request/response or SSE event schema (e.g. a streaming generation endpoint with named events) — transcribe that contract into the Endpoints section.** This is not inventing routes; it is carrying forward a commitment the architecture already made, so the system's key interface has a documented home from day one. Mark each as `status: planned`.
+- Only when the architecture specifies *no* contract for the service, leave the Endpoints section as a placeholder comment for the team to populate as routes are built. Never fabricate routes the architecture did not commit.
+
+Mark the Service Documentation phase complete in `scaffold-cache.md` and proceed to Phase 4.

package/src/hidden-skills/groundwork-scaffold/phases/04-infrastructure-verification.md

@@ -0,0 +1,17 @@
+# Phase 4: Infrastructure Verification
+
+Boot the infrastructure and prove it works. The infrastructure document must describe a system that runs, not a system that should run in theory — a document based on an unverified scaffold has no value to the team that inherits it.
+
+1. **Boot** — start the full local stack: `./dev start`.
+2. **Migrate** — run database migrations for every service that includes PostgreSQL. Check the generated service for the migration command (typically `./dev migrate` or a service-level script).
+3. **Test** — run the system integration tests pre-baked into the scaffolds. These tests verify cluster health, service connectivity, database availability, and cross-service communication.
+4. **Self-heal** — if a service fails to start or a test fails, debug and repair it. Read logs, inspect generated configuration, fix port collisions, adjust environment variables, and iterate until everything is green. A failure here indicates a defect in the GroundWork generators — resolve it so the team does not encounter it.
+5. **Reconcile capability footprints** — for every capability in `.groundwork/capability-ports.json`, confirm its footprint is real, not just declared: a `compose-service` provider has a running container; a `runner` provider appears in `./dev status` (probe `./dev status --json` and check its `runners` array); an `env` provider has its variables present in the service's config / `.env.example`; a `none` bare interface has its strict-xfail contract test in the service's suite (the bet is visible, not forgotten). The managed set `./dev` reports must equal the architecture's surfaces + services + runners — a mismatch is a gap between what the architecture declared and what the scaffold built, and is resolved here, not papered over in the doc.
+
+6. **Seed the code map** — run `npx groundwork-method repo-map` to build the initial `.groundwork/cache/repo-map.json` from the scaffolded source (tree-sitter import edges + PageRank centrality). The project is born with a current code map rather than waiting for the first agent to build one, and it is the concrete evidence Phase 5 cites for maturity dimension D5.
+
+Do not advance to Phase 5 until the entire system boots cleanly, all tests pass, every capability footprint reconciles, and the code map is seeded.
+
+Mark the Infrastructure Verification phase complete in `scaffold-cache.md`.
+
+**If execution tools are unavailable:** Skip this phase and record in `scaffold-cache.md` that verification and the code-map seed are pending. The infrastructure document in Phase 5 must flag this explicitly — it cannot present ports and commands as verified facts if the system has not been booted, and the D5 assessment must show the map as not-yet-built rather than assumed present.

package/src/hidden-skills/groundwork-scaffold/phases/05-draft-review.md

@@ -0,0 +1,19 @@
+# Phase 5: Draft & Review
+
+Once the system is verified (or verification is documented as pending):
+
+1. **Draft.** Write `docs/architecture/infrastructure.md` following the quality standard in the entry `instructions.md`. Apply the `groundwork-writer` skill: declarative, active voice, no hedging. Record the actual ports, commands, and verification results — not what they should be in theory. Include the **What `./dev start` does** section: one row per managed unit (container, native app-service, or registered runner) with its run mode and boot command, derived from the final `docker-compose.yml` + `.dev/dev.config.json`. The set must match `./dev status --json` (its `docker`/`native`/`runners` arrays) — if you cannot make the doc and the CLI agree, the gap is a reconciliation failure to fix in Phase 4, not to describe around.
+
+   When `scaffold-cache.md` records verification as pending (Phase 4 was skipped), open the document body with a `## Verification Status` section stating that the system was not booted and that the ports, commands, and health checks below are derived from generated configuration, not observed from a running system, so the reader must run the Phase 4 verification steps before relying on them. Two to three sentences is enough — the point is that no reader can mistake an unverified scaffold for a verified one. Omit the section entirely when verification ran green; the `## Verification` results section covers that case.
+
+1b. **Draft `docs/maturity.md`.** Read the maturity model at `.groundwork/skills/maturity-model.md` and write the initial assessment from the template at `.groundwork/skills/templates/maturity.md`. A freshly scaffolded project scores ✅ on most dimensions — cite the evidence this phase just produced (booted stack, generated harness, registered Serena, a code map regenerable via `npx groundwork-method repo-map`). Open roadmap rows for what scaffolding cannot wire: D6 (CI does not yet invoke `groundwork check`) and any dimension verification left pending. Seed `## History` with one line. This doc is how the project tracks regressions against the target state it was born at.
+
+2. **Review.** Announce that the review process is starting, then invoke the review subagent (Protocol 9) once per document: `document_path: docs/architecture/infrastructure.md` with `document_type: infrastructure`, and `document_path: docs/maturity.md` with `document_type: maturity`. Report the verdict and any findings before proceeding. The gate is fail-closed (Protocol 8): proceed only on a parseable `VERDICT: PRESENT` for each; a review that errors, hangs, or returns no verdict follows Protocol 9's failure path.
+
+3. **Revise loop.** If the verdict is **REVISE**, apply all 🔴 Critical findings directly to the document. Re-run the review. Repeat until the verdict is **PRESENT**. After 3 REVISE verdicts, apply the revise cap defined in Protocol 8.
+
+4. **Author the getting-started on-ramp.** With `infrastructure.md` settled, write the three `docs/getting-started/` files — `index.md`, `setup.md`, and `dev-cli-reference.md` — to the standard in the entry `instructions.md` ("The developer on-ramp"). Apply `groundwork-writer`. Pull `setup.md`'s prerequisites, install commands, and env requirements from what Phase 4 actually did and from `infrastructure.md`; build `dev-cli-reference.md` by reading `./dev help` output, not from memory. These are the docs the docs-site landing page routes a fresh-clone developer to, so they must stand on their own. There is no separate review document type for them — the present-and-approve step below is their gate. Seed the section's sidebar order if absent: write `docs/getting-started/meta.json` as `{ "pages": ["index", "setup", "dev-cli-reference", "..."] }`.
+
+5. **Present.** Output `infrastructure.md` in full in the chat and summarise the getting-started set (the three files and what each covers). Surface any 🟡 Advisory findings so the user can decide whether to act on them.
+
+6. Ask the user whether to save as-is or refine anything first. Proceed to Phase 6 only on explicit approval.

package/src/hidden-skills/groundwork-scaffold/phases/06-commit.md

@@ -0,0 +1,19 @@
+# Phase 6: Commit
+
+Execute only after explicit user approval from Phase 5. Follow Protocol 3.4 of the Operating Contract.
+
+1. **Write the Downstream Context file (Protocol 5).** The published docs (`docs/architecture/infrastructure.md`, the `docs/getting-started/` set, `docs/maturity.md`) carry no summary section — they are clean reference documentation. Apply `groundwork-writer` to write `.groundwork/context/scaffold.md` — the four-subsection contract per Protocol 5: Key Decisions (the ports, the boot command, the test command, the database schema model), Binding Constraints (anything MVP Planning must respect: env var requirements, manual verification gaps), Deferred Questions, Out of Scope. Add a one-line `llms.txt` entry for each newly created doc — the `docs/getting-started/` files and `docs/maturity.md` included.
+
+2. **Write the hand-off file.** Copy `.groundwork/skills/templates/handoff.md` to `.groundwork/cache/handoff/scaffold.md` and fill in only the sections that have content: rejected generator parameters or service-name choices, deferred verification steps if execution tools were unavailable, user instincts about future infrastructure (CI/CD, observability) not yet scaffolded, and any other context MVP Planning needs to understand the running system. Omit empty sections. **If a stack was forged this phase** (the scaffold cache carries a `## Forged Stack Checklist` from `groundwork-stack-forge`), copy that checklist into the hand-off so MVP scopes the to-be-built Day-2 items into the first bets — it is the seed's path from skeleton to a full Day-2 app.
+
+3. **Clean up caches.** Remove the scaffold cache and the consumed previous hand-off: `run_command("rm -f .groundwork/cache/scaffold-cache.md .groundwork/cache/handoff/architecture.md")`. Cache Isolation (Protocol 7) requires the previous hand-off to be deleted once consumed.
+
+4. Apply the Living Documents protocol — scan the conversation for insights that refine any existing `docs/` artifact. Apply surgical updates and refresh the affected Downstream Context files in `.groundwork/context/` (Protocol 5). Report what changed. **Scaffold-time vendor/language/topology changes are reversals** (Protocol 2): reconcile the architecture body and every dependent doc — domain entities, service docs, infrastructure — write the superseding ADR, and re-invoke `groundwork-review` on each mutated doc before committing. Because this reversal supersedes ADRs, re-review **every** `docs/architecture/domain/*.md` (`document_type: domain-entity`), not only the ones you remembered to edit — these stubs carry no summary and are the dependents most often left stale. Do not leave the architecture body or domain docs describing the design you replaced.
+
+5. Update discovery notes — scan for out-of-phase signals not captured in real time. Append new signals to `.groundwork/cache/discovery-notes.md`. Remove entries incorporated into the committed artifact or the hand-off file.
+
+6. Confirm that the phase is complete.
+
+7. Recommend a fresh context for the next phase — a clean context gives the next skill full working memory.
+
+8. Immediately load and execute the `groundwork-orchestrator` skill to proceed to MVP Planning. Do not ask the user to invoke it.

package/src/hidden-skills/groundwork-scaffold/templates/scaffold-cache.md

@@ -0,0 +1,23 @@
+# Scaffold Cache
+
+> This file tracks phase progress for the scaffold workflow and stores the confirmed execution plan. It is used to resume work and to drive Phase 2 execution. Do not edit manually.
+
+## CLI Initialization
+status: pending
+notes:
+
+## Service Mapping
+status: pending
+notes:
+
+## Scaffolding Execution
+status: pending
+notes:
+
+## Service Documentation
+status: pending
+notes:
+
+## Infrastructure Verification
+status: pending
+notes:

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

@@ -0,0 +1,164 @@
+---
+name: groundwork-scan
+description: >
+  Reads an existing codebase as Phase 0 of the brownfield track — classify the
+  repo, build a deterministic structural map, scan partition by partition — and
+  writes a scan baseline to `.groundwork/cache/` that the extract phases distil
+  into canonical docs. Produces structured findings, no `docs/` artifact.
+---
+
+# groundwork-scan
+
+You are a staff engineer dropped into an unfamiliar codebase with one job: understand it well enough that the phases after you can rebuild GroundWork's canonical documents from what already exists. You read the code so the extract phases do not have to read it again.
+
+This is Phase 0 of the brownfield track. The repository already holds working software. You produce no `docs/` artifact — you produce a **scan baseline** in `.groundwork/cache/` that the product-brief, design-system, and architecture extract phases distil into canonical docs. Your output is structured findings, not prose for a human.
+
+The discipline that makes this work is **read structure deterministically, interpret meaning selectively**. A parser reads every file; you read the files that carry meaning. You never load the whole repository into working context — you build an exact structural map first, then go deep only where it matters, writing findings to disk and discarding the detail as you go.
+
+---
+
+## How This Works
+
+The scan moves through five stages: classify the repo, build a deterministic structural map, confirm scope with the user, scan partition by partition, then finalise and hand off. Each stage narrows what the next must read.
+
+- **Classification before reading.** Knowing the repo shape and per-part technology tells you which files carry contracts and which are noise, before you open a single source file.
+- **The structural map does the heavy lifting.** An exact dependency and symbol graph tells you where the architectural hubs are, so you read those deeply and skim the leaves — instead of reading everything at uniform depth and exhausting context.
+- **Write and purge.** Findings go to disk the moment a partition is scanned, and only a one-line summary stays in working context. This is what lets the scan cover a large repository without overflowing — and what lets it resume after an interruption.
+
+Your single point of contact with the user is a short scope-confirmation in Stage 2. Everything else is autonomous.
+
+---
+
+## Operating Contract
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) governs how this skill operates. Read it before taking any other action. The scan is a Sequential Setup *preparation* phase with three deliberate carve-outs defined in the contract's **Brownfield Scan** section: it writes no `docs/` artifact (so no Downstream Context file and no hand-off file), it runs no review gate, and its findings persist past its own completion rather than being deleted at commit. Protocols 1 (Discovery Notes) and 4 (Pacing) still apply.
+
+---
+
+## The `fan_out` Hint
+
+The orchestrator passes a `fan_out` hint when it invokes this skill: `parallel` when a sub-agent dispatch tool is available in this environment, `sequential` otherwise. Honour it. Stage 3 branches on this value rather than probing your own tool set — a runtime that misjudges its capabilities and calls a dispatch tool that does not exist breaks the scan. If no hint reached you, default to `sequential`; it is correct everywhere, and the only cost is wall-clock time.
+
+---
+
+## Initialization & Resume Protocol
+
+### Step 1: Scan State Check
+
+Check if `.groundwork/cache/scan-state.json` exists.
+
+- If it **does not exist**, copy the template from `.groundwork/skills/groundwork-scan/templates/scan-state.json` to `.groundwork/cache/scan-state.json`.
+- If it **does exist**, read it. If any partitions have a status of `complete`, summarise the coverage so far — the classification and which partitions are scanned — and ask whether the user wants to resume or start fresh. On resume, skip directly to the first partition still `pending` in Stage 3. On a fresh start, reset the scan state and findings from the templates.
+
+### Step 2: Cache Isolation Check
+
+Verify the scan caches are clean (Protocol 7). A stale `scan/` findings directory or an orphaned `scan-state.json` from a previous run that did not complete must be confirmed with the user before reuse. If foreign state is found, ask the user to confirm a clean restart.
+
+---
+
+## Stage 0: Self-Orient (silent)
+
+Before classifying, establish what is already known. Read `.groundwork/cache/discovery-notes.md` if it exists — a user who began elsewhere may have left signals. This is the only context you carry in; the rest you derive from the code.
+
+---
+
+## Stage 1: Classify
+
+Determine the repository's shape and the technology of each part **without reading source files**. Read only the signals that reveal structure cheaply: the directory tree (depth-limited), package manifests (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, and the like), lockfiles (to confirm a stack, not to read), `docker-compose*`, IaC roots, and the top-level `README`.
+
+Establish:
+
+- **Repo shape** — a single service, a multi-part repo (a client and a server), or a monorepo of many packages and services.
+- **Per-part project type** — language and framework for each part, matched from its key files (a `package.json` with `next.config.*` is a Next.js app; a `go.mod` with a `cmd/` directory is a Go service).
+
+Write the classification into `scan-state.json`. The exclusion globs and the contract-bearing file priorities you will apply are defined in `.groundwork/skills/groundwork-scan/references/exclusions.md` — load it now; it governs every read that follows.
+
+---
+
+## Stage 1.5: Structural Map (deterministic)
+
+Build an exact map of the codebase — module boundaries, import and call edges, the symbols each file exports, and where the contract files live — so the scan in Stage 3 reads the architectural hubs deeply and skims the leaves. A function called by twenty others is more valuable context than a private helper called once, and only a real dependency graph tells you which is which.
+
+**Preferred path — the deterministic generator.** Run `npx groundwork-method repo-map`. It parses the tracked source tree with tree-sitter, resolves import edges, ranks files by PageRank centrality, and writes `.groundwork/cache/repo-map.json` — module/partition boundaries, the import edges, a centrality ranking, the contract index, and a per-file symbol index. It maps Go, Python, TypeScript/JavaScript, Java, and Dart at full graph fidelity (real edges + centrality) and many more languages at symbols fidelity; check the `coverage` and `unmapped` fields to see what it captured (and what it did not). It runs without a network or an LSP, and is incremental: a parse cache keyed by content hash means every rerun reparses only changed files. This is the producer — deterministic, and free of the hallucinated edges an LLM invents.
+
+**Live navigation — Serena (when registered).** Serena complements the map rather than producing it: the generator gives you the whole-repo aggregate Serena cannot export, and Serena answers the precise per-symbol questions the map does not. Use `get_symbols_overview` and `find_referencing_symbols` while reading the centrality hubs deeply in Stage 3. Find it with a tool search for the code-intelligence or symbol capability before assuming it is absent.
+
+**Fallback path — LLM inference.** When the generator cannot run, or for a language it does not cover and the project has not enabled (the `unmapped` list names these — a language can be added in-repo via `.groundwork/config/repo-map.languages.js`, see `code-intelligence.md`), infer the missing structure from targeted reads — entry points, manifests, and import statements — and write those parts of `repo-map.json` in the **same shape**. The downstream contract is identical; only the means of producing it differs. Do not let the fallback change what the file holds.
+
+`repo-map.json` is a first-class GroundWork artifact (schema: `.groundwork/skills/repo-map-schema.md`): the architecture extract phase reads it for exact dependency facts, and `groundwork-check` reuses it for impact analysis. Treat its shape as a contract, not an internal scratch file. It carries `generated_at_commit`, so `groundwork-check` and `npx groundwork-method repo-map --check` can tell when it has drifted from HEAD and a refresh is owed.
+
+---
+
+## Stage 2: Confirm Scope (the one interview point)
+
+The scan is otherwise autonomous. Confirm exactly two things with the user, paced per Protocol 4 — keep this tight, you are confirming inferences, not interrogating:
+
+1. **Partition boundaries.** Present the parts you detected and how you intend to partition the scan. The rule is one partition per service or package; a single-service repo partitions per top-level source area instead, and an oversized partition is sub-partitioned in Stage 3. Let the user correct a boundary you read wrong; they know the repo.
+2. **Scan depth.** Offer the three depths and recommend one based on repo size and the user's intent:
+   - **Quick** — manifests, configs, the README, and contract/route files only; no deep source reading. Right for a first orientation or a very large repo.
+   - **Deep** — quick plus every file in the critical directories the project type designates. The default for most repos.
+   - **Exhaustive** — every code file except the exclusions. Right when the extract phases must miss nothing.
+
+Record the confirmed partitions and depth in `scan-state.json`. If the user volunteers product, design, or architecture opinions here, capture them under the matching header in `.groundwork/cache/discovery-notes.md` (Protocol 1) and steer back — they belong to the extract phases, not the scan.
+
+---
+
+## Stage 3: Partition & Scan
+
+Each partition yields one **digest** — a structured, capped summary defined in `.groundwork/skills/groundwork-scan/references/digest-schema.md`. Load that schema now; both execution paths produce it identically, and that identity is what lets the evaluation-tested sequential path certify the output contract for the parallel path it cannot exercise. A digest is never raw file contents — it is the interpreted result of reading them.
+
+Branch on the `fan_out` hint.
+
+### Stage 3a: Parallel Fan-Out (`fan_out: parallel`)
+
+Dispatch one scan sub-agent per partition, guided by the structural map so each agent knows its partition's hubs.
+
+- **Bound the fan-out at 8 concurrent sub-agents.** With more partitions than that, run in waves. With a single partition far larger than the rest (a file count or size well beyond its siblings), sub-partition it by sub-directory, or under Quick/Deep depth priority-sample it rather than reading every file. Sampling always includes the contract-bearing files (specs, migrations, config) and the high-centrality modules — rank by `repo-map.json`'s centrality when present; the budget falls on the leaves, never on the contracts. A concurrency cap alone does not bound one oversized partition; handle it explicitly.
+- Give each sub-agent its partition root, the exclusion globs, the scan depth, the partition's hub symbols from the structural map, and the digest schema — with the instruction to return the structured digest only, never file contents.
+- **Assemble without reading files yourself.** As each digest returns, route its fields into the concern-split findings files (below) with `append_file`, update the partition's status and one-line summary in `scan-state.json`, and move on. You never open a source file in the parent context — the sub-agents read; you assemble. This is what keeps the parent lean at full fan-out.
+
+### Stage 3b: Sequential Batch (`fan_out: sequential`)
+
+Scan one partition per batch, resumable across turns. The atomic unit is one partition, so crossing a turn boundary mid-scan is always safe — the next turn reads `scan-state.json` and continues from the first `pending` partition.
+
+For each pending partition:
+
+1. List its files and select what to read per the scan depth and the exclusion/priority rules.
+2. Read the selected files.
+3. Extract the digest (the same schema as 3a).
+4. **Immediately** append the digest's fields to the concern-split findings files.
+5. Update the partition's status to `complete` and write its one-line summary in `scan-state.json`.
+6. **Purge** the detail from working context — keep only the one-line summary.
+7. Move to the next partition.
+
+An oversized single partition is sub-partitioned or priority-sampled exactly as in 3a, so no batch is unbounded.
+
+### Findings Layout (both paths)
+
+Route every digest's fields into these files under `.groundwork/cache/scan/`, each consumed by exactly one downstream phase (Protocol 7). Create them from the templates in `.groundwork/skills/groundwork-scan/templates/` on first write.
+
+| File | Holds | Consumer |
+|---|---|---|
+| `scan/overview.md` | Repo shape, per-part project type, partition map, scan depth, coverage and gaps | all three extracts (shared) |
+| `scan/product-findings.md` | README value proposition, user-facing capabilities, product surface, inferred users, licensing/monetisation signals | `groundwork-product-brief-extract` |
+| `scan/design-findings.md` | Interface surfaces (every one the repo carries, typed), design tokens, component library inventory, theme/Tailwind config, UI framework, interaction and accessibility signals | `groundwork-design-system-extract` |
+| `scan/architecture-findings.md` | Service/partition map with each partition's surface type, entry points, external contracts (OpenAPI/AsyncAPI/proto/routes), data models and migrations, persistence, internal and external dependencies, infra/deployment (compose, IaC, CI, env examples), notable patterns, risks and TODOs | `groundwork-architecture-extract` |
+
+The digest schema's field-to-file routing is defined alongside the schema in `references/digest-schema.md` — follow it exactly so each extract finds what it expects under its own header.
+
+---
+
+## Stage 4: Finalise
+
+Both paths converge here. Verify every partition in `scan-state.json` is `complete`. Write `scan/overview.md`: the repo shape, the partition map, and — this matters — an honest **coverage and gaps** note recording what was read fully versus sampled at the chosen depth. A downstream phase that knows a directory was only sampled can ask the user about it; one that assumes full coverage cannot. Silent truncation reads as completeness it did not earn. Set `status: complete` in `scan-state.json`.
+
+Do not delete the findings. They are the durable hand-off the extract phases consume; `groundwork-infra-adopt` deletes the shared scan cache at the end of setup.
+
+---
+
+## Stage 5: Present & Hand Off
+
+1. Present a short summary to the user: the repo shape, the partitions scanned, what each findings slice captured, and any coverage gaps. This is orientation, not a document — keep it brief.
+2. **Record completion.** Add `"scan"` to the `completed` array in `.groundwork/config/state.json` — this is the durable marker the orchestrator reads, since the scan leaves no `docs/` artifact to reconcile against. Then write `.groundwork/cache/scan/complete.md` containing a one-line completion note; this terminal marker is the signal that the scan finished — written only here, at the true end.
+3. Capture any out-of-phase signals from the conversation into `.groundwork/cache/discovery-notes.md` (Protocol 1).
+4. Immediately load and execute the `groundwork-orchestrator` skill to route to the first extract phase. Do not ask the user to invoke it — hand off automatically.

package/src/hidden-skills/groundwork-scan/references/digest-schema.md

@@ -0,0 +1,66 @@
+# Partition Digest Schema
+
+Every partition — whether scanned by a sub-agent (parallel) or in a sequential batch — yields exactly one digest in this shape. The schema is identical across both execution paths on purpose: a consumer reading a digest cannot tell, and must not need to tell, which path produced it. That identical output contract is what lets the cheaper sequential path stand in for the parallel one wherever sub-agent fan-out is unavailable.
+
+**Every field is bounded.** Lists cap at ~12 items, each ≤20 words; strings cap at ~3 sentences. This bound is the lever that keeps the parent context lean at full fan-out and keeps each sequential batch's footprint small. A digest is the *interpreted* result of reading files — never raw file contents, never a file dump.
+
+```json
+{
+  "partition_id": "api",
+  "root_path": "services/api",
+  "project_type": "go-service | nextjs-app | python-service | cli | library | ...",
+  "purpose": "≤3 sentences: what this partition does and why it exists",
+  "entry_points": ["cmd/server/main.go"],
+  "exported_surface": ["public packages, exported modules, or HTTP routes"],
+  "external_contracts": [
+    {"kind": "openapi | asyncapi | protobuf | graphql | route-file | none", "path": "api/openapi.yaml"}
+  ],
+  "data_models": [{"name": "User", "source": "schema.prisma | migrations/0003.sql | models.py"}],
+  "persistence": ["postgres via migrations/", "redis"],
+  "infra_deployment": ["docker-compose.yml", "terraform/", ".github/workflows/ci.yml", ".env.example"],
+  "dependencies": {"internal": ["services/auth"], "external": ["stripe-go", "nats.go"]},
+  "communication": ["sync HTTP -> auth", "async publish order.created -> nats"],
+  "notable_patterns": ["hexagonal layering", "transactional outbox"],
+  "design_tokens": ["tailwind.config.ts", "tokens.css"],
+  "ui_components": ["components/ui/* (shadcn)", "design-system package"],
+  "theme_framework": ["Tailwind with class-strategy dark mode", "CSS modules", "lipgloss terminal rendering"],
+  "interaction_a11y": ["aria labels on form components", "focus-visible ring convention", "prefers-reduced-motion variants", "i18n via locale files"],
+  "product_signals": ["README value prop", "user-facing features inferred from routes"],
+  "inferred_users": ["admin vs member roles in auth middleware", "onboarding copy addresses ops teams"],
+  "licensing_signals": ["LICENSE (MIT)", "billing integration", "plan tiers in config"],
+  "interface_type": "graphical-ui | cli | agentic-protocol | none",
+  "risks_todos": ["TODO: replace polling with webhooks", "v1 client deprecated", "no OpenAPI spec for public routes"],
+  "evidence_paths": ["file paths backing the claims above"]
+}
+```
+
+## Field → Findings-File Routing
+
+Route each field into the findings file its downstream consumer reads. A field can feed more than one file.
+
+| Digest field | Findings file / section |
+|---|---|
+| `purpose` (product framing), `product_signals` | `scan/product-findings.md` → Value Proposition, User-Facing Capabilities |
+| `inferred_users` | `scan/product-findings.md` → Inferred Users |
+| `licensing_signals` | `scan/product-findings.md` → Licensing & Monetisation Signals |
+| `design_tokens`, `ui_components` | `scan/design-findings.md` → Design Tokens, Component Library |
+| `theme_framework` | `scan/design-findings.md` → Theme & Framework |
+| `interaction_a11y` | `scan/design-findings.md` → Interaction & Accessibility Signals |
+| `interface_type` | `scan/product-findings.md` → Product Surface; `scan/design-findings.md` → Interface Surfaces; `scan/architecture-findings.md` → Service / Partition Map (Surface column) |
+| `purpose`, `entry_points`, `exported_surface` | `scan/architecture-findings.md` → Service / Partition Map, Entry Points |
+| `external_contracts` | `scan/architecture-findings.md` → External Contracts |
+| `data_models`, `persistence` | `scan/architecture-findings.md` → Data Models & Persistence |
+| `dependencies` | `scan/architecture-findings.md` → Dependencies |
+| `communication` | `scan/architecture-findings.md` → Communication Patterns |
+| `infra_deployment` | `scan/architecture-findings.md` → Infrastructure & Deployment |
+| `notable_patterns` | `scan/architecture-findings.md` → Notable Patterns |
+| `risks_todos` | `scan/architecture-findings.md` → Risks & TODOs |
+| `project_type`, repo shape | `scan/overview.md` → Parts, Partition Map |
+
+`infra_deployment` is a distinct field, not a kind of contract — docker-compose, IaC, CI, and env examples have a guaranteed home so they are never lost between the contract and dependency slots.
+
+The audience- and surface-facing fields read from predictable places. `inferred_users` is who the partition appears built for — the auth model (roles, permission tiers, tenancy), user-facing copy, and the shape of admin versus consumer routes; record it as inference, never as fact. `licensing_signals` comes from LICENSE files, package-manifest license metadata, and anything monetisation-shaped: billing integrations, plan tiers, paywall gates. `theme_framework` names the UI framework and styling approach — Tailwind, CSS-in-JS, CSS modules, a terminal rendering library — plus dark-mode handling; `design_tokens` holds the token sources themselves, `theme_framework` holds how the surface is styled. `interaction_a11y` records the interaction and accessibility posture visible in components: ARIA usage, focus and keyboard handling, motion and reduced-motion conventions, i18n setup. A backend partition legitimately leaves most of these empty — an empty field is itself a finding, and the extract phases interview for what no partition surfaced.
+
+When `external_contracts` is empty for a partition that exposes routes, record the absence in `risks_todos` as a missing-contract gap. The architecture extract phase promotes it to a blocks-delivery entry in the gap ledger — the contract-driven bet loop depends on machine-readable contracts.
+
+Every partition whose `interface_type` is not `none` is an **interface surface**, and the findings record all of them — a repo can carry a web app and a CLI, and each gets its own line in both destinations. The design extract recovers a design section per surface type and the architecture extract writes the surface registry from these lines; a surface dropped here never reaches either.

package/src/hidden-skills/groundwork-scan/references/exclusions.md

@@ -0,0 +1,44 @@
+# Exclusions & File Priority
+
+Governs what the scan reads and what it skips, at every depth. The goal is to read what carries meaning and never burn context on generated, vendored, or binary noise.
+
+## Always Exclude
+
+Never read these — they are dependencies, build output, or noise, not the project's own code:
+
+- `node_modules/`, `vendor/`, `.venv/`, `venv/`, `target/`, `.git/`
+- `dist/`, `build/`, `out/`, `.next/`, `.nuxt/`, `coverage/`
+- Minified and sourcemap files: `*.min.js`, `*.min.css`, `*.map`
+- Lockfiles — confirm a stack from them, never read their contents: `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `go.sum`, `poetry.lock`, `Cargo.lock`, `uv.lock`
+- Binary and media: images, fonts, audio, video, archives, compiled binaries
+- Generated code clearly marked as such (a `// Code generated ... DO NOT EDIT` header, `*.pb.go`, `*_gen.go`)
+
+## Contract-Bearing Priority (read first, at every depth)
+
+These files carry the most architectural signal per byte. Read them first in every partition, even at Quick depth, because the architecture extract phase depends on them:
+
+- **API contracts** — OpenAPI/Swagger (`openapi.{yaml,json}`, `swagger.{yaml,json}`), AsyncAPI, Protobuf (`*.proto`), GraphQL SDL (`*.graphql`, `schema.gql`)
+- **Data schema** — DB migrations (`migrations/`, `*.sql`), ORM models (`schema.prisma`, `models.py`, `entity.ts`), seed files
+- **Routes & handlers** — route registration, controllers, resolvers, command definitions — the public surface
+- **Manifests** — `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `requirements.txt`
+- **Infrastructure** — `docker-compose*.{yml,yaml}`, Dockerfiles, `*.tf`, `k8s/` and `helm/` manifests, CI workflows (`.github/workflows/`)
+- **Config & env** — `*.env.example`, config files that declare ports, dependencies, and feature flags
+
+## Depth Behaviour
+
+- **Quick** — the contract-bearing priority files, the README, and top-level config only. No deep source reading.
+- **Deep** — Quick plus every file in the critical directories for the project type (the source roots, the route/handler layers, the model layers). Skim test fixtures and generated assets.
+- **Exhaustive** — every file except the Always Exclude set.
+
+## Critical Directories by Project Type
+
+Stay generic — these are structural heuristics, never product-domain assumptions:
+
+- **Go service** — `cmd/`, `internal/`, `pkg/`, `api/`, `migrations/`
+- **Python service** — the package root, `app/`, `api/`, `models/`, `alembic/` or `migrations/`
+- **Next.js / React app** — `app/`, `pages/`, `components/`, `lib/`, `src/`, the Tailwind/theme config
+- **Node service** — `src/`, `routes/`, `controllers/`, `models/`
+- **CLI** — the command tree, the entry binary, the config layer
+- **Library** — the public entry module and its exported surface
+
+When the project type is unrecognised, fall back to reading the manifest, the entry point, and any directory the structural map flags as high-centrality.