discipline-md 0.1.0

package/templates/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+Human-readable record of notable changes. Update this file before committing meaningful work. Every commit should have an entry, either by commit hash after the commit exists or by exact commit title before committing.
+
+This is the **canonical chronological log of shipped work** for this project. Per the mandatory cleanup gate in `docs/HANDOFF.md` and `docs/AGENTS.md`, shipped TODO entries are deleted from `docs/TODO.md` once captured here, and completed roadmap items are marked ✅ in `docs/ROADMAP.md`. Do not introduce a separate `FEATURES.md` — it would only duplicate either this file (chronological) or `docs/PROJECT_CONTEXT.md` (current-state).
+
+This file is **project-scoped**. The framework repo additionally maintains a root `CHANGELOG.md` for changes that affect multiple downstream projects. See "Dual-CHANGELOG Convention" in `DocumentationFramework.md`. Project changelogs do not log framework-template changes; framework changelogs do not log project work.
+
+## Entry conventions
+
+Three conventions keep the log skim-able for both humans and agents looking at it cold:
+
+### 1. Date or wave headings
+
+Use H2 for the heading. The default shape is a date plus an optional branch / PR / commit-hash suffix in parentheses for traceability:
+
+```markdown
+## 2026-05-06 (feature/payment-flow)
+## 2026-05-06 (#147)
+```
+
+Projects running concurrent multi-subagent batches (a coordinator session that fans work out to several subagents and lands the results in one cleanup) should group those into a **wave** heading instead of one H2 per subagent — the wave is the unit of human review.
+
+```markdown
+## Wave 6 — 2026-05-09 (feature/dual-changelog-rollout)
+
+- (infra: framework) Adopted dual-CHANGELOG convention; root log now scoped to cross-project changes only.
+- (docs: meta) ...
+- (feat: queue) ...
+```
+
+One H2 per logical change set (date or wave); bullet body for what shipped. Newest at the top — keep ordering consistent across the file.
+
+### 2. Test-count delta on every entry
+
+Each entry includes a test-count line so regressions stand out at a glance:
+
+```markdown
+(tests N/N green, +M from prior)
+```
+
+`N/N green` is the absolute count after the change; `+M from prior` is the delta vs. the previous entry. A negative delta or a `green → red` shift lights up immediately. If the change set did not touch tests, write `(tests N/N green, +0 from prior)` so the silence is explicit.
+
+For wave entries put the test-count line directly under the H2; for single-change entries put it as the first bullet or as a parenthetical at the end of the change line.
+
+### 3. Category prefixes on bullets
+
+Tag each bullet with one of the following prefixes for skim-ability:
+
+- `(infra: ...)` — build, CI, deploy, mirroring, repo-level plumbing.
+- `(docs: ...)` — documentation-only changes, no runtime behavior delta.
+- `(fix: ...)` — bug fix; behavior was wrong and is now correct.
+- `(feat: ...)` — new feature or capability shipped to users.
+- `(refactor: ...)` — code reshape with no behavior change. Use sparingly; a refactor that doesn't unlock something usually doesn't deserve its own bullet.
+- `(test: ...)` — test additions or fixes that don't ride along with a feat/fix.
+- `(chore: ...)` — dependency bumps, formatting, housekeeping.
+
+After the prefix, lead with the **user-visible** change, then mention the file or system that moved. The prefix doubles as the section a future reader will jump to when looking for "what features shipped this quarter" or "what infra moved last month."
+
+## Worked example
+
+```markdown
+## Wave 6 — 2026-05-09 (feature/dual-changelog-rollout)
+
+(tests 142/142 green, +4 from prior)
+
+- (feat: queue) `AUTONOMOUS_QUEUE.md` now supports per-item agent-tier suggestions; the autonomous host respects them when picking a subagent.
+- (infra: framework) Mirrored the new `agents/` folder into `docs/agents/` during bootstrap.
+- (docs: meta) Documented the dual-CHANGELOG convention; clarified that `docs/CHANGELOG.md` is project-scoped.
+- (fix: handoff) `HANDOFF.md` Approval Signals section corrected: "go ahead" alone is not approval for `[needs-human-collab]` items.
+
+## 2026-05-08 (#214)
+
+(tests 138/138 green, +2 from prior)
+
+- (feat: usage) Added `--dry-run` to the daily ingest CLI so operators can preview without writing.
+- (test: ingest) Two new test cases covering empty-input and partial-failure modes.
+```
+
+## YYYY-MM-DD (branch-or-pr-or-hash)
+
+(tests N/N green, +M from prior)
+
+- (category: ...) Added/changed/fixed something notable. Lead with the user-visible change, then mention the file or system that moved.
+
+## YYYY-MM-DD (branch-or-pr-or-hash)
+
+(tests N/N green, +M from prior)
+
+- (category: ...) Subsequent change set (newest at top — keep ordering consistent across the file).

