modern-python · lesnik512 · Jun 25, 2026 · Jun 25, 2026
diff --git a/planning/README.md b/planning/README.md
@@ -30,8 +30,8 @@ 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.
+`architecture/<capability>.md`, finalize the bundle's `summary:` to the
+realized result, and run `just check-planning` before pushing.
 
 ## Conventions
 
@@ -62,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 fills `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
 
@@ -96,16 +97,18 @@ Templates live in [`_templates/`](_templates/).
 
 ### Frontmatter
 
-`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.
+`date` and `slug` are **derived from the directory / file name** — never
+repeated in frontmatter. So:
 
-**`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.
+- `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
 

diff --git a/planning/_templates/change.md b/planning/_templates/change.md
@@ -1,8 +1,5 @@
 ---
-date: YYYY-MM-DD
-slug: my-change
-summary: One line — shown in the generated index. Fill at ship time.
-outcome: Realized result — filled at ship time (~1–3 sentences); see README "Frontmatter".
+summary: One line — shown in the generated index. Written at creation; finalize at ship to state the realized result.
 ---
 
 # Change: One-line capitalized title

diff --git a/planning/_templates/decision.md b/planning/_templates/decision.md
@@ -1,7 +1,5 @@
 ---
 status: accepted        # accepted | superseded
-date: YYYY-MM-DD
-slug: my-decision
 summary: One line — shown in `just index`.
 supersedes: null
 superseded_by: null

diff --git a/planning/_templates/design.md b/planning/_templates/design.md
@@ -1,8 +1,5 @@
 ---
-date: YYYY-MM-DD
-slug: my-change
-summary: One line — shown in the generated index. Fill at ship time.
-outcome: Realized result — filled at ship time (~1–3 sentences); see README "Frontmatter".
+summary: One line — shown in the generated index. Written at creation; finalize at ship to state the realized result.
 ---
 
 # Design: One-line capitalized title

diff --git a/planning/_templates/plan.md b/planning/_templates/plan.md
@@ -1,9 +1,3 @@
----
-date: YYYY-MM-DD
-slug: my-change
-spec: design.md
----
-
 # <slug> — implementation plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use
