discipline-md 0.1.0

package/templates/README.md

@@ -0,0 +1,60 @@
+# Project Name
+
+<!-- Root README entrypoint. Keep this concise and point to docs/ for full context. -->
+<!-- If copied into docs/README.md instead, include the detailed folder structure and commands below. -->
+<!-- Do not put task lists, status updates, or volatile notes here. -->
+
+## Quick Start
+
+```bash
+# install dependencies
+
+# run locally
+
+# run tests
+```
+
+## Folder Structure
+
+```text
+project-root/
+├── docs/
+├── src/
+└── ...
+```
+
+## Important Docs
+
+- `docs/README.md` - detailed project orientation, setup, and folder structure
+- `docs/HANDOFF.md` - reading order, update rules, workflow (read first)
+- `docs/TODO.md` - current active work and test checklist
+- `docs/AGENTS.md` - AI agent playbook (host model, named subagent roles, autonomy tags, human-collab gate)
+- `docs/AUTONOMOUS_QUEUE.md` - pre-approved tasks for unsupervised AI runs (optional)
+- `docs/PROJECT_CONTEXT.md` - product and domain context
+- `docs/ARCHITECTURE.md` - runtime structure and key flows
+- `docs/DATA_MODEL.md` - persistence and schemas
+- `docs/API_REFERENCE.md` - endpoints and integrations
+- `docs/ASSETS.md` - media asset paths
+- `docs/DEPLOYMENT.md` - hosting and launch checklist
+- `docs/CHANGELOG.md` - completed changes
+- `docs/ROADMAP.md` - long-term planning
+- `docs/DECISIONS.md` - durable decision records
+- `docs/CREDITS.md` - third-party libraries, vendored code, assets, fonts, attributions
+- `LICENSE` (repo root) - project license
+- `NOTICE` (repo root) - third-party attribution summary (if applicable)
+
+## AI Workflow
+
+The full agent playbook lives at `docs/AGENTS.md`: host model and escalation rules, cross-ecosystem tier framework (Frontier / Workhorse / Recon), coordinator-heavy host posture, named subagent roles with input/output contracts (recon, doc-audit, backend-impact, frontend-impact, test-strategist, cross-repo-sync, planner, architect, security-reviewer, debugger), autonomy tags, and the human-collaboration gate. Read it before spawning subagents or picking up tagged work.
+
+Subagents do not own commits, merges, or doc-completion-gate sign-off — the host reconciles results.
+
+## Current Status
+
+Summarize development state, launch state, or known limitations.
+
+## Tests
+
+```bash
+# unit test command
+```

package/templates/ROADMAP.md