package/templates/CLAUDE.md

@@ -0,0 +1,89 @@
+<!--
+  TEMPLATE: CLAUDE.md (Tier B7 — repo-root agent onboarding)
+
+  WHEN TO USE:
+    - At the root of any repo where AI coding agents (Claude Code or others)
+      will operate. This is the agent's HOT PATH — the first file read every
+      session.
+
+  HOW TO USE:
+    1. Copy this file to the repo root as `CLAUDE.md`.
+    2. Replace every <placeholder>.
+    3. Keep it SHORT. Target under 80 lines. Anything that needs more depth
+       belongs in a doc that Reading Order points to, not here.
+    4. CLAUDE.md is for orientation, not policy detail. The Hard Rules section
+       is for things that, if violated, cause real damage; routine guidance
+       belongs in the linked docs.
+
+  WHY KEEP IT TIGHT:
+    - Every session pays the token cost of this file as part of context.
+    - A wall of text trains the agent to skim it instead of obey it.
+    - The four sections below are the minimum useful surface; resist adding more.
+-->
+
+# CLAUDE.md
+
+Working notes for Claude Code (and any other AI coding agents) operating
+inside `<repo-path>`.
+
+## Session start
+
+Preflight (loads every session — cheapest mishap insurance):
+
+1. **Read the handoff.** Read `HANDOFF.md` in your current working directory if present; treat a stale `Last updated` as a smell — flag mismatches, don't trust them.
+2. **Place yourself.** Confirm the working directory and git branch before editing; for new work, branch off the latest default branch (see Hard Rules).
+3. **Scope big moves out loud.** Multi-file edits, deletions, pushes, or deploys: say what you're about to do, then proceed.
+4. **Verify before "done."** "Builds clean" / a subagent's "done" is intent, not proof — run it, grep, or check in-app first.
+
+End of session: update this folder's `HANDOFF.md` (`Status` + `Last updated`) and clear shipped TODOs.
+
+## Reading Order
+
+Before editing, read in this order:
+
+1. `<docs/HANDOFF.md or session-state doc>` — current work-in-progress / where the last session left off.
+2. `<docs/README.md or PROJECT_CONTEXT.md>` — what this project is.
+3. `<docs/PROJECT_CONTEXT.md or equivalent>` — funded scope / build contract.
+4. `<docs/AGENTS.md or AGENTS-policy doc>` — tier routing, who does what.
+5. `<docs/TODO.md and AUTONOMOUS_QUEUE.md>` — what's in scope right now.
+
+## Common Commands
+
+```<powershell | bash>
+<install command>                # first run only, e.g. npm install / pnpm install / pip install -e ".[dev]"
+<dev command>                    # local dev server / watcher
+<typecheck command>              # e.g. tsc -b --noEmit / mypy / pyright
+<test command>                   # unit tests
+<test:watch command>             # watch-mode tests (omit if not applicable)
+<full-gate command>              # the single command CI runs and you should run before commit
+<lint command>                   # if separate from typecheck
+<build command>                  # production build
+<preview command>                # serve / preview the production build locally
+```
+
+> Keep this list to commands the agent will actually run. If the project has
+> 30 npm scripts, list the 8 that matter and link the rest from package.json.
+
+## Hard Rules
+
+Things never to do. Each line is a load-bearing rule — violating it causes
+real damage (data loss, scope creep, license drift, content-safety incident,
+secret leak).
+
+- **<funded-scope rule>.** <e.g. "The pitch in `docs/PROJECT_CONTEXT.md` is what may be built. Material drift requires a re-pitch in `docs/OPEN_DECISIONS.md` and a fresh `FUNDING_APPROVED` signal.">
+- **<no-secrets-in-repo rule>.** Never commit `.env*`, credentials, API keys, deploy tokens, or anything in `<secret-paths>`. `.gitignore` covers the common cases; if you're about to bypass it, stop.
+- **<no-push-without-approval rule>.** Don't `git push` without the operator's explicit go-ahead. Don't force-push to `<protected-branch>` ever.
+- **One PR per change — open a new one every time, never reuse.** Every change reaches `<protected-branch>` through a pull request; no direct pushes to `<protected-branch>`, never force-push it. Branch off the latest `<protected-branch>` and open a NEW PR for each set of edits. Do NOT add commits to an existing or already-open PR — even your own, even if related — unless the operator explicitly says so; when unsure, open a new PR.
+- **<no-deploy-without-security-audit rule>.** Don't deploy to a public-facing surface without a current `docs/SECURITY_AUDIT_<YYYY-MM-DD>.md` (≤90 days old OR covering all changes since the last audit, whichever is stricter). See `docs/DEPLOYMENT.md` Pre-Deploy Gate.
+- **<content-safety rule>.** <project-specific — e.g. "See `docs/agents/FOUNDER.md` for the rules: real options must link to a real Wikipedia article, fakes must be invented, no living-person gotchas, no medical claims, no tragedy material.">
+- **<doc-sync rule>.** When work crosses a doc-completion-gate boundary (`<docs/HANDOFF.md or equivalent>` lists them), update those docs in the same change.
+- **<no-shipped-todo-residue rule>.** Once a task ships and is logged in `<docs/CHANGELOG.md>`, delete it from `<docs/TODO.md>`.
+
+## Defaults
+
+- **Default model tier:** <e.g. Sonnet for routine implementation, Opus for architect / security-reviewer / planner. See `docs/AGENTS.md` for the full routing table.>
+- **Default branch:** `<main | master | trunk>`. <one line on protection state if any.>
+- **License:** `<All Rights Reserved | MIT | Apache-2.0 | …>` (see `LICENSE`). Do not silently change it.
+- **Stack:** `<one line: language + framework + runtime>`. Do not add `<things-that-would-be-scope-creep>` without a re-pitch.
+- **Code comments:** <project's stance — e.g. "Default to writing no comments; names should carry meaning." or "Document every public function.">
+- **Formatter / linter:** `<prettier | black | rustfmt>` is the source of truth — don't argue with it.

