groundwork-method 0.0.1 → 0.10.0

package/src/docs/principles/system-design/identity-and-access.md

@@ -0,0 +1,76 @@
+---
+title: Identity & Access
+description: Authentication and authorization as architecture — human identity on OIDC/OAuth 2.1, workload identity via SPIFFE, first-class agent identity, and authorization modeled rather than scattered.
+status: active
+last_reviewed: 2026-06-19
+---
+# Identity & Access
+
+## TL;DR
+
+Who may do what is an architectural decision made with the boundaries, not a middleware bolted on afterward. Humans authenticate through a proven OIDC/OAuth 2.1 provider; services authenticate each other with **workload identity** (SPIFFE/SPIRE short-lived SVIDs, mTLS through the mesh, no secret in code); and in an agent-led system, agents are **first-class non-human identities** with their own credentials and explicit delegation. Authorization is modelled once and enforced everywhere, not re-implemented per endpoint.
+
+## Why this matters
+
+Identity is where most breaches actually land — a stolen long-lived secret, an over-broad role, a service that trusted the network. And it is the hardest thing to retrofit: once authorization logic is scattered across handlers and the trust model is implicit, tightening it touches everything. Deciding identity and access at the architecture stage — the trust boundaries, the credential lifetimes, the authorization model — is far cheaper than discovering them during an incident. In 2026 the surface widened again: machines and agents now outnumber humans as actors, and each needs an identity the system can reason about.
+
+## Our principles
+
+### 1. Authn and authz are architecture
+
+The trust model — who is authenticated, how, and what each identity may do — is decided with the service boundaries, because it shapes every contract and data path. Authentication establishes *who*; authorization decides *what they may do*; we keep the two distinct and design both deliberately rather than letting them accrete in middleware.
+
+### 2. Human identity is boring and standard
+
+We do not invent auth. Humans authenticate through a proven identity provider over **OIDC / OAuth 2.1**; sessions and tokens follow current OWASP guidance. OAuth 2.1 is still a consolidating draft, but its substance is not in doubt — it folds the settled security best practice (RFC 9700) into the base spec: mandatory PKCE on every authorization-code flow, no implicit grant, no resource-owner password grant. Track those practices, not the RFC's publication date. Custom JWT handling, bespoke session cookies, and home-grown MFA are how teams learn about auth vulnerabilities the hard way.
+
+### 3. Workload identity is the service perimeter
+
+Services prove who they are with cryptographic **workload identity** — short-lived, auto-rotating credentials bound to the workload, mTLS between services, no secret in application code. Machine identity is the new perimeter; "it came from inside the network" authenticates nothing.
+
+How you *issue* that identity is a sizing decision, not dogma, and SPIFFE/SPIRE is not the default answer for everyone. If you already run a service mesh you already have SPIFFE-compatible identity — Istio issues X.509 SVIDs and mTLS by default — so the marginal cost is near zero. On a single cloud, the provider's own workload identity (IAM roles, workload identity federation, OIDC-federated tokens) gives you keyless, short-lived credentials with no new infrastructure to operate. Reach for SPIFFE/SPIRE directly when you span clouds or run off-mesh workloads that need *one* portable identity plane — and budget for it honestly: SPIRE is mature but non-trivial to run well. The anti-pattern is the static service API key in an env var, not "didn't deploy SPIRE."
+
+### 4. Authorization is modelled, not scattered
+
+Choose the model for the question you are actually answering. **Role-based (RBAC)** for coarse, stable job functions. **Relationship-based (ReBAC, the Zanzibar model)** when access follows the graph — "this user can see this document because it lives in a folder shared with a group they belong to" — which is exactly where RBAC dies of role explosion. **Attribute/policy-based (ABAC)** when the decision turns on context the subject doesn't carry: time, location, resource state. Most real systems combine them, and the practical path is one direction: start with roles, and reach for ReBAC the moment you catch yourself encoding sharing or hierarchy *as* roles.
+
+Enforce through one path, not a thicket of per-endpoint checks, and externalise shared or complex policy so the rules are inspectable. But externalising the *decision* is not the same as adding a network hop per request — a central policy service that every call must round-trip is both a latency tax and a new single point of failure. Distribute the engine (embedded library, sidecar, or local cache with a short TTL) so policy is authored centrally and evaluated locally, and reserve the synchronous call to a central decision point for genuinely sensitive, low-volume actions. Authorization copy-pasted across handlers is authorization that will be wrong somewhere; authorization behind one slow network dependency is an outage waiting to happen.
+
+### 5. Agent and non-human identity is first-class
+
+An automated actor — a service account, a CI job, an AI agent — has its own identity, not a borrowed human one. In an agent-led system this is load-bearing: an agent carries its own identity into every request, consequential tool calls are authorised per-action, and **delegation is explicit**. The mechanism is token exchange (RFC 8693): the issued token carries an `act` claim naming the actor, so the audit trail records *which* agent acted on *whose* behalf — and nested exchanges record the full chain when one agent calls another. MCP's authorization model builds on exactly this, layered on OAuth 2.1 + PKCE.
+
+Two gaps the standards are still closing, which you must design around rather than assume away. First, PKCE protects the exchange but does **not** authenticate the client — a non-human client's identity has to be asserted by the infrastructure it runs on, which is precisely what workload identity (principle 3) provides; agent identity and workload identity are the same problem at two altitudes. Second, classic OAuth has no front-channel way to capture a user's *explicit consent* for an agent to act for them; in-flight IETF on-behalf-of-user drafts add a `requested_actor`/`actor_token` flow for this, but until they land, treat consent for consequential agent delegation as something you design explicitly, not something the protocol hands you. An agent with a shared admin key is excessive agency by another name.
+
+### 6. Least privilege, short-lived credentials
+
+Every identity — human, workload, or agent — starts with the minimum it needs and is widened only on evidence. Credentials are short-lived and auto-rotated by default; a static, long-lived secret is a breach with a long fuse. Short-lived is necessary but not sufficient: a bearer token is replayable by anyone who captures it for as long as it lives, so bind tokens to their holder — sender-constrained via DPoP or mTLS, as the OAuth Security BCP (RFC 9700) and OAuth 2.1 now recommend — so a stolen token is useless off the key it was issued to. Roles and scopes are reviewed the way code is reviewed.
+
+### 7. Tenant isolation is an identity boundary
+
+In a multi-tenant system, the tenant is part of every identity and every authorization decision, enforced at the data boundary, not assumed from a query parameter. Cross-tenant access is the highest-severity failure class; the identity model is where it is prevented.
+
+## How we apply this
+
+The architect decides the trust model, the identity mechanisms, and the authorization model with the boundaries; the engineer skills implement them, and the security perimeter ([Security](../quality/security.md)) is where they are stress-tested. Workload identity and the policy engine are shared infrastructure, not per-service code.
+
+- [Security & Trust](../quality/security.md) — the perimeter identity sits inside.
+- [Agentic Systems](../ai-native/agentic-systems.md) — agent identity, delegation, per-action authorization.
+
+## Anti-patterns we reject
+
+- **Implicit network trust.** "It's an internal call, it's authenticated." It is not.
+- **Long-lived static secrets.** A shared service key in an env var is a breach waiting for its trigger.
+- **Scattered authorization.** Per-endpoint permission checks that drift out of agreement.
+- **Borrowed identity for machines.** A bot or agent acting as a human admin, with no trace of who really acted.
+- **Invented auth.** Custom JWT / session / MFA instead of the battle-tested standard.
+- **Tenant-by-query-param.** Trusting a client-supplied tenant id instead of binding it to the authenticated identity.
+
+## Further reading
+
+- *OAuth 2.1* and *OpenID Connect* — the standard human-auth stack.
+- *OAuth 2.0 Security Best Current Practice*, RFC 9700 — sender-constrained tokens, PKCE, the rules OAuth 2.1 folds in.
+- *OAuth 2.0 Token Exchange*, RFC 8693 — delegation and the `act` claim behind on-behalf-of.
+- *SPIFFE/SPIRE* (CNCF) — workload identity and short-lived SVIDs.
+- *Zero Trust Architecture*, NIST SP 800-207 — identity as the perimeter.
+- *Zanzibar*, Google — the model behind relationship-based authorization (OpenFGA, SpiceDB).

