Address CI review: thread single RELEASE_DATE through bump-version skill

CI review flagged P2 drift risk: step 3 can skip step 4 entirely when CHANGELOG
already has a populated [NEW_VERSION] entry, which meant step 5 fell back to
"today's date" for CITATION.cff even when CHANGELOG carried a different (earlier)
header date. Bump-version runs on a different day than CHANGELOG pre-population
would have produced inconsistent release metadata.

Fix: resolve RELEASE_DATE once in step 3 — parse the existing CHANGELOG header
date if the entry was pre-populated, otherwise use today's date — and thread
that single value through step 4 (CHANGELOG generation) and step 5 (CITATION.cff
date-released). Adds an abort path for malformed headers without a date. Updates
the Notes section to reflect the new single-source-of-truth model.

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

Author: igerber

.claude/commands/bump-version.md

@@ -38,11 +38,19 @@ Files that need updating:
    - Read `diff_diff/__init__.py` and extract the current `__version__` value
    - Store as `OLD_VERSION` for comparison link generation
 
-3. **Check CHANGELOG entry**:
-   - Search `CHANGELOG.md` for `## [NEW_VERSION]` section header
-   - If found: Verify it has content (at least one `### Added/Changed/Fixed` subsection with bullet points)
-   - If not found or empty: Generate entry from git commits (step 4)
-   - If found with content: Skip to step 5
+3. **Check CHANGELOG entry and resolve `RELEASE_DATE`**:
+   - Search `CHANGELOG.md` for `## [NEW_VERSION]` section header.
+   - If found with content (at least one `### Added/Changed/Fixed` subsection with
+     bullet points):
+     - **Parse the existing header date** (e.g., `## [3.1.3] - 2026-04-19` → `2026-04-19`).
+       Store as `RELEASE_DATE` and skip to step 5.
+     - If the header has no date (malformed), abort with: `Error: CHANGELOG header for
+       [NEW_VERSION] is missing a date. Fix the header before re-running.`
+   - If not found or empty: Set `RELEASE_DATE` to today's date in `YYYY-MM-DD` format,
+     then continue to step 4.
+
+   `RELEASE_DATE` is the single source of truth for the release date across every file
+   touched in this bump. Do not recompute it downstream.
 
 4. **Generate CHANGELOG from git** (only if needed):
    - Run: `git log v{OLD_VERSION}..HEAD --oneline`
@@ -51,7 +59,7 @@ Files that need updating:
      - **Added**: commits containing "add", "new", "implement", "introduce", "create"
      - **Changed**: commits containing "update", "change", "improve", "optimize", "refactor", "enhance"
      - **Fixed**: commits containing "fix", "bug", "correct", "repair", "resolve"
-   - Get today's date in YYYY-MM-DD format
+   - Use the `RELEASE_DATE` resolved in step 3 for the header.
    - Create CHANGELOG entry in this format:
      ```markdown
      ## [X.Y.Z] - YYYY-MM-DD
@@ -86,9 +94,10 @@ Files that need updating:
 
    - `CITATION.cff`:
      Replace `version: "OLD_VERSION"` with `version: "NEW_VERSION"`.
-     Also update `date-released: "OLD_DATE"` to `date-released: "YYYY-MM-DD"`
-     using today's date (same value used for the CHANGELOG section header in
-     step 4). Both fields are quoted strings; preserve the quoting style.
+     Also update `date-released: "OLD_DATE"` to `date-released: "{RELEASE_DATE}"`
+     using the `RELEASE_DATE` resolved in step 3. Both fields are quoted strings;
+     preserve the quoting style. `RELEASE_DATE` must match the CHANGELOG header
+     date; never substitute a freshly computed "today" value here.
 
 6. **Update CHANGELOG comparison links**:
    - Run `git remote get-url origin` to determine the repository's GitHub URL
@@ -125,7 +134,10 @@ Files that need updating:
 - If CHANGELOG already has the target version entry with content, it will not be overwritten
 - Commit messages are cleaned up (prefixes like "feat:", "fix:" are removed) for CHANGELOG
 - The comparison link format uses `v` prefix for tags (e.g., `v2.2.0`)
-- `CITATION.cff` `date-released` is set to today's date (same value as the CHANGELOG
-  section header). If the release is cut on a different day, update it manually at
-  release time — drift here causes auto-citation tools (Zenodo, GitHub's "cite this
-  repository", reference managers) to report stale metadata.
+- `CITATION.cff` `date-released` and the `CHANGELOG.md` section header share a single
+  `RELEASE_DATE` resolved in step 3: if the CHANGELOG entry was pre-populated, its
+  existing header date wins (so pre-written changelog drafts don't silently drift
+  from the CITATION date); otherwise today's date is used for both. If the release
+  is cut on a different day than the bump, update both surfaces manually — drift
+  causes auto-citation tools (Zenodo, GitHub's "cite this repository", reference
+  managers) to report stale metadata.