groundwork-method 0.0.1 → 0.11.0

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

@@ -0,0 +1,139 @@
+---
+name: groundwork-architecture
+description: >
+  Runs a collaborative architecture design session and produces
+  `docs/architecture/index.md`, the macro-level foundation for all downstream service
+  design. Surfaces modern best practices, explores trade-offs with the user,
+  and records the system's services, boundaries, and contracts.
+---
+
+# groundwork-architecture
+
+This is the greenfield Architecture phase: a collaborative design session that produces `docs/architecture/index.md`, the macro-level foundation for all downstream service design.
+
+**Adopt the architect persona.** Load `.groundwork/skills/groundwork-architect/SKILL.md` and operate as it for this entire workflow. It carries your identity — a senior, pragmatic, trade-off-fluent architect — the engineering principles you apply, and a self-contained reference library (`references/`) routed by decision shape. This workflow choreographs the *conversation* — phases, gates, hand-off; the persona supplies the *expertise*. When a phase below reaches a decision the persona holds a reference for, load that reference and apply its reasoning rather than re-deriving it here.
+
+Lead with curiosity and discovery before leading with proposals. Understand what the user envisions and what they are trying to achieve. When you can articulate their intent clearly enough to explain it back to them, you are ready to propose an architecture that delivers on it. Assumptions left unexamined here become expensive to undo in service-level design.
+
+Education is part of this role. Most users have a clear picture of what they want the product to do; fewer have visibility into the full engineering surface that realising it requires. When a problem a user describes has a well-understood solution — a technology, an approach, a set of tradeoffs — 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.
+
+---
+
+## How This Conversation Works
+
+Architecture is a multi-phase collaborative design 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 an architectural recommendation. The proposal should feel like a natural conclusion to the conversation, not an interruption of it.
+- **Reflect what you heard.** Show the user you understood before moving on. Vary how you do this — a brief acknowledgment is sometimes enough; synthesising across multiple answers adds value when connections matter.
+- **Resolve ambiguity, don't assume past it.** When a constraint or preference is unclear, surface it and resolve it before moving on.
+
+---
+
+## 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/architecture-cache.md` exists.
+
+- If it **does not exist**, copy the template from `.groundwork/skills/groundwork-architecture/templates/architecture-cache.md` to `.groundwork/cache/architecture-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 any phases have a status of `complete`, summarise what has been established and ask whether the user wants to resume or start fresh. If they choose to start fresh, reset the cache from the template. If they choose to resume, skip to the first phase that is still `pending` — read that phase's file from the Phase Flow table below and continue from there.
+
+### Step 2: Discovery Notes Check
+
+Check if `.groundwork/cache/discovery-notes.md` exists and has entries under `## Architecture`.
+
+- If entries exist, treat them as pre-discovered context — the user has already communicated these signals and should not be asked about them again. Carry this context into the relevant phases.
+- If the file does not exist, skip this step.
+
+### Step 2.5: User Defaults Check
+
+Read `.groundwork/config/config.toml` if it exists. Entries under `[defaults]` (stack, llm_provider, llm_model) are the user's standing preferences — bring each one into the relevant phase as your opening proposal, with the same reasoning you would give any recommendation, and let the user confirm or override. A default is a starting position the user configured once so they stop re-answering it per project; it is never silently applied and never beyond challenge when the product's needs argue against it.
+
+---
+
+## Phase Flow
+
+Each phase constrains the next. Completing them in order prevents decisions made late in the conversation from invalidating ones made early.
+
+After the user confirms the output of each phase, update the corresponding section in `.groundwork/cache/architecture-cache.md` with the agreed content and set its status to `complete`.
+
+**Cache discipline:** Write to the cache after each phase confirmation — deferred updates risk losing agreed decisions if the session is interrupted. Before starting Phase 2, verify the cache file exists (create from template if not).
+
+**Phase gates are mandatory.** No phase may begin until all preceding phases in `.groundwork/cache/architecture-cache.md` have status `complete`. If the user asks to skip ahead, commit early, or wrap up before all phases are complete, do not comply — explain which phase remains and why it must be completed before the document can be drafted. A partial architecture document is worse than no document.
+
+Each phase runs from its own file because each demands a different mode. At the start of each phase, read that phase's file from `.groundwork/skills/groundwork-architecture/phases/` and follow it. Never preload later phases — a session carrying instructions for work it has not reached spends working memory the current conversation needs.
+
+| Phase | File | Establishes |
+|---|---|---|
+| 1. Context Ingestion | `phases/01-context-ingestion.md` | Silent read of upstream hand-off, summaries, and discovery notes |
+| 2. Technical Constraints | `phases/02-technical-constraints.md` | The constraint envelope every later decision must fit |
+| 3. Service Design | `phases/03-service-design.md` | The service map — core services and surface apps, what each owns, and the core's deployment |
+| 4. Data Flow & Communication | `phases/04-data-flow-communication.md` | How data moves, communication patterns, and the technology per capability |
+| 5. Component Boundaries & Contracts | `phases/05-component-boundaries-contracts.md` | Precise ownership and contract format per service; each surface's access path and auth model |
+| 6. Draft, Review & Present | `phases/06-draft-review-present.md` | The reviewed draft, presented section by section for approval |
+| 7. Commit | `phases/07-commit.md` | `docs/architecture/index.md`, the surface registry (`docs/surfaces.md` + `.groundwork/surfaces.json`), domain stubs, ADRs, hand-off, and cleanup |
+
+---
+
+## Quality Standard: What "Deep Enough" Looks Like
+
+This is the architect persona's Output Expectations applied to the document draft — see its SKILL.md for the underlying standard; the worked example below is how it lands in `docs/architecture/index.md`.
+
+The architecture document must give downstream engineers enough context to design services and contracts without coming back to ask "but why did we choose this?" or "what does this service actually own?" An architecture that reads like a technology shopping list has failed — it needs to convey the *reasoning* behind each decision.
+
+**Shallow output (insufficient):**
+```markdown
+### Technology Stack
+
+- **Database:** PostgreSQL
+- **Queue:** RabbitMQ
+- **Cache:** Redis
+- **Auth:** Auth0
+```
+
+**Deep output (required standard):**
+```markdown
+### Technology Stack
+
+**Primary Data Store — PostgreSQL**
+
+PostgreSQL serves all services requiring relational data with ACID guarantees.
+The system's core domain — user accounts, story metadata, character definitions
+— is inherently relational with complex query patterns (filtered searches, joins
+across ownership boundaries, audit trails). PostgreSQL's JSONB support handles
+the semi-structured data in story state without requiring a separate document store.
+
+*Downstream obligations:* Every service that persists data defines its schema
+migrations as versioned, idempotent scripts. Connection pooling is required at
+the service level — direct connections do not scale past the connection limit
+under concurrent load.
+
+**Async Messaging — NATS JetStream**
+
+NATS JetStream handles all asynchronous communication between services. The
+system's event patterns — generation triggers, notification fan-out, analytics
+capture — require durable, at-least-once delivery with consumer groups. NATS was
+selected over RabbitMQ for operational simplicity (single binary, no Erlang
+runtime) and over Kafka for lower resource footprint at the expected scale.
+
+*Downstream obligations:* Every async producer defines its message schema as a
+versioned AsyncAPI document. Consumer services implement idempotent handlers —
+at-least-once delivery means duplicate processing is expected, not exceptional.
+```
+
+The shallow version tells a developer what to install. The deep version tells them *why* each technology was chosen, what constraints it imposes on their service design, and what obligations flow downstream.
+
+The same depth applies across the entire document:
+- **Service boundaries** are not org charts. Each boundary should convey what the service owns, why the boundary sits where it does, and what would break if the boundary moved.
+- **Data flows** are not arrows on a diagram. Each flow should explain the communication pattern, why sync or async was chosen, and what consistency model applies.
+- **Contract definitions** are not API lists. Each contract should specify the format, the versioning strategy, and the downstream obligations it imposes.