package/src/docs/principles/system-design/integration-patterns.md

@@ -0,0 +1,84 @@
+---
+title: Integration Patterns
+description: Webhooks, the outbox pattern, idempotency, and the sync-vs-async trade-off.
+status: active
+last_reviewed: 2026-06-19
+---
+# Integration Patterns
+
+## TL;DR
+
+Services integrate through a small set of well-understood patterns: synchronous request/response for reads and strict writes, asynchronous events for everything else, the transactional outbox for "database and event must agree," webhooks for pushing to third parties, and idempotency everywhere. We pick the pattern based on the guarantee the integration needs, not on whatever felt easy at the time.
+
+## Why this matters
+
+Most production incidents trace back to an integration that chose the wrong consistency model. A synchronous call where an async event belonged, an event without idempotency, a "fire and forget" webhook that silently dropped on a retry. Integration patterns are one of the few areas where the cost of getting it wrong is paid every day, forever, in an intermittent stream of weirdness. Getting them right means thinking about guarantees explicitly, not architectural fashion.
+
+## Our principles
+
+### 1. Choose by coupling, not by transport — and async is not free decoupling
+
+Between services, async events are our default, because a synchronous call binds the caller's availability and latency to the callee's. But the rule that earns its keep is *choose by the guarantee, not the transport*. Respected practitioners default the other way — sync is simpler to build, trace, and reason about, with no eventual-consistency semantics to explain to consumers — and they are right that async-by-default, applied thoughtlessly, buys a distributed monolith: the same request/reply shape over a queue, now with worse debugging. Async only decouples when the caller genuinely stops needing the result inline. Request/reply over a broker is synchronous coupling with extra steps and no inline answer.
+
+Decision rule: stay synchronous when the caller needs the result to proceed (most user-facing reads) or needs the write committed before it continues (strict writes), and when caller and callee share a team and a release cadence. Go async when the work can complete after the caller returns, when the consumer set is open or changing, or when you need load-leveling between a fast producer and a slow consumer. If the design is "send a message, then block waiting for the reply," that is sync — build it as sync.
+
+### 2. The outbox pattern solves the dual-write problem — pick the relay deliberately
+
+When a state change requires both a database write and an event, and we need both or neither, publishing to the broker after the DB commits is a *dual write*: a crash between the two steps leaves the system permanently inconsistent, and at scale it will happen. The fix is to make the event part of the same transaction — write it to an `outbox` table inside the state-change transaction, then relay the outbox to the broker.
+
+How the relay reads the outbox is a real choice, not a detail. A polling relay is the simplest correct option and right for moderate volume. Log-based change data capture (Debezium tailing the write-ahead log) removes both the polling load and the polling latency, at the cost of running and operating a CDC pipeline. The two compose: CDC *over the outbox table* gives near-real-time relay with a clean, app-controlled event schema, instead of streaming raw table changes and coupling every consumer to your column layout. Decision rule: poll until its load or latency is the thing that hurts, then move to CDC over the outbox table; reach for raw-table CDC only when the source genuinely is the table (replication, search indexing), not a domain event.
+
+### 3. Every consumer is idempotent
+
+Every message handler — webhook receiver, message broker worker, retry-on-failure task — is idempotent. It either carries its own de-duplication key or it operates on keys that make replay safe (an `UPSERT` on a natural key, a conditional update guarded by a version). "At-least-once delivery" is the only delivery guarantee we ever get, and idempotent handling is the only response that works.
+
+### 4. Retries have policies, not just defaults
+
+Every retry policy has an explicit maximum, an explicit backoff curve *with jitter*, and an explicit dead-letter destination. "Retry forever with 1-second backoff" is not a policy — it is how a transient failure becomes a thundering herd, and backoff without jitter just re-synchronizes that herd on the next tick. Cap the aggregate, too: retries should consume only a small, bounded fraction of total traffic (a *retry budget*), or one slow dependency turns every caller into an amplifier. Retries that hit the dead-letter queue fire an alert; the queue is not a garbage bin.
+
+### 5. Webhooks follow the Standard Webhooks shape
+
+Don't reinvent webhook security; follow the Standard Webhooks spec. Sign with HMAC-SHA256 over `id.timestamp.body`, never a shared secret in a query string. Carry a stable event id (so receivers de-duplicate) and a timestamp (so receivers reject anything outside a short replay window). Support key rotation — multiple active signing keys, published via JWKS for asymmetric setups — so a key can be retired without downtime. Surface a retry history to the sender, and outbound, sign exactly as you expect inbound to be signed. A CloudEvents-shaped payload keeps producer and consumer honest about envelope vs. data. An unsigned webhook is not a webhook; it is an unauthenticated POST endpoint.
+
+### 6. Timeouts are end-to-end budgets
+
+Every synchronous call has a timeout, and the timeout is allocated from a *budget* set by the outermost caller. A request with a 2-second budget at the edge does not get to spend 1.5 seconds on a single downstream call — that leaves no slack for retries, for the handler itself, or for the next downstream. Budgeting is a cooperative discipline; without it, tail latencies compound unpredictably ([Performance](../quality/performance.md)).
+
+### 7. Circuit breakers cut both ways — prefer retry budgets for overload
+
+The classic circuit breaker opens after a threshold of failures, fast-fails while open, and probes periodically for recovery. It earns its place against a *binary* dependency — one downstream, all-or-nothing — where fast-failing beats tying up threads on an inevitable timeout. But Marc Brooker's critique holds: a breaker is designed to turn partial failure into total failure, and in a sharded or cell-based system it cannot distinguish "the dependency is down" from "one partition is down," so it either degrades every caller or might as well not exist. A tripped breaker also slows recovery and complicates testing.
+
+Decision rule: for overload — the common case — cap retries with a token bucket or retry budget and shed load at the source, rather than swinging a global breaker. Reserve the breaker for genuinely all-or-nothing dependencies, and scope it per-partition, never across a whole sharded fleet.
+
+### 8. Every integration has a contract test
+
+A test that exercises the real integration — the real signature verification, the real retry curve, the real idempotency behaviour — runs in CI against an emulator. "It works in the happy path" is not a test; an integration that has only happy-path coverage is an incident waiting for its trigger.
+
+### 9. Multi-step flows: choreography, orchestration, or durable execution
+
+Step count is a weak proxy; the real axis is who owns the end-to-end outcome. Choreography — each service reacts to events and emits its own — keeps services loosely coupled but makes the overall flow implicit: no single place shows what is supposed to happen or where it stalled, and that cost grows with every step and branch. Orchestration puts one coordinator in charge of the sequence and its compensations, buying visibility and explicit failure handling at the price of a central coupling point.
+
+Decision rule: choreography when the steps are genuinely independent reactions with no shared deadline or rollback; orchestration when there is a real business transaction — ordering, compensation, a timeout that spans steps. For anything long-running, multi-step, or compensating, reach for durable execution (workflow-as-code) rather than hand-assembling outbox + idempotency + retry + sweeper for the hundredth time ([Durable Execution](durable-execution.md)).
+
+## How we apply this
+
+- [Reliability](../quality/reliability.md) — the broader system-level treatment of failure modes.
+- [Testing](../foundations/testing.md) — the contract-testing discipline.
+
+## Anti-patterns we reject
+
+- **Sync chains three deep.** Service A calls B calls C calls D. Every failure mode in the chain is now a failure mode for A.
+- **Async that is secretly sync.** Request/reply over a queue where the caller blocks for the response. You paid the full eventual-consistency and debugging tax and bought none of the decoupling.
+- **"Fire and forget" webhooks.** No signature, no retry, no idempotency. Works once; the next incident it causes is unfixable from the outside.
+- **Commit-and-then-publish.** Without the outbox, the dual write will leave the system inconsistent every time a process dies between steps. It will happen.
+- **Global retry policies.** "All HTTP calls retry 3 times with 1-second backoff." What matters is the *specific* downstream's failure profile, the caller's latency budget, and a cap on retries as a fraction of traffic.
+- **Dead-letter queues as logs.** If the DLQ is silently accumulating, integration is not working; it is just failing quietly. Alert and act.
+
+## Further reading
+
+- *Release It!*, Michael Nygard — the canonical treatment of stability patterns (circuit breakers, bulkheads, timeouts).
+- *Enterprise Integration Patterns*, Hohpe & Woolf — old but foundational; the vocabulary most of this page inherits.
+- *Microservices Patterns*, Chris Richardson — a practical mapping of these patterns onto a modern service architecture.
+- Pat Helland, "Life Beyond Distributed Transactions" — the paper that made the outbox pattern obvious in retrospect.
+- Marc Brooker, "Will circuit breakers solve my problems?" — why breakers turn partial failures into total ones, and the case for retry budgets under overload.
+- The Standard Webhooks spec (standardwebhooks.com) — the interoperable signing, replay-window, and verification shape worth adopting rather than reinventing.