@@ -0,0 +1,96 @@
+# Roadmap
+
+Use this file for longer-term planning. Keep immediate active tasks in `TODO.md`; keep strategic plans, future milestones, and larger feature ideas here.
+
+## Vision
+
+Describe the long-term direction of the project.
+
+## Milestone status markers
+
+Append a status marker to each milestone heading so the planning surface is skim-able at a glance:
+
+- `(✅ YYYY-MM-DD)` — completed; the date is the ship date. Cross-link the matching `docs/CHANGELOG.md` entry under the milestone (the CHANGELOG is the chronological feature log; the link keeps the two surfaces consistent without duplicating content).
+- `(🟡 in progress)` — actively being worked on right now.
+- `(⏸️ paused)` — work started, intentionally on hold (blocker, dependency, capacity).
+- `(⏭️ deferred)` — pushed out of the current planning horizon; revisit later.
+- *(no marker)* — proposed / not yet started. The default state.
+
+Avoid stacking markers (a milestone is paused or deferred, not both). When a milestone completes, set the date marker, link the CHANGELOG entry, and either keep the heading in place under `## Milestones` or move the whole block down under `## Completed` once the section gets crowded — project's call.
+
+## Milestones
+
+### Milestone Name
+
+Goal:
+
+Target timing:
+
+Planned work:
+
+- [ ] Item.
+- [x] Completed item (use `[x]` inline or strike-through; the milestone marker above tracks the rollup).
+
+### Milestone Name (✅ 2026-04-30)
+
+Shipped. See [CHANGELOG entry](./CHANGELOG.md#2026-04-30-branch-or-pr-or-hash) for details.
+
+Goal:
+
+Planned work:
+
+- [x] Item that shipped.
+- [x] Item that shipped.
+
+### Milestone Name (🟡 in progress)
+
+Goal:
+
+Target timing:
+
+Planned work:
+
+- [x] Item that shipped.
+- [ ] Item still open.
+
+### Milestone Name (⏸️ paused)
+
+Reason for pause:
+
+Goal:
+
+Planned work:
+
+- [ ] Item.
+
+### Milestone Name (⏭️ deferred)
+
+Reason for deferral:
+
+Goal (preserved for the future revisit):
+
+Planned work:
+
+- [ ] Item.
+
+## Future Features
+
+- Feature idea.
+
+## Technical Improvements
+
+- Improvement idea.
+
+## Deferred Ideas
+
+- Idea intentionally postponed.
+
+## Parking Lot
+
+- Loose idea or question that is not ready for active work.
+
+## Completed
+
+Use the `(✅ YYYY-MM-DD)` marker inline on milestone headings as they ship, or move whole milestone blocks here once the section above gets crowded. Cross-link each completed milestone to its `docs/CHANGELOG.md` entry — the CHANGELOG is the chronological feature log; this section is the planning surface kept current. Do not duplicate the CHANGELOG body here.
+
+- ✅ 2026-04-30 — Example completed roadmap item. See [CHANGELOG entry](./CHANGELOG.md#2026-04-30-branch-or-pr-or-hash).

package/templates/SECURITY_AUDIT.md

@@ -0,0 +1,235 @@
+<!--
+  TEMPLATE: SECURITY_AUDIT.md (Tier A5 — pre-launch / periodic security audit)
+
+  WHEN TO USE:
+    - Before first public deploy of any project.
+    - On a periodic cadence after launch (quarterly, or after a major architectural change).
+    - After a known incident, as a "what else have we missed" pass.
+
+  HOW TO USE:
+    1. Copy this file into the project's `docs/` directory.
+    2. Rename to the dated convention: SECURITY_AUDIT_YYYY-MM-DD.md
+       (one file per audit; never overwrite a prior audit's record).
+    3. Replace every <placeholder> with project-specific content.
+    4. Keep prior audits in the repo as a record. Append a "Resolved YYYY-MM-DD"
+       note inline when a finding closes (preserves the original text).
+    5. Severity bands (Critical / High / Medium / Low / Informational) are
+       calibrated against the PRODUCT'S risk profile, not against generic CVSS.
+       A Medium for a banking app may be a Low for a no-PII trivia game.
+
+  RELATED:
+    - Pairs with the Security Auditor agent role contract.
+    - Findings often spawn entries in OPEN_DECISIONS.md or TODO.md.
+-->
+
+# Security Audit — <project-name>
+
+**Date:** <YYYY-MM-DD>
+**Auditor:** <auditor-name-or-role-and-tier>
+**Scope:** <one-line scope statement, e.g. "Source-only review of `<repo-path>` at the state on disk on this date.">
+**Engagement:** <pre-launch | periodic | post-incident | other — and the surrounding context, e.g. "Pre-launch audit before <hosting-platform> deploy.">
+
+## 1. Scope
+
+### Audited
+
+- <list every file tree, manifest, migration, config, and doc surface that was actually read>
+- <name third-party tools run, e.g. `npm audit`, `pnpm audit`, `bandit`, `gitleaks`, etc.>
+- <name source-tree paths, not just "the repo">
+
+### Excluded (per <Founder | Operator | brief>)
+
+- <platform vendors trusted by the engagement, e.g. "Cloudflare itself", "Supabase as a platform">
+- <upstream services we are downstream consumers of>
+- <sibling projects with separate engagements>
+- <any deployed surface — note if there is no live deploy yet>
+- <active probing or penetration testing — typically out of scope for source-only review>
+
+### Assumptions
+
+- <what the operator is responsible for and is presumed to handle correctly, e.g. secret-rotation cadence, MFA on cloud accounts>
+- <what the build pipeline is presumed to do, e.g. ".env.local is gitignored and never committed">
+- <what env vars are operator-controlled vs. user-controllable>
+- <any limitation of the audit environment itself, e.g. "no `.git` history readable">
+
+## 2. Threat Model
+
+### Trust boundaries
+
+```
+        ┌──────────────────────────────────────────┐
+        │ Trusted: <build-host>                    │
+        │   - <what it reads>                      │
+        │   - <what it writes>                     │
+        └──────────────┬───────────────────────────┘
+                       │ <transport, e.g. git push>
+                       ▼
+        ┌──────────────────────────────────────────┐
+        │ Trusted: <build-pipeline>                │
+        │   - <what env / secrets it sees>         │
+        │   - <what artifact it produces>          │
+        └──────────────┬───────────────────────────┘
+                       │ deploy
+                       ▼
+  ┌──────────────────────┐         ┌────────────────────────────┐
+  │ Untrusted: <visitor> │ ◄─────► │ <runtime-host>             │
+  │ <browser | client>   │  HTTPS  │ <surface description>      │
+  └──────────┬───────────┘         └──────────────┬─────────────┘
+             │                                    │
+             │ <client-shipped credential>        │ <server-only credential>
+             ▼                                    ▼
+  ┌──────────────────────┐         ┌────────────────────────────┐
+  │ <data-store>         │ ◄─────► │ <third-party-service>      │
+  │ <table list / KV>    │         │ <vendor>                   │
+  └──────────────────────┘         └────────────────────────────┘
+```
+
+> Replace boxes / arrows with the actual project shape. The point of the diagram
+> is to make the trust boundaries explicit so every finding can be located on
+> one of them. Keep it small enough to read at a glance.
+
+### Data assets
+
+- **<asset-1>.** <one paragraph: what it is, where it lives, what it would mean if leaked / mutated / deleted, value tier (High / Medium / Low).>
+- **<asset-2>.** <…>
+- **<…>.**
+
+> List the SPECIFIC data the project handles. "PII" is too generic — name the
+> tables, columns, files, KV keys. If "no sensitive data" is the answer, state
+> it explicitly so the calibration is documented.
+
+### Attacker shapes
+
+| Shape | Capability | Goal | Realistic? |
+|---|---|---|---|
+| **Script kiddie / curiosity** | Browser dev tools, `curl`, no infra | Poke at endpoints, look at JS | <yes/no + one line> |
+| **Opportunistic spammer / botter** | A few thousand requests/sec from rotating IPs | <stat-skew | quota-exhaust | spam | other> | <yes/no + one line> |
+| **Targeted attacker** | Skilled adversary with patience | Exfiltrate data, gain RCE, pivot to <cloud-account> | <yes/no + one line> |
+| **Insider / operator misconfig** | <Founder | operator | role> | <paste-mistake | accidental commit | other> | <yes/no + one line> |
+| **<custom-shape>** | <…> | <…> | <yes/no + one line> |
+
+> Calibrate "Realistic?" against the actual product. A targeted attacker is
+> implausible against a free trivia game and very plausible against a payments
+> system. Without this calibration the findings get the wrong severity.
+
+### In-scope attack surface
+
+1. <endpoint or surface 1, with file:line if possible>
+2. <endpoint or surface 2>
+3. <client-side bundle contents>
+4. <build-pipeline / dependency posture>
+5. <…>
+
+## 3. Findings
+
+Severity tiers per the role contract, calibrated against the product's actual
+risk profile. Each finding carries: severity, where, exploit story,
+why-it-matters-for-this-product, recommended fix, effort.
+
+### CRITICAL
+
+#### C-1. <one-line finding title>
+
+- **Severity:** Critical
+- **Where:** <file:line, migration name, or "absent file" with the doc that says it should exist>
+- **Exploit story:** <concrete attacker walkthrough — actual command / payload / steps; what they achieve>
+- **Why it matters for THIS product:** <link to the product's value prop or trust contract; explain why this is Critical here even if it would be lower elsewhere>
+- **Recommended fix:**
+  1. <step 1>
+  2. <step 2>
+  3. <…>
+- **Effort:** <XS | S | M | L | XL>
+
+### HIGH
+
+#### H-1. <…>
+
+- **Severity:** High
+- **Where:** <…>
+- **Exploit story:** <…>
+- **Why it matters for THIS product:** <…>
+- **Recommended fix:** <…>
+- **Effort:** <…>
+
+### MEDIUM
+
+#### M-1. <…>
+
+(same shape as above)
+
+### LOW
+
+#### L-1. <…>
+
+(same shape as above)
+
+### INFORMATIONAL
+
+#### I-1. <…>
+
+- **Where:** <…>
+- **Note:** <one paragraph — not a finding, but a flag for completeness or a future-pass item>
+
+## 4. Accept-Risk Candidates
+
+These are real findings the <Founder | Operator> may reasonably accept-risk
+given the product's stage, scope, and audience. Each carries the rationale for
+why an accept-risk decision is defensible AND triggers that should reopen it.
+
+- **AR-1. <finding-id> (<short-title>) accepted <permanently | for the launch window | until <milestone>>.** <one-paragraph rationale>
+  - **Triggers to revisit:** <concrete observable signals — traffic spike, scope expansion, feature add, etc.>
+
+- **AR-2. <finding-id> accepted <…>.** <…>
+  - **Triggers to revisit:** <…>
+
+> Accept-Risk is a deliberate decision, not a forgotten finding. State the
+> accept-risk reasoning explicitly so a future reader (or auditor) can tell
+> "this was considered" from "this was missed."
+
+## 5. Hardening Recommendations Beyond Findings
+
+Defense-in-depth and product-quality items not tied to any specific finding above.
+
+- **H-1. <recommendation>.** <one paragraph — what + why + effort estimate>
+- **H-2. <…>**
+- **H-…**
+
+## 6. Dependencies
+
+### Root manifest (`<package.json | pyproject.toml | Cargo.toml | …>`)
+
+`<npm audit | pnpm audit | pip-audit | cargo audit>` summary, run <YYYY-MM-DD>:
+
+```
+total: <N>
+  critical: <n>
+  high:     <n>
+  moderate: <n>
+  low:      <n>
+  info:     <n>
+
+<one line per finding: package, version range, severity, advisory id, one-line description>
+```
+
+<Plain-language paragraph: which findings reach production runtime vs. dev-only;
+what the realistic exploit window is for each; the recommended fix path
+(`pnpm up …`, `npm audit fix`, semver-major upgrade, etc.).>
+
+### Production-runtime dependencies
+
+<list the production-runtime deps and their audit status — clean or which
+findings apply. Make explicit what does NOT reach production (dev-tool chains
+that show up in audit but never ship).>
+
+## 7. Out-of-Scope Notes
+
+These were noticed during the walk but are outside the agreed scope. Documenting
+so they are not lost.
+
+- **OoS-1.** <one paragraph: what was noticed, why it's out of scope, what the operator should do about it later>
+- **OoS-2.** <…>
+- **OoS-…**
+
+---
+
+**End of report.**

package/templates/SETUP.md

@@ -0,0 +1,162 @@
+<!--
+  TEMPLATE: SETUP.md (one-time first-run discussion checklist)
+
+  WHEN TO USE:
+    - At first-run when the framework is being initialized in a new repo. The
+      agent walks through these questions with the user; the answers are
+      recorded into `docs/HANDOFF.md` ("Project-Specific Landing Zone") or
+      `docs/AGENTS.md` ("Local Overrides"). Each question below names where
+      its answer goes.
+    - This file is a *discussion* surface, not a runtime doc. Once the
+      answers have landed in HANDOFF/AGENTS, delete `docs/SETUP.md` from the
+      project. The framework's own copy stays in `templates/` as the
+      canonical seed.
+
+  HOW TO USE:
+    1. Copy this file into the new project's `docs/` folder alongside the
+       rest of the templates.
+    2. The agent prompts the user through each section in order. Defaults are
+       suggestions, not decisions — the user states their preference and the
+       agent records it in the named destination doc.
+    3. Once every section's answer has landed in HANDOFF / AGENTS / etc.,
+       delete this file from the project. Do not keep stale answers here.
+
+  WHY THIS ISN'T A TEMPLATE DEFAULT:
+    These questions encode per-project preferences (autonomy posture,
+    approval-signal literals, deploy gating thresholds, stakeholder identity,
+    sibling-repo wiring). Baking any one project's answers into the framework
+    would mis-seed the next. The discussion is the point — the *answers* are
+    project-local and live in the project's own docs.
+-->
+
+# Project Setup — First-Run Discussion Checklist
+
+Walk through this once when initializing the framework in a new repo. Each section is a question (with options and a default) plus a "Recorded in:" pointer naming the doc that owns the answer afterward. Delete this file once every answer has landed.
+
+## 1. Autonomy level
+
+What posture does the autonomous host run with on this project?
+
+- **High** — autonomous merges on `[autonomy: safe]` items, opens DRAFT PRs for `[autonomy: review]` items, blocks on `[autonomy: needs-human-collab]`. Best for solo / trusted-author projects with a strong test suite.
+- **Medium** — every merge gets a PR review, regardless of autonomy tag. Autonomous host implements but never auto-merges. Best for shared repos or anywhere a second pair of eyes is cheap insurance.
+- **Low** — human approves each step. Autonomous mode is effectively disabled; supervised sessions only. Best when the project is in early shape-finding or when the codebase changes faster than the test suite covers it.
+
+Cross-reference: see "Autonomy Markers" in `docs/AGENTS.md` for the per-task tags. The level chosen here governs the *default posture*; per-task tags still apply.
+
+**Recorded in:** `docs/AGENTS.md` "Local Overrides" (state which level applies and why).
+
+## 2. Approval signal literals
+
+Which exact phrases gate work on this project?
+
+Default: at least one funding/scope signal so material drift requires a re-pitch. Common choices:
+
+- `<PROJECT>_APPROVED` — funding/scope signal for the pitch in `docs/PROJECT_CONTEXT.md`. Gate for any work that would expand scope beyond the funded shape.
+- `RELEASE_APPROVED` — gate for cutting a public release / version bump.
+- `DEPLOY_APPROVED` — gate for promoting a build to a public-facing surface (see also: Pre-Deploy Gate in `docs/DEPLOYMENT.md`).
+- `ACTIVE_PROBE_APPROVED` — gate for security-reviewer active probing of a deployed surface (see `docs/agents/SECURITY_REVIEWER.md`).
+
+Pick literals that are unambiguous (the agent matches on exact strings). Project may add additional signals (e.g. `MIGRATION_APPROVED` for risky schema work).
+
+**Recorded in:** `docs/HANDOFF.md` "Approval Signals" section.
+
+## 3. Default model tier
+
+Which tier drives routine implementation work on this project?
+
+- **Workhorse (Sonnet 4.6 / equivalent)** — typical default for most projects. Cost-efficient over long sessions, sufficient for most feature work, refactors, and doc updates.
+- **Frontier (Opus 4.7 / equivalent)** — preferred default for ARG-style projects, security-heavy domains, novel-research builds, or anywhere Workhorse-tier slips have historically been expensive to recover from.
+
+Subagent tiers (Recon for lookup, Frontier for `planner` / `architect` / `security-reviewer` / `debugger`) follow the standard playbook regardless of host default.
+
+**Recorded in:** `docs/AGENTS.md` "Local Overrides" (only if differing from the framework default of Workhorse).
+
+## 4. Test gating
+
+Which test pass(es) gate which milestones on this project?
+
+- **Commit gate** — what must pass before each commit? (Default: unit tests + typecheck.)
+- **Merge gate** — what must pass before merging into the default branch? (Default: full test suite + lint + typecheck.)
+- **Deploy gate** — what must pass before promoting to a public surface? (Default: full test suite + smoke test against the build artifact + Pre-Deploy Gate; see §5.)
+
+Skip a tier if the project doesn't have it (e.g. single-author repos may collapse commit and merge into one).
+
+**Recorded in:** `docs/HANDOFF.md` "Project-Specific Landing Zone" or `docs/DEPLOYMENT.md` (deploy gate specifically).
+
+## 5. Deploy gating
+
+Who has deploy authority on this project, and what must hold before a deploy?
+
+- **Deploy authority** — which human(s) can authorize a public-facing deploy? Name them. The autonomous host never deploys without an explicit signal from this person.
+- **Required signals** — typically `DEPLOY_APPROVED` plus any project-specific gate (e.g. `MIGRATION_APPROVED` if the deploy includes a schema change).
+- **Security-audit recency** — default: a current `docs/SECURITY_AUDIT_<DATE>.md` must exist, **either ≤90 days old OR covering all changes since the last audit, whichever is stricter**. See `docs/DEPLOYMENT.md` "Pre-Deploy Gate" for the hard-requirement spec.
+
+**Recorded in:** `docs/DEPLOYMENT.md` (Pre-Deploy Gate is already templated; project fills in authority and signals).
+
+## 6. Content-safety rules
+
+Project-specific hard rules that the agent must never violate. Examples by domain:
+
+- ARG / fiction project: no living-person gotchas, no medical claims, no tragedy material.
+- Trivia / quiz project: real options must link to a real source; fakes must be invented; no defamatory content.
+- Compliance-bearing project: PII handling rules, HIPAA / GDPR boundaries, data-retention limits.
+- Internal tooling: secrets-in-logs prohibition, customer-data redaction rules.
+
+Default: at minimum, no secrets in commits, no PII in docs, no real user data in fixtures.
+
+**Recorded in:** `docs/agents/<ROLE>.md` "Content-Safety Rules" section per affected role, plus a one-line rule in `CLAUDE.md` "Hard Rules" if it's universally load-bearing.
+
+## 7. Stakeholder identity
+
+Who's the lead stakeholder on this project, and which entity owns revenue / contracts / legal?
+
+- **Lead stakeholder** — name (or role title) of the person who funds scope, accept-risks security findings, and signs off on `[needs-human-collab]` items.
+- **Revenue / contract entity** — the legal entity that owns commercial output. Affects copyright lines, license decisions, NOTICE wording.
+
+If the project has a `docs/agents/STAKEHOLDER.md` role file, this is where its identity lives.
+
+**Recorded in:** `docs/agents/STAKEHOLDER.md` (or equivalent role contract) and `LICENSE` / `NOTICE` copyright lines.
+
+## 8. Sibling repos
+
+Which other repos must stay in sync with this one via the cross-link invariant?
+
+List repo paths plus the kind of sync expected (palette swap, shared template promotion, doc back-link, etc.). The `cross-repo-sync` subagent uses this list when making coordinated edits.
+
+**Recorded in:** `docs/HANDOFF.md` "Related Repos" section.
+
+## 9. Mirror / backup setup
+
+Does this project fan out pushes to multiple hosts? Where do backups live?
+
+- **Multi-host fan-out** — e.g. GitHub + GitLab + a NAS bare repo, configured via `origin` pushurls. See the framework's own `REMOTES.md` for the pattern.
+- **Backup cadence** — full repo mirror frequency, snapshot location, retention.
+- **Recovery procedure** — what does "restore from backup" look like in practice? Document it before you need it.
+
+**Recorded in:** `docs/HANDOFF.md` "Remotes & Backup" section.
+
+## 10. Worktree convention
+
+How does this project organize worktrees for parallel/edit-capable subagent work?
+
+- **Default** — `.claude/worktrees/<task-name>/` adjacent to the repo, gitignored. Edit-capable subagents in autonomous runs use these so parallel work cannot conflict.
+- **Custom location** — some projects keep worktrees under `<sibling-path>/worktrees/` to avoid cluttering the main repo. State the path.
+- **No worktrees** — small / single-author / supervised-only projects may skip the worktree convention entirely. State that explicitly so the host doesn't try to use one.
+
+**Recorded in:** `docs/HANDOFF.md` "Project-Specific Landing Zone" or `docs/AGENTS.md` "Local Overrides".
+
+## 11. Permissions posture
+
+How permissive should Claude Code's auto-approval be on this project?
+
+- **Default (recommended starting point):** project-level `.claude/settings.json` is empty; the project inherits whatever the operator has at user-level (`~/.claude/settings.json`). Pick this if the operator's posture is appropriate for the project's threat model.
+- **Tighter (project overrides user):** add an `ask`/`deny` block at project scope to force prompts on commands the user-level config would auto-approve. Use this when a project handles secrets, regulated data, or shared CI.
+- **Looser:** generally not recommended — projects shouldn't expand trust beyond user defaults. If absolutely necessary, document why in `docs/DECISIONS.md`.
+
+The `templates/.claude/settings.json` template ships with the empty default plus an opt-in permissive preset under `_alternatives` for reference. Do NOT paste the preset blindly.
+
+**Recorded in:** `docs/AGENTS.md` Local Overrides section.
+
+---
+
+Once every section above has a recorded answer, **delete `docs/SETUP.md` from this project**. The framework's `templates/SETUP.md` stays in place as the seed for the next project.

package/templates/SPEC.md

@@ -0,0 +1,105 @@
+# Functional Spec: <product name>
+
+<!--
+  Stage A output of the Spec & Design phase (see SPEC_WORKFLOW.md).
+  ENTIRELY PLAIN ENGLISH. No tech choices, no stack, no libraries — those
+  belong in BUILD_PLAN.md (Stage B). A non-engineer must be able to read
+  this and recognize their product.
+
+  Every requirement is tagged [AUTO] (a machine can check it) or [HUMAN]
+  (needs human judgment). Every requirement is testable — if you can't say
+  how it would be verified, rewrite it or tag it [HUMAN].
+
+  This file is LOCKED by the verbatim token SPEC_APPROVED. Stage B does not
+  begin until it lands.
+-->
+
+**Status:** Draft — awaiting `SPEC_APPROVED`
+**Interaction tier:** Thorough  <!-- Express | Guided | Thorough | Exhaustive — set at first prompt -->
+**Last updated:** <YYYY-MM-DD>
+
+## Goal
+
+<One or two sentences. What "done" looks like for this product, in plain English.>
+
+## Context / Inputs
+
+<What already exists, what's provided, the relevant constraints. For a funded
+pitch, link it: `docs/pitches/<status>/<PRODUCT>.md`.>
+
+## Screens / Pages
+
+<One subsection per screen. A reader should be able to picture the product
+from this section alone.>
+
+### <Screen name>
+
+- **Purpose:** <what this screen is for, who reaches it and how>
+- **Controls:** <every button / input / menu / tool on it, and what each one does>
+- **States:** <empty / loading / error / populated / max — what the user sees in each>
+
+## Requirements
+
+<!--
+  Numbered. Each tagged [AUTO] or [HUMAN]. Each phrased as an observable,
+  checkable condition: "<thing> MUST <condition>".
+-->
+
+- **R1** `[AUTO]` <thing> MUST <observable, checkable condition>.
+- **R2** `[AUTO]` <thing> MUST <observable, checkable condition>.
+- **R3** `[HUMAN]` <thing that needs judgment, e.g. "the onboarding copy reads warmly">.
+
+## User Flows
+
+<The paths through the product. For each: the steps, the state transitions,
+and what success looks like at the end.>
+
+1. **<Flow name>:** <step → step → step → success condition>
+
+## Boundaries & Edge Cases
+
+<Explicit behavior at the limits and on bad input — this is where most spec
+failures hide.>
+
+- **Empty / zero / none:** <behavior>
+- **Maximum / overflow:** <behavior>
+- **Malformed / invalid input:** <behavior>
+- **Conflict resolution:** <when requirement X and Y disagree, X wins because …>
+
+## Out of Scope
+
+<What this deliberately does NOT do. The highest-leverage section — it is what
+stops scope creep at build time. Be specific; "for now" items go here too.>
+
+- <explicitly excluded capability>
+
+## Assumptions
+
+<Everything the spec takes for granted. An executor resolves unstated
+assumptions in the most generic direction — so state them and have the human
+confirm or correct each one.>
+
+- <assumption the human should confirm>
+
+## Acceptance Tests
+
+<For each [AUTO] requirement, the concrete check that proves it. These become
+the verifier suite generated in Stage B. Reference the requirement number.>
+
+- **R1** → <the check: unit test / schema validation / round-trip / headless smoke / shell check that passes iff R1 holds>
+- **R2** → <the check>
+
+## Human Checklist
+
+<For each [HUMAN] requirement, the specific thing the reviewer confirms after
+the build. This plus anything the runner flags is the entire post-build review
+surface.>
+
+- [ ] **R3** — <the specific thing to confirm>
+
+## Open Questions
+
+<Anything the red-team pass surfaced that needs a human decision before
+SPEC_APPROVED. Resolve these; do not paper over them with a default.>
+
+- <open question awaiting a human call>