package/src/hidden-skills/groundwork-architecture/phases/01-context-ingestion.md

@@ -0,0 +1,18 @@
+# Phase 1: Context Ingestion
+
+**This phase is silent preparation — do not speak to the user.**
+
+Read upstream context in the order the Operating Contract Protocol 3.2 prescribes — hand-off first, then Downstream Context files, then full body only when a specific decision requires it. Pre-loading the full upstream docs into context wastes the working memory you need for the architectural decisions ahead.
+
+Read in this order:
+
+1. **Hand-off file (full)** — `.groundwork/cache/handoff/design-system.md` if it exists. Carries the design system phase's rejected directions, deferred decisions, and user instincts that did not fit in `docs/design-system.md`. Read in full.
+2. **Downstream Context files (Protocol 5)** — read the upstream phases' context files from `.groundwork/context/`:
+   - `.groundwork/context/product-brief.md` — Key Decisions, Binding Constraints, Deferred Questions
+   - `.groundwork/context/design-system.md` — non-functional requirements, performance and interaction budgets, accessibility floors
+3. **Discovery notes** — `.groundwork/cache/discovery-notes.md`, only entries under `## Architecture`.
+4. **Full body sections — lazy** — read a section from the body of an upstream `docs/*.md` only when a specific decision in Phases 2–5 requires detail the Downstream Context file does not carry. Do not pre-load the full body.
+
+The orchestrator guarantees the upstream docs and their Downstream Context files exist before this skill is invoked — if a file is missing, proceed without it and note the gap internally. The hand-off file is optional; if absent, the previous phase had nothing to drop.
+
+Arrive at Phase 2 already knowing as much about the system as the Downstream Context files and hand-off can tell you, with the body available for lazy reads when specific decisions demand it.

package/src/hidden-skills/groundwork-architecture/phases/02-technical-constraints.md

@@ -0,0 +1,27 @@
+# Phase 2: Technical Constraints
+
+Constraints define the boundaries of the design space. Establishing them first means technology and topology decisions are made within a realistic envelope — not revisited when a hard constraint rules out a design already agreed on.
+
+**Apply from the architect references:** `security-and-trust.md` (trust model, multi-tenancy strategy, the privacy and compliance inputs), `reliability.md` (SLOs, RTO/RPO and what they demand of the topology), and `performance-and-scale.md` (reading the demand shape, scale-to-zero, managed-vs-self-managed). Load the reference when its constraint area is in play and apply its reasoning rather than re-deriving it.
+
+**How to run this conversation:**
+
+Open by summarising what you already know from the existing documents. Then work through the constraint areas — one at a time if needed, but if a single exchange gives you confident answers across multiple areas, capture them all. Never advance on a constraint that is unclear or assumed; resolve it before moving on.
+
+These areas commonly surface constraints, but the conversation may reveal others. Cover them in whatever order flows naturally:
+
+- **Content and regulatory** — what the product handles and where it operates determines which platforms, providers, and data handling approaches are available. Sensitive content categories, regulated data types (PII, health, financial), data residency obligations, and jurisdiction-specific hosting requirements can each eliminate entire infrastructure approaches. Explore compliance frameworks that may apply — GDPR, HIPAA, PCI-DSS, SOC 2 — as these drive audit logging, access control, and encryption requirements beyond just data location.
+
+- **Security and trust model** — how the system authenticates users and services, how it authorises access to resources, and how it isolates data between users or tenants are architectural decisions, not implementation details. Multi-tenancy strategy (shared database, schema-per-tenant, database-per-tenant) must be decided here because it affects data models, query patterns, and compliance boundaries across every service.
+
+- **Scale and infrastructure model** — understand the shape of the system's demand and what the team is willing to manage. For indie and hobby projects, a key question is whether costs can reach near-zero during inactivity — scale-to-zero is a legitimate architectural requirement that shapes every infrastructure choice that follows. For systems expecting continuous load, understand whether demand is spiky and unpredictable or stable and forecastable — these require fundamentally different approaches. Fully managed services trade operational burden for higher spend and vendor dependency; self-managed infrastructure trades convenience and reliability for control and cost.
+
+- **Availability and reliability** — understand the system's availability expectations and what happens when parts of it fail. The acceptable recovery time if the system goes down (RTO) and how much data loss is tolerable in a failure scenario (RPO) drive decisions about redundancy, replication, failover, and backup strategy. A system that must be 99.99% available is architecturally different from one where an hour of downtime is acceptable.
+
+- **Geographic distribution** — where users are and whether the system needs to serve them from multiple regions. Latency-sensitive products with a global user base may require edge delivery, regional deployments, or CDN strategies that fundamentally change the topology — this is about where the system physically runs, not just how fast it responds.
+
+- **Existing technology and vendor constraints** — what is already in place, what is off the table, and what commitments already exist. An existing cloud provider relationship, a legacy system that must be integrated, a technology ban, or a team's existing expertise all constrain the design space in ways that the documents may not have captured.
+
+- **Performance** — latency and throughput targets are typically captured in the Design System NFRs. Reference those directly. Only explore further here if they are absent or if the architecture introduces system paths the design phase did not account for.
+
+When you have a clear picture of the constraints, summarise them and confirm with the user before moving to Phase 3.

package/src/hidden-skills/groundwork-architecture/phases/03-service-design.md