package/src/docs/principles/system-design/real-time.md

@@ -0,0 +1,83 @@
+---
+title: Real-Time
+description: WebSockets, streaming, backpressure, and the patterns that make live experiences survive a degraded network.
+status: active
+last_reviewed: 2026-06-19
+---
+# Real-Time
+
+## TL;DR
+
+Real-time features are long-lived bidirectional contracts between client and server, not request-response interactions. They must survive reconnection, handle backpressure without losing state, and never treat the network as a guarantee. Every real-time feature we ship is designed against the assumption that the connection will drop mid-flight.
+
+## Why this matters
+
+The difference between a real-time product that feels smooth and one that feels broken is almost always the difference in how the implementers thought about failure modes: reconnection, duplicated messages, out-of-order delivery, and backpressure. Getting real-time right is less about picking a protocol and more about having a disciplined stance on those failure modes.
+
+## Our principles
+
+### 1. Transport is a per-direction decision
+
+**SSE** is the default for server→client streaming — auto-reconnecting (via `Last-Event-ID`), CDN-friendly, no sticky sessions, plain HTTP — and it is the streaming substrate for AI (MCP and LLM token delivery ride it; OpenAI and Anthropic both stream tokens over SSE). Its real constraints are worth knowing at design time, not discovering in production: SSE is text-only, and over HTTP/1.1 a browser caps concurrent connections per origin at six, so several open tabs starve each other — serve it over HTTP/2+ where streams multiplex over one connection. The native `EventSource` API also cannot set request headers, so carry auth in a cookie or use a `fetch`-based SSE reader when you need an `Authorization` header.
+
+**WebSockets** are for genuinely bidirectional connections where the client also pushes frequently — collaborative cursors, typing, mid-stream control. Reaching for a WebSocket to push a one-way stream is over-engineering.
+
+**Long-polling** is not a primary transport and we never design around it. But it is the universal floor: it traverses every proxy, WAF, and corporate firewall ever shipped, because all of them understand plain request-response HTTP. On hostile networks that break persistent connections, long-polling is the legitimate degraded fallback (the Socket.IO model: attempt the upgrade, fall back when it fails). Rejecting it outright costs you the users behind the worst networks.
+
+Decision rule: one-way server→client → SSE over HTTP/2; client pushes frequently mid-stream → WebSocket; datagram or multiplexed-stream workloads (media, gaming, high-fanout) → consider WebTransport (§9); and keep long-polling as the fallback only when you must serve clients on networks you do not control.
+
+### 2. Every message carries a sequence number
+
+Every event on the wire carries a monotonic sequence. The client can detect gaps; the server can detect duplicates; the pair of them can resynchronise after a reconnect without the client having to refetch everything. Sequence numbers are per-session, not global.
+
+### 3. Reconnection is the normal case, not the error case
+
+Clients reconnect with exponential backoff, jitter, and a resumption token that tells the server where they left off. "Reconnected" is logged, not paged. If a reconnection rate spikes, that is a signal about network or server health — not a client bug.
+
+### 4. Backpressure is explicit
+
+When the server is producing faster than the client is consuming, the server either **sheds** (drops non-critical messages, logs the shed rate), **coalesces** (merges consecutive updates into a single event), or **blocks** (applies flow control). What it does *not* do is buffer unbounded. Buffering unbounded is how a real-time service dies.
+
+### 5. Echo suppression is a design concern
+
+In streaming scenarios where a client's own output may be re-ingested as incoming events, the suppression mechanism — whether it is a sender ID on the stream, a per-session filter at the gateway, or client-side gating — is part of the protocol design, not a bolt-on fix. Echo handling is specified before the first line of code.
+
+### 6. Idempotent handlers
+
+The client will reconnect and resend. The server must handle the resend gracefully — the same sequence number processed twice has no additional effect. This is the same principle as HTTP idempotency keys ([API Design](api-design.md)), applied to the streaming surface.
+
+### 7. Observability is unbroken across the socket
+
+A trace that enters via HTTP, opens a WebSocket, streams many events, and closes — all of it belongs to the same trace. OTel instrumentation propagates the trace context into the socket, and every event carries it forward. A broken real-time trace is a test failure, not a nuisance (see [Testing](../foundations/testing.md)).
+
+### 8. Client state is recoverable, not sacred
+
+Any state held on the client that matters must be recoverable from the server. We do not rely on the client's in-memory view surviving. If the client crashes or navigates away, rejoining the session should produce the same observable state — the server is the source of truth.
+
+### 9. LLM streaming and local-first collaboration
+
+The canonical AI real-time pattern is **SSE for the token data-plane** plus a WebSocket (or internal gRPC) **control-plane** for cancel and feedback injection — its failure modes (slow first token, partial-response loss on a provider retry, backpressure stalls) extend the ones above.
+
+For multi-user editing the live debate is **OT vs CRDT**, and it is a genuine fork, not a settled question. **OT** (operational transformation — what Google Docs runs on) keeps the server authoritative: clients send operations, the server transforms and orders them, and steady-state memory is just the current document. It is lean on the wire but demands a reliable central coordinator and notoriously fiddly transform logic. **CRDTs** (Yjs, Automerge) push merge rules into the data structure so replicas converge with no coordinator — the local copy is the source of truth and edits survive disconnection — at the cost of metadata overhead from tombstones and version vectors (even columnar-encoded Automerge runs well above raw-text size). Decision rule: server-authoritative editing against a reliable backend → OT is leaner; offline-first, peer-to-peer, or local-first where clients edit while disconnected → CRDT earns its overhead. This is also the principled home for echo suppression and recoverable state.
+
+**WebTransport** crossed into Baseline in March 2026 when Safari 26.4 shipped it, joining Chrome, Edge, and Firefox. It is now a real option for datagram and multiplexed-stream workloads where head-of-line blocking hurts. It does not replace SSE for token streaming, and because it rides QUIC/UDP it can be blocked on corporate networks that permit only TCP — ship it with a WebSocket or HTTP fallback path, never as the sole transport.
+
+## How we apply this
+
+- [Reliability](../quality/reliability.md) — the broader resiliency patterns these principles sit inside.
+- [Observability](../quality/observability.md) — how we trace across streaming connections.
+
+## Anti-patterns we reject
+
+- **Treating the socket as a fire-and-forget event bus.** No sequence numbers, no resumption, no idempotency. Works in demos; breaks in production.
+- **Per-connection unbounded buffers.** A slow client should not kill the server's memory. Shed, coalesce, or block.
+- **Reconnect-then-refetch-everything.** If the full state refresh is the recovery strategy, the protocol is broken. Use resumption tokens.
+- **Ad-hoc event schemas.** Real-time events are contracts. They belong in AsyncAPI specs, versioned, generated.
+- **Client-side reconciliation of echoes.** Echo suppression on the client is a fallback, not a design. Handle it at the gateway where the full context is available.
+
+## Further reading
+
+- *Designing Data-Intensive Applications*, Martin Kleppmann — the chapters on streaming, ordering, and exactly-once semantics.
+- *The Little Book of Semaphores*, Allen B. Downey — the fundamentals of flow control.
+- *High Performance Browser Networking*, Ilya Grigorik — the chapters on WebSocket and real-time transports.
+- The WebSocket RFC (RFC 6455) — worth reading at least once if you are going to build on top of it.

