discipline-md 0.1.0

package/templates/IMPROVEMENT_LOOP.md

@@ -0,0 +1,103 @@
+<!--
+  Discipline optional template. Install with: npx discipline-md add IMPROVEMENT_LOOP
+  Pairs with VERIFICATION_GATE.md (the ground-truth signal the loop is built on).
+  This is a COLD-PATH doc — read it when running or wiring the loop, not every session.
+-->
+
+# Improvement Loop
+
+A closed, recursive loop that uses AI subagents to **discover → execute → verify → evaluate → integrate → repeat** on this project. The recursion is that the discovery phase re-runs on the now-improved system, so the loop generates its own next work-list instead of waiting for a human to hand-write one.
+
+This doc is mostly **composition, not new machinery** — the loop wires together Discipline primitives you already have:
+
+- `AUTONOMOUS_QUEUE.md` — the work-list (discovery output / execution input).
+- autonomy tags (`[autonomy: safe|review|needs-human-collab]`) + the curated queue — the two-gate human-judgment control.
+- `DECISIONS.md` / `OPEN_DECISIONS.md` — judgment record + the inbox where the loop parks decisions it isn't allowed to make.
+- `CHANGELOG.md` — completed work.
+- `PLAYBOOK_FEEDBACK.md` — where the loop proposes improvements to *itself* (meta-recursion).
+- the role roster in `AGENTS.md` / `agents/*` — `RECON` fans out for discovery; `SECURITY_REVIEWER` / `TEST_STRATEGIST` / `DEBUGGER` for adversarial evaluation. **The loop adds no new roles.**
+
+The **one genuinely new primitive** is `VERIFICATION_GATE.md` — the machine-checkable ground-truth signal. Without it the loop optimizes "sounds done" instead of "is done" and silently rots. **Do not run the loop on any step that has no verification gate** — that step is judgment, not execution; escalate it.
+
+## The two non-negotiables
+
+1. **A ground-truth gate** (`VERIFICATION_GATE.md`). Every iteration must prove itself against a signal a human didn't generate — compile/test/run, an eval suite, a reproduction harness. The gate is what catches the agents' *own* mistakes (a fix that breaks a test, a "done" that doesn't build). No gate → no loop.
+2. **Human judgment gates.** The loop is only allowed to act where (1) exists; every consequential, taste-dependent, or hard-to-reverse fork escalates to `OPEN_DECISIONS.md` and stops. Automate execution and adversarial evaluation; keep humans on *what's worth doing*.
+
+## The cycle
+
+```
+1. DISCOVER  fan out read-only RECON agents across dimensions (correctness /
+             lifetime / UX / robustness / security). Each returns STRUCTURED
+             findings (severity, location, fix-sketch, confidence). Dedup →
+             append to AUTONOMOUS_QUEUE.md with honest autonomy tags.
+
+2. SELECT    take the highest-severity items tagged [autonomy: safe] that are
+             also IN the queue (two-gate). Anything [needs-human-collab] →
+             OPEN_DECISIONS.md and STOP that item.
+
+3. EXECUTE   fan out implementation agents. Disjoint files run in parallel
+             (worktrees if they'd conflict); shared files run serially.
+
+4. GATE      run VERIFICATION_GATE. FAIL → loop-fix → re-gate (inner loop)
+             until green. Never trust an agent's "done" — re-run the gate.
+
+5. EVALUATE  fan out adversarial reviewers prompted to REFUTE the change
+             (multiple lenses, confidence vote). New findings → back to the
+             queue. The reviewer is NEVER the agent that wrote the code.
+
+6. INTEGRATE commit; delete shipped items from TODO/queue and log them in
+             CHANGELOG (cleanup gate); record durable choices in DECISIONS.
+
+7. CONVERGE  repeat from 1. Stop when a DISCOVER pass is "dry" (K consecutive
+             rounds with no new finding above the severity floor) OR a budget /
+             iteration cap is hit OR the only remaining items are judgment.
+
+8. REFLECT   propose improvements to the loop's OWN contracts via
+             PLAYBOOK_FEEDBACK.md — human-reviewed, never auto-applied.
+```
+
+Stages 1→7 are the object-level recursion (the improved system gets re-scanned). Stage 8 is the meta-recursion (the framework improving how it improves). All loop state lives in the Markdown ledgers, so the loop is inspectable, diffable, and resumable from any point.
+
+## Tier routing (see `AGENTS.md`)
+
+- **DISCOVER / EVALUATE** read-only fan-out → **Recon** tier (cheap, broad). Bound expensive spend to where it pays.
+- **EXECUTE** → **Workhorse** tier.
+- **Architecture decisions, security-sensitive fixes, the verification-gate design itself** → **Frontier** tier.
+
+The host stays at Workhorse and spawns Frontier subagents only for the hard subtask — never run the whole loop at Frontier tier.
+
+## Convergence rules
+
+- **Loop-until-dry, not fixed-N.** A simple "do 5 rounds" misses the tail; a single round misses the recursion. Stop after K consecutive empty DISCOVER passes (K=2 is a sane default).
+- **Severity floor.** Only spend EXECUTE tokens on findings above a bar; log + defer the rest so cheap discovery is most of the cost, not expensive fix-fanout.
+- **Hard budget cap.** A token/iteration ceiling the loop cannot exceed — the runaway backstop.
+- **No silent truncation.** If the loop caps coverage (top-N, sampling, deferred items), it must LOG what it dropped. "Covered everything" must never quietly mean "covered the easy 80%."
+
+## Failure modes this loop is designed against
+
+- **Reward hacking** — optimizing the gate instead of the goal (deletes the failing test rather than fixing the bug). Mitigation: gate on *behavior / reproduction*, not self-reported success; a separate adversary confirms the fix is real; spot-check.
+- **Drift** — wandering from intent over many iterations. Mitigation: re-state the goal + constraints in each iteration's context; a completeness-critic pass ("are we still solving the original problem?"); human re-anchoring at chapter boundaries.
+- **"Looks done but isn't"** — the most common one. Mitigation: re-run the gate every iteration; an agent's "done" is intent, not proof.
+- **Compounding error** — small mistakes amplify across rounds. Mitigation: gate every iteration (not every N); keep iterations small/atomic; isolate parallel work.
+- **Cost runaway** — fan-out × loops. Mitigation: the convergence rules above; run on a cadence (manual or scheduled), not always-on.
+
+## Running it
+
+Harness-agnostic: the host follows the cycle above, using the roster in `AGENTS.md` for fan-out and `VERIFICATION_GATE.md` for the gate. For a Claude Code convenience wrapper (a `/improve-loop` skill + a cleanup-gate Stop hook), see `HARNESS_INTEGRATION.md` "deep mapping" — opt-in, adoption-gated, never required.
+
+## Stop conditions (hand back to the human)
+
+- A DISCOVER finding implies a scope/product change beyond the funded spec → `OPEN_DECISIONS.md`.
+- A fix needs a design decision with no ground-truth answer → `OPEN_DECISIONS.md`.
+- The verification gate itself is unreliable or missing for a needed step → fix the gate first; do not loop without it.
+- Discovery keeps outpacing execution → surface to the stakeholder for a re-pitch.
+
+## Inputs
+
+- `AUTONOMOUS_QUEUE.md`, `TODO.md`, `PROJECT_CONTEXT.md`, `DECISIONS.md`, the role roster.
+- `VERIFICATION_GATE.md` (required).
+
+## Outputs
+
+- A refilled, prioritized queue; shipped fixes logged in `CHANGELOG.md`; judgment forks parked in `OPEN_DECISIONS.md`; loop-self-improvements proposed in `PLAYBOOK_FEEDBACK.md`.

package/templates/INVESTIGATION.md

@@ -0,0 +1,154 @@
+<!--
+  TEMPLATE: INVESTIGATION.md (Tier B4 — bounded research writeup)
+
+  WHEN TO USE:
+    - Before committing to a tech-stack pick, hosting choice, framework migration,
+      or any other "we have to choose between N options" decision that benefits
+      from a structured side-by-side rather than an in-line discussion.
+    - When a question has been raised that's bigger than a TODO line item but
+      smaller than a full architectural decision (which would land in DECISIONS.md).
+    - When you need to record an investigation where the OPERATOR is the one who
+      ultimately picks — an investigation produces a recommendation, not a fait
+      accompli.
+
+  HOW TO USE:
+    1. Copy this file into the project's `docs/` directory.
+    2. Rename to the convention: INVESTIGATION_<TOPIC>.md
+       (UPPER_SNAKE_CASE topic, one file per investigation; e.g.
+       INVESTIGATION_DASHBOARD_TECH_STACK.md, INVESTIGATION_LLM_HOSTING.md).
+    3. Replace every <placeholder> with project-specific content.
+    4. When the operator picks, leave this file in place as a record. Add a
+       one-line "Decision: <picked> on <YYYY-MM-DD>; see DECISIONS.md#<anchor>"
+       at the top so future readers can trace from investigation to outcome.
+    5. Investigations are CHEAP TO ABANDON — if the operator picks differently
+       than recommended, that's fine; the value is in the record of options
+       considered, not in being right.
+
+  RELATED:
+    - Pairs with DECISIONS.md (where the final, locked decision lives).
+    - Pairs with OPEN_DECISIONS.md (where pending picks are tracked).
+-->
+
+# Investigation — <topic>
+
+Status: <investigation in progress | investigation complete; operator decision pending | resolved YYYY-MM-DD — see DECISIONS.md#<anchor>>
+
+> Note on sources: <state explicitly whether live web access (WebFetch / WebSearch)
+> was available during the investigation. If not, note that version numbers and
+> "active maintenance" claims may need a spot-check before the operator commits.>
+
+## TL;DR
+
+<two-to-four-sentence summary: which option to pick, why, what to avoid, what the
+runner-up is. The operator should be able to read this section and stop if they
+already trust the framing.>
+
+## Background — why this came up
+
+<one-to-three paragraphs: what triggered the investigation. The TODO line that
+spawned it, the milestone it gates, the decision that's blocked on it. Include
+enough context that a reader six months from now can re-derive the question.>
+
+## Requirements
+
+<bulleted list — the hard constraints the option must meet. Cite the source doc
+that anchors each constraint where possible (e.g. "Single operator — per
+PROJECT_CONTEXT.md §Non-Goals").>
+
+- <constraint 1, with citation if applicable>
+- <constraint 2>
+- <constraint 3>
+- <…>
+
+## Candidates Compared
+
+### <Option A>
+
+**Elevator pitch.** <one-to-two-sentence description of the option.>
+
+**Learning curve.** <hours / days / weeks to a working prototype, with what assumed prerequisites.>
+
+**Ecosystem.** <maintenance status, community size, recent release cadence, vendor stability.>
+
+**<criterion-1, e.g. Charting | Performance | Pydantic reuse>.** <how the option handles it.>
+
+**<criterion-2>.** <…>
+
+**Deployment.** <where it can run, free-tier options, self-host viability.>
+
+**Footguns.** <bulleted list of gotchas — known weak points, surprises, things that bite teams who pick this option.>
+
+**Verdict.** <one-paragraph judgment for THIS use case.>
+
+### <Option B>
+
+(same shape as Option A)
+
+### <Option C>
+
+(same shape)
+
+### <Option D — optional, only if it's a real candidate>
+
+(same shape)
+
+## Comparison table
+
+| Option        | <criterion-1> | <criterion-2> | <criterion-3> | <criterion-4> | Maturity   | Verdict for this use case            |
+| ------------- | ------------- | ------------- | ------------- | ------------- | ---------- | ------------------------------------ |
+| <Option A>    | <…>           | <…>           | <…>           | <…>           | <…>        | **Recommended**                      |
+| <Option B>    | <…>           | <…>           | <…>           | <…>           | <…>        | <runner-up | overkill | wrong-fit>     |
+| <Option C>    | <…>           | <…>           | <…>           | <…>           | <…>        | <…>                                  |
+| <Option D>    | <…>           | <…>           | <…>           | <…>           | <…>        | <avoid for this build>               |
+
+## Verdict / Recommendation
+
+**<Option A>.** The decision is driven by <number> concrete properties of this
+use case, not by general popularity:
+
+1. **<property-1>.** <one paragraph linking the property to why option A wins on it.>
+2. **<property-2>.** <…>
+3. **<property-3>.** <…>
+
+If the operator finds <Option A> limiting after the MVP ships
+(e.g. <concrete trigger>), **migrating to <Option B> later is straightforward**
+because <reason — usually a shared substrate, e.g. "both are Python + Plotly,
+the schema imports don't change">.
+
+## Operator Decision Pending
+
+- **Pending?** <yes | no — if no, skip this section>
+- **What's needed:** <a sentence stating exactly what the operator must do — pick A vs. B vs. C, or sign off on the recommendation, or provide info that the investigation could not get.>
+- **Blocking:** <what work is blocked by this decision, if anything>
+- **Default if no decision:** <what the project does in absence of a pick — proceed with recommendation? wait? something else?>
+
+## Next Steps
+
+<assuming the recommendation is accepted, the concrete steps to act on it.
+Numbered list. Each step is short and actionable.>
+
+1. <step 1, e.g. "Provision the chosen hosting tier and capture the project ID in DEPLOYMENT.md.">
+2. <step 2>
+3. <step 3>
+4. <…>
+
+## Open Questions
+
+<questions the investigation could NOT answer from available materials —
+operator follow-up, vendor outreach, or a spike on the operator's own account.
+Be honest about the unknowns so the operator can decide whether to spend the
+time to close them or to ship under uncertainty.>
+
+- <unknown 1 — what would close it>
+- <unknown 2>
+- <…>
+
+## Sources Consulted
+
+<short list of docs read / URLs hit / project files inspected. If live web
+access was denied, name what would have been consulted and recommend a
+verification step.>
+
+- <source 1>
+- <source 2>
+- <…>

package/templates/LICENSE

@@ -0,0 +1,68 @@
+### LICENSE — STARTER (replace the placeholders before publishing)
+###
+### This file goes at the REPO ROOT, not in `docs/`. When you copy
+### `templates/*` into a new project, move LICENSE and NOTICE up to
+### the project root.
+###
+### **Default: All Rights Reserved** (below). This is intentional: the
+### framework defaults to closed-source so that open-sourcing is an
+### explicit, conscious decision rather than an accident. Replace
+### <YEAR> and <COPYRIGHT_HOLDER>, delete this header block, and you're
+### done.
+###
+### **Switch to an open-source license when:**
+###
+### - The project incorporates copyleft code (GPL, AGPL) — your project
+###   MUST be open-sourced under a compatible license.
+### - The project incorporates code under a license that requires
+###   propagation of attribution / source distribution at scale.
+### - You consciously choose to open-source for community / collaboration
+###   reasons.
+###
+### **Common alternatives** (replace the All Rights Reserved body
+### below with the chosen license's verbatim text — do not paraphrase;
+### courts read the exact words):
+###
+### - **MIT** — permissive, most common for open source. Lets anyone do
+###   anything as long as they preserve the copyright notice.
+### - **Apache-2.0** — permissive + explicit patent grant. If you choose
+###   this, ALSO ship a `NOTICE` file at repo root (see `templates/NOTICE`).
+### - **BSD-3-Clause** — permissive, similar to MIT plus a non-endorsement
+###   clause.
+### - **GPL-3.0 / AGPL-3.0** — copyleft. Derivatives must be open-sourced
+###   under the same license. AGPL extends copyleft to network-served
+###   software.
+### - **CC0 / CC-BY / CC-BY-SA** — for content (text, art, media).
+###   Use alongside a code license, not in place of one.
+###
+### Full text for each: https://choosealicense.com or https://spdx.org/licenses
+###
+### **Mixed-license projects** (code + copyrighted media, e.g. games /
+### ARGs / creative content): keep "All Rights Reserved" for media and
+### state any open-source code license boundary explicitly at the top
+### of the file before the license body. Example:
+###
+###     The source code in this repository (files under `src/`,
+###     `backend/`, etc.) is licensed under the MIT License (text
+###     below). Audio, artwork, and other media assets are All Rights
+###     Reserved by <HOLDER> and are NOT covered by that license.
+###
+### Once filled in, the rest of this file should read as a plain license
+### statement with no comment markers.
+
+Copyright (c) <YEAR> <COPYRIGHT_HOLDER>
+All Rights Reserved.
+
+No part of this software, its documentation, or its associated assets
+may be reproduced, distributed, transmitted, modified, or used to
+prepare derivative works in any form or by any means, electronic or
+mechanical, without the prior written permission of the copyright
+holder, except as permitted by applicable law (e.g. fair use, fair
+dealing) or by the terms of any separate written agreement.
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF OR INABILITY TO
+USE THIS SOFTWARE.

package/templates/NOTICE

@@ -0,0 +1,55 @@
+### NOTICE — STARTER (replace before publishing)
+###
+### This file goes at the REPO ROOT, not in `docs/`. When you copy
+### `templates/*` into a new project, move LICENSE and NOTICE up to
+### the project root.
+###
+### What this file is:
+###
+### NOTICE is a human-readable summary of the third-party components
+### bundled or distributed with this project, with their copyright
+### notices and license types. It satisfies attribution obligations for
+### dependencies whose licenses require them (Apache-2.0 explicitly;
+### BSD-3-Clause non-endorsement; some MIT-style licenses by convention).
+###
+### **Apache-2.0 specifically requires a NOTICE file** at the root of
+### the distribution if any included Apache-2.0 component shipped one.
+### NOTICE is not optional in that case — it must propagate.
+###
+### **CREDITS vs NOTICE**: `docs/CREDITS.md` is the human-friendly
+### attribution surface (what each library is, why it's used, where it
+### lives in the project). NOTICE is the legal-flavor summary that
+### travels with distributions. Both can exist; CREDITS is for
+### contributors and curiosity, NOTICE is for license compliance.
+###
+### Replace the placeholders below, populate the components list from
+### your actual dependencies, and DELETE this header before shipping.
+
+<PROJECT_NAME>
+Copyright (c) <YEAR> <COPYRIGHT_HOLDER>
+
+This product includes software developed by third parties. The full
+list of dependencies, their sources, and their licenses lives in
+`docs/CREDITS.md`. Components whose licenses require notice-level
+attribution are listed below with the required text verbatim.
+
+----
+
+### <Component name> (<License SPDX-id>)
+
+Copyright notice from upstream, copied verbatim if the license requires
+it. For Apache-2.0 components, copy the upstream NOTICE file's contents
+into a sub-block here.
+
+----
+
+### <Second component name> (<License SPDX-id>)
+
+Copyright notice...
+
+----
+
+(Add one block per component that requires notice-level attribution.
+Components under permissive licenses with no NOTICE requirement —
+plain MIT without an explicit NOTICE file upstream — do not need to
+appear here; CREDITS.md is enough for them.)

package/templates/OPEN_DECISIONS.md

@@ -0,0 +1,61 @@
+# Open Decisions
+
+Staging file for design or product decisions that block active work and need user input before implementation can proceed. Sits between "a decision arose during a session" and "the decision is recorded in `docs/DECISIONS.md`" (durable architecture) or folded into a `docs/TODO.md` entry (implementation detail).
+
+When this file holds only the heading, the project is unblocked.
+
+## When to add an entry
+
+- A paired session with the user produced a concrete question that needs an answer before the next session can ship its work.
+- An autonomous run hit a fork in the road that required user judgment beyond the autonomy gate (`[autonomy: needs-human-collab]` work).
+- An ambiguity surfaced that, if resolved by the agent unilaterally, would lock in an architectural choice the user should make.
+
+## When NOT to add an entry
+
+- Implementation details that don't change observable behavior — pick the cleanest option and note it in the relevant TODO.
+- Trivial decisions where the user has already given a directive in conversation — write the answer directly into the affected doc / code.
+- Speculative "we might want to think about X someday" entries that aren't blocking active work — those belong in `docs/ROADMAP.md` or the relevant TODO.
+- Wording or formatting preferences — pick one and move on.
+
+The file is a staging inbox, not a wishlist. Bloat here makes it useless as a blocker surface.
+
+## When to remove an entry
+
+Remove the entry once the user has answered AND the answer has been folded into:
+
+- `docs/DECISIONS.md` if the decision is durable architecture worth recording for future maintainers.
+- The relevant `docs/TODO.md` entry if it's an implementation detail.
+- The kickoff prompt for the next session if it's session-scoped guidance.
+
+Don't leave answered entries here as a log — that's what `docs/CHANGELOG.md` and `docs/DECISIONS.md` are for.
+
+## Format
+
+Each entry follows this template. Numbering is project-defined — match prior conversation references where possible so the user can trace decisions back to the discussion that surfaced them.
+
+```markdown
+### #N. Short title
+
+**Context**: brief statement of why this is blocking and what work is gated on it.
+
+**Options**:
+- (a) Option A.
+- (b) Option B.
+
+**Recommendation**: (X) — short reason.
+
+**Asymmetry** (optional): what the worst case looks like if the user picks differently.
+
+> **Your answer**: 
+```
+
+Group entries by topic (Operational, [feature area], etc.) when more than ~6 are open at once. Use letters (`A`, `B`, ...) for cross-cutting operational decisions and numbers (`#11`, `#12`, ...) for feature-area decisions if the project benefits from the distinction.
+
+## Open decisions
+
+*(empty — add entries here as they arise.)*
+
+## Notes
+
+- This file is project-local. Patterns that prove themselves cross-project should be promoted into the framework template via the playbook improvement loop (`docs/PLAYBOOK_FEEDBACK.md`).
+- If an entry has been open for >2 weeks without movement, surface it to the user explicitly rather than letting it fossilize. Stale blockers are worse than visible blockers.

package/templates/PLAYBOOK_FEEDBACK.md

@@ -0,0 +1,87 @@
+# Playbook Feedback
+
+Staging file for proposed improvements to the project's workflow docs (`docs/AGENTS.md`, `docs/HANDOFF.md`, `docs/TODO.md` conventions, completion gate, etc.) and for proposed promotions of project-local patterns to the framework template at `the framework's canonical templates/`.
+
+This file is the **inbox** between "the agent noticed something" and "the canonical doc gets edited." Direct edits to AGENTS / HANDOFF / etc. without going through this file skip the user review gate.
+
+See `docs/AGENTS.md` (Playbook Improvement Loop section) for the full lifecycle.
+
+## Workflow-impact discipline (hard rule)
+
+**Do not propose changes just to check a box.** Improvement-theater is the failure mode — adding aspirational language because language is easy. Stale aspirational guidance is worse than absent guidance.
+
+A proposal must satisfy at least one of:
+
+1. **A real friction point in this session would have been prevented or reduced** by the change.
+2. **A real friction point is foreseeable in upcoming work** and the change prevents it.
+3. **A pattern showed up multiple times** and is worth codifying so future agents don't re-derive it.
+4. **A subagent role's contract had to be bent** to fit a real situation, suggesting the contract needs tuning.
+
+If none of these apply, do not propose. Note the observation in your end-of-session summary if useful, but do not add it here.
+
+## Two kinds of proposal
+
+- **Local improvements** — edits to project-local docs (this repo's `AGENTS.md`, `HANDOFF.md`, TODO conventions, completion gate, etc.). Most proposals are local.
+- **Template promotions** — a pattern that started project-local has proved general enough to push back to `the framework's canonical templates/`. Higher bar: the pattern should have shipped at least once in this project and demonstrably worked. Don't promote untested ideas.
+
+## Lifecycle
+
+1. **Propose** — agent adds an entry below under Proposed Local Improvements or Proposed Template Promotions, with rationale + the specific friction point that motivated it.
+2. **Review** — user reads the proposal, accepts / rejects / asks for revision.
+3. **Apply** — on accept, agent edits the canonical doc (project-local AGENTS/HANDOFF/etc., or framework template), adds a `docs/CHANGELOG.md` entry, moves the PLAYBOOK_FEEDBACK entry to "Applied (recent)" **with the friction it was meant to kill recorded inline** (so a later session can check whether it actually worked).
+4. **Trim** — once the CHANGELOG entry exists, the "Applied (recent)" entry can be deleted from this file on the next cleanup pass.
+5. **Verify (closes the loop — later, not the same session)** — the next session that works in the changed area checks whether the recorded friction is actually gone. Gone → the change earned its keep; let it stand. The rule is being ignored, worked around, or the friction recurs → that is improvement-theater surfacing late: propose the rule's *removal* or revision. A loop that only ever adds guidance becomes the rot it was built to prevent; this step is what lets it subtract.
+
+Rejected proposals get a brief one-line note under "Rejected (recent)" so the same idea does not get re-proposed by a future session.
+
+## Proposed Local Improvements
+
+<!--
+Format:
+### YYYY-MM-DD — Short title
+
+**Trigger:** the friction point or pattern that motivated this proposal. Be specific.
+**Proposed change:** exact edit (which doc, what wording).
+**Workflow impact:** what would change for next session if this lands.
+**Tier:** small / medium / large (rough effort to write up).
+-->
+
+(none yet)
+
+## Proposed Template Promotions
+
+<!--
+Format:
+### YYYY-MM-DD — Short title
+
+**Project pattern:** the project-local doc/section that has proved its worth.
+**Track record:** what specifically demonstrated the pattern works (sessions / commits / measurable improvement).
+**Proposed promotion:** exact edit to the framework template (file path under `the framework's canonical templates/`).
+**Generality check:** would another project (different domain) benefit from this without modification?
+-->
+
+(none yet)
+
+## Applied (recent)
+
+<!--
+Once a proposal is approved and the canonical doc is edited + CHANGELOG entry added, move the entry here briefly. Trim on the next cleanup pass once CHANGELOG covers it.
+
+### YYYY-MM-DD — Short title (applied)
+**Friction it killed:** the specific friction this change was meant to remove (carried over from the proposal's Trigger).
+**Verify by:** the next session that touches <area/doc> — confirm the friction is gone (let it stand) or recurring (re-propose removal/revision per Lifecycle step 5).
+Brief note + CHANGELOG date reference.
+-->
+
+(none yet)
+
+## Rejected (recent)
+
+<!--
+Brief note so future agents don't re-propose the same idea.
+
+### YYYY-MM-DD — Short title (rejected)
+One-line reason the user rejected.
+-->
+
+(none yet)

package/templates/PROJECT_CONTEXT.md

@@ -0,0 +1,91 @@
+# Project Context
+
+Update this document when product direction, user audience, design language, runtime shape, constraints, or non-obvious intent changes.
+
+## Elevator Pitch
+
+One paragraph. What this is, who it serves, what problem it solves. The hook a future contributor reads first.
+
+## What This Project Is
+
+*One paragraph: what it is, who it serves, what problem it solves. Expand on the elevator pitch above with one level more detail. Not a feature list — that lives in CHANGELOG and the cold-path docs.*
+
+Describe the product, application, library, or system.
+
+## Runtime Shape
+
+*High-level system overview. Point readers at deeper docs (`ARCHITECTURE.md`, `DATA_MODEL.md`, `API_REFERENCE.md`) rather than restating their content.*
+
+- Frontend / client surface: (web app, CLI, library, mobile, embedded — or "n/a")
+- Backend / server: (Express on Railway, serverless functions, none)
+- Persistence: (Postgres, SQLite file, no persistent state)
+- Build step: (yes / no — keeps setup expectations clear)
+
+Delete or rename rows that don't apply. A pure-source library may have only a "Build step" row.
+
+## Goals
+
+*Outcomes the project aims to achieve, not features it ships.*
+
+- Goal 1
+- Goal 2
+- Goal 3
+
+## Users / Audience
+
+*Personas and their needs. Not feature lists.*
+
+Describe who uses this and what they need.
+
+## Product Principles
+
+*The "feel" or quality bar. What good looks like.*
+
+- Principle 1
+- Principle 2
+
+## Design / UX Direction
+
+*Visual language, interaction patterns, tone, and accessibility requirements. Libraries / CLIs may rename this section to "API Surface Style" (naming conventions, error message tone, output format) or delete it if the project has no UI.*
+
+Describe visual language, interaction patterns, tone, and accessibility requirements.
+
+## Important Constraints
+
+*Limits the project must respect. Sub-categorize when the list grows:*
+
+### Technical
+- Constraint.
+
+### Regulatory / Compliance
+- Constraint.
+
+### Resource (time, budget, team size)
+- Constraint.
+
+(Drop sub-categories if a flat list of 2–4 items is enough.)
+
+## Non-Goals
+
+*What this project explicitly does NOT do. Prevents scope creep and clarifies the project's edges.*
+
+- Non-goal 1
+- Non-goal 2
+
+## Known Open Questions
+
+*Decisions deferred, ambiguity worth surfacing. Resolve over time; once resolved, the answer lands in `DECISIONS.md`.*
+
+- Question 1
+- Question 2
+
+## Related Documents
+
+This file is meant to be a thin index, not a deep reference. For specifics:
+
+- Persistence and data shape: `docs/DATA_MODEL.md`
+- API endpoints / public surface: `docs/API_REFERENCE.md`
+- Runtime architecture: `docs/ARCHITECTURE.md`
+- Deployment + operations: `docs/DEPLOYMENT.md`
+- Decision history: `docs/DECISIONS.md`
+- Long-term planning: `docs/ROADMAP.md`