package/templates/CREDITS.md

@@ -0,0 +1,109 @@
+# Credits
+
+Record of third-party code, libraries, assets, fonts, and notable inspirations the project depends on. Update this file whenever a new dependency is added, an asset is licensed in, or a code snippet is vendored from another source.
+
+This file is for **attribution and credit**. License compliance is a related-but-separate concern — note license obligations here when they require attribution text in the running app, but project-wide license tracking belongs in `LICENSE` and (for distributed projects) a `NOTICE` file at the repo root.
+
+## How to use this file
+
+For each entry, capture enough that a future maintainer can:
+
+- Find the original source.
+- Verify the license still permits use as the project evolves.
+- Reproduce any required attribution text in the right place.
+
+Group entries by category. Use the categories below as a starting point; delete the ones that don't apply, add new ones as needed.
+
+---
+
+## Runtime Dependencies
+
+(Libraries the project ships with or depends on at runtime — npm packages, system libraries, CDN-loaded scripts, etc.)
+
+### Library Name
+
+- **Source:** repository or registry URL.
+- **Version:** version pinned in the project (or "latest", or a range).
+- **License:** SPDX identifier (e.g. MIT, Apache-2.0, BSD-3-Clause).
+- **Purpose:** what the project uses it for.
+- **Used in:** files / modules that import it.
+- **Attribution required in app?** yes/no — if yes, where it lives (footer, About page, NOTICE file).
+
+---
+
+## Development / Build Dependencies
+
+(Tools used during development that don't ship to users — test runners, linters, bundlers, scaffolding tools.)
+
+### Tool Name
+
+- **Source:**
+- **Version:**
+- **License:**
+- **Purpose:**
+
+---
+
+## Vendored Code / Snippets
+
+(Code copied or adapted from another project rather than imported as a dependency. Each entry is a discrete chunk, not a sweeping copy.)
+
+### Snippet Name
+
+- **Original source:** URL of the original code.
+- **Original author / project:**
+- **Original license:**
+- **Lives at:** path in this repo.
+- **Modifications:** what was changed from the original.
+- **Why vendored instead of depended on:** brief reason (size, no package available, customization needed).
+
+---
+
+## Assets
+
+(Fonts, images, audio, video, icons — anything visual or media-shaped that the project uses.)
+
+### Asset Name
+
+- **Source:** URL or marketplace.
+- **License:** specific license terms (CC0, CC-BY, custom).
+- **Attribution text:** if the license requires a credit line, the exact wording goes here.
+- **Used in:** files that reference the asset.
+- **Modifications:** if the asset was edited, what was changed (matters for some licenses).
+
+---
+
+## Fonts
+
+(Treat fonts as a sub-category of assets, but break them out because licensing is often distinct.)
+
+### Font Family
+
+- **Source:**
+- **License:** SIL Open Font License, custom EULA, etc.
+- **Loaded via:** Google Fonts CDN, self-hosted, system font, etc.
+- **Used in:**
+
+---
+
+## Inspirations / References (optional)
+
+(Projects, papers, or designs the project drew from without copying code or assets directly. Optional but useful for posterity, especially for creative or research projects.)
+
+### Reference Name
+
+- **Source:**
+- **What it inspired:** the part of this project that was influenced.
+- **Notes:**
+
+---
+
+## Sunsetted (optional)
+
+(Dependencies, assets, or sources that were used in earlier versions of the project but no longer ship. Keep them recorded if their license terms required attribution at the time, or if their absence would otherwise be confusing to a future archaeologist.)
+
+### Former Dependency
+
+- **Was used for:**
+- **Removed in:** date or version.
+- **Why removed:**

package/templates/DATA_MODEL.md

@@ -0,0 +1,88 @@
+# Data Model
+
+Update this document when tables/collections/fields change, persistence moves between layers, sensitive data classification changes, or import/export/migration behavior changes.
+
+## Persistence Overview
+
+Describe where state lives in production and local development. One short paragraph; reserve detail for the per-entity sections below.
+
+**Canonical schema / source-of-truth file:** `path/to/schema.sql` (or Prisma file, ORM models, OpenAPI spec, "n/a — ephemeral state").
+
+## Production Data Stores
+
+- Store/service:
+- Purpose:
+- Backup/migration notes:
+
+## Local Development Data
+
+- File/database/cache:
+- Reset process:
+
+## Tables / Collections / Entities
+
+### Entity Name
+
+Purpose:
+
+Important fields:
+
+- `field`: Description.
+
+Constraints / uniqueness:
+
+- E.g. unique on `(handle)`, foreign key on `parent_id`, NOT NULL on `created_at`.
+
+Relationships:
+
+- Relationship description.
+
+Never expose / server-only:
+
+- Fields that must not appear in client responses, logs, or exports (`password_hash`, `reset_token`, internal IDs, etc.). Empty list = explicitly nothing.
+
+## Sensitive Data
+
+- Data type:
+- Storage rule (encryption, hashing, never-stored):
+- Exposure rule (which API responses include / exclude):
+- Logging rule (redaction, what shows up in error logs):
+
+## Import / Export / Seed / Migration Notes
+
+Describe any CSV imports, schema migrations, seed data, generated files, or export tooling. For each:
+
+- Trigger / when it runs.
+- Expected columns/keys (or pointer to the source spec).
+- What it produces / where it writes.
+
+## State Change Map (optional — delete if N/A)
+
+For projects with backends, queues, or background jobs, list each operation/endpoint/job and the entities it reads/writes. Useful when state can be touched by multiple paths.
+
+| Operation | Reads | Writes |
+|---|---|---|
+| `POST /example` | `users` | `users`, `audit_log` |
+
+Skip this section for libraries, CLI tools, or apps with no persistent operations.
+
+## Concurrency & Atomicity (optional — delete if N/A)
+
+For projects with contended writes, document:
+
+- Locking strategy (DB transactions, application-level mutexes, optimistic concurrency).
+- Idempotency keys / replay protection.
+- Transaction boundaries (what is and is not atomic).
+- Race conditions known about and how they are handled.
+
+Skip for projects without concurrent writes.
+
+## Derived / Computed State (optional — delete if N/A)
+
+For state derived from other state rather than stored:
+
+- Derivation rule.
+- Where it is computed (SQL view, application code, per-request).
+- What invalidates it.
+
+Skip for projects without derived state.

package/templates/DECISIONS.md

@@ -0,0 +1,120 @@
+# Decisions
+
+Record important product and technical decisions that future maintainers should not have to rediscover. The `architect` Frontier-tier subagent (defined in `docs/AGENTS.md`) produces draft entries in this format; the host reviews and lands them.
+
+Each decision is its own H2 section dated and titled. Body subsections are H3 so multiple decisions stack cleanly in one file.
+
+## Common Decisions Worth Recording
+
+A non-exhaustive prompt list — decisions you'll likely face on any non-trivial product, worth recording the moment they're made (or the moment you realize an unwritten convention has hardened into one). Each is a stub shape; expand into a full entry when the decision is actually made.
+
+- **Branded ID types in the domain layer.** When the domain has multiple entity types with string- or number-shaped IDs, branded types (e.g. `SampleId` ≠ `SourceId` ≠ `ProjectId`) prevent cross-entity confusion at the type-checker level. Record the branding mechanism, the entities that get branded, and which boundaries enforce or unwrap them.
+- **`schemaVersion: N` on persisted state with a load-time guard.** Any state that round-trips through a file, KV, or database earns a `schemaVersion` field plus a load-time switch that runs migrations forward (and rejects `version > current`). Record the initial version, where the guard lives, and the migration strategy (forward-only, reversible, etc.).
+- **Auth model.** Anonymous-first vs sign-in-first; password vs magic-link vs OAuth; session storage (cookie / JWT in localStorage / opaque KV token).
+- **Local-only vs hosted phase.** Whether the project is intentionally not deployed yet, with explicit exit criteria for graduating to a hosted phase.
+- **Persistence boundary in dev vs prod.** Local JSON / SQLite for dev, hosted DB for prod — and the seam that switches between them.
+- **License choice.** Default (e.g. All Rights Reserved) vs open-source vs source-available. Affects whether external contributions are accepted.
+- **Funding / scope drift rule.** When implementation diverges materially from a funded spec, what's the procedure? (Pause and re-pitch upstream, or proceed under stated authority.)
+- **Error-shape conventions.** How errors flow from data layer → service → UI. Status codes, error envelopes, `Result<T, E>` vs throws.
+- **ID generation.** UUIDv4 vs ULID vs nanoid vs DB sequence; client-generated vs server-generated.
+- **Time and timezone handling.** UTC everywhere internally vs local time at boundaries; how "today" is defined for daily-reset features.
+
+When one of these gets decided, write it up as a full entry below using the format that follows.
+
+## Entry Format
+
+Every decision uses the same H3 structure under an H2 header:
+
+```
+## YYYY-MM-DD — <Decision Title>
+
+Status: Decided | Accepted | Superseded
+Decided: YYYY-MM-DD
+Decision: <one-line summary of what was chosen>
+
+### Context
+
+Why this came up — the problem, the tradeoff, the trigger. Reference relevant docs (`PROJECT_CONTEXT.md`, prior `DECISIONS.md` entries, `ARCHITECTURE.md`) rather than restating their content.
+
+### Consequences
+
+What changes as a result. Use bullets for clarity:
+
+- Positive consequence.
+- Negative or tradeoff consequence.
+- New maintenance burden, constraint, or downstream work introduced.
+
+### Asserted by
+
+Files, tests, code locations, deployment assets, or external configuration that **depend on this decision being true**. If any of these change shape, the decision is implicitly broken and should be revisited. Use `path:line` format where possible so a future reader can jump straight there.
+
+- `<path/to/test>:Lxx` — `<what it asserts>`
+- `<path/to/code>:Lxx-Lyy` — `<the implementation that embodies this decision>`
+- `<path/to/deployment-asset>` — `<config that encodes this decision>`
+
+### Future audits
+
+Conditions under which this decision should be revisited. Not a deadline — a list of *triggers* that should automatically re-open the question.
+
+- If `<X>` is ever retired, this decision should be re-evaluated.
+- If `<metric>` exceeds `<threshold>`, the alternative (`<alt>`) becomes worth reconsidering.
+- When `<dependency>` ships `<version>`, check whether the workaround is still needed.
+
+### Alternatives Considered (optional)
+
+- Alternative — why it was not chosen.
+- Alternative — why it was not chosen.
+```
+
+## YYYY-MM-DD — <Worked Example: Use Branded ID Types in Domain Layer>
+
+Status: Decided
+Decided: YYYY-MM-DD
+Decision: All entity IDs in `<src/domain/types.ts>` use TypeScript branded types so cross-entity ID confusion is a compile error.
+
+### Context
+
+The domain has `<EntityA>`, `<EntityB>`, and `<EntityC>`, each with string-shaped IDs. Without branding, `function foo(id: string)` accepts any of the three, and a refactor that swaps argument order silently compiles. Caught a real instance of this in `<test or code path>` during `<milestone>`.
+
+### Consequences
+
+- Cross-entity ID mix-ups become compile errors instead of runtime bugs.
+- Constructing an ID from a raw string requires going through a branded constructor (`<makeEntityAId(s)>`), which adds one line per ID-creating boundary (parsers, DB reads, URL params).
+- Generic helpers that take "any ID" need either a union type or a generic parameter.
+- Test fixtures need the constructor too — `<fixture-helper-path>` exposes `<asEntityAId(s)>` etc. for ergonomic construction.
+
+### Asserted by
+
+- `<src/domain/types.ts>:Lxx-Lyy` — branded type declarations.
+- `<src/domain/ids.ts>:Lxx` — branded constructors and unwrap helpers.
+- `<test/domain/ids.test.ts>:Lxx` — type-level negative test (should fail to compile if branding is removed).
+- `<src/api/routes/*.ts>` — every route handler that accepts an ID parses it through the branded constructor at the boundary.
+
+### Future audits
+
+- If the project migrates off TypeScript (e.g. to Go or Rust), the branding mechanism changes shape — re-record under the new language's idiom (newtype, distinct types, etc.).
+- If the domain is ever flattened to a single entity type, branding becomes overhead — revisit.
+- If runtime parsing libraries (zod, valibot) are adopted project-wide, fold branded constructors into their schemas rather than maintaining parallel constructors.
+
+### Alternatives Considered
+
+- Plain `string` aliases (`type EntityAId = string`) — rejected; aliases are not nominal in TypeScript, so the compiler still treats them as interchangeable.
+- Wrapper objects (`{ kind: "EntityA", value: string }`) — rejected; runtime overhead and ergonomics worse than zero-cost branding.
+
+## YYYY-MM-DD — <Second Decision Title>
+
+Status: Accepted
+Decided: YYYY-MM-DD
+Decision: <one-line summary>
+
+### Context
+
+(Each decision repeats the same H3 structure. Keep entries chronological — newest at the bottom or newest at the top, pick one and stay consistent across the file.)
+
+### Consequences
+
+### Asserted by
+
+### Future audits
+
+### Alternatives Considered