chore: adopt canonical planning convention

Vendor index.py + _templates/ verbatim from lesnik512/planning-convention
(v1.0.0), slim every bundle's frontmatter to the lean form (summary-only
specs; plans carry none; date/slug derived from the dir/file name), rewrite
planning/README.md to the canonical Quick-path + Conventions prose, wire the
planning validator into just lint-ci, add a check-planning recipe, record the
applied version in planning/.convention-version.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lesnik512

Justfile

@@ -15,11 +15,16 @@ lint-ci:
     uv run ruff format --check
     uv run ruff check --no-fix
     uv run ty check
+    uv run python planning/index.py --check
 
-# Print the planning change index (grouped by status) to stdout.
+# Print the planning change index (flat, newest-first) to stdout.
 index:
     uv run python planning/index.py
 
+# Validate planning bundles + decisions; CI runs this via lint-ci.
+check-planning:
+    uv run python planning/index.py --check
+
 test *args:
     uv run --no-sync pytest {{ args }}
 

planning/.convention-version

@@ -0,0 +1 @@
+1.0.0

planning/README.md

@@ -4,12 +4,42 @@ Specs, plans, and change history for `httpware`. The living truth about
 *what the system does now* lives in [`architecture/`](../architecture/) at
 the repo root; this directory records *how it got there*.
 
