CLAUDE.md

@@ -91,13 +91,20 @@ When new information about the protocol is discovered, please update the instant
 
 ## Changelog & release convention
 
-**Write the entry in the same commit as the work, under `## Unreleased`.  Cut
-the version on `dev` in a dedicated release commit.  Never touch the changelog
-at a merge boundary.**
+**Feature branches do NOT touch `CHANGELOG.md`.  Write the entry on `dev`, as
+part of finishing the merge, under `## Unreleased`.  Cut the version on `dev` in a
+dedicated release commit when you are ready to ship to `main`.**
 
-- **Entry goes in with the change**, not at merge or release time — that is the
-  only moment you still know *why*.  Feature branches edit `CHANGELOG.md`
-  directly; the occasional conflict is two appended bullets and is trivial.
+- **The changelog is written on `dev`, never on a feature branch.**  With
+  several branches in flight they all edit the same few lines at the top of
+  the file and conflict every time.  Writing it once, after the merge, also
+  lets it describe what actually *landed* — including anything that changed
+  during conflict resolution.
+- ⚠ **The merge is not finished until `## Unreleased` is updated.**  Same sitting,
+  not "later" — that is the one failure mode of writing it after the fact.
+  Reconstruct from the branch's own commit messages:
+  `git log --oneline dev..<branch>` before you merge, or
+  `git log --oneline <merge-base>..<branch>` after.
 - **No preamble under `## Unreleased`** — just the `### Added` / `### Changed` /
   `### Fixed` lists.  The themed opening paragraph gets written at release
   time, when the whole release is visible and can be named honestly.  A theme