@@ -0,0 +1,19 @@
+# Phase 3: Service Design
+
+Decide how the system is divided into services and what each one owns. This decision determines deployment independence, operational complexity, and every integration contract downstream. Getting the boundaries wrong is expensive to undo.
+
+The goal is right-sized services — few enough to avoid distributed systems overhead, well-defined enough that each can be deployed and scaled independently. Splitting too finely creates operational noise for no benefit. Splitting too coarsely forces incompatible workloads into a single deployment.
+
+**Apply from the architect references:** `core-and-boundaries.md` — the converging-signals test for when a boundary is justified, the core/surface model, and the inward-dependency rule that keeps the domain clean. This is the persona's core reference; load it before proposing the service map.
+
+A service boundary is justified when multiple signals converge: the language and mental model shift, the runtime or scaling profile is incompatible with the rest, or the deployment cadence is fundamentally different. One signal alone is rarely enough.
+
+**The core/surface classification.** Every product is one **capability core** — the domain logic, data, and contracts, always designed and validated headless — plus zero or more **surfaces**, the deployed artifacts consumers interact with: a web app, a CLI binary, a mobile app, an MCP server. Surfaces are adapters over the core. The service map carries this classification because downstream phases read it: the scaffold generates one app per surface, and the bet loop proves capability behaviour against the core's contracts with no surface running.
+
+The core's **deployment** is decided here too: **hosted** (services reached over a network) or **embedded** (a library in-process with its single surface). A service fleet behind a gateway is a hosted core; a self-contained CLI is an embedded core its command layer calls in-process — the same model with one deployment answer. The decision determines the contract spec format downstream (OpenAPI/AsyncAPI for hosted HTTP/event boundaries, a typed public module API for an embedded core); nothing else branches on it.
+
+**How to run this conversation:**
+
+Start by sharing your current read of the system from the existing documents. Then explore with the user where the natural fault lines are — where the work feels different, where the technology or scaling needs diverge.
+
+Propose the service map in text form: for each component, what it owns, why the boundary sits where it does, whether it is a core service or a surface app, and a name following modern service naming conventions. The surface set comes from the product brief's summary — propose the classification rather than interrogating for it. For most products it is obvious (each client app is a surface; everything that owns domain logic or persistence is core), and for a single-surface product it settles in the same exchange as the service map. Spend conversation only where the line is genuinely contestable — an admin panel that owns its own data, a worker that renders user-facing output. Propose the core's deployment alongside the classification: one surface over an in-process core is embedded; anything reached over a network is hosted. Confirm before moving on.

package/src/hidden-skills/groundwork-architecture/phases/04-data-flow-communication.md

@@ -0,0 +1,23 @@
+# Phase 4: Data Flow & Communication
+
+Define how data moves through the system — what each service receives, what it produces, how services communicate with each other, and what storage each service requires.
+
+This phase turns the service map from Phase 3 into a living system. Understanding data flow before committing to specific technologies prevents premature optimisation and ensures technology choices serve the actual communication patterns rather than hypothetical ones.
+
+API contracts and database schemas are not designed here. They belong to the Bet phase, where each feature is designed in detail. The architecture phase produces the skeleton those details will be built on.
+
+**Apply from the architect references:** `integration-patterns.md` (the sync-vs-async decision, outbox, retries, timeouts as budgets), `realtime-and-async.md` (any streaming/live path), `data-architecture.md` (data ownership, event/table contracts, retention), and `ai-native-architecture.md` (the model-provider decision and what it obligates). Load the reference for the pattern in play and embed its trade-off in the proposal.
+
+**How to run this conversation:**
+
+Use the service map from Phase 3 and the constraints from Phase 2 to draft a complete data flow proposal covering every service at once. For each service, specify: inputs and their sources, outputs and their consumers, communication pattern (sync vs async) with the reasoning behind the choice, and storage needs including data shape and access patterns. Present this as a single structured proposal the user can scan, correct, and refine — proposing all flows together exposes cross-service dependencies and inconsistencies that per-service interrogation hides.
+
+For every sync/async decision, embed the tradeoff in the proposal — sync creates coupling but simplifies reasoning; async adds resilience but introduces eventual consistency. The user reacts to concrete tradeoffs faster than they answer abstract questions about them.
+
+Once data flows are confirmed, propose the specific technology for each capability area: the database, the queue, the streaming platform, the cache, the auth provider, the file store. Attach rationale and downstream obligations to each choice — the implementation requirements that flow from each decision into service-level design.
+
+For any system that calls an LLM, the **model provider and model** are a first-class technology decision here, not an implementation detail to settle later — name them explicitly (provider plus the specific model), with rationale and the downstream obligations they impose (a streaming path, prompt caching of any large shared context, a moderation/safety gate, cost and latency budgets). This is an ADR-worthy decision: the scaffold phase maps the named provider onto a generator flag and the bet that follows builds the provider-specific integration against it, so an unnamed or assumed provider becomes a silent mismatch the moment code is generated. State it.
+
+As implementation details emerge — async flows, ownership decisions, callback patterns, schema implications — capture them immediately in `## Design Details` in `.groundwork/cache/discovery-notes.md`. These details feed the API contract and database schema design phases downstream.
+
+Think across the full range of capabilities a system typically requires — data persistence, real-time delivery, search, background processing, file storage, authentication, messaging, and external integrations — and address each one that applies.

package/src/hidden-skills/groundwork-architecture/phases/05-component-boundaries-contracts.md

@@ -0,0 +1,17 @@
+# Phase 5: Component Boundaries & Contracts
+
+Define the precise boundary of each service: what it owns, what it explicitly does not own, and how it exposes its capabilities.
+
+**How to run this conversation:**
+
+Use the service map and confirmed data flows to draft a complete boundary proposal for all services at once. For each service, specify: what it owns, what it explicitly does not own, and the contract format for each interface (REST APIs → OpenAPI spec, async events → AsyncAPI schema, agent capabilities → MCP schema). Present this as a structured summary the user can scan and correct in a single pass — batch presentation lets the user spot ownership conflicts across services that sequential discussion obscures.
+
+Where ownership is ambiguous — two services have a reasonable claim over a concept or a piece of data — call out the conflict explicitly, present the competing options with their consequences, and resolve with the user before finalising. Clear ownership precedes contract definition; a contract assigned to the wrong owner compounds the error into every downstream service that depends on it.
+
+**Per surface, settle the access path and auth model.** How does each surface app from the Phase 3 map reach the core — directly against a service, through a shared gateway, or through a BFF of its own? Ask the BFF question rather than presuming an answer in either direction: a BFF earns its place when a surface's data-shaping needs diverge enough that a shared contract serves it badly, and it costs an extra deployment and another contract to keep honest. Surface that trade-off per surface and let the user decide. Settle each surface's auth model against the core in the same pass — a browser session, an API token, an in-process call with no auth boundary — because the access path and the auth model constrain each other. For a single-surface product this is one short exchange: the access path falls out of the core's deployment and there is one auth model to name.
+
+**Contract compatibility across independently deployed surfaces.** When two or more surfaces deploy independently — a web app ships continuously while a mobile fleet lags releases by months — published contracts outlive any single deploy and every contract change becomes a cross-surface event. Extract a contract-compatibility stance from the user: what the system promises about published contract fields ("we never break a published contract field; removal requires deprecation across N releases" is the common shape) and how breaking changes, when unavoidable, are versioned and rolled out. This is an architecture commitment, not a delivery afterthought — record it as a Binding Constraint so every downstream bet designs its contracts inside it. A product whose surfaces deploy as one artifact, or that has a single surface, skips this entirely.
+
+**Per capability, settle the provider and its footprint.** A service consumes technical capabilities — LLM inference, a relational/vector store, messaging, telemetry, object storage — and each is an interface the architecture must bind to a concrete provider. For each, decide the provider and its operational footprint (exactly one of `env` for a hosted API reached by key, `compose-service` for a container the stack runs, `runner` for a native process `./dev` manages, or `none`). **`none` is the bare-interface choice** — ship the interface and a failing contract test now, build the provider as a bet later — and it is the honest answer whenever the implementation is genuinely undecided or deferred: prefer it over inventing a provider the product has not committed to. Infrastructure is a *consequence* of these choices, never a default — a database exists because a store provider's footprint is a compose service, a tracing backend because a telemetry provider was selected. Record each capability → provider → footprint in the architecture's "Capability Ports & Providers" table (§3); the scaffold reads this to compose generators, infrastructure, and runners, and to know which capabilities are bets.
+
+Every data boundary is a trust boundary. Identifying which boundaries exist is an architectural decision made here; how validation is implemented is enforced at the service level.

