docs(claude): rewrite release section for auto-promote workflow + link-ref on promote (#437)

Two paired updates:

1. **`CLAUDE.md` § Releases** — rewritten to match the actual workflow now
   that #436's auto-promote step lands the entries automatically.

   The old text told Claude to 'Add a new `## [X.Y.Z] - YYYY-MM-DD`
   block at the top of CHANGELOG.md' as the first step. That instruction
   is the exact pattern that caused the v0.9.5 sparse-release-notes
   incident — a hand-added sparse `[X.Y.Z]` block (one early fix
   pre-staged) is what the extractor picked, ignoring everything under
   `[Unreleased]` above it.

   New default: write entries under `## [Unreleased]` during normal
   work. The Release workflow promotes them at release time. The
   formatting rules (sub-section grouping, user-perspective wording,
   issue/PR refs) are preserved. The link-reference rule moves to 'don't
   add it yourself' since `prepare-release.mjs` now appends it.

2. **`scripts/prepare-release.mjs`** — extended to also append a
   `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`
   link reference at the end of CHANGELOG.md when promoting (idempotent
   — no-op if one already exists, regardless of where in the file it
   sits). This is what makes the `## [X.Y.Z]` heading text auto-link
   to its release tag in GitHub's renderer; without it the heading still
   renders, just unlinked. 3 new tests cover Case A append, Case B
   append-when-merging, and no-double-add.

940/942 existing tests still pass (2 pre-existing skips); +3 new tests.

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

scripts/prepare-release.mjs

@@ -195,7 +195,8 @@ function main() {
       body: ['', ''], // two blank lines for the next round of entries
     };
     parsed.blocks.splice(unrelIdx, 1, emptied, promoted);
-    writeFileSync(CHANGELOG_PATH, joinChangelog(parsed));
+    const next = joinChangelog(parsed);
+    writeFileSync(CHANGELOG_PATH, appendLinkRef(next, version));
     console.log(`prepare-release: ${version} — renamed [Unreleased] to [${version}] - ${today}`);
     return;
   }
@@ -234,10 +235,33 @@ function main() {
   // Empty out Unreleased.
   unrel.body = ['', ''];
 
-  writeFileSync(CHANGELOG_PATH, joinChangelog(parsed));
+  const merged_text = joinChangelog(parsed);
+  writeFileSync(CHANGELOG_PATH, appendLinkRef(merged_text, version));
   console.log(`prepare-release: ${version} — merged ${merged} Unreleased entries into existing [${version}] block`);
 }
 
+/**
+ * Append a `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`
+ * link reference at the end of the file IF one doesn't already exist. The
+ * link ref is what makes `## [X.Y.Z]` heading text auto-link to its tag in
+ * GitHub's renderer; without it the heading still renders, just unlinked.
+ *
+ * Idempotent. The existing CHANGELOG mixes link refs scattered through the
+ * file and a sorted block at the bottom — we just append at the very end,
+ * which CommonMark accepts regardless.
+ */
+function appendLinkRef(text, version) {
+  const refLine = `[${version}]: https://github.com/colbymchenry/codegraph/releases/tag/v${version}`;
+  // Already there? Look for a line that EQUALS this (anywhere in the file)
+  // to keep idempotency robust against the scattered-vs-block layout.
+  const lines = text.split('\n');
+  if (lines.some((l) => l.trim() === refLine)) return text;
+  // Append, separated by a blank line from the prior content. Preserve a
+  // single trailing newline at EOF.
+  const trailingNewline = text.endsWith('\n') ? '' : '\n';
+  return text + trailingNewline + refLine + '\n';
+}
+
 try {
   main();
 } catch (err) {