@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/skills/scenario/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: scenario
+owner: baseline
+description: Write executable failing tests from a recipe handed to you by the main context. Used by `/tdd` Step 2 and ad-hoc when a phase needs tests-first to drive implementation. Decisions about which scenarios to cover, which categories matter, and which fixtures to use are made by the caller — this skill executes that recipe with code-structure discipline.
+---
+
+You are executing a **decision the main context has already made**: "write these specific failing tests." You do not invent scope, expand categories, or rewrite test conventions to your taste.
+
+# Mandatory first step
+
+Invoke `Skill(code-structure)` before writing any test file. Test files are code; the layer/abstraction rules apply.
+
+# Inputs the caller must provide
+
+If any are missing, **stop and ask** — do not infer. Inference is the failure mode.
+
+- **Recipe**: an explicit list of scenarios to write. Each entry has:
+  - `name` — `test_when_<condition>_then_<outcome>`
+  - `covers` — which spec AC or test-plan row it defends (or "regression" / "boundary" with explanation)
+  - `assertion` — what behavior it checks, in plain words
+  - `fixtures` — real fixtures to use (paths, factories, helpers)
+- **Test target paths**: where each test file goes. The caller resolves this from `project.json → tdd.test_globs` and the source under test.
+- **Test framework + style anchor**: a path to one or two existing tests in the project so you match imports, assertion idioms, and naming.
+- **Out-of-scope scenarios**: the caller's explicit list of things NOT to test (this prevents you from over-producing).
+
+# Method
+
+1. Read the style anchor tests in full. Match imports, assertion idioms, fixture wiring, naming.
+2. Read `MEMORY.md` at `.claude/skill-memory/scenario/` if present — accumulated test conventions for this repo (fixture locations, framework quirks, helper idioms).
+3. For each entry in the recipe, write a test that:
+   - Uses the exact `name` the caller specified.
+   - Asserts the behavior described in `assertion`. No softer, no broader.
+   - Uses the `fixtures` provided. Real test DB, real filesystem temp dir. Mocks ONLY for: third-party HTTP APIs that can't run locally, system clock, OS randomness — each marked `# MOCK: <reason>`.
+   - Is the smallest test that demonstrates the assertion. No setup theater.
+4. Confirm each test fails for the right reason: run the test command on the new files and grep for the new test names. Capture which ones FAIL (good — they're red, ready for `implement`) vs which ones PASS or ERROR (bad — surface to caller).
+5. After authoring, append any new convention you discovered to `.claude/skill-memory/scenario/MEMORY.md` (file path conventions, fixture idioms, framework quirks). Do not record per-task scenario content there.
+
+# Output
+
+Return inline:
+
+```
+# Scenarios — <slug or task id>
+
+## Written
+- <test_file_path>
+  - <test_name> — covers <recipe.covers> — RED | PASS_UNEXPECTEDLY | ERROR
+
+## Did NOT write
+- <recipe entry skipped> — reason
+
+## Open questions for the caller
+- <a question that the recipe didn't answer and you couldn't safely guess>
+```
+
+# Constraints
+
+- **You receive a recipe; you do not author scenario lists.** If the caller says "write tests for the auth flow" without listing scenarios, stop and ask for the recipe. Do not improvise.
+- **Never write stub tests** (bodies that are `pass` or `assert true`).
+- **Never write implementation code.** Tests only.
+- **Never write a test file that won't be collectable.** If the source module doesn't exist yet, use `pytest.importorskip` / dynamic import / equivalent so the test loads and fails with a clear error.
+- **Never modify other tests** to make yours pass.
+- **Never approve specs or write to `docs/specs/`.**
+- **Memory writes only to `.claude/skill-memory/scenario/`.** Test files go to project paths.

package/obj/template/.claude/skills/scout/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: scout
+owner: baseline
+description: Workflow Phase 2 — Codebase Scouting and Constraint Discovery. Maps the relevant slice of the codebase for a given task. Produces a scout report at `docs/scout/<slug>.md` naming the files, modules, and patterns the proposed work touches or constrains. Executes in main context with full conversation visibility — no agent delegation.
+argument-hint: "[optional: specific path to scope the scout]"
+---
+
+You are mapping the slice of the codebase that matters for the current task — no more, no less. The scout report is consumed downstream by `/research` and `/spec`.
+
+# Prereqs
+
+- `.claude/state/workflow.json` exists.
+- `intake` is in `completed` OR in `exceptions`. If neither, stop and direct the user to invoke `intake`.
+
+# Inputs
+
+- The intake document at `docs/intake/<slug>.md` — read **Problem** and **Goal** first; they define scope.
+- The BRD at `docs/brd/<slug>.md` if present — In/Out scope lists.
+- The codebase at the project root.
+- Optional argument: a specific path to scope the scout.
+
+If no intake exists (ad-hoc invocation), fall back to the parent task description and note in the report that the scout ran without a structured intake.
+
+# Method
+
+1. **Identify the nouns and verbs in the task.** Each is a search anchor.
+2. **For each anchor:**
+   - `rg` (or `grep -r`) for the exact term, filtered to source directories.
+   - Read the top 3–5 hits with surrounding context.
+   - Follow imports/callers one hop out. Do not recurse further.
+3. **Identify entry points** — HTTP routes, CLI commands, cron jobs, queue consumers — that would trigger the code path being modified.
+4. **Identify existing tests** for the affected code. Note flaky/skipped ones.
+5. **Note constraints** — config files, feature flags, migrations, deploy manifests that need lockstep changes.
+
+# Output
+
+Write the report to `docs/scout/<slug>.md` (create the directory if missing). Format:
+
+```
+# Codebase Scout Report — <task>
+
+## Primary touchpoints
+- <path:line> — <role in the task>
+- ...
+
+## Entry points that reach this code
+- <HTTP route / CLI cmd / job> at <path:line>
+
+## Existing tests
+- <test path> — <what it covers> — <passing? skipped?>
+
+## Constraints and co-changes
+- <config / migration / flag> — <why it's linked>
+
+## Patterns in use here
+- <1–3 sentences on the style the code follows, for the implementer>
+
+## Risks / landmines
+- <anything surprising: dead code, TODO comments, shims, version skew>
+```
+
+After writing the file, append `"scout"` to `workflow.json → completed`.
+
+Tell the user: `Scout report at <path>. Next: /research.`
+
+# Constraints
+
+- **Project source is read-only during scout.** Do not modify project files. The only write is to `docs/scout/<slug>.md`.
+- **Do not speculate.** If a search turns up nothing, say so. Do not invent paths.
+- **Keep the report under ~300 lines.** If the surface is genuinely larger, say so and propose a scoping split with the user.
+- **Do not recommend an implementation approach.** That is `/research`'s job. Stick to what is.
+- **No code generation.** No new files outside `docs/scout/`.

package/obj/template/.claude/skills/security/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: security
+owner: baseline
+description: Workflow Phase 8 (optional) — OWASP-aligned security review of pending code changes. Produces a prioritized findings report (Critical/High/Medium/Low) mapped to OWASP Top 10 and CWE IDs. Output at `docs/security/<slug>-<date>.md`. Read-only.
+---
+
+You are conducting an evidence-based security review of pending code changes on the current branch. No fixes are applied here — fixes go through `/tdd` or a follow-up patch. This skill produces findings.
+
+# Prereqs
+
+- `simplify` in `completed`.
+
+Per `workflow.json → exceptions`, security may be skipped for low-risk changes. Triage decides.
+
+# Scope
+
+Review the current branch's changes (git diff vs. base branch) and any files the user names explicitly. Do **not** review the full repo history.
+
+Focus areas, in order:
+
+1. **OWASP Top 10 (2021)** — A01 Broken Access Control, A02 Cryptographic Failures, A03 Injection, A04 Insecure Design, A05 Security Misconfiguration, A06 Vulnerable & Outdated Components, A07 Identification & Authentication Failures, A08 Software & Data Integrity Failures, A09 Logging & Monitoring Failures, A10 SSRF.
+2. **Secrets hygiene** — hardcoded tokens, API keys, private keys, `.env` leakage.
+3. **Input validation / output encoding** at trust boundaries (HTTP handlers, CLI entrypoints, message consumers, file parsers).
+4. **AuthN / AuthZ** — missing checks, IDOR, privilege confusion, session fixation.
+5. **Cryptography** — weak algorithms, hardcoded IVs, ECB mode, unsalted hashes, homegrown crypto.
+6. **Dependency risk** — newly added packages; check known CVEs via context7 / WebFetch advisory DBs.
+
+# Method
+
+1. `git diff --stat` then `git diff` against the base branch.
+2. For each changed file, identify the trust boundary (if any) and enumerate tainted data flows.
+3. For any library's secure-usage API in doubt, hit the `context7` MCP — never recall crypto/auth APIs from training data.
+4. Run existing security linters if configured (`bandit`, `semgrep`, `gosec`, `npm audit`, `pip-audit`) via Bash. Do **not** install new tools.
+
+# Output
+
+Write the report to `docs/security/<slug>-<date>.md`. Format:
+
+```
+# Security Review — <branch name> — <date>
+
+## Summary
+<1–3 sentences. State overall risk: LOW | MEDIUM | HIGH | CRITICAL.>
+
+## Findings
+
+### [CRITICAL|HIGH|MEDIUM|LOW] <short title>
+- **OWASP**: <A0X - category> | **CWE**: CWE-XXX
+- **File**: path:line
+- **Evidence**:
+  ```
+  <5–10 lines of the offending code>
+  ```
+- **Impact**: <what an attacker can do>
+- **Recommendation**: <concrete fix, not "consider sanitizing">
+
+## Dependencies
+<new packages in this diff, with CVE check results>
+
+## Out of scope / Noted
+<Observations not in the diff but worth flagging for later.>
+```
+
+# Decision after review
+
+- **CRITICAL or HIGH findings** → surface them, do **not** mark this phase complete. Ask the user how to proceed (fix now, track and accept risk, or defer).
+- **Only MEDIUM/LOW** → append `"security"` to `workflow.json → completed`. Tell the user: `Security review at <path>. Next: /integrate.`
+
+# Constraints
+
+- **Never modify project code.** This skill is read-only against project files. The only write is to `docs/security/`.
+- **Never claim PASS/clean without enumerating what you checked.**
+- **Speculative findings ("could potentially")** → mark LOW and say so.
+- **Don't dump full file contents.** Cite `path:line` and show minimal snippets.
+- **If the diff is empty or larger than ~2000 lines**, report that and stop.

package/obj/template/.claude/skills/simplify/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: simplify
+owner: baseline
+description: Workflow Phase 7 — Mechanical cleanup pass over the branch diff, followed by a `code-structure` review pass and a `verify` re-stamp. Shadows the global `simplify` skill at project scope; the cleanup pass is performed inline rather than via Skill self-call.
+---
+
+# Prereq
+
+`tdd` in `completed` AND `.claude/state/last_test_result` line 1 is `PASS`.
+
+# Note on shadowing
+
+This skill **shadows** the global `simplify` skill (same name, project scope wins). To avoid invoking itself, the cleanup pass is performed inline below — do **not** invoke `simplify` via the Skill tool from inside this file.
+
+# Steps
+
+## 1. Verify prereq
+
+Read `.claude/state/last_test_result`; line 1 must be `PASS`.
+
+## 2. Mechanical cleanup pass over the diff
+
+Across the diff of this branch — **delete, don't comment out**:
+
+- Dead code (unreferenced functions, unused imports, unreachable branches).
+- Duplication that can collapse without harming readability.
+- Over-abstraction (premature factories, single-implementation interfaces).
+- Commented-out code — seed.md forbids it.
+- `TODO` / `FIXME` / `HACK` / `XXX` — resolve or remove; seed.md forbids them in source.
+- Stubs, `raise NotImplementedError`, "not implemented" placeholders.
+
+## 3. `code-structure` review pass
+
+Invoke `Skill(code-structure)` and apply its Detection Rules to every file the branch touches:
+
+- Orchestration files leaking raw primitives or inline business logic.
+- Siblings at mixed abstraction levels (named call next to raw primitive).
+- Loop bodies carrying more than one abstraction level.
+- Domain modules reaching directly for raw infrastructure.
+- Files longer than ~80 lines of substantive code — split along layer lines.
+
+Fixes here are in scope. Refactors that go beyond layering (new design patterns, interface changes) are **out of scope** — flag them and leave for a follow-up spec.
+
+## 4. Scope guardrails
+
+- Do not add features.
+- Do not refactor scope beyond cleanup.
+- Do not change public APIs. If a public API needs changing, surface it and stop — that belongs in a new spec.
+
+## 5. Re-verify (inlined)
+
+Inline the four mechanical operations from `.claude/skills/verify/SKILL.md` (the contract doc):
+
+- Read `.claude/project.json` → `test.cmd`. If absent or empty, the verdict is `FAIL` with reason "project.json not configured" and step 5 stops with that verdict.
+- Run the command via Bash from the project root. Capture stdout, stderr, exit code. Do not retry.
+- Apply verdict rules: `PASS` iff exit code 0 AND at least one test executed AND no failed/errored test; otherwise `FAIL`.
+- Atomically write `.claude/state/last_test_result` with the canonical four-line format (`<PASS|FAIL>\n<ISO-8601 UTC timestamp>\n<exact command>\n<exit code>\n`). The `verify_pass_guard` hook reads line 1 as the binding verdict.
+
+## 6. Decide + write harness_state
+
+- **Still PASS** → append `"simplify"` to `completed`. Marker FIRST: `echo "<slug>" > .claude/state/.harness_active` (refresh the active marker). Then write `.claude/state/harness_state` with `{state: "continue", slug, reason: "simplify clean; next: security or integrate"}` — exactly three keys; no `written_at`, no `tick_count`. Tell the user: "Cleanup done, tests green. Next: `/security` (optional) or `/integrate`."
+- **FAIL** → revert the cleanup changes and surface exactly what broke (test name + first assertion). Marker FIRST: `rm -f .claude/state/.harness_active`. Then write `harness_state` with `{state: "yielded", slug, reason: "simplify FAIL after cleanup; reverted; needs user review"}`.
+
+# Constraints
+
+- **Never invoke the global `simplify` via the Skill tool from this file.** Name shadowing makes that a self-call.
+- **Cleanup is mechanical.** If you find yourself reasoning about a refactor's design implications, stop — that's outside this phase's scope.

package/obj/template/.claude/skills/spec/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: spec
+owner: baseline
+description: Draft a Workflow Phase 4 technical spec from an intake (and optionally a BRD + scout + research memo). The spec defines how the system will change: design (C4 + UML + dependency graph in PlantUML), data, APIs, tests, rollout, rollback. Output lives at `docs/specs/<slug>.md`. Never self-approves — approval happens via `/approve-spec`.
+---
+
+# Spec — Workflow Phase 4
+
+You are drafting a **technical spec**. The spec answers "how" — what changes, in which files, behind which flags, with which tests and rollout. It is the document a different engineer can pick up tomorrow and build from.
+
+The spec is **diagram-driven**: C4 + UML + a dependency graph in PlantUML, tables for contracts and traceability, prose only for what a diagram cannot say. Three hooks enforce this at the Write boundary:
+
+- `artifact_template_guard` — required `##` headings present.
+- `spec_diagram_presence_guard` — required diagram kinds present inside ```plantuml``` fences.
+- `plantuml_syntax_guard` — every ```plantuml``` fence parses.
+
+## Prerequisite
+
+Per `.claude/state/workflow.json`, `research` must be in `completed` OR in `exceptions` (quickfixes and some bugfixes skip research). The `track_guard` hook enforces this at Write time, but verify upfront so you can stop with a clear message rather than hitting the guard.
+
+## Inputs
+
+- **Required**: the intake at `docs/intake/<slug>.md` (or the bugfix description if entry was `/triage` → `spec`).
+- **Optional**: BRD at `docs/brd/<slug>.md`, scout report at `docs/scout/<slug>.md`, research memo at `docs/research/<slug>.md`.
+- `template.md` in this skill directory — the canonical structure.
+
+## Steps
+
+1. Read all available upstream artifacts. Note the acceptance-criterion IDs from the intake/BRD — the spec's AC table must either reuse those IDs or trace to them explicitly.
+2. Read `template.md`. Every `##` heading must appear in the output; every required diagram kind (C4 Context/Container/Component, class, sequence, dependency graph) must appear inside a ```plantuml``` fence.
+3. Draft each diagram **first**, then the surrounding table/prose. If you cannot draw a diagram, you do not understand that part of the design yet — record it under **Open questions** rather than faking prose.
+4. Confirm every third-party API cited (in the Libraries table, Contracts rows, or diagram labels) via the `context7` MCP. Record the library version. Never recall an API from training data.
+5. Verify each `AC-NNN` row points to a real `§Behavior #N` anchor, and that the corresponding sequence diagram actually defines the promised behaviour.
+6. Run `/spec-lint <slug>` before saving if you want to preview what the guards will report — same checks, not enforced.
+7. Write to `docs/specs/<slug>.md`.
+8. **NEVER write `Status: Approved`, `Approved: true`, or any variation.** The `spec_approval_guard` blocks self-approval. Approval is the token written by `/approve-spec` to `.claude/state/spec_approvals/<slug>.approval`.
+9. Append `"spec"` to `.claude/state/workflow.json` → `completed`.
+10. Tell the user: "Spec drafted at `docs/specs/<slug>.md`. Render diagrams with `/spec-render <slug>`, review, then `/approve-spec <slug>` (or pass the full path). After approval, `/tdd`."
+
+## Diagram rules (non-negotiable)
+
+- **Renderable PlantUML only.** Every fence must validate — broken diagrams are worse than missing ones because they waste reviewer time. Test locally with `plantuml -checkonly -pipe` or the `plantuml` MCP server.
+- **C4 uses the stdlib includes**: `!include <C4/C4_Context>`, `!include <C4/C4_Container>`, `!include <C4/C4_Component>`. No remote URL includes — they break offline review.
+- **One sequence per AC.** The sequence *is* the contract; prose descriptions of behaviour are forbidden. If an AC spans multiple interactions, use `==` dividers inside one sequence diagram rather than splitting into two.
+- **Dependency graph is directed and acyclic.** `A --> B` means "A depends on B". Cycles mean the design has a deadlock risk — surface under Open questions, don't draw the cycle.
+- **Class diagram mirrors the migration DDL.** Every `<<new>>` / `<<changed>>` field must have a matching `ALTER` in the DDL block. If the DDL changes, update the class diagram in the same edit.
+
+## Drafting rules (from seed.md § Code Standards)
+
+- **No stubs — EVER.** If the spec declares a function or endpoint, define its contract fully: inputs, outputs, errors, idempotency, side effects, ownership. If you can't, do not declare it — flag it as an Open question.
+- **YAGNI.** The spec describes what is built now. A "future option" with no current test driving it does not belong here.
+- **Context7 for every library API.** API shape confirmed via the `context7` MCP, not training recall. Record the library version.
+- **Acceptance criteria are testable.** Numbered, concrete, traced. "Users can retry" is not an AC; "on 5xx from upstream, worker retries with 100/200/400 ms backoff, max 3 tries, then dead-letters" is.
+- **Rollout and rollback are named, not 'standard.'** Which flag? Which kill-switch? Which metric + threshold + window detects a bad rollout within 5 minutes?
+
+## Archive planning
+
+The spec template includes an **Archive plan** section. Its purpose is to *document at drafting time* which artifacts ship together when this work lands. For 90% of specs the default bundle (every file named `<slug>.*` in the workflow directories) is exactly right — leave the "Extras" list as *(none)*. Only populate it if this work produces a one-off file that isn't slug-named but belongs with the bundle (e.g., a migration script kept for reference, a runbook).
+
+The `archive` skill (Phase 10.5) reads the slug convention automatically; the human-authored "Extras" list is an advisory — surface it to the reviewer so the bundle is transparent before approval.
+
+## Common failure modes (don't)
+
+- Restating the intake verbatim — the spec earns its keep by adding design, not by re-narrating requirements.
+- Writing behavior as prose ("we'll retry on 5xx") — draw the sequence.
+- A `C4_Container` diagram that invents containers not in any code path — if it isn't deployable today, it belongs in a future-work spec.
+- An AC row whose `§Behavior #N` anchor resolves to an empty section.
+- Hiding open questions in body prose — surface them under **Open questions** so the reviewer (and `/approve-spec` gate) sees them.
+- Pre-optimizing — if profiling hasn't run, a performance plan is speculation.

package/obj/template/.claude/skills/spec/template.md

@@ -0,0 +1,274 @@
+# <Spec — technical, short, specific>
+
+<!--
+Technical spec. Produced by the `spec` skill.
+
+Guard-enforced invariants:
+  - Required ## headings (artifact_template_guard):
+        Goal, Design, Acceptance criteria, Test plan.
+  - Required diagram kinds inside ```plantuml``` fences
+    (spec_diagram_presence_guard, configured in project.json →
+     artifacts.required_diagrams.spec):
+        c4_context, c4_container, c4_component,
+        sequence, class, dependency_graph.
+  - Every ```plantuml``` fence must parse (plantuml_syntax_guard).
+
+Approval: NEVER add "Status: Approved" — spec_approval_guard blocks it.
+Approval is a token written by /approve-spec.
+-->
+
+## Context
+
+| Input | Path |
+|---|---|
+| Intake | `docs/intake/<slug>.md` |
+| BRD *(if any)* | `docs/brd/<slug>.md` |
+| Scout *(if any)* | `docs/scout/<slug>.md` |
+| Research *(if any)* | `docs/research/<slug>.md` |
+
+## Goal
+
+<One sentence. What the system does after this spec ships. Not why — the intake owns why.>
+
+## Non-goals
+
+- <Explicit exclusion. Keeps the spec from quietly growing.>
+
+## Design
+
+Diagrams are the contract. Prose is only for things a diagram cannot say.
+
+### C4 — System context
+
+Who interacts with the system, and which external systems it depends on.
+
+```plantuml
+@startuml
+!include <C4/C4_Context>
+title System Context — <system>
+Person(user, "<Role>", "<responsibility>")
+System(sut, "<System under change>", "<one-line purpose>")
+System_Ext(dep1, "<External dep>", "<purpose>")
+Rel(user, sut, "<action>")
+Rel(sut, dep1, "<protocol, verb>")
+@enduml
+```
+
+### C4 — Container
+
+Deployable units inside the system boundary and how they communicate.
+
+```plantuml
+@startuml
+!include <C4/C4_Container>
+title Container — <system>
+System_Boundary(sut, "<System>") {
+  Container(api, "<API>", "<tech>", "<role>")
+  Container(worker, "<Worker>", "<tech>", "<role>")
+  ContainerDb(db, "<DB>", "<engine>", "<stores>")
+}
+Rel(api, worker, "<queue or RPC>")
+Rel(api, db, "reads/writes")
+Rel(worker, db, "writes")
+@enduml
+```
+
+### C4 — Component (changed containers only)
+
+One diagram per container whose internals change. Skip containers that are untouched.
+
+```plantuml
+@startuml
+!include <C4/C4_Component>
+title Component — <container>
+Container_Boundary(api, "<API>") {
+  Component(ctrl, "<Controller>", "<tech>", "<role>")
+  Component(svc,  "<Service>",    "<tech>", "<role>")
+  Component(repo, "<Repo>",       "<tech>", "<role>")
+}
+Rel(ctrl, svc, "invokes")
+Rel(svc, repo, "persists via")
+@enduml
+```
+
+### Data model — class diagram
+
+Entities, fields, and cardinality. Mark new/changed with `<<new>>` or `<<changed>>`.
+
+```plantuml
+@startuml
+title Data model — <domain>
+class Order {
+  +id: UUID <<pk>>
+  +status: OrderStatus
+  +total_cents: int <<new>>
+  +created_at: timestamp
+}
+class LineItem {
+  +order_id: UUID <<fk>>
+  +sku: string
+  +qty: int
+}
+Order "1" *-- "many" LineItem
+@enduml
+```
+
+#### Migration DDL
+
+```sql
+-- forward
+ALTER TABLE orders ADD COLUMN total_cents int NOT NULL DEFAULT 0;
+-- reverse
+ALTER TABLE orders DROP COLUMN total_cents;
+```
+
+### Behavior — sequence per AC
+
+One sequence diagram per acceptance criterion. The sequence is the contract: label every arrow with method + payload, include failure branches explicitly. Section anchors here (`§Behavior #N`) are referenced from the AC table.
+
+```plantuml
+@startuml
+title Behavior #1 — <AC-001 summary>
+actor Client
+participant API
+participant Service
+database DB
+
+Client -> API : POST /orders {sku, qty}
+API -> Service : createOrder(cmd)
+Service -> DB : INSERT order
+alt success
+  DB --> Service : order_id
+  Service --> API : 201 Created {order_id}
+else idempotency conflict
+  DB --> Service : conflict
+  Service --> API : 409 Conflict
+end
+API --> Client : response
+@enduml
+```
+
+### State — core entity *(only if stateful)*
+
+Finite-state model. Omit the block if the system has no non-trivial state machine — but keep the heading so reviewers see the explicit choice.
+
+```plantuml
+@startuml
+title State — <entity>
+[*] --> Draft
+Draft --> Submitted : submit
+Submitted --> Approved : approve
+Submitted --> Rejected : reject
+Approved --> [*]
+Rejected --> [*]
+@enduml
+```
+
+### Dependencies — graph
+
+Directed graph of build/runtime dependencies. Edge `A --> B` reads "A depends on B". The first line `' @kind dependency-graph` is a PlantUML comment that identifies the block to `spec_diagram_presence_guard`.
+
+```plantuml
+@startuml
+' @kind dependency-graph
+title Dependencies — <system>
+left to right direction
+[api] --> [service]
+[service] --> [repo]
+[repo] --> [postgres]
+[service] --> [redis]
+[worker] --> [service]
+[worker] --> [sqs]
+@enduml
+```
+
+### Contracts
+
+One row per endpoint / CLI command / message. Tables, not prose.
+
+| Kind | Name | Input | Output | Errors | Idempotent |
+|---|---|---|---|---|---|
+| HTTP | `POST /orders` | `{sku, qty}` | `201 {order_id}` | 400, 409, 5xx | yes (`Idempotency-Key`) |
+| Event | `order.created.v1` | `{order_id, total_cents}` | — | — | consumer de-dupes |
+
+### Libraries and versions
+
+Every entry must be confirmed via the `context7` MCP — no training-data recall for third-party APIs (seed.md § Context7 Rule).
+
+| Library@version | Purpose | Key APIs | Confirmed via context7 |
+|---|---|---|---|
+| `<lib@x.y.z>` | `<use>` | `<api names>` | yes |
+
+### Alternatives considered
+
+| Alt | Summary | Rejected because |
+|---|---|---|
+| A | <description> | <reason> |
+| B | <description> | <reason> |
+
+## Design calls
+
+When this spec's `write_set` intersects `project.json → tdd.ui_globs`, every UI surface needs a design call here. `/tdd` Step 6 reads each row, serializes it to a `task_brief`, and invokes `Skill(design-ui, task_brief)` once per row. design-ui then routes through `impeccable` for the actual design work.
+
+If the write_set has no UI files, leave the section body as `*(none)*` — the required heading must still be present per `project.json → artifacts.required_sections.spec`. `spec_design_calls_guard` only fires (denies the write) when both conditions hold: write_set intersects ui_globs AND the section body is missing or empty.
+
+| Slug | Intent | Target files | Write set | Register | References |
+|---|---|---|---|---|---|
+| settings-page | build a settings page that doesn't feel like a SaaS template | `app/settings/page.tsx` | `app/settings/**` | inherit | — |
+
+For specs with no UI surface:
+
+- *(none)*
+
+## Acceptance criteria
+
+Numbered, testable, traced. Each AC points to the §Behavior sequence that defines it.
+
+| ID | Criterion (given / when / then) | Upstream AC | Sequence |
+|---|---|---|---|
+| AC-001 | given X, when Y, then Z | intake AC 1 | §Behavior #1 |
+| AC-002 | given X, when Y, then Z | BR-001 | §Behavior #2 |
+
+## Test plan
+
+Scenarios by category. The `scenario` skill (invoked from `/tdd` or `/swarm-dispatch` workers) turns these into failing tests; main context decides the recipe before invocation. Every row must reference at least one AC (or an invariant the regression row defends).
+
+| Category | Scenario | Expected | Covers |
+|---|---|---|---|
+| Golden path | <case> | <result> | AC-001 |
+| Input boundary | empty / max / off-by-one / unicode | <result> | AC-001 |
+| Contract violation | invalid type / missing field / unauthorized | <result> | AC-002 |
+| Concurrency / ordering | <race, interleaving> | <result> | — |
+| Failure mode | dep down / timeout / partial write | <result> | — |
+| Regression trap | <invariant> | unchanged | — |
+
+## Observability
+
+| Signal | Name | Shape | Purpose |
+|---|---|---|---|
+| Log | `<event>` | fields: `<names>` | audit / debug |
+| Metric | `<name>` | counter/histogram, labels: `<names>` | SLO |
+| Alarm | `<name>` | `<metric + threshold + window>` | page target |
+
+## Rollout
+
+- **Feature flag**: `<flag.name>` — default off.
+- **Migration order**: 1 DDL → 2 backfill → 3 dual-write → 4 read-swap → 5 cleanup.
+- **Canary**: <percentage, duration, success signal>.
+
+## Rollback
+
+- **Kill-switch**: `<flag off | deploy revert | command>`.
+- **Signal to roll back**: `<metric + threshold + window>` — must trip within 5 minutes of a bad rollout.
+
+## Archive plan
+
+When this spec ships, the `archive` skill (Phase 10.5) moves the following into `docs/archive/<ship-date>/<slug>/`. Defaults are the slug-matched artifacts; add any one-off files this work produced (e.g., migration scripts kept for reference) below. Advisory — the `archive` skill discovers slug-matched files automatically; this section documents the *bundle* for the human reviewer.
+
+- Defaults *(automatic)*: intake, brd, scout, research, spec, spec-rendered/, spec approval, swarm plan + approval (if used), security reports (concatenated).
+- Extras *(list any non-default files)*:
+  - *(none)*
+
+## Open questions
+
+- <question — blocks approval until resolved>