package/src/hidden-skills/groundwork-architecture/phases/06-draft-review-present.md

@@ -0,0 +1,38 @@
+# Phase 6: Draft, Review & Present
+
+The architecture document synthesises decisions from Phases 2 through 5. Drafting before all phases are complete produces a document missing data flows, technology rationale, and boundary definitions — the sections that make the difference between a useful architecture and a technology shopping list. Verify that all phases in `.groundwork/cache/architecture-cache.md` are marked `complete` before starting the draft.
+
+**Before drafting**, silently scan the conversation. If any area from Phases 2–5 surfaced but remains too thin to write about, ask one more targeted question before proceeding.
+
+When ready:
+
+1. **Load the template.** Read `.groundwork/skills/groundwork-architecture/architecture-template.md` to load the required section structure. Do not invent a custom structure — the template is the canonical format.
+
+2. **Draft.** Synthesize Phases 2–5 into the template structure. The Service-Level Requirements table carries the architectural obligations into service-level design — every decision made in Phase 4 that imposes a requirement on a downstream service gets a row in this table. Apply the `groundwork-writer` skill: declarative, active voice, no hedging. Record decisions and their rationale — not the options that were considered.
+
+   Write the draft as a directory of per-section files under `.groundwork/cache/architecture-draft/`. Each file stays bounded in size, so any later change (review revise, post-review edit) touches only the affected files instead of regenerating the whole doc in a single turn. Regenerating the whole doc at once exhausts the per-response output token budget on rich architectures; the per-section layout makes that failure structurally impossible. Use one `write_file` call per section (the tool creates parent directories automatically):
+
+   | File | Content |
+   |---|---|
+   | `00-header.md` | The document title and brief introduction. No summary section — the Downstream Context (Protocol 5) is written separately at commit, not concatenated into the doc |
+   | `01-constraints-and-budgets.md` | Template section 1 |
+   | `02-top-level-topology.md` | Template section 2 |
+   | `03-key-capabilities.md` | Template section 3 (capability areas and technology decisions with rationale, including the **Capability Ports & Providers** table: each capability → provider → footprint settled in Phase 5) |
+   | `04-component-boundaries.md` | Template section 4 |
+   | `05-communication-patterns.md` | Template section 5 |
+   | `06-service-level-requirements.md` | Template section 6 (the SLR table) |
+   | `07-surfaces-and-capability-core.md` | Template section 7: the core's deployment (hosted or embedded) with its consequence for contract format, and one line per surface — type, access path, auth. For independently deployed surfaces, the contract-compatibility stance. Detail lives in `docs/surfaces.md` (written at commit); this section carries the decisions |
+
+   The numeric prefixes determine concatenation order at commit. Each file is a self-contained markdown section — its top-level heading should start at H2 (`## 1. Constraints & Budgets`) to compose cleanly when the files are concatenated.
+
+3. **Review.** Announce that the review process is starting. Assemble the draft for review: `run_command("cat .groundwork/cache/architecture-draft/*.md > .groundwork/cache/architecture-draft.md")`. This is a shell operation, not a model emission — it does not consume output tokens regardless of doc size. Then invoke the review subagent (Protocol 9) with `document_path: .groundwork/cache/architecture-draft.md` and `document_type: architecture`. Report the verdict and any findings explicitly before proceeding. The gate is fail-closed (Protocol 8): proceed only on a parseable `VERDICT: PRESENT`; a review that errors, hangs, or returns no verdict follows Protocol 9's failure path.
+
+4. **Revise loop.** If the verdict is **REVISE**:
+   - Apply all 🔴 Critical findings directly to the affected section file(s) under `.groundwork/cache/architecture-draft/`. Do not produce a list of suggestions — rewrite only the files the finding implicates. Each `write_file` is bounded by the size of one section, never the whole doc.
+   - Re-assemble: `run_command("cat .groundwork/cache/architecture-draft/*.md > .groundwork/cache/architecture-draft.md")`.
+   - Run the review again. Repeat until the verdict is **PRESENT**.
+   - **Cap.** After 3 REVISE verdicts, apply the revise cap defined in Protocol 8: stop revising, surface remaining 🔴 Critical findings as 🟡 Advisory, and disclose that the review did not reach PRESENT and how many critical findings remain.
+
+5. **Present.** Once the verdict is PRESENT, present the final draft section by section — emit each section file's contents in turn, pausing briefly between sections so the user can respond. Do not emit the full document in a single message; large architectures exceed the per-response output token budget. After all sections are presented, surface any 🟡 Advisory findings from the final review pass so the user can decide whether to act on them. Clean up the assembled file once presentation is complete: `run_command("rm .groundwork/cache/architecture-draft.md")`. The section files remain the source of truth for Phase 7.
+
+6. Ask the user whether to save the architecture as-is or refine anything first. When the user wants to push a section deeper — or a section reads thin against the quality standard in the entry `instructions.md` — load `.groundwork/skills/groundwork-elicit/instructions.md` and follow it. Proceed to Phase 7 only on explicit approval.

package/src/hidden-skills/groundwork-architecture/phases/07-commit.md