+## Quick path (start here)
+
+> The fast lane for making a change. The full reference is in
+> [Conventions](#conventions) below — read it only when this isn't enough.
+
+**1. Choose a lane — first matching rule wins:**
+
+1. Any of: needs design judgment · new file/module · public-API change ·
+   cross-cutting or multi-file · non-trivial test design → **Full**
+   (`design.md` + `plan.md`)
+2. Purely mechanical: typo · dep bump · linter/formatter/CI tweak ·
+   mechanical rename · single-line config → **Tiny** (no bundle, conventional
+   commit)
+3. Small-but-real, none of the above: ≲30 LOC net · ≤2 files · no new file ·
+   no public-API change · one straightforward test → **Lightweight**
+   (`change.md`)
+
+Ambiguous between two? Take the heavier. A `change.md` that outgrows its lane
+splits into `design.md` + `plan.md`.
+
+**2. Create the bundle** (Full / Lightweight only):
+`planning/changes/YYYY-MM-DD.NN-<slug>/`, where `.NN` is a zero-padded
+intra-day counter. Copy the matching template from
+[`_templates/`](_templates/).
+
+**3. Ship in the implementing PR:** hand-edit the affected
+`architecture/<capability>.md`, finalize the bundle's `summary:` to the
+realized result, and run `just check-planning` before pushing.
+
 ## Conventions
 
-> This section is the portable convention — identical across the
-> modern-python repos. The generated change listing (`just index`) and the `## Other` pointers below are repo-local. To adopt elsewhere,
-> copy this section plus [`_templates/`](_templates/) and point that repo's
-> `CLAUDE.md` Workflow + truth home at it.
+> This is the portable convention, sourced from the canonical repo
+> [`lesnik512/planning-convention`](https://github.com/lesnik512/planning-convention)
+> (applied version in [`.convention-version`](.convention-version)). To update
+> it, run that repo's `APPLY.md` flow. The generated change index (`just index`)
+> and the `## Other` pointers below are repo-local.
 
 ### Two axes, never mixed
 
@@ -32,10 +62,11 @@ A change is a folder `changes/YYYY-MM-DD.NN-<slug>/`:
   (`.01`, `.02`, …) that breaks same-date ties so the timeline sorts stably.
 - `<slug>` — kebab-case description, not a story ID.
 
-`summary` is written when the change is created (it is the change's
-one-liner). The implementing PR then sets `status: shipped` and fills `pr`
-and `outcome` **in the branch**, alongside the code and the `architecture/`
-promotion — no post-merge bookkeeping, no folder move.
+`summary` is written when the change is created (the intent one-liner) and
+**finalized at ship** to state the realized result — set in the implementing
+PR, alongside the code and the `architecture/` promotion. No post-merge
+bookkeeping, no folder move. `date` and `slug` are never written — they are
+read from the bundle's directory name.
 
 ### Three lanes
 
@@ -53,32 +84,38 @@ into `design.md` + `plan.md`.
 - **`design.md`** — the spec: the *thinking* (why, design, trade-offs, scope).
 - **`plan.md`** — the plan: the *sequencing* (the executor's task checklist).
 - **`change.md`** — both, condensed, for the lightweight lane.
-- **`decisions/<YYYY-MM-DD>-<slug>.md`** — one file per design decision taken
-  (especially options *rejected*), each with a revisit trigger, so reviews don't
-  re-litigate them; listed by `just index`.
 - **`releases/<semver>.md`** — per-release user-facing notes.
 - **`audits/<date>-<slug>.md`** — findings from a code/docs/bug-hunt sweep;
   spawns fix changes.
 - **`retros/<date>-<slug>.md`** — what we learned after a body of work.
 - **`deferred.md`** — real-but-unscheduled items, each with a revisit trigger.
+- **`decisions/<YYYY-MM-DD>-<slug>.md`** — one file per design decision taken
+  (especially options *rejected*), each with a revisit trigger; listed by
+  `just index`.
 
 Templates live in [`_templates/`](_templates/).
 
 ### Frontmatter
 
-`design.md` / `change.md`: `status` (draft|approved|shipped|superseded),
-`date`, `slug`, `summary` (single line), `supersedes`, `superseded_by`, `pr`,
-`outcome`. `plan.md`: `status`, `date`, `slug`, `spec`, `pr`.
-`decisions/*.md`: `status` (accepted|superseded), `date`, `slug`, `summary`,
-`supersedes`, `superseded_by`, `pr`.
-Files in `architecture/` carry **no** frontmatter — living prose, dated by git.
+`date` and `slug` are **derived from the directory / file name** — never
+repeated in frontmatter. So:
+
+- `design.md` / `change.md`: `summary` (single line) only.
+- `plan.md`: **no frontmatter** — its identity is the bundle directory.
+- `decisions/*.md`: `status` (accepted|superseded), `summary`, and optional
+  `supersedes` / `superseded_by`.
+- Files in `architecture/` carry **no** frontmatter — living prose, dated by git.
+
+**`summary`** is one line: written at creation as the intent, then **finalized
+at ship** to state the realized result — what shipped and its effect. It is the
+only field the index renders.
 
 ## Index
 
 The listing is **generated**, not maintained — run `just index` to print it:
-changes grouped by `status` (In progress / Shipped / Superseded), then
-decisions newest-first. The frontmatter in each bundle / decision file is the
-single source of truth; there is no committed copy to drift.
+changes as a flat newest-first list, then decisions newest-first. Each bundle's
+`summary` frontmatter (and the directory name, which supplies `date`/`slug`) is
+the single source of truth; there is no committed copy to drift.
 
 ## Other
 

planning/_templates/change.md

@@ -1,12 +1,5 @@
 ---
-status: draft
-date: YYYY-MM-DD
-slug: my-change
-summary: One line — shown in the generated index. Fill at ship time.
-supersedes: null
-superseded_by: null
-pr: null
-outcome: null
+summary: One line — shown in the generated index. Written at creation; finalize at ship to state the realized result.
 ---
 
 # Change: One-line capitalized title

planning/_templates/decision.md

@@ -1,11 +1,8 @@
 ---
 status: accepted        # accepted | superseded
-date: YYYY-MM-DD
-slug: my-decision
 summary: One line — shown in `just index`.
 supersedes: null
 superseded_by: null
-pr: null                # PR/commit where the decision was made or recorded
 ---
 
 # One-line capitalized title

planning/_templates/design.md

@@ -1,12 +1,5 @@
 ---
-status: draft
-date: YYYY-MM-DD
-slug: my-change
-summary: One line — shown in the generated index. Fill at ship time.
-supersedes: null
-superseded_by: null
-pr: null
-outcome: null
+summary: One line — shown in the generated index. Written at creation; finalize at ship to state the realized result.
 ---
 
 # Design: One-line capitalized title

planning/_templates/plan.md

@@ -1,11 +1,3 @@
----
-status: draft
-date: YYYY-MM-DD
-slug: my-change
-spec: my-change
-pr: null
----
-
 # <slug> — implementation plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use
@@ -46,9 +38,7 @@ in the spec.
 
   ```bash
   git add path/to/file.py
-  git commit -m "<type>: <subject>
-
-  Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
+  git commit -m "<type>: <subject>"
   ```
 
 ---

planning/_templates/release.md

@@ -0,0 +1,39 @@
+# modern-di <version> — <one-line headline>
+
+<One or two sentences: what this release is and its headline change. Say up
+front if there are no behavior/API changes.>
+
+<!-- Keep only the sections that apply; reorder/rename freely. A tiny release
+     may be just the title + one section. Versioning is tag-driven — the
+     release tag sets the version (`just publish` runs `uv version`), so there
+     is no pyproject bump. -->
+
+## Feature
+
+- **<name>.** What it adds and how to use it.
+
+## Fix
+
+- **<name>.** What was broken, now fixed (reference the issue/regression).
+
+## Internal refactors
+
+- **<name>.** What changed under the hood, stated as no behavior change.
+
+## Packaging
+
+- Metadata / build / dependency changes visible to installers.
+
+## Why
+
+Context a reader needs for the headline change. Omit for small releases.
+
+## Downstream
+
+What integrations (FastAPI, Litestar, FastStream, Typer, `modern-di-pytest`)
+must do — e.g. bump their `modern-di` floor — or "No action needed" when there
+is no API change.
+
+## Internals
+
+- Coverage / tooling notes (e.g. 100% line coverage across Python 3.10–3.14).

planning/changes/2026-05-31.01-bmad-to-superpowers-transition/design.md

@@ -1,12 +1,5 @@
 ---
-status: shipped
-date: 2026-05-31
-slug: bmad-to-superpowers-transition
 summary: Bootstrapped the planning workflow
-supersedes: null
-superseded_by: null
-pr: 6
-outcome: 'Bootstrapped the planning workflow'
 ---
 
 # bmad → superpowers transition (design)

planning/changes/2026-05-31.01-bmad-to-superpowers-transition/plan.md

@@ -1,11 +1,3 @@
----
-status: shipped
-date: 2026-05-31
-slug: bmad-to-superpowers-transition
-spec: bmad-to-superpowers-transition
-pr: 6
----
-
 # bmad → superpowers transition Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.