package/src/docs/principles/system-design/surface-architecture.md

@@ -0,0 +1,74 @@
+---
+title: Surface Architecture
+description: Architecting the surfaces that sit over a headless capability core — the backend-for-frontend seam, surface decomposition, render placement, and the design system as a contract.
+status: active
+last_reviewed: 2026-06-19
+---
+# Surface Architecture
+
+## TL;DR
+
+A surface — web app, mobile app, CLI, desktop, an agent UI — is an adapter over the capability core, not a place for business logic. Its architecture is about the **seam**: how the surface reaches the core (a backend-for-frontend that shapes contracts to that surface), how a large surface is decomposed without sprawling, where rendering runs, and how the design system serves as a shared contract. Get the seam right and the surface stays thin, replaceable, and consistent with every sibling surface.
+
+## Why this matters
+
+The most common way a system rots from the front is by letting business logic leak into the surface — validation rules, pricing, state machines re-implemented in a component because the API "didn't quite return the right shape." Now the rule lives in two places and they drift. The discipline of surface architecture is to keep the core authoritative and the surface an adapter: rendering, interaction, and orchestration of contracts, nothing more. That is also what lets a second surface (a mobile app, a CLI, an agent) be added without re-deriving the domain.
+
+## Our principles
+
+### 1. Surfaces are adapters over the core
+
+A surface renders state and orchestrates calls to the core's contracts; it holds no domain rules. The capability core owns business logic and is designed headless and validated with no surface running. If a rule has to be true on every surface, it lives in the core — a surface that re-implements it is a drift waiting to happen.
+
+### 2. The backend-for-frontend shapes the contract per surface
+
+A **BFF** adapts the core's contracts to what one surface actually needs — aggregating, trimming, and reshaping so the client is not stitching together six calls or over-fetching a viewport's worth of data. The unit is the *user experience*, not the device: a single web app serving customers, partners, and admins may warrant three BFFs, not one (Sam Newman's distinction). React Server Components are a built-in BFF for a web surface — the server-component tree *is* the aggregation layer.
+
+The contested part is whether you need a separate BFF tier at all. You do not when there is one surface, when the core's contract is already flexible enough to let each client select and embed what it needs, or when GraphQL federation lets the client shape its own query — a dedicated BFF there is just another tier to operate. Reach for one when surfaces diverge sharply in their data needs, when chatty round-trips or over-fetching hurt, or when frontend and backend teams keep colliding on contract changes. Either way the BFF is an adapter, not a second core: the moment business rules accrete there you have built a shadow core, and a little duplication between BFFs is cheaper than the coupling you recreate by merging them back into one general-purpose tier.
+
+### 3. Render on the server and at the edge by default
+
+Push rendering and data assembly to the server; ship the client the least work it can do. Server-first rendering flattens latency, shrinks the JavaScript payload, and concentrates the server/client boundary in one place instead of scattering fetch logic through the component tree.
+
+This is a default, not a dogma. Server Components add a real boundary to reason about — no `useState`, `useEffect`, or context on the server — and they are a poor fit for surfaces dominated by continuous client interaction: complex editors, real-time collaborative canvases, local-first apps that must run offline. There the state lives on the client by nature, and forcing it through the server buys latency and complexity for nothing. The decision rule: render on the server when the surface is content- and navigation-shaped — the data changes between requests, not between keystrokes — and keep state on the client when interaction is continuous and local. Most surfaces are both: render the shell and the data-bound regions on the server, island the interactive parts.
+
+The *edge* is a separate, narrower call. It wins for latency-sensitive work that needs little or no data — auth, redirects, personalization, A/B splits — and loses when the render needs the database, because the edge node is far from your data and the round-trips dominate. Put compute at the edge only when it sits close to what it reads.
+
+### 4. Decompose a large surface by domain, right-sized
+
+A surface decomposes the way services do — by bounded domain, only when teams or load genuinely demand it. The driver is organizational, not technical: **micro-frontends** earn their cost when independent teams must build, test, and deploy parts of one surface on their own cadence. Absent that, a single well-structured surface — a "modular monolith" front-end with strict internal module boundaries — is simpler and correct, and it is where the field has settled: the State of Frontend survey reports self-described micro-frontend use falling from roughly 75% in 2022 to 24% in 2024 as teams found the DevOps overhead outran the benefit. The distributed-monolith failure mode has a front-end twin: many micro-frontends that must deploy in lock-step. Module Federation, the main micro-frontend mechanism, is increasingly used *inside* a monolith to update parts independently — proof the runtime tool is useful without the team-splitting topology.
+
+### 5. The design system is architecture
+
+The design system — tokens and components — is a contract between every surface, not decoration. It is versioned, it is the single source of visual and interaction truth, and a surface consumes it rather than re-inventing it. Design-system-as-architecture is what keeps ten screens and three platforms feeling like one product.
+
+### 6. The contract presumes no surface
+
+The core's contract serves every surface and presumes none — a session assumption baked into a response, markup where data belongs, or pagination sized to one viewport is the bug the next surface hits. An agent driving the interface (via **AG-UI**) is itself a surface type, and the most demanding test of a surface-neutral contract.
+
+### 7. Accessibility and performance are architectural budgets
+
+A surface ships against committed budgets — interaction latency, bundle size, accessibility floors — enforced in CI, because they are properties of the architecture, not polish applied at the end. A surface that meets its budget only on a fast laptop has no budget.
+
+## How we apply this
+
+The architect owns the *seam* — the core/surface boundary, the BFF, the decomposition decision, render placement. The design system's content and the surface's UI implementation belong to the design-system and surface-engineer skills; this reference decides where the line sits, not how the button looks.
+
+- [How We Structure Code](code-structure.md) — the surface is a driving edge over the core.
+- [API Design](api-design.md) — the surface-neutral contract the BFF adapts.
+- [Agentic Systems](../ai-native/agentic-systems.md) — agent-driven surfaces and AG-UI.
+
+## Anti-patterns we reject
+
+- **Business logic in the surface.** A pricing rule in a component. It will drift from the core.
+- **The fat BFF.** A backend-for-frontend that grows its own domain rules and becomes a shadow core.
+- **Micro-frontends by default.** Distributing one surface across teams that don't need it, then deploying them in lock-step.
+- **The re-invented design system.** Each screen styling its own buttons; consistency dies one component at a time.
+- **Viewport-shaped contracts.** A response only the current web layout can consume, which the mobile app and the agent cannot.
+- **Client-heavy by reflex.** Shipping a megabyte of JavaScript to render what the server could have sent as HTML.
+
+## Further reading
+
+- *Backend for Frontend*, Sam Newman — the BFF pattern and its boundaries.
+- *Micro Frontends*, Luca Mezzalira — decomposition of large front-ends, and when not to.
+- *Design Systems*, Alla Kholmatova — the design system as a shared, versioned contract.

package/src/docs/ways-of-working/documentation.md

@@ -0,0 +1,69 @@
+---
+title: Documentation Protocol
+description: How GroundWork keeps documentation current — Living Documents, doc hierarchy, and groundwork-check.
+status: active
+last_reviewed: 2026-05-26
+---
+
+# Documentation Protocol
+
+## The Living Documents Protocol
+
+All `docs/` artifacts are living documents. Any phase of any bet that surfaces new information that refines an existing document updates that document immediately, before moving on. This is not optional — stale docs are worse than no docs.
+
+The direction does not matter:
+
+- A bet can update the product brief.
+- Architecture can update the design system.
+- Delivery can update architecture.
+- A user interview can update everything.
+
+Updates are surgical and targeted. Change only what new information warrants. Do not rewrite sections that remain accurate. Do not ask for permission — these are refinements consistent with decisions already made. After updating, report what changed and why.
+
+## The Document Hierarchy
+
+Every GroundWork project contains a defined set of documents. Each has a different ownership model.
+
+**`docs/principles/**` and `docs/ways-of-working/**`** — project-owned from the moment they are deployed. Edit freely to match your team's practices. These documents describe how your team works and what your team values. GroundWork seeds them; your team owns them.
+
+**`docs/product-brief.md`, `docs/design-system.md`, `docs/architecture/index.md`** — owned by the product and architecture. Updated via the relevant GroundWork skill when significant new information surfaces. Do not edit these ad hoc. Changes go through the skill so that discovery notes, operating contract protocols, and downstream consistency checks are applied.
+
+**`docs/architecture/domain/<entity>.md`** — created by the architecture phase, extended by bet planning. Each bet that touches a domain entity updates its stub. Domain stubs are the contract between teams working on different components of the same entity.
+
+**`docs/architecture/decisions/NNNN-<slug>.md`** — append-only. Never edited after acceptance. To revise a decision, write a new ADR that supersedes the old one. The superseded ADR's `status:` field is updated to reference the new one; its content is never changed.
+
+**`docs/bets/<slug>/`** — immutable once a bet is committed. These are historical records. They document what was decided, why, and on what terms. Do not edit committed bet documents.
+
+## How groundwork-check Works
+
+`groundwork-check` detects documentation drift — the state where docs describe the system differently from the code. Run it in CI or on demand.
+
+What it flags:
+
+- Docs that describe the system differently from the code — mismatched API signatures, schema fields, service names.
+- `docs/architecture/domain/` entities missing from the codebase, or codebase domain concepts with no corresponding stub.
+- `docs/architecture/decisions/` numbering gaps or invalid status values.
+
+What it does not flag:
+
+- `docs/principles/**` and `docs/ways-of-working/**` are not checked for code drift — these are project-stable documents not derived from code. groundwork-check does flag `last_reviewed` ages above 12 months as a low-severity advisory to prompt periodic review.
+
+When groundwork-check flags something: investigate, do not suppress. Fix the doc or fix the code — the mismatch is the bug. Suppressing a drift flag leaves the system in an unverifiable state.
+
+## Docs and Skills
+
+Docs are for humans and project state. Skills are how agents act on them.
+
+Skills read docs to understand the current system. Docs record what the skills have built. They are complementary, not redundant. A skill that writes a bet plan reads `docs/architecture/index.md` to understand service boundaries — that reading depends on the architecture doc being current. A doc that describes a domain entity accurately depends on the architecture skill having updated it after the last bet touched it.
+
+The Living Documents protocol is what keeps this relationship coherent. When it breaks — when a skill writes code that the docs do not reflect — groundwork-check surfaces the gap.
+
+## ADR Conventions
+
+**When to write one**: Any decision a future engineer should not relitigate without a new ADR. Significance test: would someone joining six months from now need to know this to avoid repeating the decision? If yes, write an ADR.
+
+**How to write one**: Use the template at `.groundwork/skills/templates/adr.md`. Number sequentially with zero-padded four digits: 0001, 0002, 0003. The slug is a short hyphenated description of the decision.
+
+**How to supersede**: Change `status:` to `superseded by [NNNN](NNNN-slug.md)` and add a note at the bottom explaining what changed and why. Never edit an ADR's content after acceptance. Supersede it instead.
+
+**What goes in the decision record**: the context (what forced the decision), the decision itself, the consequences (what this enables and what it closes off). Do not document options that were not seriously considered — decision records are not design documents.

package/src/docs/ways-of-working/how-we-work.md

@@ -0,0 +1,76 @@
+---
+title: How We Work
+description: The GroundWork lifecycle — Setup, Delivery Loop, and Living Documents.
+status: active
+last_reviewed: 2026-05-26
+---
+
+# How We Work
+
+GroundWork is an AI-driven framework that enforces **Upfront Technical Delivery**: software is meticulously designed, contracted, and verified *before* code is written, eliminating "just-in-time" engineering.
+
+## The GroundWork Lifecycle
+
+GroundWork operates in two modes: **Setup** (one-time) and **Delivery Loop** (ongoing).
+
+### Setup
+
+A greenfield setup runs six phases in sequence, each producing a canonical document the next phase depends on:
+
+| Phase | Skill | Output |
+|---|---|---|
+| 1. Product Brief | `groundwork-product-brief` | `docs/product-brief.md` |
+| 2. Design System | `groundwork-design-system` | `docs/design-system.md` |
+| 3. Architecture | `groundwork-architecture` | `docs/architecture/index.md` |
+| 4. Scaffolding | `groundwork-scaffold` | `docs/architecture/infrastructure.md` |
+| 5. MVP Planning | `groundwork-mvp` | `docs/bets/<slug>/pitch.md` |
+| 6. First Bet | `groundwork-bet` | First delivered feature; enters Delivery Loop afterwards |
+
+Every setup phase commits to its final document, then hands off to the orchestrator, which routes to the next incomplete phase. The MVP→Bet handoff is the one exception that preserves context across the transition — the rich greenfield discovery feeds directly into the first bet without a context reset.
+
+Brownfield projects (initialising GroundWork against an existing codebase) are on the roadmap. They are not currently implemented.
+
+### Delivery Loop
+
+After the first bet ships, the project enters an ongoing cycle. Every bet runs `groundwork-bet`'s five phases:
+
+| Bet Phase | Purpose |
+|---|---|
+| Discovery | Shape the problem into a Pitch — problem statement, appetite, solution sketch, success signal, and explicit no-gos. |
+| Design Foundations | Produce the technical design contract: interface design, data flows, API contracts, and data schema. The design is locked before any decomposition begins. |
+| Decomposition | Break the bet into milestones and slices; author bet-progress tests from the locked design. Tests are written red, up front. |
+| Delivery | Turn bet-progress tests green, slice by slice. All APIs must be documented in machine-readable format (OpenAPI/protobuf/AsyncAPI) by end of delivery. |
+| Validation | Run the full test suite, archive the bet-progress suite, apply Living Documents updates to upstream docs, and seed the next bet via discovery notes. |
+
+Discovery produces a **Pitch**. When the team decides to execute the Pitch, it becomes a **Bet** — active from that moment through Validation. Multiple Pitches may exist at once; committing to one converts it to the active Bet.
+
+**Roadmap:** A Betting Table will support queuing and prioritising multiple Pitches before committing to one. The current implementation takes one Pitch at a time.
+
+All `docs/` artifacts are living documents. They grow as the project learns. Any phase, any bet, any conversation: if new information surfaces that refines an existing document, update it immediately.
+
+## The Operating Contract
+
+All methodology skills share a single set of behavioral protocols defined in the Operating Contract (`operating-contract.md`). These protocols govern:
+
+- **Discovery Notes**: How out-of-phase signals are captured under a canonical 5-section header set (`## Product Brief`, `## Design System`, `## Architecture`, `## Design Details`, `## Bets`) and carried forward to the phase that needs them.
+- **Living Documents**: How any phase or bet updates upstream `docs/` artifacts when new information warrants — surgically, without asking permission, with a report of what changed.
+- **Phase Lifecycle**: How each phase initialises (checks cache and discovery notes), executes (works through its stages), commits (writes the final artifact, runs Living Documents scan, updates discovery notes), and hands off.
+
+Every methodology skill loads and follows the Operating Contract. The protocols are defined once and referenced everywhere — never duplicated.
+
+## The Philosophy: Upfront Technical Delivery
+
+GroundWork explicitly rejects the common AI-assisted workflow of "just start coding and figure it out." Instead, it operationalises a disciplined progression:
+
+1. **Pitch**: Every bet begins with a problem statement bounded by an appetite (an opportunity-cost judgment of how much time the work is worth). A Pitch includes a falsifiable success signal — a measurable outcome that confirms the bet delivered its intended value.
+2. **Design First**: Before any decomposition begins, Design Foundations produces the technical contract — interface design, data flows, API contracts, and data schema. This is the document Decomposition and Delivery execute against.
+3. **Tests-Up-Front**: With the design locked, Decomposition authors bet-progress tests derived from the design contract — failing tests that define exactly what "done" means for each milestone and slice. These are Proof of Work.
+4. **Constrained Delivery**: Implementation turns bet-progress tests green, slice by slice. All APIs must be documented in machine-readable format (OpenAPI, protobuf, or AsyncAPI) by the end of delivery — clients are generated from this documentation. Discovering a flaw in the contracts means pausing, reverting to Design Foundations, updating, and re-approving — not improvising.
+5. **Validation & Living Documents**: After tests pass, upstream docs are surgically updated to reflect what the bet delivered. The architecture, brief, design system, and infrastructure documents continue to describe the system as it is.
+
+If a developer cannot implement the API contracts purely from the Architecture and Design Foundations artifacts, those artifacts are incomplete. **GroundWork builds the map before it drives the car.**
+
+## Where to Go Next
+
+- [Units of Work](units-of-work.md) — the delivery vocabulary: what a Bet, Milestone, and Slice are and how they nest.
+- [Documentation Protocol](documentation.md) — how Living Documents work in practice, the document hierarchy, and how `groundwork-check` detects drift.

package/src/docs/ways-of-working/units-of-work.md

@@ -0,0 +1,40 @@
+---
+title: Units of Work
+description: How GroundWork structures delivery — Bet, Milestone, and Slice.
+status: active
+last_reviewed: 2026-05-26
+---
+
+# Units of Work
+
+GroundWork organises delivery through three nested units — **Bet**, **Milestone**, and **Slice** — each defined by the contract its dependents can rely on. A Bet's appetite holds while scope is designed. A Milestone's capability is provable behind a flag before customers see it. A Slice's API surface is testable before anything consumes it.
+
+## Pitch
+
+A Pitch is the shaped plan for solving a problem within an appetite. It contains: a problem statement, a high-level solution sketch, explicit rabbit holes and no-gos, and a falsifiable success signal — the measurable outcome that confirms the bet delivered its intended value. The appetite is an opportunity-cost judgment made before the solution is designed, not a post-design estimate.
+
+A Pitch does not contain milestones or slices. Those are derived in Decomposition, after the design is locked in Design Foundations.
+
+Multiple Pitches may exist at once. Committing to a Pitch converts it into an active Bet.
+
+## Bet
+
+A Bet is the committed execution of a Pitch — active from the moment the team decides to execute through Validation. A Bet operates on a fixed appetite with variable scope: the worth it is bounded to — judged by opportunity cost, not a calendar-time estimate — is set upfront and does not move; scope adjusts to fit what can be delivered within it.
+
+Milestones and slices are defined in the Decomposition phase, from the locked technical design. They are not part of the Pitch.
+
+## Milestone
+
+A Milestone is a demonstrable state the product reaches within a Bet — visible in the UI and verifiable behind a feature flag, but not yet exposed to customers. Milestones sequence by dependency: a Milestone that requires an earlier one to be complete must declare that dependency explicitly.
+
+The Milestone is not a customer release. It is an internal proof point: the capability exists, can be demonstrated, and composes with other Milestones toward a customer-releasable Bet.
+
+## Slice
+
+A Slice is a vertical cut through a single tech stack component — a service, a module, or a domain area — that delivers a new capability at that component's API boundary. A Slice spans the full depth of its component (schema, business logic, API surface) and stops there. The component above it — the UI or a downstream service — can consume it once the Slice is complete.
+
+The hamburger method defines what "vertical" means in practice: rather than building all schemas across components, then all business logic, then all APIs, each Slice delivers one complete column through a single component's layers. The column is independently testable before anything above it is built.
+
+Milestones close when every Slice that contributes to the Milestone's required API surface is complete.
+
+**Brownfield systems**: Services in brownfield codebases often own multiple domains or share domain logic across services. A Slice is architecture-agnostic — the definition does not assume one service equals one domain. What matters is that a Slice delivers a testable API-level capability at a component boundary, regardless of how that component's internal responsibilities are structured.