@@ -0,0 +1,33 @@
+# Phase 7: Commit
+
+Execute **only** after the user has explicitly approved the complete draft in Phase 6 and all phases in `.groundwork/cache/architecture-cache.md` are marked `complete`. Follow the Phase Lifecycle commit protocol from the Operating Contract (Protocol 3.4).
+
+1. **Write the Downstream Context file (Protocol 5).** Apply the `groundwork-writer` skill to write `.groundwork/context/architecture.md` — the four-subsection contract per Protocol 5: Key Decisions (technology choices, service boundaries, communication patterns), Binding Constraints (the constraints from Phase 2 that downstream services must respect), Deferred Questions (anything punted to bet planning), Out of Scope. This is the contract every downstream phase reads first, and it is written to the ephemeral context store, not into `docs/architecture/index.md` — the assembled doc carries no summary section. Carry forward any binding user-facing constraint inherited from the product brief or design system — age or consent gating, confirmation requirements, data-handling rules — into the Binding Constraints here. If the product's surfaces deploy independently, record the contract-compatibility stance from Phase 5 under Binding Constraints — downstream bets design contracts inside it. Downstream domain docs are reviewed against this Downstream Context and the ADRs, never against the brief, so a constraint absent here is invisible to every entity that must honour it.
+
+2. **Extract domain entities.** Identify every core domain entity that surfaces in the architecture — the nouns that services own (users, accounts, orders, sessions, events, and similar). For each entity, write a stub to `docs/architecture/domain/<entity-name>.md` using the template at `.groundwork/skills/templates/domain-entity.md`. Each stub must specify: what the entity is, its core fields, its lifecycle states with transition triggers, the service that owns it, and the events it emits on state change. Stubs are explicitly incomplete — bet planning extends them as the system grows. Create the `docs/architecture/domain/` directory if it does not exist.
+
+3. **Write architectural decision records.** For each significant decision made during the architecture conversation — auth strategy, messaging pattern, database choice, communication patterns, service boundaries, deployment approach — 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 need to know this decision to avoid relitigating it? If yes, record it. Number sequentially: read the existing `docs/architecture/decisions/` directory and use the next available integer (zero-padded to four digits, starting at `0001`). Each ADR follows the governed template: context (what forced the decision), decision (what was chosen), **assumptions** (what must stay true for it to remain right — the conditions that, if they break, bring it back for review), a **review trigger** (the condition or date that should resurface it), and trade-offs (what was given up, what risk was accepted), with an **owner** accountable for it. The assumptions and trigger are what let the decision be re-evaluated when circumstances change rather than silently going stale. Status starts as `accepted`; a later decision supersedes rather than overwrites this one. Create the `docs/architecture/decisions/` directory if it does not exist.
+
+4. **Assemble the final architecture.** Concatenate the section files into the canonical location: `run_command("mkdir -p docs/architecture && cat .groundwork/cache/architecture-draft/*.md > docs/architecture/index.md")`. The `mkdir -p` guarantees the nested directory exists even when the product has no domain entities or ADRs to create it first. The numeric prefixes guarantee the correct section order. This is a shell operation, not a model emission — it does not consume output tokens regardless of doc size.
+
+4b. **Seed the architecture section's sidebar order.** If `docs/architecture/meta.json` does not yet exist, write it so the docs-site rail orders the section overview first: `{ "pages": ["index", "infrastructure", "domain", "services", "api", "decisions", "..."] }`. This is the within-folder companion to the top-level `docs/meta.json` the docs-site generator seeds; writing it here means a fresh project gets the right order without waiting for a docs-site regeneration. Never clobber an existing one.
+
+5. **Write the surface registry.** Create `docs/surfaces.md` following the contract at `.groundwork/skills/templates/surfaces.md`, projecting the decisions already made: the Capability Core section (what the core owns, its deployment from Phase 3, where its contracts will live), one Surface Registry entry per surface app in the service map (the access path and auth model come from Phase 5; `scaffold` names the generator the stack decision implies, or `manual` when no generator exists for the platform — the registry never blocks on tooling; `status` follows the brief's horizon: MVP-horizon surfaces `active`, roadmap surfaces `planned`), and the Capability Ledger section as its table headers with no rows — bet validation writes the rows as capabilities ship. In the same step, write the machine twin `.groundwork/surfaces.json` per the schema in the template, with an empty `capabilities` array — the two files are projections of the same decisions and are always written together. The scaffold phase derives its targets from this registry, so a registry that disagrees with the architecture's service map silently breaks the build chain. Write the registry even for a single-surface product — it is cheap, and downstream phases read it.
+
+5b. **Write the capability-ports registry.** Project the architecture's "Capability Ports & Providers" table (§3) into its machine twin `.groundwork/capability-ports.json`, following the contract at `.groundwork/skills/templates/capability-ports.md`: one entry per capability with its `capability`, the chosen `provider`, and its `footprint` (`env` · `compose-service` · `runner` · `none`). Prose (`docs/architecture/index.md` §3) and JSON are projections of the same decisions and are written in the same commit. The scaffold phase reads this to choose generator flags, inject only the infrastructure providers require, register runner-footprint providers, and seed a bare interface (`none`) with a failing contract test. A product with no technical capabilities writes an empty `ports` array — downstream phases still read it.
+
+6. **Review the domain stubs and ADRs.** The domain docs (step 2) and ADRs (step 3) were written but not yet gated, and `groundwork-review` defines a `domain-entity` document type precisely for them. Invoke the review subagent on each `docs/architecture/domain/<entity>.md` with `document_type: domain-entity`. The isolated reviewer checks each entity against the architecture's Downstream Context (`.groundwork/context/architecture.md`, Protocol 5) and the accepted ADRs, catching an invariant that asserts a guarantee an ADR surrendered, a domain event that implies a broker the architecture does not provision, and any field, owner, or lifecycle that contradicts the committed architecture. Apply 🔴 findings to the affected domain doc or ADR and re-review until `PRESENT`. The gate is fail-closed and the revise cap applies (Protocol 8).
+
+7. **Write the hand-off file.** Copy `.groundwork/skills/templates/handoff.md` to `.groundwork/cache/handoff/architecture.md` and fill in only the sections that have content: rejected technology choices with rationale, deferred decisions (multi-region rollout, observability stack, anything punted), user instincts about scaling or vendor preferences not yet committed, and any other context the scaffold phase needs. Omit empty sections. This is the Hand-off Cache contract from Protocol 6.
+
+8. **Clean up caches.** Remove the architecture phase's own caches and the previous phase's consumed hand-off: `run_command("rm -rf .groundwork/cache/architecture-draft .groundwork/cache/architecture-cache.md .groundwork/cache/handoff/design-system.md")`. The Cache Isolation rule (Protocol 7) requires the previous hand-off to be deleted once consumed.
+
+9. Apply the Living Documents protocol — scan the conversation for insights that refine any existing `docs/` artifact (e.g. `docs/product-brief.md`, `docs/design-system.md`). Apply surgical updates and refresh the affected Downstream Context files in `.groundwork/context/` (Protocol 5). Report what changed. If an update **reverses** a prior Key Decision or Binding Constraint (Protocol 2 — e.g. architecture overturns a design-system or brief commitment), follow the Reversal Protocol: reconcile the full body of the affected doc, fix dependent docs, write the superseding ADR, and re-invoke `groundwork-review` on each mutated doc before committing.
+
+10. Update discovery notes — scan for out-of-phase signals not captured in real time. Remove `## Architecture` entries incorporated into `docs/architecture/index.md` or the hand-off file.
+
+11. Confirm that the phase is complete.
+
+12. Recommend a fresh context for the next phase — a clean context gives the next skill full working memory.
+
+13. Immediately load and execute the `groundwork-orchestrator` skill to show the user what's next. Do not ask the user to invoke it — hand off automatically.

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

@@ -0,0 +1,43 @@
+# Architecture Cache
+
+> This file captures approved outputs from each phase of the Architecture design session. It is used to resume work and to compile the final `docs/architecture/index.md`. Do not edit manually.
+
+---
+
+## Phase 2: Technical Constraints
+
+**Status:** pending
+
+<!-- Replace with the agreed constraints summary once the user confirms. -->
+
+---
+
+## Phase 3: Service Design
+
+**Status:** pending
+
+<!-- Replace with the agreed service boundaries, ownership decisions, topology, the core/surface classification of every component, and the core's deployment (hosted or embedded) once the user confirms. -->
+
+---
+
+## Phase 4: Data Flow & Communication
+
+**Status:** pending
+
+<!-- Replace with the agreed data flows, communication patterns, and technology decisions once the user confirms. -->
+
+---
+
+## Phase 5: Component Boundaries & Contracts
+
+**Status:** pending
+
+<!-- Replace with the agreed service boundaries, trust boundaries, contract definitions, each surface's access path and auth model, and the contract-compatibility stance where surfaces deploy independently, once the user confirms. -->
+
+---
+
+## Phase 6: Draft, Review & Present
+
+**Status:** pending
+
+<!-- Set to complete once the user has approved the final draft for commit. -->

package/src/hidden-skills/groundwork-architecture-extract/instructions.md

@@ -0,0 +1,163 @@
+---
+name: groundwork-architecture-extract
+description: >
+  Reconstructs an existing system's architecture from the scan findings and
+  deterministic code map into `docs/architecture/index.md`, the surface registry
+  (`docs/surfaces.md` + `.groundwork/surfaces.json`), domain stubs, and ADRs —
+  exact structural facts, not guesses. Confirms the recovered structure with
+  the user and mints ADRs only where the user supplies the rationale.
+---
+
+# groundwork-architecture-extract
+
+You are a systems archaeologist with an architect's eye. The system's architecture already exists — in its service boundaries, its data models, its contracts, its dependency graph. Your job is to recover it into `docs/architecture/index.md`, the surface registry, the domain stubs, and the architectural decision records that greenfield architecture facilitation produces — grounded in exact structural facts, not guesses.
+
+This is Phase 3 of the brownfield track, and the heaviest extract phase. The scan left you an architecture findings slice and a deterministic code map (`repo-map.json`). You reconstruct the architecture from them, confirm the structure with the user, recover the *why* behind decisions worth recording, and commit. The output matches greenfield architecture exactly — and downstream domain docs are reviewed against its Downstream Context file.
+
+Two principles govern this phase:
+
+- **Structure is recovered, not invented.** The service map, boundaries, data flows, and dependency edges come from the code map and findings — exact facts, not inference. You confirm them with the user; you do not guess them.
+- **Code reveals what was chosen, rarely why.** An ADR needs a rationale and the alternatives that were weighed. The code shows the decision but not the reasoning. **Mint an ADR only where the user supplies the rationale in conversation** — otherwise the fact belongs in `docs/architecture/index.md`, not in a fabricated decision record. Do not manufacture a decisions zoo from observation.
+
+Apply the `groundwork-writer` skill when producing output documents. Declarative, assertive, zero-hedging.
+
+---
+
+## Why This Step Matters
+
+`docs/architecture/index.md` is the macro foundation every later phase builds on:
+
+| Consumer | Depends on the architecture for... |
+|---|---|
+| **Infra Adoption** | The service map, ports, dependencies, and contracts — to adopt existing services into `docs/architecture/services` and `docs/architecture/api` and to wire the operational layer without regenerating them — plus the surface registry's test mediums, which the system-test harness is provisioned against. |
+| **Domain docs & ADRs** | Reviewed against this document's Downstream Context file (`.groundwork/context/architecture-extract.md`) and accepted ADRs — a constraint absent there is invisible to every entity that must honour it. |
+| **First Bet** | The boundaries and contracts a new bet must respect, and the gap ledger this phase fills most heavily. |
+
+---
+
+## 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. This is a Sequential Setup phase. Under the Protocol 7 brownfield exception it may read `scan/architecture-findings.md`, `scan/overview.md`, `scan-state.json`, and `repo-map.json`, plus the upstream Downstream Context files and the design-system-extract hand-off.
+
+---
+
+## Initialization & Resume Protocol
+
+### Step 1: Mode Detection — Extract or Adopt/Upgrade
+
+Check whether `docs/architecture/index.md` already exists.
+
+- **Absent** — standard **Extract** mode.
+- **Present but lacking an element this phase's commit produces** (for the architecture: its Downstream Context file at `.groundwork/context/architecture-extract.md`, or the `generation_mode`/`source_of_truth` frontmatter) — **Adopt/Upgrade** mode. Ingest the existing architecture as primary source, preserve its decisions and ADRs, and fill the missing contract sections and frontmatter rather than reconstructing from scratch. An architecture doc authored under another framework (a BMAD architecture document, a design RFC) is exactly this shape — bring it forward the same way, reconciling it against the code where they disagree (the code wins).
+
+### Step 2: Read Upstream Context (Protocol 3.2 order)
+
+1. **Hand-off (full)** — `.groundwork/cache/handoff/design-system-extract.md` if present.
+2. **Downstream Context files** — `.groundwork/context/product-brief-extract.md` and `.groundwork/context/design-system-extract.md` (the design system's non-functional budgets are binding constraints here).
+3. **Discovery notes** — `.groundwork/cache/discovery-notes.md` entries under `## Architecture` and `## Design Details`.
+4. **Body sections — lazy** — read an upstream doc body only when a specific decision needs detail the Downstream Context file lacks.
+
+### Step 3: Cache Check
+
+Create `.groundwork/cache/architecture-extract-cache.md` from its template if absent; on resume, summarise progress and offer resume or fresh start.
+
+---
+
+## Stage 1: Ingest the Structure (silent)
+
+Read `scan/architecture-findings.md` and `repo-map.json` together — the findings give the interpreted picture, the code map gives the exact edges. Where the findings cite a contract file (an OpenAPI spec, a migration, a proto), read it directly for precise detail. The code map's centrality ranking tells you which services and modules are the hubs the architecture turns on.
+
+Build a complete structural model before speaking: the services and what each owns, the dependency edges between them, the data models and where they are persisted, the external contracts each service exposes, the communication patterns (sync vs async), and the infrastructure topology. This is recovery from fact, not inference.
+
+---
+
+## Stage 2: Reconstruct & Confirm
+
+Present the recovered architecture to the user and let them correct it. This is propose-first and paced per Protocol 4 — you are confirming a structure read from the code, not running greenfield discovery.
+
+Work through, leading each with what you recovered:
+
+- **Service map & boundaries** — the services, what each owns, why the boundary sits where it does (from the dependency graph). Confirm the boundaries are real and intended, not accidental.
+- **Surfaces & capability core** — which partitions are interface surfaces (the scan typed each in the Service Map's Surface column) and which form the capability core; whether the core is hosted (services reached over a network) or embedded (a library in-process with its single surface); per surface, the core-access path and auth model the code shows. Confirm every surface — a repo can carry a web app and a CLI, and the registry written at commit records each one.
+- **Data flows & communication** — how data moves between services, sync vs async, what each persists. Confirm the patterns and surface any the code makes ambiguous.
+- **Technology stack** — the datastores, brokers, auth providers, and any LLM provider the code reveals, with the obligations each imposes. Name an LLM provider and model explicitly if the system calls one — it is a first-class architectural fact.
+- **Capability ports & providers** — recover the technical capabilities the code already binds (an LLM client, a store, a messaging client, a telemetry exporter) and the provider satisfying each, with its observed operational footprint: a hosted API by key (`env`), a container in compose (`compose-service`), a native process (`runner`), or an interface with no implementation behind it (`none` — a bare interface the code stubs). Record capability → provider → footprint; this becomes the architecture's Capability Ports & Providers table (§3) and its machine twin. A capability the code declares but never implements is `none`, not a guess at a provider.
+- **Constraints & budgets** — the binding constraints inherited from the design system's non-functional requirements, plus any the infrastructure enforces (scale-to-zero, regional hosting, compliance posture visible in the code).
+
+Resolve ambiguity with the user rather than assuming past it.
+
+---
+
+## Stage 3: Recover Rationale & Gaps (the interview)
+
+Two distinct pursuits in one focused conversation:
+
+- **Rationale for ADR-worthy decisions.** For each significant decision the code reveals — the auth strategy, the messaging pattern, the database choice, a notable service boundary — ask the user *why* it was chosen and what alternatives were weighed. Where the user supplies real rationale, that decision earns an ADR. Where they cannot (the decision predates them, or was incidental), record the fact in `docs/architecture/index.md` and mint no ADR. An ADR without a genuine context-decision-tradeoff is noise.
+- **Delivery gaps.** Identify where the system diverges from a clean GroundWork service standard in ways that will hamper the bet loop. The sharpest: **a service exposes routes with no machine-readable contract** — the contract-driven bet loop cannot verify work against it. Flag these for the gap ledger at blocks-delivery severity. Also note off-pattern divergences (no transactional outbox where events cross services, missing health endpoints, no contract versioning) at standard-divergence severity.
+
+Capture out-of-phase signals under their headers in `.groundwork/cache/discovery-notes.md` (Protocol 1).
+
+---
+
+## Quality Standard: What "Deep Enough" Looks Like
+
+The recovered architecture must convey the *reasoning* the system embodies, not just inventory its parts. "Service A calls Service B over HTTP" is an inventory line. "The booking service calls the inventory service synchronously because a hold must fail closed — an async hold risks double-selling, which the domain cannot tolerate" is architecture. Recover the reasoning the structure implies, and confirm or correct it with the user. The depth bar matches greenfield: service boundaries explain what would break if the boundary moved; data flows explain the consistency model; technology choices carry their downstream obligations.
+
+---
+
+## Stage 4: Draft, Review & Present
+
+1. **Load the template.** Read `.groundwork/skills/groundwork-architecture/architecture-template.md` for the canonical section structure. Do not invent a structure.
+
+2. **Draft as per-section files** under `.groundwork/cache/architecture-extract-draft/`, one `write_file` per section, so any later edit touches only the affected file and never exhausts the output budget on a rich architecture:
+
+   | File | Content |
+   |---|---|
+   | `00-header.md` | The document title and intro (no summary section — the cross-phase contract is written separately to the Downstream Context file at commit, Protocol 5) |
+   | `01-constraints-and-budgets.md` | Template section 1 |
+   | `02-top-level-topology.md` | Template section 2 (the recovered service map) |
+   | `03-key-capabilities.md` | Template section 3 (technology decisions with rationale and obligations) |
+   | `04-component-boundaries.md` | Template section 4 |
+   | `05-communication-patterns.md` | Template section 5 |
+   | `06-service-level-requirements.md` | Template section 6 (the SLR table — every obligation a service must honour) |
+   | `07-surfaces-and-capability-core.md` | Template section 7: the core's deployment as observed (hosted or embedded) with its consequence for contract format, and one line per observed surface — type, access path, auth. Detail lives in `docs/surfaces.md` (written at commit); this section carries the facts |
+
+   Each section's heading starts at H2 to concatenate cleanly. Apply `groundwork-writer`.
+
+3. **Review.** Assemble: `run_command("cat .groundwork/cache/architecture-extract-draft/*.md > .groundwork/cache/architecture-extract-draft.md")`. Invoke the review subagent (Protocol 9) with `document_path: .groundwork/cache/architecture-extract-draft.md` and `document_type: architecture`. Fail-closed gate (Protocol 8): proceed only on `VERDICT: PRESENT`.
+
+4. **Revise loop.** On REVISE, apply all 🔴 Critical findings to the affected section file(s), re-assemble, and re-review. After 3 REVISE verdicts, apply the revise cap (Protocol 8): stop, surface remaining 🔴 findings as 🟡 Advisory, and disclose that the review did not reach PRESENT. The cap is a hard stop, not a target to push past. If the reviewer keeps finding fresh contract↔body desyncs every pass, the fault is an unreconciled Downstream Context file (Protocol 5: author it last at commit, from the finished doc), not a draft that needs five reviews.
+
+5. **Present** section by section (not the whole doc in one message), then surface 🟡 Advisory findings. Clean up the assembled file: `run_command("rm .groundwork/cache/architecture-extract-draft.md")`. Proceed to commit only on explicit approval.
+
+---
+
+## Stage 5: Commit
+
+Execute **only** after explicit user approval (Protocol 3.4):
+
+1. **Assemble** the final doc and **write its Downstream Context file.** `run_command("mkdir -p docs/architecture && cat .groundwork/cache/architecture-extract-draft/*.md > docs/architecture/index.md")` to produce the clean published doc (no summary section). If `docs/architecture/meta.json` is absent, seed the section's sidebar order — `{ "pages": ["index", "infrastructure", "domain", "services", "api", "decisions", "..."] }` — without clobbering an existing one. Then then write the Downstream Context file to `.groundwork/context/architecture-extract.md` (Protocol 5) via `groundwork-writer`: the four subsections (Key Decisions, Binding Constraints, Deferred Questions, Out of Scope), ≤200 words. Carry forward every binding user-facing constraint from the brief and design system into Binding Constraints — domain docs are reviewed against this Downstream Context file, so a constraint absent there is invisible.
+
+2. **Extract domain entities.** For every core entity the architecture owns (recovered from schemas, migrations, and models), write a stub to `docs/architecture/domain/<entity>.md` using `.groundwork/skills/templates/domain-entity.md`: what it is, core fields, lifecycle states with triggers, the owning service, events emitted. Create `docs/architecture/domain/` if absent.
+
+3. **Write ADRs — only where rationale exists.** For each decision the user supplied genuine rationale for in Stage 3, write an ADR to `docs/architecture/decisions/NNNN-<slug>.md` using `.groundwork/skills/templates/adr.md`: context, decision, trade-offs. Number sequentially from the existing `docs/architecture/decisions/`. Status `accepted`. **Do not write an ADR for a decision whose rationale you could not recover** — record that fact in `docs/architecture/index.md` instead.
+
+4. **Write the surface registry.** Create `docs/surfaces.md` following the contract at `.groundwork/skills/templates/surfaces.md`, projecting what the code shows: the Capability Core section (what the core owns, its deployment as observed, where its contracts live), and one Surface Registry entry per observed surface with `status: active` — these surfaces ship today, so the registry records each one, and one dropped here is invisible to design tracks, scaffolding, and parity tracking for the life of the product. Per entry: `core access` and `auth` as the code shows them; `scaffold: manual` — adopted surfaces were not generated, and `manual` is first-class; `test medium` as the fixture family the surface's type and platform imply (`playwright` for a web `graphical-ui`, `subprocess-cli` for a `cli`, `protocol-client` for an `agentic-protocol`) — infra adoption provisions the harness against it; `design track` pointing at the matching type section of `docs/design-system.md`. The Capability Ledger section is its table header with **no rows**, and the machine twin `.groundwork/surfaces.json` is written in the same step with an empty `capabilities` array — the two files are projections of the same facts and are always written together. Do not reverse-engineer capability rows from the code: a scanned ledger is confidently wrong where an empty one is honestly unknown — rows grow per-bet as validation touches capabilities, and infra adoption records this stance in the gap ledger. Write the registry even for a single-surface repo — one entry, and downstream phases read it.
+
+   In the same commit, write the **capability-ports registry** — `docs/architecture/index.md` §3 Capability Ports & Providers and its machine twin `.groundwork/capability-ports.json` per the contract at `.groundwork/skills/templates/capability-ports.md` — projecting the capability → provider → footprint facts recovered above. A capability the code declares but leaves unimplemented is recorded `provider: none, footprint: none` (a bare interface), never a fabricated provider. An empty `ports` array is legal for a repo with no technical capabilities.
+
+5. **Stamp drift-baseline frontmatter.** Add frontmatter to `docs/architecture/index.md` and each `docs/architecture/domain/<entity>.md`: `generation_mode: extracted`, `source_of_truth:` (the code paths each doc was reconstructed from — service roots, contract files, migration dirs), and `last_reviewed:` (today's date). This is what `groundwork-check` reads to detect drift between the extracted docs and the code they came from, and the `extracted` mode routes its recovery through `groundwork-doc-sync` rather than a generator re-run.
+
+6. **Review the domain stubs and ADRs.** Invoke the review subagent on each `docs/architecture/domain/<entity>.md` with `document_type: domain-entity`. The isolated reviewer checks each entity against the architecture's Downstream Context file and the accepted ADRs. Apply 🔴 findings and re-review until PRESENT. Fail-closed, revise cap applies (Protocol 8).
+
+7. **Append architecture gaps to the ledger** at `.groundwork/cache/gap-ledger.md` (create from `.groundwork/skills/templates/gap-ledger.md` if absent). This is the heaviest gap contribution: every missing machine-readable contract at blocks-delivery severity, every standard divergence at its tier, with the evidence path.
+
+8. **Write the hand-off** to `.groundwork/cache/handoff/architecture-extract.md` from the shared template: deferred decisions, recovered-but-unrecorded reasoning the infra phase needs, user instincts about the operational layer. Omit empty sections (Protocol 6).
+
+9. **Teardown.** Delete the consumed findings slice `.groundwork/cache/scan/architecture-findings.md`, the previous hand-off `.groundwork/cache/handoff/design-system-extract.md`, the draft directory, and the phase cache. Leave `scan/overview.md`, `scan-state.json`, and `repo-map.json` — infra adoption still reads them.
+
+10. Apply the Living Documents protocol — refine `docs/product-brief.md` or `docs/design-system.md` where the architecture conversation surfaced refinements, and refresh their live Downstream Context files where the change touched a Key Decision, Binding Constraint, or Deferred Question. If any update reverses a prior Key Decision or Binding Constraint, follow the Reversal Protocol: reconcile the full body and dependent docs, write the superseding ADR, and re-review every mutated doc.
+
+11. Update discovery notes — remove `## Architecture` and `## Design Details` entries now captured.
+
+12. Confirm completion, recommend a fresh context, and immediately load and execute `groundwork-orchestrator`. Do not ask the user to invoke it. Record nothing in `state.json` — the orchestrator infers this phase's completion from `docs/architecture/index.md` plus its Downstream Context file `.groundwork/context/architecture-extract.md` and the stamped `generation_mode`/`source_of_truth` frontmatter; only the scan writes a durable marker, because it leaves no `docs/` artifact.

package/src/hidden-skills/groundwork-architecture-extract/templates/architecture-extract-cache.md

@@ -0,0 +1,21 @@
+# Architecture Extract — Phase Cache
+
+> Resume state for `groundwork-architecture-extract`. Deleted at commit.
+
+- **Mode:** <!-- extract | adopt-upgrade -->
+- **Stage 1 — Ingest structure:** pending
+- **Stage 2 — Reconstruct & confirm:** pending
+- **Stage 3 — Recover rationale & gaps:** pending
+- **Stage 4 — Draft, review & present:** pending
+
+## Recovered structure
+
+<!-- Service map, boundaries, surfaces (every one, typed) and core deployment, data flows, stack — as confirmed. -->
+
+## ADR candidates
+
+<!-- Decisions the user supplied rationale for (→ ADR) vs decisions with no recoverable why (→ fact in architecture.md). -->
+
+## Gap-ledger candidates
+
+<!-- Missing contracts (blocks-delivery), standard divergences, with evidence paths. -->