@@ -44,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>"
   ```
 
 ---

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,8 +1,5 @@
 ---
-date: 2026-06-05
-slug: bug-hunt-audit
 summary: Four-dimension bug-hunt audit harness and report; 18 findings actioned in 2.15.0.
-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).
 ---
 
 # Bug-Hunt Audit — Design

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,3 @@
----
-date: 2026-06-05
-slug: bug-hunt-audit
-spec: design.md
----
-
 # Bug-Hunt Audit 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.

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,8 +1,5 @@
 ---
-date: 2026-06-05
-slug: singleton-rlock
 summary: RLock-guarded singleton creation to eliminate re-entrant deadlock; shipped in 2.15.0.
-outcome: RLock guards singleton creation; shipped in 2.15.0.
 ---
 
 # Singleton Re-Entrant Lock Fix — Design

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,3 @@
----
-date: 2026-06-05
-slug: singleton-rlock
-spec: design.md
----
-
 # Singleton RLock Fix 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.

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,8 +1,5 @@
 ---
-date: 2026-06-05
-slug: validate-rework
 summary: Reworked validate() for transitive cycle/scope checks; shipped in 2.15.0.
-outcome: validate() reworked for transitive cycle/scope checks; shipped in 2.15.0.
 ---
 
 # `Container.validate()` Rework — Design

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,3 @@
----
-date: 2026-06-05
-slug: validate-rework
-spec: design.md
----
-
 # `Container.validate()` Rework 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.

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,8 +1,5 @@
 ---
-date: 2026-06-07
-slug: mkdocs-github-pages-migration
 summary: Docs hosting moved to GitHub Pages at modern-di.modern-python.org.
-outcome: Docs hosting moved to GitHub Pages at modern-di.modern-python.org.
 ---
 
 # Migrate docs from Read the Docs to GitHub Pages

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,3 @@
----
-date: 2026-06-07
-slug: mkdocs-github-pages-migration
-spec: design.md
----
-
 # MkDocs to GitHub Pages Migration 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.

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,8 +1,5 @@
 ---
-date: 2026-06-08
-slug: scheduled-dep-check
 summary: Weekly scheduled dependency-check GitHub Actions workflow.
-outcome: Weekly scheduled dependency-check workflow (.github/workflows/scheduled.yml).
 ---
 
 # Scheduled dependency-breakage check

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,3 @@
----
-date: 2026-06-08
-slug: scheduled-dep-check
-spec: design.md
----
-
 # Scheduled Dependency-Breakage Check 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.

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,8 +1,5 @@
 ---
-date: 2026-06-09
-slug: docs-improvements
 summary: Docs-site improvements: recipes section, concept pages, refreshed Quick Start.
-outcome: Docs-site improvements shipped.
 ---
 
 # Spec: Docs improvements — recipes + concept pages

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,8 +1,5 @@
 ---
-date: 2026-06-09
-slug: migration-guide-from-that-depends
 summary: Migration guide from that-depends covering all provider types and conceptual shifts.
-outcome: docs/migration/from-that-depends.md published.
 ---
 
 # Spec: Rewrite `from-that-depends.md` migration guide

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,8 +1,5 @@
 ---
-date: 2026-06-12
-slug: code-docs-audit
 summary: Full code+docs audit harness; produced the 57-finding report.
-outcome: Full code+docs audit harness; produced the 57-finding report in audits/2026-06-12-code-docs-audit-report.md.
 ---
 
 # Code & Docs Audit — Design

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,3 @@
----
-date: 2026-06-12
-slug: code-docs-audit
-spec: design.md
----
-
 # Code & Docs Audit 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.

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,9 +1,5 @@
 ---
-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
-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,9 +1,5 @@
 ---
-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
-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,8 +1,5 @@
 ---
-date: 2026-06-13
-slug: docs-ux-audit
 summary: Reader-experience audit producing a 70-finding report (16 Medium, 54 Low).
-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.
 ---
 
 # Design: Docs UX & Consistency Audit

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,9 +1,3 @@
----
-date: 2026-06-13
-slug: docs-ux-audit
-spec: design.md
----
-
 # Plan: Docs UX & Consistency Audit
 
 Execution is a single multi-agent workflow (`Workflow` tool). This plan records

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,9 +1,5 @@
 ---
-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
-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

diff --git a/planning/changes/2026-06-13.02-docs-ux-fixes/design.md b/planning/changes/2026-06-13.02-docs-ux-fixes/design.md
@@ -1,8 +1,5 @@
 ---
-date: 2026-06-13
-slug: docs-ux-fixes
 summary: Fixed all 16 Medium findings from the docs UX audit (runnable examples, accuracy, nav).
-outcome: All 16 Medium findings fixed and merged in PR #212 (#11b7b70). mkdocs --strict green; runnable snippets verified; O-5/O-6 confirmed against sibling repos. Architecture pages (scopes.md, providers.md) hand-edited as part of the fixes.
 ---
 
 # Design: Docs UX fixes (all 16 Medium audit findings)

diff --git a/planning/changes/2026-06-13.02-docs-ux-fixes/plan.md b/planning/changes/2026-06-13.02-docs-ux-fixes/plan.md
@@ -1,9 +1,3 @@
----
-date: 2026-06-13
-slug: docs-ux-fixes
-spec: design.md
----
-
 # Docs UX Fixes 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.

diff --git a/planning/changes/2026-06-13.03-portable-planning-convention/design.md b/planning/changes/2026-06-13.03-portable-planning-convention/design.md
@@ -1,8 +1,5 @@
 ---
-date: 2026-06-13
-slug: portable-planning-convention
 summary: Adopted the two-axis planning convention (architecture/ truth + changes/ bundles) from faststream-outbox.
-outcome: Adopted the two-axis convention — architecture/ truth home (README + 6 capability docs) + planning/changes/{active,archive}/ bundles; migrated 11 historical spec/plan pairs into archive bundles; added portable README, _templates/, CLAUDE.md Workflow. Also aligned CLAUDE.md Architecture with the code.
 ---
 
 # Design: Adopt the portable planning convention

diff --git a/planning/changes/2026-06-14.01-docs-ux-lows/change.md b/planning/changes/2026-06-14.01-docs-ux-lows/change.md
@@ -1,8 +1,5 @@
 ---
-date: 2026-06-14
-slug: docs-ux-lows
 summary: Fixed all 53 Low findings from the docs UX audit (cross-links, imports, terminology, docstrings).
-outcome: All 53 Low findings fixed and merged in PR #213 (b81c23f). mkdocs --strict green, lint clean, 199 tests / 100% coverage. D-10 was already resolved by X-3 (#212); R-2/D-24 already satisfied there. Executed via parallel file-scoped subagents + central verification.
 ---
 
 # Change: Docs UX audit — fix the 53 Low findings

diff --git a/planning/changes/2026-06-14.02-set-context-cross-scope-staleness/design.md b/planning/changes/2026-06-14.02-set-context-cross-scope-staleness/design.md
@@ -1,11 +1,5 @@
 ---
-date: 2026-06-14
-slug: set-context-cross-scope-staleness
 summary: Resolve ContextProvider params live so late set_context always propagates across scopes.
-outcome: Shipped. ContextProvider values now resolve live on every resolve;
-  invalidate_compiled_kwargs deleted (net simplification). Late set_context
-  propagates across scopes for non-cached factories; cached-singleton limitation
-  documented. 205 tests, 100% coverage.
 ---
 
 # Design: Resolve context values live so late `set_context` always propagates

diff --git a/planning/changes/2026-06-14.02-set-context-cross-scope-staleness/plan.md b/planning/changes/2026-06-14.02-set-context-cross-scope-staleness/plan.md
@@ -1,9 +1,3 @@
----
-date: 2026-06-14
-slug: set-context-cross-scope-staleness
-spec: design.md
----
-
 # set-context-cross-scope-staleness — implementation plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use

diff --git a/planning/changes/2026-06-14.03-audit-doc-rulings-batch1/change.md b/planning/changes/2026-06-14.03-audit-doc-rulings-batch1/change.md
@@ -1,9 +1,5 @@
 ---
-date: 2026-06-14
-slug: audit-doc-rulings-batch1
 summary: Action batch-1 rulings from the 2026-06-14 deep audit (B-4 pin, B-5/S-1/S-2 doc notes, A-1 comment + nogil caveat; A-2 closed). Doc/test/comment-only. Plan-only; spec = the audit report.
-spec: ../../../audits/2026-06-14-deep-audit-report.md
-outcome: Actioned batch-1 doc/test/comment rulings from 2026-06-14 deep audit (B-4 pin, B-5/S-1/S-2 doc notes, A-1 comment + nogil caveat; A-2 closed with no action); shipped in PR #217.
 ---
 
 # audit-doc-rulings-batch1 — implementation plan

diff --git a/planning/changes/2026-06-14.04-audit-fixes-batch2/change.md b/planning/changes/2026-06-14.04-audit-fixes-batch2/change.md
@@ -1,9 +1,5 @@
 ---
-date: 2026-06-14
-slug: audit-fixes-batch2
 summary: B-3 (gapped custom-enum child-scope derivation) + P-1 (drop the per-resolve throwaway `CacheItem` alloc via a `get` fast path, keeping atomic `setdefault` on creation). Plan-only; spec = the audit report.
-spec: ../../../audits/2026-06-14-deep-audit-report.md
-outcome: Fixed B-3 (gapped custom-enum child-scope derivation) and P-1 (eliminate per-resolve throwaway CacheItem alloc via get fast path) from 2026-06-14 deep audit; shipped in PR #218.
 ---
 
 # audit-fixes-batch2 — implementation plan

diff --git a/planning/changes/2026-06-14.05-audit-fixes-batch3/change.md b/planning/changes/2026-06-14.05-audit-fixes-batch3/change.md
@@ -1,9 +1,5 @@
 ---
-date: 2026-06-14
-slug: audit-fixes-batch3
 summary: R-1 (`AbstractProvider.display_name` dedupes the bound-type-or-repr idiom across ~5 sites) + R-2 minimal (public `fetch_context_value`, drop the `SLF001` reach-in). Plan-only; spec = the audit report.
-spec: ../../../audits/2026-06-14-deep-audit-report.md
-outcome: Added AbstractProvider.display_name deduping R-1 (~5 sites) and public fetch_context_value dropping the SLF001 reach-in (R-2) from 2026-06-14 deep audit; shipped in PR #219.
 ---
 
 # audit-fixes-batch3 — implementation plan

diff --git a/planning/changes/2026-06-14.06-audit-fixes-batch4-5/change.md b/planning/changes/2026-06-14.06-audit-fixes-batch4-5/change.md
@@ -1,9 +1,5 @@
 ---
-date: 2026-06-14
-slug: audit-fixes-batch4-5
 summary: Final audit cleanup: test hardening (P-6 compile-once pin, R-3 behavioral singleton assert, X-2 structured suggestion/path asserts) + DX/docs (X-3 exception docstrings, X-4 `exceptions` export, X-5 `ResolutionStep` docs). Closes every actionable finding. Plan-only; spec = audit report.
-spec: ../../../audits/2026-06-14-deep-audit-report.md
-outcome: Closed every actionable 2026-06-14 audit finding (P-6/R-3/X-2 test hardening; X-3/X-4/X-5 DX/docs); only won't-fix R-4/R-5/R-6 and the A-1 nogil follow-up remain.
 ---
 
 # audit-fixes-batch4-5 — implementation plan