docs(changelog): bring ## [Unreleased] to Keep a Changelog conformance

[pbean]

Rewrites ## [Unreleased] to the shape the format actually specifies. 1193 → 835 lines, 149 → 124 entries, no user-facing fact lost.

The section had drifted into a flat list of multi-paragraph engineering narratives: each entry re-derived its own root cause, restated mechanism a reader cannot act on, and duplicated fixes already shipped in ## [0.9.1]. Keep a Changelog asks for something else — "for humans, not machines", a terse statement of what changed and why it matters to someone deciding whether to upgrade.

Scope: released sections are deliberately untouched

scripts/release.py pipes a released section's prose verbatim into the published GitHub release notes (release.py:417-437). Editing ## [0.9.1] or earlier would silently rewrite the body of a release that is already published, so every commit here is confined to ## [Unreleased]. The diff is one file.

Three passes

1. Subtractive (0007a33) — dedup, deflate, reference. No prose rewritten.

• Dropped bullets restating a ## [0.9.1] fix with no main-specific difference: five byte-identical subject leads plus eight near-identical pairs. Where the port needed a genuinely different fix the bullet stays and keeps the underlying issue number.
• Dropped eight internal-churn entries — test/CI/refactor bookkeeping outside Keep a Changelog's user-visible scope, two of which said so in their own text.
• Collapsed fragmented entries (forward-port the 0.9.1 hotfix (#405) to main #433: 11 bullets → 2; awaiting-operator: terminal state for stories owing human external actions #335: three parts → one; [BUG] validate and run blocked: bmm >=6.10.1 renamed the dev primitive to bmad-build-auto, leaving bmad-dev-auto a shim #393: two → one).
• Added 13 issue references, each traced with git log -S to the introducing commit. The 16 that stay unreferenced have no issue behind them — inventing a number would be worse.

2. Added / Changed / Removed (7c3a205) — 259 → 183 lines.

3. Fixed (94f8d8d) — 768 → 645 lines, 93 entries.

Passes 2 and 3 apply the same rule: bold subject lead, then a short statement of user-facing impact and why. Mechanism, root-cause narration and internals move back to the issues and docstrings.

Kept deliberately, because a reader acts on them: symptoms you would recognize having hit, config knobs, CLI flags, --json field names, journal and finding ids you would grep for, the CLEANUP_SCHEMA_VERSION bump, behavior changes and contributor credits. Dropped: private function names, code-level mechanism, and "why the old code did that".

Structural fixes worth calling out

• Wrapped bold leads. Nine leads (two in pass 2, seven in pass 3) broke across source lines, defeating the one scannable element in the entry. All unwrapped; two needed shortening to fit the column budget.
• The upgrade runbook moves. The provision_worktree's exclude patterns are repo-wide and permanent: new files under .claude/skills silently stop being staged in the main checkout #384 entry filed a nested procedure list under Fixed, and the only precedent for a standalone section is the non-standard ### Migration at [0.8.0]. Keep a Changelog specifies neither. The instruction now rides the entry it applies to — the git-add shield fix whose old behavior left the residue — in two sentences naming git rev-parse --git-path info/exclude and git check-ignore -v, pointing at provision_worktree's exclude patterns are repo-wide and permanent: new files under .claude/skills silently stop being staged in the main checkout #384 for the full account.
• Entries that stopped standing alone after the earlier merges and deletions: Ledger snapshot disarm is skipped when _rollback_or_pause raises anything but RunPaused #420's lead had lost the mechanism naming which snapshot, and Sprint board is read from the main repo but advanced in the worktree #350 carried a dangling "Without it _pick_next …" tail with no subject. Both given their antecedent.
• One restored fact. Pass 1 dropped the Enforce the git chokepoint invariant, and close the two remaining bypasses #390 chokepoint entry as internal churn, but it also carried a user-visible fact: a commit subject undecodable in the run's codec crashed the TUI's story-checkpoint modal. Verified against tui/app.py:855-873 and fd0d41f before restoring it as its own entry.
• Two restored cross-references lost in the rewrite: fix: preserve seed file modes + pause on verify env faults (rc 126/127) #130 (the charged-attempt regression Windows: verify env-fault classification never fires — cmd reports missing/non-executable tools as 9009/1, not 126/127 #302 left live on win32) and Codec except-tuple asymmetry in _append_diag_jsonl (and POSIX-only strictness in tmux_base) #380 (the decode half of Untagged sessions are weak ownership: they leak once their run dir is gone, and can be pruned by the wrong project on a run-id collision (the fallback behind #320) #419's tag).

Wrapping stays hand-maintained at 100 columns — prettier.config.mjs sets proseWrap: preserve, so no formatter reflows this file and nothing enforces it but review.

Stacked on #582

Based on fix/changelog-release-contract so the diff is exactly these three commits. #582 should merge first; this retargets to main automatically when it does. That PR is the natural pair — it makes a release promote ## [Unreleased] rather than author a new section beside it, which is what makes conformance of this section load-bearing rather than cosmetic.

Verification

• trunk check --all: clean, 254 files
• uv run pytest: 5411 passed, 44 skipped, 5 xfailed
• scripts/release.py check: clean
• Mechanically re-verified: 93 Fixed entries in, 93 out; every issue reference in the pre-rewrite text still present (or deliberately dropped and listed above); no bold span straddling a line; no line over 100 columns; code-span and link integrity preserved across the reflow; ## [0.9.1] onward byte-identical to HEAD.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 724c4f1f-3620-4aaf-8ed0-7cf9772231e6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}