modern-python · lesnik512 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -98,26 +98,15 @@ class MyGroup(Group):
 
 ## Workflow
 
-Planning follows a portable two-axis convention (shared with
-`faststream-outbox`); full details in [`planning/README.md`](planning/README.md).
-
-- **`architecture/`** (repo root) is the **truth home** — living capability
-  prose, the promotion target on every ship. The `## Architecture` section
-  above is quick orientation; `architecture/` holds the authoritative,
-  up-to-date account.
-- **`planning/changes/<YYYY-MM-DD.NN-slug>/`** are change
-  bundles: `design.md` + `plan.md` (full lane), or `change.md` (lightweight).
-  Tiny changes (typo, dep bump, CI tweak) skip bundles entirely.
-- **`planning/decisions/<YYYY-MM-DD>-<slug>.md`** — when something is decided
-  *not* to be done (a rejected option with a load-bearing reason), record it
-  here, one file each with a revisit trigger, so it isn't re-litigated; listed
-  by `just index`. (`deferred.md` is the flat backlog of real-but-unscheduled
-  work.)
-- Templates live in [`planning/_templates/`](planning/_templates/).
-- **Shipping a change** hand-edits the affected
-  `architecture/<capability>.md` and sets `status: shipped` + `pr:` +
-  `outcome:` **in the implementing PR** — there is no folder move. The
-  change listing is generated: run `just index`.
+Planning uses a portable two-axis convention — `architecture/` (repo root) is
+the living **truth home** and promotion target; `planning/changes/` holds the
+per-change bundles. **Start at the
+[Quick path](planning/README.md#quick-path-start-here)** in
+`planning/README.md` to choose a lane, create a bundle, and ship — that file
+is the authoritative spec. Run `just check-planning` to validate bundles and
+`just index` to print the change listing. The `## Architecture` section above
+is quick orientation; `architecture/` holds the authoritative account.
+
 - **Cutting a release (maintainers)** is tag-driven via
   [`.github/workflows/release.yml`](.github/workflows/release.yml): write the
   notes at `planning/releases/<version>.md` (used verbatim as the GitHub Release

diff --git a/Justfile b/Justfile
@@ -15,6 +15,7 @@ lint-ci:
     uv run ruff format --check
     uv run ruff check --no-fix
     uv run ty check
+    uv run python planning/index.py --check
 
 test *args:
     uv run --no-sync pytest {{ args }}
@@ -41,3 +42,7 @@ docs-build:
 # Print the planning change index (grouped by status) to stdout.
 index:
     uv run python planning/index.py
+
+# Validate planning bundles + decisions (frontmatter, lanes, spec links); CI runs this.
+check-planning:
+    uv run python planning/index.py --check
diff --git a/planning/README.md b/planning/README.md
@@ -4,6 +4,35 @@ Specs, plans, and change history for `modern-di`. 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`, fill `outcome:` in
+the bundle frontmatter, and run `just check-planning` before pushing.
+
 ## Conventions
 
 > This section is the portable convention — identical across the
@@ -33,8 +62,8 @@ A change is a folder `changes/YYYY-MM-DD.NN-<slug>/`:
 - `<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/`
+one-liner). The implementing PR fills `outcome`
+**in the branch**, alongside the code and the `architecture/`
 promotion — no post-merge bookkeeping, no folder move.
 
 ### Three lanes
@@ -66,18 +95,21 @@ 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.
+`design.md` / `change.md`: `date`, `slug`, `summary` (single line), `outcome`.
+`plan.md`: `date`, `slug`, `spec`. `decisions/*.md`: `status`
+(accepted|superseded), `date`, `slug`, `summary`, `supersedes`, `superseded_by`.
+Files in `architecture/` carry **no** frontmatter — living prose, dated by git.
+
+**`outcome`** is filled at ship time: one line, ~1–3 sentences (≤ ~300 chars),
+stating the realized result — what shipped and its effect (deviations from the
+plan included), written so a future reader grasps the consequence without
+opening the diff. It is distinct from `summary`, which is the pre-ship intent
+one-liner.
 
 ## 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
+changes then decisions, newest first. The frontmatter in each bundle / decision file is the
 single source of truth; there is no committed copy to drift.
 
 ## Other

diff --git a/planning/_templates/change.md b/planning/_templates/change.md
@@ -1,12 +1,8 @@
 ---
-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
+outcome: Realized result — filled at ship time (~1–3 sentences); see README "Frontmatter".
 ---
 
 # Change: One-line capitalized title

diff --git a/planning/_templates/decision.md b/planning/_templates/decision.md
@@ -5,7 +5,6 @@ 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

diff --git a/planning/_templates/design.md b/planning/_templates/design.md
@@ -1,12 +1,8 @@
 ---
-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
+outcome: Realized result — filled at ship time (~1–3 sentences); see README "Frontmatter".
 ---
 
 # Design: One-line capitalized title

diff --git a/planning/_templates/plan.md b/planning/_templates/plan.md
@@ -1,9 +1,7 @@
 ---
-status: draft
 date: YYYY-MM-DD
 slug: my-change
-spec: my-change
-pr: null
+spec: design.md
 ---
 
 # <slug> — implementation plan

diff --git a/planning/changes/2026-06-05.01-bug-hunt-audit/design.md b/planning/changes/2026-06-05.01-bug-hunt-audit/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-05
 slug: bug-hunt-audit
 summary: Four-dimension bug-hunt audit harness and report; 18 findings actioned in 2.15.0.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: Four-dimension bug-hunt audit harness; report in audits/2026-06-05-bug-hunt-audit-report.md; 18 findings actioned in 2.15.0 (#188–#197).
 ---
 

diff --git a/planning/changes/2026-06-05.01-bug-hunt-audit/plan.md b/planning/changes/2026-06-05.01-bug-hunt-audit/plan.md
@@ -1,9 +1,7 @@
 ---
-status: shipped
 date: 2026-06-05
 slug: bug-hunt-audit
 spec: design.md
-pr: null
 ---
 
 # Bug-Hunt Audit Implementation Plan

diff --git a/planning/changes/2026-06-05.02-singleton-rlock/design.md b/planning/changes/2026-06-05.02-singleton-rlock/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-05
 slug: singleton-rlock
 summary: RLock-guarded singleton creation to eliminate re-entrant deadlock; shipped in 2.15.0.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: RLock guards singleton creation; shipped in 2.15.0.
 ---
 

diff --git a/planning/changes/2026-06-05.02-singleton-rlock/plan.md b/planning/changes/2026-06-05.02-singleton-rlock/plan.md
@@ -1,9 +1,7 @@
 ---
-status: shipped
 date: 2026-06-05
 slug: singleton-rlock
 spec: design.md
-pr: null
 ---
 
 # Singleton RLock Fix Implementation Plan

diff --git a/planning/changes/2026-06-05.03-validate-rework/design.md b/planning/changes/2026-06-05.03-validate-rework/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-05
 slug: validate-rework
 summary: Reworked validate() for transitive cycle/scope checks; shipped in 2.15.0.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: validate() reworked for transitive cycle/scope checks; shipped in 2.15.0.
 ---
 

diff --git a/planning/changes/2026-06-05.03-validate-rework/plan.md b/planning/changes/2026-06-05.03-validate-rework/plan.md
@@ -1,9 +1,7 @@
 ---
-status: shipped
 date: 2026-06-05
 slug: validate-rework
 spec: design.md
-pr: null
 ---
 
 # `Container.validate()` Rework Implementation Plan

diff --git a/planning/changes/2026-06-07.01-mkdocs-github-pages-migration/design.md b/planning/changes/2026-06-07.01-mkdocs-github-pages-migration/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-07
 slug: mkdocs-github-pages-migration
 summary: Docs hosting moved to GitHub Pages at modern-di.modern-python.org.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: Docs hosting moved to GitHub Pages at modern-di.modern-python.org.
 ---
 

diff --git a/planning/changes/2026-06-07.01-mkdocs-github-pages-migration/plan.md b/planning/changes/2026-06-07.01-mkdocs-github-pages-migration/plan.md
@@ -1,9 +1,7 @@
 ---
-status: shipped
 date: 2026-06-07
 slug: mkdocs-github-pages-migration
 spec: design.md
-pr: null
 ---
 
 # MkDocs to GitHub Pages Migration Implementation Plan

diff --git a/planning/changes/2026-06-08.01-scheduled-dep-check/design.md b/planning/changes/2026-06-08.01-scheduled-dep-check/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-08
 slug: scheduled-dep-check
 summary: Weekly scheduled dependency-check GitHub Actions workflow.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: Weekly scheduled dependency-check workflow (.github/workflows/scheduled.yml).
 ---
 

diff --git a/planning/changes/2026-06-08.01-scheduled-dep-check/plan.md b/planning/changes/2026-06-08.01-scheduled-dep-check/plan.md
@@ -1,9 +1,7 @@
 ---
-status: shipped
 date: 2026-06-08
 slug: scheduled-dep-check
 spec: design.md
-pr: null
 ---
 
 # Scheduled Dependency-Breakage Check Implementation Plan

diff --git a/planning/changes/2026-06-09.01-docs-improvements/design.md b/planning/changes/2026-06-09.01-docs-improvements/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-09
 slug: docs-improvements
 summary: Docs-site improvements: recipes section, concept pages, refreshed Quick Start.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: Docs-site improvements shipped.
 ---
 

diff --git a/planning/changes/2026-06-09.02-migration-guide-from-that-depends/design.md b/planning/changes/2026-06-09.02-migration-guide-from-that-depends/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-09
 slug: migration-guide-from-that-depends
 summary: Migration guide from that-depends covering all provider types and conceptual shifts.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: docs/migration/from-that-depends.md published.
 ---
 

diff --git a/planning/changes/2026-06-12.01-code-docs-audit/design.md b/planning/changes/2026-06-12.01-code-docs-audit/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-12
 slug: code-docs-audit
 summary: Full code+docs audit harness; produced the 57-finding report.
-supersedes: null
-superseded_by: null
-pr: null
 outcome: Full code+docs audit harness; produced the 57-finding report in audits/2026-06-12-code-docs-audit-report.md.
 ---
 

diff --git a/planning/changes/2026-06-12.01-code-docs-audit/plan.md b/planning/changes/2026-06-12.01-code-docs-audit/plan.md
@@ -1,9 +1,7 @@
 ---
-status: shipped
 date: 2026-06-12
 slug: code-docs-audit
 spec: design.md
-pr: null
 ---
 
 # Code & Docs Audit Implementation Plan

diff --git a/planning/changes/2026-06-12.02-audit-fixes/change.md b/planning/changes/2026-06-12.02-audit-fixes/change.md
@@ -1,10 +1,9 @@
 ---
-status: shipped
 date: 2026-06-12
 slug: audit-fixes
 summary: First batch of code+docs audit fixes. Plan-only; spec = the audit report.
 spec: ../../../audits/2026-06-12-code-docs-audit-report.md
-pr: "202"
+outcome: Fixed bugs B-1..B-11/X-1, dead code Q-2..Q-4, pinning tests Q-10..Q-15, and doc drift D-3/D-6..D-14 from the 2026-06-12 code+docs audit; shipped in PR #202.
 ---
 
 # Audit Fixes Implementation Plan

diff --git a/planning/changes/2026-06-13.01-audit-fixes-round2/change.md b/planning/changes/2026-06-13.01-audit-fixes-round2/change.md
@@ -1,10 +1,9 @@
 ---
-status: shipped
 date: 2026-06-13
 slug: audit-fixes-round2
 summary: Round-2 fixes for the 21 deferred code+docs audit findings. Plan-only; spec = the audit report.
 spec: ../../../audits/2026-06-12-code-docs-audit-report.md
-pr: "203"
+outcome: Fixed 21 deferred code+docs audit findings (Q-1/Q-5/Q-9/X-2..X-5, Q-6..Q-8/X-6, D-2/D-4/D-5/G-1..G-11) including None-injection and coverage-gate move; shipped in PR #203.
 ---
 
 # Audit Fixes — Round 2 Implementation Plan

diff --git a/planning/changes/2026-06-13.01-docs-ux-audit/design.md b/planning/changes/2026-06-13.01-docs-ux-audit/design.md
@@ -1,11 +1,7 @@
 ---
-status: shipped
 date: 2026-06-13
 slug: docs-ux-audit
 summary: Reader-experience audit producing a 70-finding report (16 Medium, 54 Low).
-supersedes: null
-superseded_by: null
-pr: 212
 outcome: Produced the 70-finding reader-experience report (0 High, 16 Medium, 54 Low) in audits/2026-06-13-docs-ux-audit-report.md. All 16 Mediums fixed in PR #212; 54 Lows catalogued for later.
 ---
 

diff --git a/planning/changes/2026-06-13.01-docs-ux-audit/plan.md b/planning/changes/2026-06-13.01-docs-ux-audit/plan.md
@@ -1,7 +1,7 @@
 ---
-status: shipped
 date: 2026-06-13
 slug: docs-ux-audit
+spec: design.md
 ---
 
 # Plan: Docs UX & Consistency Audit

diff --git a/planning/changes/2026-06-13.02-alias-scope-transparency/change.md b/planning/changes/2026-06-13.02-alias-scope-transparency/change.md
@@ -1,10 +1,9 @@
 ---
-status: shipped
 date: 2026-06-13
 slug: alias-scope-transparency
 summary: Deprecate decorative `Alias(scope=...)`; `validate()` checks scope transitively via `effective_scope` (X-4). Plan-only; spec = the code-docs audit report.
 spec: ../../../audits/2026-06-12-code-docs-audit-report.md
-pr: "207"
+outcome: validate() now checks scope transitively via effective_scope through aliases (X-4); decorative Alias(scope=) deprecated; enforces_dependency_scope stopgap retired; shipped as 2.17.0 in PR #207.
 ---
 
 # Alias Scope Transparency (X-4) Implementation Plan