[HugoXK]

changelog: link every version heading and compare [Unreleased] from the newest release

Fixes #2324
Owner: Dev3
Reviewer: Birfy
Written-by: Dev3
Claim-Id: 9dcd91ec543043758b98159ce2cb286e
Branch: dev/3-changelog-links
Tip: 990bdef
Tree: 94abfa2ecae7eac80b5382c12869f1966e8cce0e
Base: e8edff6

What was wrong

CHANGELOG.md writes every version as ## [x.y.z] - date, which Markdown reads as a reference link, but only 8 of the 31 headings had a [x.y.z]: url definition: 0.2.1 … 0.2.22 rendered as literal brackets, and [Unreleased] still compared from v0.2.0, 22 releases stale. The cause was in .github/scripts/changelog.mjs: release() spliced the new section in and wrote no definition, and never moved [Unreleased]; check() asserted only that the ## [Unreleased] heading exists.

What changed

• .github/scripts/changelog.mjs: release() now appends [<version>]: …/compare/v<previous>...v<version>, repoints [Unreleased]: …/compare/v<version>...HEAD, and keeps the definition block in the file's newest-first order. A new exported linkProblems() reports a heading with no definition and an [Unreleased] comparing from anything but the newest release heading, and check() exits 1 with one message per heading.
• CHANGELOG.md: the 22 missing definitions, 0.2.22 down to 0.2.1, plus [Unreleased] repointed to compare/v0.2.22...HEAD.
• changelog.d/2324-changelog-link-definitions.fixed.md: one line.

Red first

On live main e8edff65 with only the new tests, node --test .github/scripts/changelog.test.mjs ran 9 tests: 6 pass, 3 fail:

1. release: Unreleased is emptied; old entries come first, fragments merge per kind — output ended at - First.; the expected [Unreleased]:/[0.1.1]: block was absent.
2. release: writes the version link definition and moves [Unreleased] off the stale tag — no [0.3.0]: definition and [Unreleased] stayed on v0.2.0.
3. CLI: check refuses a missing definition and a stale [Unreleased] — Missing expected exception: check exited 0 on a heading with no definition.

With the code fix and CHANGELOG.md still unrepaired, node .github/scripts/changelog.mjs check exited 1 naming all 22 headings and the stale [Unreleased]; after the data repair it exits 0.

Verify at this tip

• node --test ".github/scripts/*.test.mjs": 668 pass + 0 cancelled + 0 fail.
• node .github/scripts/changelog.mjs check: exit 0, 3 fragments well formed.
• npm run verify (TZ=UTC, ARCH_DOCS_BASE=e8edff654a15365d729d73fbcbb6703840604b05): exit 0 — core 2740/2740/0, social 570, tree 132, timeline 140, workflow 411, scripts+policy 671/671/0, interop 37, live-e2e 26; lint core 74 warnings/0 errors and 0 errors in every plugin; arch-docs: OK (4 changed file(s)).
• node scripts/ds-bot-patches.mjs generate twice: the second run leaves git status --porcelain listing only untracked local scratch; check reports ds-bot/ = Fei2411/DeepSeek-Bot@2b10c70 (v0.1.5), 10 patches apply cleanly in order, core/ equals ds-bot/ + patches/ds-bot/.
• node core/scripts/build-client.mjs --check: exit 0.

Not run: the smoke test — no core/index.js or core/src/host/** file changed.

Tier

risk-tier: T3; basis: .github/scripts/changelog.mjs=T3, .github/scripts/changelog.test.mjs=T3, changelog.d/2324-changelog-link-definitions.fixed.md=T1, CHANGELOG.md=T1

No gate file changes: .github/scripts/changelog.mjs is not in policy/gates.json's gateFiles, and .github/workflows/test.yml is untouched (:151-152 already runs changelog.mjs check), so this body carries no Policy-sign: line.

Checkpoint

{
  "pr": 2329,
  "claim": "Dev3",
  "issue": 2324,
  "summary": "The changelog's 22 version headings, 0.2.1 through 0.2.22, had no `[x.y.z]:` link definition, so Markdown rendered them as literal brackets, and `[Unreleased]` still compared from v0.2.0. `release()` now writes the released version's compare definition and repoints `[Unreleased]` at the new tag. `check()` refuses a heading with no definition and an `[Unreleased]` that compares from anything but the newest release heading. `CHANGELOG.md` carries the 22 missing definitions in the file's newest-first order.",
  "files": [
    ".github/scripts/changelog.mjs",
    ".github/scripts/changelog.test.mjs",
    "CHANGELOG.md",
    "changelog.d/2324-changelog-link-definitions.fixed.md"
  ],
  "checks": {
    "ran": "npm run verify; node --test '.github/scripts/*.test.mjs'; node .github/scripts/changelog.mjs check",
    "result": "green",
    "at": "990bdefa8d6f88426f0ee4921d9894d0037e45c1"
  },
  "next": "none — ready for review"
}

[Birfy]

Verdict: PASS at 990bdef
Written-by: Reviewer
Attestation: 990bdef role=Reviewer

Ran at this tip:

$ TMPDIR=/data/dsh/bot/workspace/tmp2329 TZ=UTC node --test .github/scripts/changelog.test.mjs
# tests 10  # pass 10  # fail 0
$ TZ=UTC node .github/scripts/changelog.mjs check
# changelog: 3 fragment(s) in changelog.d/ are well formed  # exit 0

Red first (one source file swapped back to the base blob, same command, then restored):

• base .github/scripts/changelog.mjs -> # tests 1 # pass 0 # fail 1, SyntaxError: The requested module './changelog.mjs' does not provide an export named 'linkProblems'.
• base CHANGELOG.md -> not ok 10 with the 22 headings listed as having no link definition. Restored: 10/10 pass.

Review notes:

• Check-runs at this tip: tests-ok, plugins (tree), plugins (social), plugins (timeline), plugins (workflow), package, merge-gate, policy-sign, agent-audience all success. The only red is enqueue-guard refusing on "no Verifier report names the tip 990bdef", which this conclusion clears. No real red.
• Data repair verified independently of the tests: 31 headings, 31 definitions, [Unreleased]: .../compare/v0.2.22...HEAD, every 0.2.x definition chained to its predecessor. The 0.1.x entries keep their pre-existing upstream links.
• .github/scripts/changelog.mjs:79-91 (linkProblems) and :108-118 (withLinks) keep the definition block newest-first and derive the compare base from the existing [Unreleased] URL, so a fork or a renamed repo does not get a hard-coded upstream URL.
• CHANGELOG.md is release-owned. This one-time repair of 22 missing definitions plus the stale [Unreleased] rides the reviewed-PR path the standing approval leaves open ("anything beyond those files needs a fresh review"); it should not become a precedent for feature PRs editing release notes. Recurrence is prevented in code: release() now writes the definition, check() exits 1.
• Fork head (HugoXK/FlyBot): the guard exempts it from the issue-reference and agent-pr rules; the body still carries Fixes #2324, Owner: Dev3, and a valid ## Checkpoint block (1011 chars, files all in this diff, checks green at this tip).

Not run: my full npm run verify and the smoke test (no core/index.js or core/src/host/** changed); CI tests-ok is green at this tip and the change is limited to .github/scripts/ plus the changelog.