discipline-md 0.1.0

package/templates/DEPLOYMENT.md

@@ -0,0 +1,342 @@
+# Deployment
+
+Update this document when hosting, environment variables, secrets, deployment commands, CI/CD, launch checklist, or production operations change.
+
+## Pre-Deploy Gate (Hard Requirement)
+
+This gate **fails closed**: no phase that ships code to a public surface may proceed unless the gate passes. "Public surface" means anything reachable by users outside the dev team — production URL, staged URL with real users, public CDN-fronted artifact, public API endpoint.
+
+**Gate condition:** a current `docs/SECURITY_AUDIT_<YYYY-MM-DD>.md` exists, **EITHER** (a) ≤90 days old, **OR** (b) covering all changes since the last audit, **whichever is stricter**. Stricter = whichever produces the more recent required-audit cutoff for this deploy.
+
+**If the gate fails:**
+
+- Invoke the `security-reviewer` subagent (see `templates/agents/SECURITY_REVIEWER.md`).
+- Do not proceed to any phase that ships code to a public surface until the audit lands.
+- The audit becomes the new `docs/SECURITY_AUDIT_<YYYY-MM-DD>.md` of record.
+
+**Reviewer accept-risk:** only the stakeholder named in `docs/agents/STAKEHOLDER.md` (or the equivalent role contract for this project) can accept-risk a finding to unblock the gate. The acceptance is recorded in the audit's "Accept-Risk Candidates" section with explicit rationale (severity, blast radius, reason for accepting, expiry / re-evaluation date). The host does NOT have authority to accept-risk.
+
+**This gate also applies to:**
+
+- Schema migrations on production data — even if the migration is shipped via a separate tool from the standard deploy flow.
+- Secrets rotation that touches the deploy pipeline (rotating the deploy provider's API key, rotating the production database credential, etc.).
+- Any change to the auth surface — auth provider swap, session-handling change, token issuance/verification change — even if those don't ship via the standard deploy phases.
+
+In other words: anywhere a change crosses the trust boundary between dev and production, the gate applies.
+
+## Phased Rollout
+
+Non-trivial deployments rarely happen in one shot — they unfold across phases that gate each other (DNS before TLS, schema before service, secrets before first traffic). Capture that explicitly so the operator can resume at any green-light state and know exactly what's been verified and what hasn't.
+
+### Dependency graph
+
+A short ASCII or bulleted graph showing which phases block which. Each arrow is a hard gate: the next phase cannot start until the previous one's exit criteria are green. Parallel phases are allowed when they share no inputs.
+
+```
+Phase A (source on <git-host>) ──► Phase B (<frontend-host> project)
+                                            │
+                                            ▼
+                                   Phase C (<backend-or-worker>)
+                                            │
+                                            ▼
+                  Phase D (wire frontend ↔ backend env vars) ──► Phase E (custom domain + TLS)
+                                            │                              │
+                                            ▼                              ▼
+                                   Phase F (<email-routing>)      Phase G (analytics, parallel to F)
+                                            │
+                                            ▼
+                                   Phase H (<feature-flag-flip>)
+                                            │
+                                            ▼
+                                   Phase I (<asset-or-OG-pass>)
+                                            │
+                                            ▼
+                                   Phase J (<optional-extension>)
+```
+
+Even a tiny graph like `Phase A → Phase B → Phase C, Phase D (parallel to B)` is enough to seed the pattern. Replace with the real shape of this project's deploy.
+
+### Phase outline
+
+For each phase: a 1-line goal, the steps, **exit criteria** (testable conditions that must hold before the next phase begins), and a **rollback path** (what reverting this phase looks like, or a callout that it's not safely reversible).
+
+#### Phase A — <source-on-git-host> (~5 min)
+
+Goal: get the canonical source on the git host that the deploy provider authorizes.
+
+Exit criteria:
+- [ ] Repo created at `<git-host>/<org>/<repo>`.
+- [ ] `main` branch pushed; remote tracking confirmed (`git remote -v`).
+- [ ] `<deploy-provider>` can read the repo (test via OAuth flow or `gh repo view`).
+
+Rollback: trivial — delete or unlink the remote. No production impact yet.
+
+#### Phase B — <frontend-host> first deploy (~10 min)
+
+> **Pre-Deploy Gate must pass before this phase** — see "Pre-Deploy Gate (Hard Requirement)" above. This is the first phase that puts code on a public-reachable URL.
+
+Goal: build artifact lands at the provider's default URL (`<project>.<provider>.app`) with no env vars wired.
+
+Exit criteria:
+- [ ] First build succeeds in the provider dashboard.
+- [ ] Default URL serves the app; degraded features (those needing env vars) gracefully no-op.
+- [ ] Build command and output directory captured in the dashboard config.
+
+Rollback: delete the project, or roll back to "no deployments" state. Reversible.
+
+#### Phase C — <backend-or-worker> deploy (~15 min)
+
+> **Pre-Deploy Gate must pass before this phase** — see "Pre-Deploy Gate (Hard Requirement)" above. Backend ships code to a public-reachable URL.
+
+Goal: backend service is live and reachable; smoke-test endpoint returns expected shape.
+
+Exit criteria:
+- [ ] Service deployed (`<provider> deploy` or equivalent prints a live URL).
+- [ ] Health-check endpoint returns 200 with expected JSON.
+- [ ] Persistent stores (KV / DB / cache) bound to the service.
+
+Rollback: redeploy from the previous git commit (`<provider> rollback` or checkout-and-redeploy). Reversible.
+
+#### Phase D — wire frontend ↔ backend (~5 min)
+
+Goal: frontend env vars point at the backend URL from Phase C; rebuild bakes them in.
+
+Exit criteria:
+- [ ] `<FRONTEND_API_URL>` set in frontend host's production env.
+- [ ] Triggered rebuild has the new env baked in.
+- [ ] End-to-end smoke flow (load → action → write → read) works in production.
+
+Rollback: clear the env var and redeploy — frontend reverts to "degraded but functional" state from Phase B. Reversible.
+
+#### Phase E — custom domain + TLS (~10 min)
+
+Goal: `<custom-domain>` resolves to the frontend with a valid certificate.
+
+Exit criteria:
+- [ ] Apex (`<custom-domain>`) and `www.<custom-domain>` both routed.
+- [ ] SSL/TLS certificate active (provider dashboard shows green).
+- [ ] Curl from external network confirms 200 + valid cert.
+- [ ] Backend CORS allowlist tightened to the new origin and redeployed.
+
+Rollback: **partially reversible.** Removing the custom domain in the dashboard reverts traffic to the default URL within minutes. **DNS nameserver changes (if any) are not instantly reversible** — TTL-bounded propagation, up to 48h. Document the previous nameservers before changing them.
+
+#### Phase F — <email-routing> (~5 min, parallel to G)
+
+Goal: `<address>@<custom-domain>` routes to operator inbox.
+
+Exit criteria:
+- [ ] Routing rule created.
+- [ ] Destination address verified (verification link clicked).
+- [ ] Test email round-trips end-to-end.
+
+Rollback: disable the routing rule. Reversible.
+
+#### Phase G — analytics (~3 min, parallel to F)
+
+Goal: traffic visibility from minute one of public launch.
+
+Exit criteria:
+- [ ] Snippet or first-party endpoint live.
+- [ ] First test pageview shows in the analytics dashboard.
+
+Rollback: remove the snippet, redeploy. Reversible.
+
+#### Phase H — <feature-flag-flip> (when ready)
+
+Goal: turn on a gated feature (donation link, premium tier, beta surface) once its operational prerequisites land.
+
+Exit criteria:
+- [ ] Prerequisites listed under this phase are all green (e.g. payment account exists, legal copy reviewed).
+- [ ] Feature env var set in production scope.
+- [ ] Feature renders in production smoke test.
+
+Rollback: clear the env var and redeploy. Reversible.
+
+#### Phase I — <asset-or-OG-pass> (queued)
+
+Goal: production polish — share images, favicons, manifest, accessibility metadata.
+
+Exit criteria:
+- [ ] Asset(s) committed at `<asset-paths>`.
+- [ ] Meta tags present in `<entry-html>`.
+- [ ] Validated via `<og-checker>` or similar.
+
+Rollback: revert the commit. Reversible.
+
+#### Phase J — <optional-extension> (deferred)
+
+Goal: a follow-on capability funded as a later shape (account sync, additional platform target, paid tier wiring). Has its own internal sub-phases.
+
+Exit criteria:
+- [ ] Sub-phase J.1 … J.N each green (define inline).
+- [ ] End-to-end smoke for the new capability passes.
+
+Rollback: feature is gated behind env vars / secrets — clearing them disables the capability without code rollback. Reversible by config; data written during the phase persists unless explicitly cleaned up.
+
+### Rollback summary
+
+| Phase | Reversible? | Notes |
+|---|---|---|
+| A | Yes | Remove remote / delete repo. |
+| B | Yes | Delete project / promote previous deploy. |
+| C | Yes | Redeploy previous git commit. |
+| D | Yes | Clear env var, redeploy. |
+| E | **Partial** | Domain unlink is fast; nameserver changes are TTL-bounded (up to 48h). |
+| F | Yes | Disable routing rule. |
+| G | Yes | Remove snippet, redeploy. |
+| H | Yes | Clear feature env var, redeploy. |
+| I | Yes | Revert asset commit. |
+| J | Config-reversible | Clearing secrets disables capability; persisted data may need explicit cleanup. |
+
+Call out any phase that performs an **irreversible** action (e.g. destructive schema migration, billing-account creation, third-party data deletion) directly in that phase's rollback line.
+
+## Stack
+
+| Layer | Service | Cost / Tier | Notes |
+|---|---|---|---|
+| Frontend | (e.g. GitHub Pages, Vercel, Netlify) | | |
+| Backend | (e.g. Railway, Fly.io, self-hosted) | | |
+| Database | (e.g. Supabase, RDS, SQLite file) | | |
+| Email / notifications | (e.g. Resend, Postmark) | | |
+| Storage / CDN | | | |
+| Other services | | | |
+
+For non-cloud deployments (CLI tool, Docker artifact, distributed binary), repurpose the table to capture distribution channel, build target, and signing/release service.
+
+## Environment Variables
+
+### Public config (safe to commit, e.g. `.env.example`)
+
+```text
+VARIABLE_NAME=description
+```
+
+### Secrets (server-only, NEVER committed)
+
+```text
+SECRET_NAME=how to generate it
+```
+
+Note: secrets must come from a secrets manager (Railway / Vercel / Fly env, Doppler, 1Password, etc.) — never checked into the repo and never logged. Add a `.env.example` with placeholder values; gitignore the real `.env`.
+
+## Local Setup
+
+```bash
+# install
+# copy .env.example -> .env, fill in values
+# run dev server
+# run tests
+```
+
+## Production Setup
+
+Numbered steps to bring the project up from scratch. Group by tier where applicable (database → backend → frontend → email → automation):
+
+1. Step one.
+2. Step two.
+3. Step three.
+
+## Data / Seed Setup
+
+For the one-time bootstrap distinct from code deploy: schema migrations, seed data, asset uploads, code/voucher imports, etc.
+
+1. Step.
+2. Step.
+
+Skip if the project has no persistent state to seed.
+
+## Custom Domain / Distribution (optional)
+
+For web apps: DNS configuration, certificate setup, custom domain mapping.
+For CLI tools / libraries: package registry publishing (npm, PyPI, crates.io), binary distribution, signing.
+For Docker: image registry, tag conventions.
+
+Skip if the project ships only at a default URL or has no distribution channel.
+
+## CI/CD
+
+- **Trigger:** when does CI run (push to main, PR, tag, manual)?
+- **Required checks:** what must pass before merge / deploy?
+- **Deploy target:** what gets deployed where on success?
+- **Secrets source:** where does CI get production secrets from?
+- **Rollback hook:** how to abort a bad deploy mid-flight if possible.
+
+## Launch Checklist
+
+Group by category so nothing slips. Tick everything before declaring launch.
+
+### Infrastructure
+- [ ] Hosting provider provisioned.
+- [ ] DNS / custom domain pointed.
+- [ ] HTTPS / TLS verified.
+- [ ] Monitoring / logging hooked up.
+
+### Code
+- [ ] Production env vars set.
+- [ ] Tests pass on the deploy branch.
+- [ ] Build artifact verified (no debug flags, no test data).
+
+### Data
+- [ ] Schema migrations applied.
+- [ ] Seed data imported.
+- [ ] Backups configured.
+
+### Verification
+- [ ] Smoke test core user flows.
+- [ ] Health-check / version endpoint responding.
+- [ ] Rollback plan documented (see below).
+
+## Post-Deploy Verification
+
+After every deploy (initial or subsequent):
+
+- Hit the health-check / version endpoint.
+- Smoke test the critical user flow.
+- Check logs for unexpected errors in the first 5 minutes.
+- Confirm no regression in monitoring metrics.
+
+## Day-2 Operations / Updating
+
+For routine updates after launch (distinct from initial deploy):
+
+1. Step (e.g. push to main → CI deploys → verify).
+2. Step.
+
+Schema changes, secret rotation, and dependency updates each get their own short procedure — link or fold them in here.
+
+## Rollback
+
+Three rollback surfaces, each with their own procedure:
+
+- **Code rollback:** how to revert to the previous deploy (Git tag, hosting provider's previous deployment, container image swap).
+- **Schema / data rollback:** how to revert a migration or restore a backup. Note schema changes that are NOT safely reversible.
+- **Configuration / secrets rollback:** how to revert env-var or feature-flag changes.
+
+## Cost & Scaling (optional)
+
+For deployments where cost-per-tier matters or scaling thresholds will eventually trigger:
+
+- Current tier cost / monthly burn.
+- Free-tier or starter-tier limits (request count, storage, bandwidth).
+- Triggers that would warrant an upgrade.
+- Largest cost levers if costs spike.
+
+Skip if the project is self-hosted on owned hardware, runs at fixed cost, or is too small to care.
+
+### Cost summary
+
+One row per phase that incurs cost, with the provider, tier, and monthly cost at MVP scale. Use placeholders until real numbers are known.
+
+| Phase | Provider | Tier | Monthly cost |
+|---|---|---|---|
+| B — <frontend-host> | `<provider>` | `<free / hobby / pro>` | `$<n>` |
+| C — <backend-or-worker> | `<provider>` | `<free / hobby / pro>` | `$<n>` |
+| C — datastore (KV / DB) | `<provider>` | `<tier>` | `$<n>` |
+| E — domain registration | `<registrar>` | n/a | `$<n>/yr` (~`$<n>/mo`) |
+| F — <email-routing> | `<provider>` | `<tier>` | `$<n>` |
+| G — analytics | `<provider>` | `<tier>` | `$<n>` |
+| H — <feature-flag-flip> | `<provider>` | `<tier>` | `$<n>` |
+| J — <optional-extension> | `<provider>` | `<tier>` | `$<n>` |
+| **Total at MVP scale** | | | **`$<n>/mo`** |
+
+Note any line item that's `$0` only while under a free-tier ceiling, with the trigger that would push it to paid (e.g. *"$0/mo while under 100k requests/day; $5/mo if exceeded"*).

package/templates/HANDOFF.md

@@ -0,0 +1,289 @@
+# Handoff
+
+Use this as the first-read handoff document for AI coding agents and future developers. Keep it updated whenever workflow, documentation structure, or project conventions change.
+
+## Project-Specific Landing Zone
+
+*(Add sections relevant to this project here, near the top, so first-read agents see them. The framework template intentionally leaves this empty — it is for project-shaped content that does not generalize. Common uses:*
+
+- *Sibling repos / subproducts list and integration paths.*
+- *Recently landed work worth flagging for context.*
+- *Operator credentials, demo accounts, sandbox URLs.*
+- *Cross-repo registration checklists when adding a new sibling.*
+- *Project-specific hazards or "read this before changing X" warnings.*
+
+*Delete this header and replace with project-specific sections, or delete the whole zone if the project doesn't need it.)*
+
+## Related Repos
+
+If this project has sibling repos (subproducts, shared-tooling repos, paired build/runtime repos), list them here so first-read agents can navigate the constellation:
+
+- **`<sibling-repo>`** (`<absolute_path_to_sibling>`) — one-line purpose; how this repo depends on or is depended on by it; integration path if any (e.g. `/tools/<slug>/`).
+- **`<another-sibling>`** (`<absolute_path_to_sibling>`) — …
+
+**Cross-link invariant (cleanup-gate item):** When this section is updated — sibling added, removed, renamed, relocated, or its dependency direction shifted — sync the matching "Related Repos" section in each sibling's `HANDOFF.md` so the reference graph stays consistent. A missing back-link means the next agent reading the sibling will not know this repo exists. Treat the sync as part of the same task, not as follow-up work.
+
+For projects with a clear hub repo (one repo holds the canonical subproduct list), siblings may link back to the hub instead of duplicating the full list — but the back-link itself must exist.
+
+## Remotes & Backup
+
+If this project mirrors to multiple hosts (canonical forge + redundant forge + private/LAN backup), document the fan-out here so push discipline and recovery procedures stay first-read.
+
+| Remote | URL | Role |
+|---|---|---|
+| `<canonical>` | `<git@host:org/repo.git>` | Canonical hosting; PRs, CI, issues |
+| `<redundant>` | `<git@other-host:org/repo.git>` | Redundant hosting |
+| `<backup>` | `<ssh://user@host/~/repo.git>` | Private LAN / NAS backup |
+
+The recommended pattern is a single `origin` configured with **multiple `pushurl` entries** so a single `git push` fans out to every destination. `git pull` / `git fetch` reads from one canonical URL. Keep the named remotes (`<canonical>`, `<redundant>`, `<backup>`) defined separately so you can target one specifically when needed.
+
+Example fan-out config (in `.git/config`):
+
+```ini
+[remote "origin"]
+    url = <git@canonical-host:org/repo.git>
+    pushurl = <git@canonical-host:org/repo.git>
+    pushurl = <git@redundant-host:org/repo.git>
+    pushurl = <ssh://user@backup-host/~/repo.git>
+    fetch = +refs/heads/*:refs/remotes/origin/*
+```
+
+If the project keeps host-specific notes (key rotation cadence, gitleaks hook, push-protection setting, fan-out verification), put them in a project-local `REMOTES.md` and link from here. See the framework-level [`REMOTES.md`](../REMOTES.md) for the canonical pattern this section is derived from.
+
+### When to push
+
+The fan-out is only a backup strategy for work that has been pushed.
+
+- **After every commit on a meaningful checkpoint.** Pushing is cheap; redundancy is the point.
+- **Before stepping away from the machine** for any non-trivial period.
+- **Before history-rewriting or destructive operations** (rebase, force-push, branch delete) — push first so the unmodified state survives on at least one remote.
+- **End of session, no exceptions.**
+
+Not pushing leaves work on a single machine. The point of multiple remotes is recovery from any single point of failure.
+
+### Recovery procedure
+
+If the canonical host is unavailable or a working copy is lost:
+
+1. Identify the most-recently-pushed remote — typically `<canonical>`, but fall back to `<redundant>` or `<backup>` if needed.
+2. Clone from that remote: `git clone <url> <workspace_path>/<repo>`.
+3. Re-establish the fan-out: re-add the missing `pushurl` entries (see example above) or run the project's mirror-setup script if one exists (e.g. `<workspace_path>/setup-mirrors.ps1`).
+4. Verify with `git remote -v` (expect one `fetch` URL and N `push` URLs on `origin`) and a `git push origin --dry-run`.
+
+### Approval Signals & Drift Rules
+
+Some projects gate material work behind explicit human approval signals carried in conversation transcripts. The convention:
+
+- **Approval-signal literal.** A short SCREAMING_SNAKE_CASE token the lead stakeholder writes verbatim to authorize a phase of work. Common shapes: `FUNDING_APPROVED` (the funded scope is locked in), `SCOPE_APPROVED` (a specific feature set is approved for this milestone), `DEPLOY_APPROVED` (production deploy is authorized for this release). Pick names that reflect the actual gate.
+- **Drift-and-re-pitch rule.** When implementation diverges materially from the approved scope — target audience, value proposition, stack choice, burn envelope, or any other axis the original approval was conditioned on — pause and re-pitch in `docs/OPEN_DECISIONS.md` before continuing. Material drift requires a fresh approval signal; trivial additions inside the funded envelope do not.
+- **Where the actual signals live.** This file states the convention; the project-specific signal list, drift triggers, and authority boundary live in the role contract under `docs/agents/<ROLE>.md` (e.g. `docs/agents/FOUNDER.md` for projects with a funder/scope-guardian role). Cross-reference both directions so the contract and the convention stay in sync.
+
+Approval-signal matching rule: a signal matches when the token appears verbatim, compared case-insensitively, ignoring surrounding whitespace and punctuation ("FUNDING_APPROVED." and "funding_approved" both match). Nothing else matches — paraphrases, enthusiasm, or "sounds good, approved" do not open the gate. If the user appears to be approving but the token is absent, ask for the exact token; never infer it.
+
+If the project does not use a stakeholder-approval gate, delete this subsection.
+
+## IMPORTANT: Documentation Is Part of the Work
+
+Keeping docs current is not optional. Every session that changes code must leave the docs accurate. Stale docs are worse than no docs because they actively mislead future agents.
+
+Documentation is a completion gate, not a cleanup task. Before any final response or commit, audit documentation impact and either update the relevant docs or explicitly state why no docs were needed.
+
+Do not mark work complete if the relevant docs have not been updated. Specifically:
+
+- Update root `README.md` when the repository entrypoint, top-level purpose, or first-read directions change.
+- Update `docs/TODO.md` as work progresses and before ending a session.
+- Update `docs/CHANGELOG.md` before committing meaningful work.
+- Update `docs/ARCHITECTURE.md` when file layout, runtime flow, or frontend/backend structure changes.
+- Update `docs/DATA_MODEL.md` when persistence, schema, auth, or rewards change.
+- Update `docs/API_REFERENCE.md` when endpoints, request shapes, or auth behavior change.
+- Update `docs/ASSETS.md` when media assets are added, renamed, or referenced by code.
+- Update `docs/DEPLOYMENT.md` when env vars, hosting, email setup, or the launch checklist changes.
+- Update `docs/PROJECT_CONTEXT.md` when product direction, design language, or domain context changes.
+- Update `docs/DECISIONS.md` when a durable technical or product decision is made.
+- Update `docs/OPEN_DECISIONS.md` when a paired session surfaces a blocking decision that needs user input before work can continue. Remove entries once the answer has folded into `docs/DECISIONS.md` or the matching `docs/TODO.md` entry.
+- Update `docs/AGENTS.md` when the host model, subagent roles, autonomy tags, or human-collab gate change.
+- Update this file when any documentation responsibility changes.
+
+Required end-of-task documentation audit (mandatory cleanup gate):
+
+- Run or inspect `git diff -- docs` before calling the task complete.
+- If code changed and no docs changed, verify that the change is truly internal-only and say so explicitly.
+- For renames, endpoint changes, asset path changes, or product wording changes, search docs for stale old names/paths before finishing.
+- **Delete completed entries from `docs/TODO.md`** once they are captured in `docs/CHANGELOG.md`. TODO is a queue, not a log; do not leave `[x] DONE` entries.
+- **Mark completed `docs/ROADMAP.md` items with ✅** or move them under a `## Completed` section.
+- **Reflect on the playbook**: if this session revealed a real workflow-impact change to AGENTS / HANDOFF / TODO conventions, add a proposal to `docs/PLAYBOOK_FEEDBACK.md`. Do not edit workflow docs directly without user review. Workflow-impact discipline is mandatory — see `docs/AGENTS.md` Playbook Improvement Loop section for the rule and what NOT to propose.
+- Final responses should include a concise docs status, e.g. `Docs updated: docs/API_REFERENCE.md, docs/ASSETS.md` or `Docs unchanged: no behavior/API/file/path changes`.
+
+## Start Here
+
+1. Read `docs/README.md` for setup commands and folder structure.
+2. Read `docs/TODO.md` for current context and active tasks.
+3. Read `docs/AGENTS.md` for the AI agent playbook (host model, subagent roles, autonomy tags).
+4. Read `docs/AUTONOMOUS_QUEUE.md` if running unsupervised — it lists pre-approved tasks.
+5. Read `docs/CHANGELOG.md` for recent completed changes.
+6. Read area-specific cold-path docs before editing related systems.
+
+*Projects may reorder the first 2–3 entries when a different doc carries more upfront context (e.g. lead with `PROJECT_CONTEXT.md` for a project where domain understanding gates everything else). Keep the agent-playbook entry in the top half regardless.*
+
+## Documentation Index
+
+- `docs/README.md`: Quick overview and setup. (Hot path)
+- Root `README.md`: Concise repository entrypoint. Keep it stable and point to `docs/` for full context.
+- `docs/TODO.md`: Short-term active work and test checklist. (Hot path)
+- `docs/AGENTS.md`: AI agent playbook — host model, named subagent roles, autonomy tags, human-collab gate, playbook improvement loop.
+- `docs/AUTONOMOUS_QUEUE.md`: Priority-ordered list of pre-approved tasks for unsupervised AI runs. Optional — only present if the project has enabled autonomous workflows.
+- `docs/PLAYBOOK_FEEDBACK.md`: Staging file for proposed improvements to the workflow docs. Inbox between "agent noticed something" and "canonical doc gets edited" — see `docs/AGENTS.md` for the lifecycle.
+- `docs/IMPROVEMENT_LOOP.md`: (Cold path) The object-level recursive improvement loop (discover → execute → verify → evaluate → integrate → repeat). Optional — only present if the project runs an autonomous improvement loop. Pairs with VERIFICATION_GATE.
+- `docs/VERIFICATION_GATE.md`: (Cold path) The machine-checkable ground-truth signal every loop iteration must pass (compile/test/repro). Optional — required by IMPROVEMENT_LOOP.
+- `docs/PROJECT_CONTEXT.md`: Product and domain context.
+- `docs/ARCHITECTURE.md`: Codebase and runtime architecture.
+- `docs/DATA_MODEL.md`: Persistence and schemas.
+- `docs/ASSETS.md`: Media asset paths and preparation notes.
+- `docs/API_REFERENCE.md`: Endpoints and integrations.
+- `docs/DEPLOYMENT.md`: Production setup and operations.
+- `docs/CHANGELOG.md`: Completed notable changes.
+- `docs/ROADMAP.md`: Long-term plans, milestones, and deferred ideas.
+- `docs/DECISIONS.md`: Durable decision records.
+- `docs/OPEN_DECISIONS.md`: Staging file for design/product decisions that block active work and need user input. Inbox between "decision arose in a session" and "decision recorded in `docs/DECISIONS.md` or folded into a `docs/TODO.md` entry." Optional — only present if the project hits blocking design questions worth tracking. When this file holds only the heading, the project is unblocked.
+- `docs/CREDITS.md`: Third-party libraries, vendored code, assets, fonts, attributions.
+- `LICENSE` (repo root): Project license. Default scaffold is All Rights Reserved.
+- `NOTICE` (repo root): Third-party attribution summary; required by Apache-2.0, optional otherwise.
+- `REMOTES.md` (repo root): Multi-host mirror config, push discipline, recovery procedure, and any project-local backup-hygiene checklist. (Cold path) Optional — only present if the project mirrors to more than one remote.
+
+*Projects may add domain-specific cold-path docs (e.g. `PUZZLE_DESIGN.md`, `HARDWARE_SPECS.md`, `COMPLIANCE.md`, `BACKEND_GUIDE.md`) — index them above with a one-line description. Keep this list in sync with the actual files in `docs/`.*
+
+**Avoid duplicate update-rule lists.** This file already has an "IMPORTANT: Documentation Is Part of the Work" list above. Do not also create a separate "Update Rules" section restating the same bullets — the two will drift. If projects need a quick-reference list, link back to the IMPORTANT section.
+
+## Persistence Rules
+
+If the project has persistent state, document the per-environment rules here so first-read agents internalize them before editing data flows. Skip this section for stateless projects.
+
+- Where production state lives:
+- Where local-dev state lives / how to reset:
+- What must NEVER be exposed to clients (secrets, hashes, tokens, internal IDs):
+- What must NEVER be committed to the repo (real secrets, live state files, large binaries):
+
+## Current Local Dev
+
+How to bring the project up locally for the first time. Generic stub:
+
+- Start command (full paths if a particular shell can't find them):
+- Local URL / port:
+- Seeded credentials, demo account, sandbox token (if any):
+- How to reset local state (delete which file, drop which database):
+
+Skip this section for projects with no local-dev mode.
+
+## Project Workflow
+
+### Branching
+
+- Start every new feature, bugfix, or working session on a fresh branch from the main branch unless explicitly directed otherwise.
+- Use short descriptive branch names (e.g. `feature/<topic>`, `fix/<topic>`, `docs/<topic>`).
+- Before starting unrelated work, merge or resolve the previous feature branch back into the main branch.
+- If there are uncommitted changes on the main branch when starting new work, commit them, branch them, or ask the user how to proceed.
+- **One PR = one feature = one branch off latest main.** When a PR merges, or work pivots to a meaningfully different feature, start a fresh branch off the *updated* main: `git fetch && git checkout -b <new-branch> <remote>/<main-branch>`. Never push follow-on commits to a merged or stale branch — those commits become orphans that never reach main. If you've already committed onto a stale branch, cherry-pick onto a fresh branch and open a new PR; do not try to salvage the stale one.
+
+### Cross-repo git invocations
+
+Use `git -C "<absolute path>" <command>` instead of `cd "<path>" && git <command>` when operating on a sibling repo. See `docs/AGENTS.md#shell-and-git-invocation` — `cd && git` triggers a per-call permission prompt, `git -C` does not.
+
+### What stays uncommitted
+
+- Real secrets, `.env` files, signing keys.
+- Local-dev state files (e.g. JSON-backed dev databases).
+- Build outputs and caches not meant to be vendored.
+- `package-lock.json` — this project uses pnpm; lockfile is `pnpm-lock.yaml`.
+
+### Pre-commit checks
+
+```bash
+# syntax / type check
+# unit tests
+# linter (if applicable)
+```
+
+### Commit style
+
+State the project's commit-message convention here (Conventional Commits, prefix-tag, free-form, etc.).
+
+### Test commands
+
+```bash
+# unit tests
+```
+
+### Build commands
+
+```bash
+# pnpm install  # first run
+# build
+```
+
+### Deployment commands
+
+See `docs/DEPLOYMENT.md` for the full procedure. Day-to-day shortcuts:
+
+```bash
+# deploy
+```
+
+## AI Agent Playbook
+
+The full host-model policy, escalation rules, named subagent roles (with input/output contracts and per-role model tiers), autonomy tag scheme, and human-collaboration gate live in `docs/AGENTS.md`. Read that file before spawning subagents or picking up tagged work.
+
+Quick rules that must hold regardless of project specifics:
+
+- The host reconciles all subagent output; subagents do not own commits, merges, or doc-completion-gate sign-off.
+- Tasks tagged `[autonomy: needs-human-collab]` must NOT start without explicit user approval.
+- Spawn edit-capable subagents in worktrees during autonomous runs so parallel work cannot conflict.
+
+## Safety Rules
+
+- Do not commit secrets.
+- Do not overwrite user work.
+- Do not expose private data in logs or frontend responses.
+- Confirm destructive operations with the user.
+- **Package manager: pnpm.** Run `pnpm install` / `pnpm add` — never `npm install`. Never commit `package-lock.json` (the lockfile is `pnpm-lock.yaml`). The repo `.npmrc` sets `ignore-scripts=true`; pass `--ignore-scripts=false` only when a legitimate postinstall is required.
+
+## Testing Expectations
+
+- Every project should have unit tests.
+- Run unit tests before committing meaningful code changes.
+- Add or update tests when behavior changes.
+- Prefer testing pure helpers for important logic instead of relying only on manual smoke tests.
+
+## Completion Gate
+
+A code task is not complete until all applicable docs are audited and updated. Use this mapping as the default trigger list:
+
+- API route, auth, request, or response change -> `docs/API_REFERENCE.md`.
+- Schema, persistence, state, entitlement, or data ownership change -> `docs/DATA_MODEL.md`.
+- Runtime flow, folder structure, frontend/backend structure, or deployment topology change -> `docs/ARCHITECTURE.md` and usually `docs/README.md`.
+- Repository entrypoint, top-level purpose, or first-read directions change -> root `README.md`.
+- Asset/media addition, rename, optimization, or referenced path change -> `docs/ASSETS.md`.
+- Launch requirement, environment variable, hosting, storage, or deployment checklist change -> `docs/DEPLOYMENT.md`.
+- Product behavior, user flow, domain context, or design direction change -> `docs/PROJECT_CONTEXT.md`.
+- Durable technical/product decision -> `docs/DECISIONS.md`.
+- Blocking design/product decision surfaced (paired session, autonomous-run fork) -> `docs/OPEN_DECISIONS.md`.
+- New dependency, vendored snippet, licensed asset, or font added/removed -> `docs/CREDITS.md`.
+- License chosen / changed, copyright holder updated -> `LICENSE` (repo root).
+- Notice-level dependency added/removed, Apache-2.0 component bundled -> `NOTICE` (repo root).
+- AI host model, escalation rules, subagent roles, or autonomy tag scheme change -> `docs/AGENTS.md`.
+- Any meaningful completed work -> `docs/CHANGELOG.md`.
+- Any active/follow-up work or smoke-test need -> `docs/TODO.md`.
+- Any completed TODO entry -> deleted from `docs/TODO.md` once captured in `docs/CHANGELOG.md`.
+- Any completed roadmap item -> ✅ in `docs/ROADMAP.md` or moved under a `## Completed` section.
+
+## End-of-Session Housekeeping
+
+Before declaring a session complete, run through this short list:
+
+1. **Delete shipped entries from `docs/TODO.md`** once captured in `docs/CHANGELOG.md`. No `[x] DONE` carryover.
+2. **Mark completed `docs/ROADMAP.md` items with ✅** or move under `## Completed`.
+3. **Update `docs/CHANGELOG.md`** with a dated one-line entry per meaningful change.
+4. **Trim `docs/AUTONOMOUS_QUEUE.md`** if a queued item shipped (delete from queue; out-of-queue holdouts stay until reviewed).
+5. **Trim `docs/OPEN_DECISIONS.md`** if any entries were answered this session and the answers have been folded into `docs/DECISIONS.md` or the matching `docs/TODO.md` entry. The file is a staging inbox, not a log.
+6. **Reflect on the playbook**: add a proposal to `docs/PLAYBOOK_FEEDBACK.md` only if a real workflow-impact change surfaced — see `docs/AGENTS.md` Playbook Improvement Loop. Do NOT edit AGENTS / HANDOFF directly.
+7. If a cross-repo dependency or sibling-repo arrangement changed, update the "Related Repos" section above and the matching section in each sibling's `HANDOFF.md` so the reference graph stays consistent (cross-link invariant).
+8. If the remote fan-out, mirror-host list, or backup procedure changed, update the "Remotes & Backup" section above and any project-local `REMOTES.md`.