groundwork-method 0.0.1 → 0.10.0

package/src/hidden-skills/groundwork-architect/references/evolutionary-architecture.md

@@ -0,0 +1,37 @@
+# Evolutionary Architecture
+
+An architecture is a system that must change safely under constant pressure, not a blueprint delivered once. Two jobs at design time: make the structure cheap to change, and protect the characteristics you care about with **fitness functions** — automated checks that *assure* a property the way a test assures behaviour. A decision record documents what was chosen; a fitness function proves it still holds. A rule that lives only in prose or code review is already drifting.
+
+## Design for change
+
+Optimise for evolvability over speculative completeness. You cannot predict which requirements shift, so build to absorb change cheaply — clear boundaries, reversible decisions, replaceable parts — rather than guessing the future and building for it. **Reversibility is the property worth paying for**: the cost of a decision is dominated by how hard it is to undo. Prefer one-way doors made deliberately and visibly (and recorded — see [decision-records.md](decision-records.md)); an architecture full of irreversible choices cannot evolve.
+
+## Fitness functions assure what decisions document
+
+Every architectural characteristic you actually care about should get an automated check that fails when it is violated:
+
+- **dependency direction / layering** — the inward-flow rule (the core imports nothing concrete; edges depend inward) is the archetype, automatable with `depguard` / `import-linter` / ArchUnit; this is what turns it from a style into a guarantee.
+- **API conformance** — spec linting (Spectral) + contract tests with a `can-i-deploy` gate ([api-and-contracts.md](api-and-contracts.md)).
+- **budgets** — latency, bundle size, allowed couplings — checked in CI against committed thresholds.
+
+The architect's job is to **advise which characteristics deserve a fitness function and where the seam goes**; the engineer skills build them. A new service ships with its dependency-direction check from day one. When you record a load-bearing decision, ask: what check would catch its violation? — that check is the decision's other half.
+
+## Evolve incrementally, guarded by checks
+
+Change lands in small reversible steps, each guarded by the fitness functions, so a regression is caught the moment it lands and the system can be reshaped continually instead of in big-bang migrations. Atomic checks guard one characteristic; holistic checks guard interactions; both run continually, not as a periodic audit.
+
+## Modernise with the strangler fig, not the rewrite
+
+Evolve legacy systems; do not replace them wholesale. New capability grows around the old behind a **façade** that routes traffic to the new implementation as each slice is proven, until the old system is starved and removed. The big-bang rewrite has the highest failure rate of any modernization approach; incremental replacement keeps the system shippable the whole way across. (This is the same discipline a brownfield adoption applies — strangle, don't stop the world.)
+
+## Governance is advisory, not a gate
+
+Decentralise the decision, centralise the visibility. An **advice process** (the decider must seek advice from those affected and those with expertise, but keeps the decision), a lightweight RFC, or an architecture guild replaces the central review board teams route around. Let fitness functions do the gatekeeping that can be automated; spend human judgement where automation cannot reach. "Governed decisions" never means a person standing at a gate.
+
+## Antipatterns to catch
+
+- **ADR graveyard** — decisions documented, never enforced. Pair the load-bearing ones with a check.
+- **Big-bang rewrite** — replacing a working system all at once. Strangle it.
+- **Review board as veto** — a central gate that becomes a bottleneck. Advise and automate.
+- **Convention-only rules** — an agreed boundary with nothing failing the build when it is crossed.
+- **Speculative future-proofing** — building for imagined requirements instead of for change.

package/src/hidden-skills/groundwork-architect/references/identity-and-access.md

@@ -0,0 +1,41 @@
+# Identity & Access
+
+Who may do what is an architectural decision made with the boundaries, not a middleware bolted on later — and the hardest thing to retrofit once authorization is scattered and the trust model is implicit. Decide three things with the boundaries: how each actor authenticates, how services prove identity to each other, and how authorization is modelled. In 2026 a fourth actor joined: agents, which need an identity the system can reason about.
+
+## Authn vs authz — keep them distinct
+
+Authentication establishes *who*; authorization decides *what they may do*. Design both deliberately. Conflating them, or letting either accrete in middleware, is how access control becomes unauditable.
+
+## Human identity is boring and standard
+
+Do not invent auth. Humans authenticate through a proven provider over **OIDC / OAuth 2.1**; sessions and tokens follow current OWASP guidance. Custom JWT handling, bespoke session cookies, and home-grown MFA are how teams learn auth vulnerabilities the hard way.
+
+## Workload identity is the service perimeter
+
+Services prove who they are with cryptographic **workload identity** — SPIFFE/SPIRE issuing short-lived, auto-rotating SVIDs, mTLS through the mesh with no secret in app code. "It came from inside the network" authenticates nothing; machine identity is the perimeter ([security-and-trust.md](security-and-trust.md)).
+
+## Authorization is modelled, not scattered
+
+Choose the model deliberately and enforce it through one path:
+- **RBAC** for coarse role-based access.
+- **ReBAC** (relationship-based, Zanzibar-style) for "can *this* user see *this* document".
+- **ABAC / policy** where rules are dynamic.
+
+Externalise complex or shared policy to a policy engine so the rules are inspectable and consistent. Per-endpoint permission checks copy-pasted across handlers are authorization that will be wrong somewhere.
+
+## Agent & non-human identity is first-class
+
+An automated actor — service account, CI job, AI agent — has its own identity, never a borrowed human one. In an agent-led system this is load-bearing: the agent carries an identity into every request, consequential tool calls are authorised **per-action**, and **delegation is explicit** (on-behalf-of token exchange) so authorization can reason about which agent acted on whose behalf. An agent with a shared admin key is excessive agency by another name ([agentic-systems.md](agentic-systems.md)).
+
+## Least privilege, short-lived credentials, tenant as identity
+
+Every identity starts minimal and widens only on evidence; credentials are short-lived and auto-rotated (a static long-lived secret is a breach with a long fuse). In a multi-tenant system the **tenant is part of every identity and every authorization decision**, enforced at the data boundary — never trusted from a client-supplied parameter. Cross-tenant access is the highest-severity failure class.
+
+## Antipatterns to catch
+
+- **Implicit network trust** — "internal, so authenticated." No.
+- **Long-lived static secrets** — a shared service key with no rotation.
+- **Scattered authorization** — per-endpoint checks that drift apart.
+- **Borrowed identity for machines** — a bot acting as a human admin, no trace of who acted.
+- **Invented auth** — custom JWT/session/MFA instead of the standard.
+- **Tenant-by-query-param** — trusting a client-supplied tenant id.

package/src/hidden-skills/groundwork-architect/references/integration-patterns.md

@@ -0,0 +1,39 @@
+# Integration Patterns
+
+Services integrate through a small set of well-understood patterns. Pick the pattern based on the **guarantee the integration needs**, not on whatever felt easy. Most production incidents trace back to an integration that chose the wrong consistency model — a sync call where async belonged, an event without idempotency, a fire-and-forget webhook that dropped on retry. The cost of getting it wrong is paid every day, forever, as an intermittent stream of weirdness.
+
+## The decisions
+
+1. **Default to async; upgrade to sync only when required.** Async events are the default for inter-service communication. Upgrade to synchronous RPC only when the response value is needed inline (most user-facing reads) or the caller needs the commit to have happened before proceeding (strict writes). Making sync the default couples services in ways invisible in code and disastrous at load.
+2. **Outbox when a DB write and an event must agree.** When a state change needs both a database write and an event emission — both or neither — write the event to an `outbox` table inside the same transaction, then relay it to the broker. This is the only correct solution without distributed transactions. "Just emit after commit" leaks inconsistency every time the process dies between the two steps. It will.
+3. **Every consumer is idempotent.** At-least-once is the only delivery guarantee you ever get. Every handler carries a de-duplication key or operates on keys that make replay safe (an `UPSERT` on a natural key, a version-guarded conditional update). Idempotent handling is the only response that works.
+4. **Retries have policies, not 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. The DLQ fires an alert; it is not a garbage bin.
+5. **Webhooks verify, sign, and replay.** Inbound and outbound webhooks are authenticated with an HMAC signature over the payload, not a secret in the query string. Both sides support replay (store the signature, reject duplicates) and surface a retry history. An unsigned webhook is just an unauthenticated POST endpoint.
+6. **Timeouts are end-to-end budgets.** Every sync call has a timeout allocated from a budget set by the outermost caller. A 2-second edge budget does not get to spend 1.5s on one downstream — that leaves no slack for retries or the next hop. Without budgeting, tail latencies compound unpredictably.
+7. **Circuit breakers protect the system from itself.** When a downstream is failing, stop calling it. The breaker opens after a failure threshold, fast-fails the calls, and probes periodically for recovery — protecting both the recovering service and the upstream callers waiting on inevitable timeouts.
+8. **Every integration has a contract test.** A test exercising the real signature verification, the real retry curve, the real idempotency behaviour, run in CI against an emulator. Happy-path-only coverage is an incident waiting for its trigger.
+
+## The sync-vs-async call
+
+| Choose sync when | Choose async when |
+|---|---|
+| The caller needs the response value inline | The work can complete after the caller returns |
+| The caller must know the write committed before proceeding | Eventual consistency is acceptable |
+| It is a user-facing read | It is fan-out, notification, or cross-service propagation |
+
+When in doubt, async with an idempotent consumer is the more resilient default. Reserve sync for where the guarantee genuinely demands it.
+
+## Dead letters, jitter, and when workflow-as-code takes over
+
+- **Dead-letter handling is a named primitive.** A consumer that exhausts its retries routes the message to a DLQ that *alerts and is worked*, never a silent bin — poison messages are expected, not exceptional.
+- **Backoff carries jitter.** Bounded exponential backoff **with jitter** is mandatory, not optional — synchronized retries without jitter are a retry storm (a self-inflicted DDoS).
+- **Orchestration vs choreography is a step-count call.** Choreography (services react to events) for simple 2–4-step flows; orchestration for 5+ steps, branching, or when you need visibility. And when a flow is genuinely long-running, multi-step, or compensating, reach for **durable execution** (workflow-as-code) instead of hand-assembling outbox + idempotency + retry + sweeper — see [durable-execution.md](durable-execution.md).
+- **Webhooks, current.** A stable event-id for idempotent dedup, a timestamp for a replay-window rejection, **rotating signing keys via JWKS** (not a long-lived shared HMAC secret), and a CloudEvents-shaped payload.
+
+## Antipatterns to catch
+
+- **Sync chains three deep** — A→B→C→D. Every failure mode in the chain becomes A's failure mode.
+- **Fire-and-forget webhooks** — no signature, no retry, no idempotency. Works once; the next incident is unfixable from the outside.
+- **Commit-then-publish without the outbox** — guaranteed inconsistency the first time a process dies mid-step.
+- **Global retry policies** — "all HTTP calls retry 3× with 1s backoff" ignores the specific downstream's failure profile and the caller's budget.
+- **Dead-letter queues as silent logs** — a DLQ quietly accumulating means integration is failing quietly. Alert and act.

package/src/hidden-skills/groundwork-architect/references/observability.md

@@ -0,0 +1,36 @@
+# Observability
+
+Observability is a design property, not a monitoring bolt-on. The difference between a team that ships with confidence and one that cannot is, most of the time, a difference in what they can see. Observability buys three things: knowing whether the system is healthy, localising a fault when it is not, and explaining what happened after the fact. Decide instrumentation at design time — when a system behaves strangely and you cannot see why in your data, the instrumentation is the bug.
+
+## The design decisions
+
+1. **OpenTelemetry is the common language.** Every service emits traces, metrics, and logs through OTel SDKs to a single collector. Vendor lock-in lives at the collector boundary, not in application code — switching backends is a config change, not a rewrite.
+2. **Traces are the primary signal.** Given the choice between a metric and a richer trace, enrich the trace. Traces preserve causality; metrics aggregate it away. When one user action crosses half a dozen services, causality is the difference between a diagnosable incident and a guessing game.
+3. **The three pillars are one pillar.** Logs, metrics, and traces are projections of the same events: a log line carries its trace ID; a metric carries dimensions that pivot back to traces; an exemplar points at the trace that produced it. Three disconnected telemetry systems is no observability.
+4. **Dashboards derive from SLOs.** Every dashboard starts with the user-journey SLO it supports, then fills in latency percentiles, error rates, saturation, and traffic. Dashboards assembled from "interesting-looking" graphs drift into uselessness.
+5. **Trace-driven development.** Sketch the trace a feature should produce — what spans, what attributes, what parent-child relationships — *before* writing the handler. The instrumentation design shapes the code, making it nearly impossible to ship an unobservable feature.
+6. **Assert on telemetry in tests.** System tests assert traces are unbroken end-to-end; a missing span is a test failure. The instrumentation is part of the contract, not optional decoration.
+7. **Logs are structured, sampled, contextual.** Every line is JSON, carries its trace ID, and is emitted at an agreed severity. Sample aggressively at debug/info; never sample errors.
+8. **Cardinality is a design choice.** High-cardinality attributes (per-user, per-tenant) are valuable on traces where they are queryable, expensive on metrics where they multiply by every time window. Runaway cardinality is one of the most expensive mistakes in observability — a deliberate call, not a default.
+9. **Wide events over pre-aggregation ("observability 2.0").** Prefer emitting arbitrarily-wide, high-cardinality structured events you can slice after the fact over pre-deciding which metrics to aggregate. The query you need is rarely the one you anticipated.
+10. **Auto-instrument with eBPF; profiling is a signal.** Kernel-level, zero-code instrumentation (OpenTelemetry OBI / eBPF) gives high-cardinality telemetry without touching application code; continuous profiling correlated to trace IDs is a first-class signal, not a special exercise. Reserve hand-instrumentation for the domain spans that auto-instrumentation cannot infer.
+
+## AI/LLM observability
+
+A model in the system needs telemetry classic APM does not capture, via the **OTel GenAI semantic conventions**:
+
+- **Token usage** (`gen_ai.usage.input_tokens` / `output_tokens`) — because cost and latency correlate with *token* count, not request count. Telemetry that does not capture tokens cannot explain the bill.
+- **Prompt/response capture and eval traces** — the inputs, outputs, and scored quality of model calls, plus agent-orchestration and **MCP tool-call** spans, all on the same trace.
+- **Online evals** feeding the loop: failed production traces are promoted into the eval set so the suite grows from real behaviour ([agentic-systems.md](agentic-systems.md)).
+
+## What this means at design time
+
+When you set a boundary or a data flow, decide what it must emit. Observability is a downstream obligation of the contract: name the spans a flow must produce and the SLO a dashboard will track, so the instrumentation ships with the feature rather than chasing it.
+
+## Antipatterns to catch
+
+- **Pillar-at-a-time adoption** — "metrics now, traces later." You will not.
+- **Vendor SDKs in application code** — application code imports OTel; the collector talks to the vendor.
+- **Dashboards without SLOs** — pretty charts without a question they answer.
+- **Logs-as-debugger** — `printf`-tracing a single bug instead of writing a test and adding a span.
+- **Cardinality explosions** — a UUID in a Prometheus label. The bill and the query planner both remember.

package/src/hidden-skills/groundwork-architect/references/performance-and-scale.md

@@ -0,0 +1,41 @@
+# Performance & Scale
+
+Performance is not "fast enough" — it is a budget, spent deliberately across every hop of an interaction and enforced in CI. Users notice latency before almost anything else: a response at 800ms feels instant, at 3000ms feels broken. That gap is not four times the effort — it is the difference between treating latency as a design constraint and treating it as a post-hoc tuning problem. Performance handled as an afterthought is invariably more expensive than performance designed in.
+
+## The design decisions
+
+1. **Latency is a budget, allocated top-down.** Every user-facing operation starts with an edge budget (say 500ms) allocated to downstream hops. If one fetch takes 300ms and a join 150ms, the handler has 50ms of its own. When a hop overruns, someone else's budget is squeezed — the budgeting view makes the trade-off explicit.
+2. **Measure tail latency, not average.** p50 is a marketing number; p95 and p99 are what users experience. Design for the tail and alert on it. A great median with a terrible p99 earns an awful reputation regardless of the dashboard.
+3. **Pre-compute, cache, denormalise deliberately — across tiers.** Hot read → pre-compute. Stable computation → cache. Expensive join → denormalise. Caching is multi-tier (client, CDN/edge, service, datastore) with an explicit origin-offload/hit-ratio target, not a single layer. Each trades complexity for latency and must earn its keep with data, not intuition. Speculative caching is how cache-invalidation becomes the biggest source of data incidents.
+4. **Backpressure is designed in, not hoped for.** Every producer has a bounded queue and a defined full-queue behaviour: shed, coalesce, block. "It works in load tests" is not a backpressure strategy.
+5. **Load shedding protects the system from itself.** When saturated, serve fewer requests well rather than trying harder. Shed on clear criteria — low-priority first, new sessions before active ones, non-interactive before interactive. A designed degradation mode, not an accident.
+6. **Profile before optimising.** The "obvious" bottleneck is almost always wrong; tuning a cold path is wasted effort. Profile in production-representative conditions — laptop profiles lie.
+7. **Budgets are enforced in CI.** Bundle sizes, worst-case handler latencies, and the like are measured against committed thresholds; a regression requires a reviewed waiver. Regressions that slip in once slip in a hundred times — automation is cheaper than vigilance.
+
+## Understand the demand shape before choosing infrastructure
+
+Decide the scaling model from the shape of the demand, not from defaults:
+- **Spiky and unpredictable** vs **stable and forecastable** demand call for fundamentally different approaches.
+- For indie/hobby contexts, whether cost can reach near-zero during inactivity (**scale-to-zero**) is a legitimate architectural requirement that shapes every infrastructure choice after it.
+- Fully managed services trade operational burden for higher spend and vendor dependency; self-managed trades convenience for control and cost.
+
+Autoscaling is designed, not enabled: aggressive scaling on a bursty workload multiplies cost without improving experience; conservative scaling on a steady workload wastes headroom. Tune each policy to the production load profile. The 2026 default is **event-driven** autoscaling (KEDA on queue depth / lag / custom signals, Karpenter for nodes) with genuine **scale-to-zero** — which is what closes the idle-cost gap to serverless. CPU-only HPA is the dated reflex.
+
+## Compute placement is a design axis
+
+*Where* code runs is now a first-class decision, not just *how much* of it:
+- **Edge** for latency-sensitive, cacheable, or geo-distributed work (auth, personalization, gateway logic) — proximity flattens tail latency; target a high edge hit ratio.
+- **WebAssembly** is the edge/FaaS/plugin/multi-tenant-density compute unit (1–5ms cold start, sandboxed, polyglot) — production-ready for those, not yet a general microservice runtime.
+- **Containers/serverless** for stateful or heavy work. Most teams blend all three; the placement decision trades latency, cost, and the edge's constraints (no raw TCP, limited CPU, no direct DB drivers).
+
+## The AI-cost lever
+
+For a model-in-the-loop feature, latency and cost track **tokens, not requests** (output ≈4× input). The architectural levers: **model routing** (small model for the easy majority, frontier for the hard minority — often a 100×+ delta), **semantic caching** (large savings on repetitive prompts), and an **AI gateway** that enforces budgets, routing, and fallback ([platform-and-delivery.md](platform-and-delivery.md)). A latency budget that ignores token count is incomplete for an AI path.
+
+## Antipatterns to catch
+
+- **Optimising on hunch** — no profile, no optimisation.
+- **"Fast on my laptop"** — dev latency is not production latency.
+- **Average-as-metric** — p50 is a lie; use percentiles.
+- **Unbounded queues** — a queue without a max is a latency bomb.
+- **"We'll fix performance later"** — ship slow and users remember slow.

package/src/hidden-skills/groundwork-architect/references/platform-and-delivery.md

@@ -0,0 +1,47 @@
+# Platform, Delivery & Cost
+
+How the system is deployed, released, and paid for is an architectural concern, not an operational afterthought. The topology you choose constrains how fast the team can ship and what it costs to run — decide it with the boundaries, not after them.
+
+## Platform: the substrate is a product
+
+The platform is the substrate every team builds on — the local stack, the CI/CD pipeline, the observability collector, the secrets manager, the dev CLI fronting all of it. Treat it as a product with users, a backlog, and a quality bar. A good platform makes the right thing the easy thing.
+
+1. **Self-service is the goal.** Spinning up a service, requesting a secret, adding a dashboard, flipping a flag — all self-service. When a team files a ticket and waits, the platform is the bottleneck.
+2. **Golden paths over policy.** Pave the specific routes (create a service, deploy, observe) and make them the easiest path. Policy without a paved path produces compliance in shape, drift in substance.
+3. **One paved-road pipeline per service type.** One pipeline definition for every service of a kind; deviation earns the cost of its own maintenance. This is how snowflake CI configurations are prevented.
+4. **Observability is part of the platform.** One collector, one backend, one set of dashboards — telemetry set up independently by each team is broken in five different ways.
+
+## Progressive delivery: decouple deploy from release
+
+Deploying code and releasing a feature are different acts. Ship to production many times a day from one branch, but users see a change only when a flag opens, a canary routes, or a cohort is promoted. Deploys become small and boring; releases become observable, controllable, reversible.
+
+1. **Trunk-based development, short-lived branches.** Every change lands on `main` when ready; branches measured in days, not weeks. Long-lived branches accumulate integration bugs quietly.
+2. **Feature flags separate deploy from release.** New features deploy behind a flag defaulted off (use the vendor-neutral **OpenFeature** standard so the flag system is swappable). A bad feature is disabled without a redeploy; a risky one rolls to 1% before 100%. Every flag has an owner, a purpose, and an expiry — stale flags are removed in the normal course of work.
+3. **Canary before promote, driven by GitOps.** Anything that could affect latency, reliability, or experience goes through a canary — a small traffic fraction for a bounded window — evaluated against SLO burn rates by automated comparison, not eyeballs. The progressive-delivery engine follows the GitOps tool (Argo Rollouts with ArgoCD, Flagger with Flux), which owns the traffic-weight and automated analysis.
+4. **Release is reversible, cheaply.** Every release has a rollback any on-call engineer can execute in minutes: reversible migrations, flippable flags, re-routable canaries. "We can't roll that back" is a red flag on the release itself.
+
+## Cost: a non-functional requirement with a dollar sign
+
+Most teams discover cost too late — after a quarterly bill, when the decisions that drove it are already in production with consumers. Make the economic consequence visible at the point of the decision.
+
+1. **Cost is a first-class metric.** Cost-per-call, cost-per-user, cost-per-feature, tracked alongside latency and error rate. A team that does not know what its features cost cannot reason about the trade-offs that matter.
+2. **Budgets are set and defended.** Every significant service runs inside a cost budget set at design time; exceeding it triggers the same response as any SLO breach.
+3. **Egress is expensive; plan for it.** Inter-region chatter, chatty logs, large frequent payloads add up. Place data where its consumers are; batch and compress where cheap.
+4. **AI spend runs through a gateway.** Every model call has a measured cost and a caching strategy, mediated by an **AI gateway** — a token-aware control plane between apps/agents and providers that does model routing, semantic caching, fallback, per-key budgets, audit, and guardrails. "Pass the whole context to the largest model" is how an AI feature becomes a cost incident ([performance-and-scale.md](performance-and-scale.md)).
+
+## Substrate choices
+
+- **IaC is a real choice now, not a default.** Name it: **Terraform** (incumbent), **OpenTofu** (OSS-governed, diverging — it has state encryption Terraform lacks, and provider compatibility may drift, so it is no longer a silent drop-in), or **Pulumi** (real languages). Pick deliberately.
+- **Buy-vs-build the IDP.** Backstage is the share leader but self-hosting it is a platform-team tax; under a couple hundred engineers, a managed portal usually wins. The platform is a product — including the build/buy decision.
+
+## Carbon is a design input
+
+Sustainable software has crossed into a first-class concern: measure with the Green Software Foundation's SCI, and shift demand for *carbon* the way you already shift it for cost — run deferrable/batch work when and where the grid is cleaner (carbon-aware scheduling). This extends the demand-shaping you already do; express it as a fitness function so it does not regress silently.
+
+## Antipatterns to catch
+
+- **Platform-as-gatekeeper** — a platform that says "no" more than "self-serve" is a bottleneck.
+- **Release trains** — batching a month of changes into a Friday deploy that breaks unlocalisably.
+- **Flags without expiry** — a year-old "temporary" flag is a permanent decision hidden in runtime config.
+- **Canary-by-eyeball** — promoting because the graph "looks fine." Automate the comparison.
+- **"Optimise cost later"** — later never comes; by then the architecture is what it is.

package/src/hidden-skills/groundwork-architect/references/realtime-and-async.md

@@ -0,0 +1,28 @@
+# Real-Time & Streaming
+
+Real-time features are long-lived bidirectional contracts between client and server, not request-response interactions. The difference between a live experience that feels smooth and one that feels broken is almost always how the implementers thought about failure modes — reconnection, duplicate messages, out-of-order delivery, backpressure. Design every real-time feature against the assumption that **the connection will drop mid-flight.**
+
+## The design decisions
+
+1. **Transport is a per-direction decision.** **SSE** is the default for server→client streaming — auto-reconnecting, CDN-friendly, no sticky sessions, plain HTTP — and it is the streaming substrate for AI (MCP and token delivery ride it). **WebSockets** are for genuinely bidirectional connections where the client also pushes frequently. Reaching for WebSockets to push a one-way stream is over-engineering; long-polling is rejected.
+2. **Every message carries a sequence number.** A monotonic, per-session sequence lets the client detect gaps, the server detect duplicates, and the pair resynchronise after a reconnect without refetching everything.
+3. **Reconnection is the normal case.** Clients reconnect with exponential backoff, jitter, and a resumption token telling the server where they left off. "Reconnected" is logged, not paged. A reconnection-rate spike is a signal about network or server health, not a client bug.
+4. **Backpressure is explicit.** When the server produces faster than the client consumes, it **sheds** (drops non-critical messages, logs the shed rate), **coalesces** (merges consecutive updates), or **blocks** (flow control). What it never does is buffer unbounded — that is how a real-time service dies.
+5. **Echo suppression is a design concern.** Where a client's own output may be re-ingested as an incoming event, the suppression mechanism — a sender ID on the stream, a per-session gateway filter, client-side gating — is part of the protocol, specified before the first line of code, not bolted on later.
+6. **Idempotent handlers.** The client will reconnect and resend; the same sequence number processed twice has no additional effect. The HTTP idempotency principle applied to the streaming surface.
+7. **Observability is unbroken across the socket.** A trace that enters via HTTP, opens a socket, streams many events, and closes belongs to one trace. Propagate trace context into the socket and carry it on every event.
+8. **Client state is recoverable, not sacred.** Any client state that matters must be reconstructable from the server. Rejoining a session produces the same observable state — the server is the source of truth.
+
+## LLM streaming, collaboration, and what not to ship yet
+
+- **LLM streaming** is the canonical 2026 real-time pattern: **SSE for the token data-plane**, a WebSocket (or internal gRPC) for the **control-plane** (cancel, feedback injection). Its failure modes extend the ones above — slow first token, partial-response loss on a provider retry, backpressure stalls — so apply sequencing and backpressure to the token stream.
+- **Collaborative / offline-first → CRDTs.** For multi-user editing and local-first apps, **CRDTs** (Yjs the ecosystem default, Automerge for Git-like history) make the local copy the source of truth with background sync — the principled answer where "echo suppression + recoverable client state" was gesturing. Don't hand-roll last-write-wins where a CRDT is the right tool.
+- **WebTransport: prototype, don't ship.** QUIC/HTTP-3-based and promising for high-scale/low-latency, but with no Safari support in 2026 it is not production-ready — keep it to prototypes.
+
+## Antipatterns to catch
+
+- **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 exhaust server memory. Shed, coalesce, or block.
+- **Reconnect-then-refetch-everything** — if a 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 and generated, not invented per feature.
+- **Client-side echo reconciliation as the design** — handle echoes at the gateway where the full context lives; client-side gating is a fallback, not the plan.

package/src/hidden-skills/groundwork-architect/references/reliability.md

@@ -0,0 +1,31 @@
+# Reliability
+
+Reliability is not a feature added after the system is built — it is a design property paid for up front, measured in error budgets, defended by graceful-degradation patterns, and rehearsed through deliberate failure injection. Users do not experience uptime percentages; they experience "the thing I needed did not work just now." In a real-time product unreliability compounds: a dropped request becomes a failed operation becomes a broken journey. The cost of a small reliability failure is rarely proportional to its scope.
+
+## The design decisions
+
+1. **SLOs, not uptime percentages.** Every significant service defines a Service Level Objective — a per-endpoint or per-journey target with latency and success-rate components over a rolling window. "99.9% uptime" is not an SLO; "p95 `POST /resource` < 300ms over 30 days, 99.5% success" is. The SLO is the measurement surface everything else hangs on.
+2. **Error budgets govern velocity.** The budget implied by the SLO is a spendable resource. Below budget, ship riskier changes and run experiments; above budget, pause feature work and pay down reliability debt. Reliability as a gate on velocity, not a tax on top of it.
+3. **Graceful degradation is a design, not a hope.** Every user-facing feature has a defined behaviour when its downstream fails — a view without synthesis data renders a "not yet ready" state; a pipeline without a model client enqueues and returns when it can. Decided at design time, implemented alongside the happy path.
+4. **Timeouts, retries, and circuit breakers are defaults.** Every outbound call has a timeout, every retry a bounded policy with jitter, every client a breaker against its important downstreams. Set in a shared library so new services inherit them; opting out requires a written reason.
+5. **Isolate blast radius — cells.** A single tenant, user, or noisy consumer must not degrade everyone else. Isolate by quota (per-tenant rate limits), by resource (dedicated queues for hot workloads), and by bulkhead (separate worker pools). At scale this generalises to **cell-based architecture** — partition the system into independent cells so a failure is contained to one cell's users. The design question is always "if this goes bad, who else is affected?" — and the target answer is "only the thing that went bad."
+6. **Verify failure continuously, within a policy.** Inject failures — killed pods, degraded networks, slow databases — routinely in staging and carefully in production, as *continuous verification* bounded by an automated blast-radius policy (cap the fraction of traffic/pods, forbid touching critical paths in business hours), not an occasional unguarded game-day. The goal is to discover the reliability assumptions you are making without knowing it.
+7. **Alert on user impact, not mechanism.** Page on SLO burn rate and journey error spikes, not on 80% CPU. Mechanism alerts without user impact teach on-call to ignore pages — which is how a real incident gets missed.
+8. **Every incident teaches a specific lesson.** A blameless postmortem names the specific assumption the incident invalidated and the specific change that would have caught it. Not "be more careful," not "add more monitoring" — one concrete, closable ticket.
+
+## SLOs are living, and AI fails differently
+
+SLOs are hypotheses reviewed against burn, not set-and-forget contracts: alert on **multi-window, multi-burn-rate** signals; consistently under-burning means the target is too loose, a blown budget triggers a reliability project. And a model-in-the-loop changes the failure shape: a wrong answer returns **HTTP 200, valid JSON, within latency** — semantic failure, not an exception. So AI features carry **per-SLI budgets** (an accuracy/consistency budget distinct from the latency budget, burning independently), and the model provider is treated as your least-reliable dependency (rate limits and provider drift are first-class failure modes with their own degradation path).
+
+## RTO / RPO drive the topology
+
+When availability is a stated requirement, pin the two numbers that shape redundancy, replication, failover, and backup: **RTO** (acceptable recovery time if the system goes down) and **RPO** (tolerable data loss in a failure). A system that must be 99.99% available is architecturally different from one where an hour of downtime is acceptable — decide which you are building before the boundaries harden.
+
+## Antipatterns to catch
+
+- **"Five-nines" as a reflexive target** — reckless for a non-core service. Set an SLO the team can defend.
+- **Retries without policies** — retry-forever is a self-inflicted DDoS.
+- **Mechanism alerts** — paging on CPU/memory/disk untied to user impact. Noise.
+- **"It hasn't failed yet"** — absence of a known failure mode is not evidence of its absence. Rehearse.
+- **Postmortems that blame humans** — a system that depends on everyone being perfect will fail. Fix the system.
+- **SLOs nobody tracks** — an SLO without a dashboard and a burn-rate alert is theatre.

package/src/hidden-skills/groundwork-architect/references/security-and-trust.md

@@ -0,0 +1,47 @@
+# Security & Trust
+
+Security is every engineer's job, every day. Treat every service as untrusted, every dependency as a supply-chain risk, every input as hostile, and every secret as already-compromised unless proven otherwise. The goal is not zero risk — it is a system that stays standing when any single control fails. A system that is reliable but exploitable is not reliable.
+
+The trust model is an architectural decision, decided with the boundaries — not an implementation detail discovered later.
+
+## The design decisions
+
+1. **Zero trust between services, on workload identity.** Services authenticate each other on every request; no "internal" network is implicitly trusted. The concrete 2026 mechanism is **workload identity** — SPIFFE/SPIRE issuing short-lived, auto-rotated SVIDs, mTLS established via the service mesh with no secret in app code. Machine identity is the new perimeter. If an attacker pivots into one service, they do not inherit the blast radius of the whole system.
+2. **Threat model the change, not just the product.** Every significant change asks before sign-off: who could misuse this, and how? A new endpoint, field, or integration gets a five-minute threat conversation — cheap up front, and it catches most of what a pen test or production would otherwise find.
+3. **Secrets are managed, rotated, audited.** No secret lives in source. Secrets live in a manager, are fetched at runtime, rotated on a schedule, and every access is audited — so a leak's damage window is hours, not years.
+4. **Input is hostile; validate at the boundary.** Every input at a trust boundary is validated: request bodies, webhook payloads, queue events, model outputs. Inside the boundary, trust your own types. The discipline is that the boundary is explicit and every crossing is scrutinised.
+5. **Supply chain is part of the attack surface.** Pin versions, review new dependencies before adoption, scan on every build. Move past SBOM-alone to **provenance**: sign artifacts (Sigstore/cosign) and emit signed build attestations as **SLSA build levels** — "an SBOM says what's inside; provenance proves where it came from." A dependency added without review is a back door added without review (npm carried 450k+ malicious packages in 2025).
+6. **Least privilege by default.** Every service, database role, and cloud identity starts with the minimum it needs and is extended only on evidence. "Give it admin and fix later" has a lifetime of never.
+7. **Auth is boring technology.** Do not invent auth. Proven providers handle user authentication; service-to-service uses short-lived tokens from a standard IdP; sessions follow OWASP guidance. Exotic auth is how a team learns about auth vulnerabilities the hard way.
+8. **Detect and respond, not just prevent.** Assume prevention sometimes fails. Log security-relevant events, alert on suspicious patterns, rehearse incident response.
+
+## AI & agent security
+
+A model in the system widens the attack surface in ways classic AppSec misses:
+
+- **Prompt injection is structural, and it leads OWASP's LLM risks** (LLM01). The model mixes instructions and data in one channel, and the injection arrives *indirectly* — through retrieved documents, tool outputs, and other agents (it propagates across co-running agents). Output validation alone is insufficient; scrutinise the inputs and constrain what a model-driven action can reach.
+- **Excessive agency** is the architectural control: an agent gets least privilege and a bounded toolset, and consequential tool calls are authorised per-action, not granted wholesale ([agentic-systems.md](agentic-systems.md)).
+- **Agent identity.** A non-human actor needs its own identity and delegation, carried into the request (SPIFFE-for-agents) so authorization can reason about *which* agent acted on whose behalf ([identity-and-access.md](identity-and-access.md)).
+- **MCP/tool security.** A tool surface is an execution surface — tool poisoning and exec-capable tools are real; threat-model the tool catalogue, not just the API.
+
+## Multi-tenancy is decided here
+
+The tenancy isolation strategy — **shared database**, **schema-per-tenant**, or **database-per-tenant** — is an architectural decision made with the boundaries, because it shapes data models, query patterns, and compliance boundaries across every service. Decide it before the schema hardens; retrofitting isolation is brutal.
+
+## Privacy is a design input
+
+Regulated data shapes the architecture before procurement, not after:
+- **Collect the minimum**, retain for a bounded time, scope and audit every access.
+- **Data residency** (EU data on EU infrastructure for some purposes) is an input to storage and pipeline topology.
+- **PII is handled distinctly from content** — shorter retention, tighter access, not co-located where avoidable, and never in logs.
+- **Data-subject rights** (access, rectification, portability, deletion) are first-class features flowing through the same plumbing as retention expiry.
+- Compliance frameworks that may apply — GDPR, HIPAA, PCI-DSS, SOC 2 — drive audit logging, access control, and encryption requirements beyond data location alone. Surface them while establishing constraints.
+
+## Antipatterns to catch
+
+- **"Internal network = trusted"** — the assumption every modern breach exploits.
+- **Secrets in env vars committed to Git** — use the manager, always.
+- **"It's internal, skip auth"** — internal tools are an attacker's favourite foothold.
+- **Dependencies pulled on intuition** — a 12-star package with no maintainer is a supply-chain risk.
+- **Exotic auth** — custom JWT/session/MFA handling. Use the battle-tested thing.
+- **PII in logs** — trace and log data outlive the systems that produced them.

package/src/hidden-skills/groundwork-architect/references/surface-architecture.md

@@ -0,0 +1,40 @@
+# Surface Architecture
+
+A surface — web, mobile, CLI, desktop, an agent UI — is an adapter over the capability core, not a home for business logic. The architect owns the **seam**: how the surface reaches the core, how a large surface decomposes, where rendering runs, and where the design-system contract sits. (UI implementation belongs to the surface-engineer skills; design language to the design-system skill — this reference decides where the line is, not how the button looks.)
+
+## Surfaces are adapters over the core
+
+A surface renders state and orchestrates calls to the core's contracts; it holds no domain rules. If a rule must hold on every surface, it lives in the core — a surface that re-implements pricing, validation, or a state machine is a drift waiting to happen. The core is designed headless and proven with no surface running.
+
+## The backend-for-frontend shapes the contract per surface
+
+Each surface gets a thin **BFF** that adapts the core's contracts to what that surface needs — aggregating, trimming, reshaping — so the client is not stitching six calls or over-fetching a viewport. React Server Components act as a built-in BFF for a web surface. Keep it an adapter: the moment business rules accrete in the BFF, it has become a shadow core.
+
+## Render on the server / edge by default
+
+Push rendering and data assembly server-side or to the edge; ship the client the least work it can do. Server-first flattens latency, shrinks the JS payload, and keeps data-fetching boundaries explicit. Reach for heavy client state only where genuine interactivity demands it ([performance-and-scale.md](performance-and-scale.md) on compute placement).
+
+## Decompose a large surface by domain, right-sized
+
+A surface decomposes like services do — by bounded domain, only when teams or load demand it. **Micro-frontends** / **islands** are for independent teams shipping parts of one surface autonomously; for most products a single well-structured surface is simpler and correct. The distributed-monolith failure mode has a front-end twin: many micro-frontends that must deploy in lock-step. Apply the same converging-signals discipline as [core-and-boundaries.md](core-and-boundaries.md).
+
+## The design system is a contract
+
+Tokens and components are a versioned contract across every surface, not decoration — the single source of visual and interaction truth a surface consumes rather than re-invents. Design-system-as-architecture is what keeps many screens and platforms feeling like one product.
+
+## The contract presumes no surface
+
+The core's contract serves every surface and presumes none — a session assumption in a response, markup where data belongs, viewport-sized pagination is the bug the next surface hits ([api-and-contracts.md](api-and-contracts.md)). An agent driving the interface via **AG-UI** is itself a surface type, and the most demanding test of a surface-neutral contract.
+
+## Budgets are architectural
+
+A surface ships against committed budgets — interaction latency, bundle size, accessibility floors — enforced in CI as a fitness function, because they are properties of the architecture, not end-of-project polish.
+
+## Antipatterns to catch
+
+- **Business logic in the surface** — a rule that will drift from the core.
+- **The fat BFF** — a backend-for-frontend grown into a shadow core.
+- **Micro-frontends by default** — distributing one surface across teams that don't need it, deployed in lock-step.
+- **Re-invented design system** — each screen styling its own components.
+- **Viewport-shaped contracts** — a response only the current layout can consume.
+- **Client-heavy by reflex** — a megabyte of JS to render what the server could have sent.

package/src/hidden-skills/groundwork-architect/sync-anchor.md

@@ -0,0 +1,34 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds. When any listed file
+changes, this skill must be reviewed in the same commit. CI verifies the
+hashes match (`scripts/check_sync_anchors.py`, run by `./dev test contracts`).
+
+The `references/` in this skill are self-contained distillations of these
+sources, written for the architect's decision-time lens. A source edit forces
+a review of the matching reference so the distillation never drifts.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/docs/principles/system-design/code-structure.md | e46fb0a5fc9c4ecee1ac840af9b43dcf00fa66cf9635ce55faabfd5d95bc2362 | 2026-06-19 |
+| src/docs/principles/system-design/api-design.md | e892bd9a1e5edbb016d95fd7a6073076c0cbd1369c22ea6b489bb2fb54d2358f | 2026-06-19 |
+| src/docs/principles/system-design/integration-patterns.md | c06186e2611f1cf393639fbbee46eb19851f83d0b68ec03c8e56df8db781d43c | 2026-06-19 |
+| src/docs/principles/system-design/real-time.md | da420fd1c174b7baa1e9a71902a2384e62f561eb3801a531fdc9831ded72d8f3 | 2026-06-19 |
+| src/docs/principles/system-design/data-engineering.md | fd0df432fc96d51c52e6ad87bd0159fa7eac7840e669fbb4174a2b6a68ae331d | 2026-06-19 |
+| src/docs/principles/quality/reliability.md | 9c9788504e0963458667d2727c3fc2359776108be593a2efc6603f6470002252 | 2026-06-19 |
+| src/docs/principles/quality/performance.md | 18b6d3391c57d97342068f9f1da732b24de4221489d0459bb6ad8900fac0a02e | 2026-06-19 |
+| src/docs/principles/quality/observability.md | d38ac0eb660fdcebf2532f5955f371e10ada7030c6eda58e360f40e1b82b439c | 2026-06-19 |
+| src/docs/principles/quality/security.md | 61157d97677142737ec537954dc5aaad7a04012cc8a3dcc855e2d324287fdc64 | 2026-06-19 |
+| src/docs/principles/quality/privacy.md | d84f6bed50169b40daeb2a0ec7082dbd12d91d3abfa304b169cb9eb3fab494fb | 2026-06-19 |
+| src/docs/principles/delivery/platform.md | 3cbf6c13298bf1c148278ae26acdbc2601a06615ff8d85cdb0de3b41c008c626 | 2026-06-19 |
+| src/docs/principles/delivery/progressive-delivery.md | 002806b15448ea8c509edd0fdf050d35397ed9e39e77abf5b8fbb3943ab296d9 | 2026-06-19 |
+| src/docs/principles/delivery/cost-engineering.md | b2e29328e8f704c6d385173247b7d3ccaf205b71b240b54f14193b8372befe58 | 2026-06-19 |
+| src/docs/principles/ai-native/agent-native-systems.md | a59972f54655061a66e696b000fb484563f7e882a463d7d448fe848f6b1a6162 | 2026-06-19 |
+| src/docs/principles/ai-native/ai-engineering.md | 79f8796d9ede943a3685ffc897e196c3ed081fd2861052df3003d34d3374e939 | 2026-06-19 |
+| src/docs/principles/ai-native/agentic-systems.md | faf79028b59ccb6221c1e88ab2f67685c4e1b3626498a81e2bf5c7fc58298990 | 2026-06-19 |
+| src/docs/principles/system-design/architecture-decisions.md | f02a30e5b490d2228ec1c06277e9e5967d40b9c3677e03c86a9b0683b119b874 | 2026-06-24 |
+| src/docs/principles/system-design/evolutionary-architecture.md | 6b50d45c4c15b087160e37f1cc98934eb5ba1031319adae61aa838b930abd366 | 2026-06-19 |
+| src/docs/principles/system-design/surface-architecture.md | 724e2183433b0db8d54466deffc0be877d847cdb6b61f0da9060491907151b91 | 2026-06-19 |
+| src/docs/principles/system-design/identity-and-access.md | 18c99f755a37bec69de595a9784171c88639845c13c2f5a8497b55e40c3a5edf | 2026-06-19 |
+| src/docs/principles/system-design/durable-execution.md | e4faad5864bcbecb80c79983be6a941fee652f2f78b38701dd8bd2dda47c3ec3 | 2026-06-19 |
+| src/docs/principles/index.md | 768a6702488641666b785e1aaa694414b4544d97ee098488d447c3c59b20b096 | 2026-06-19 |

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

@@ -0,0 +1,50 @@
+# Architecture Foundation
+
+This document defines the physical and logical boundaries of the system required to deliver the MVP.
+
+## 1. Constraints & Budgets
+
+## 2. Top-Level Topology
+
+A `graph` diagram is **required** here — it is the reader's first mental model of the system. Show every service and the external dependencies (datastores, brokers, third-party APIs) and the connections between them; label each edge with what flows along it. The prose names what each node owns; the diagram carries the shape.
+
+```mermaid
+graph TD
+    client[Client] --> api[Core API]
+    api --> db[(Postgres)]
+```
+
+## 3. Key Capabilities & Technical Decisions
+
+### Capability Ports & Providers
+
+Each technical capability the system depends on — LLM inference, a relational or vector store, messaging, telemetry, object storage, email, payments — is an **interface** the system depends on, satisfied by exactly one chosen **provider**: the implementation that fulfils it, wired in at the edge and swappable. Record the capability, the provider, and the provider's **operational footprint** (exactly one of `env` · `compose-service` · `runner` · `none`), with a one-line rationale. `none` is a first-class choice: a **bare interface** — the capability plus a failing contract test, no provider yet — to be built later as a bet. There are no default providers; infrastructure (a database, a tracing backend) appears *because* a provider's footprint requires it, never as a guess.
+
+> Distinct from the **capability ledger** in `docs/surfaces.md`, which tracks user-facing *features* across surfaces. This table is about *technical capabilities* and the providers that satisfy them.
+
+| Capability | Provider | Footprint | Rationale |
+|---|---|---|---|
+
+## 4. Component Boundaries & Contracts
+
+## 5. Communication & Integration Patterns
+
+For each non-trivial flow across services — a request that fans out, an event chain, an async path — draw a `sequenceDiagram` so timing and ordering are legible. The prose explains the failure modes and the design decisions the diagram cannot show. Skip trivial single-hop calls.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant A as Core API
+    participant W as Worker
+    C->>A: submit job
+    A->>W: enqueue
+    W-->>A: result
+    A-->>C: 200 + job id
+```
+
+## 6. Service-Level Requirements
+
+| Requirement | Originates From | Applies To |
+|---|---|---|
+
+## 7. Surfaces & Capability Core