chore(release): promote changelog into [4.0.4] (+ fix promote tooling) (#3219)

* fix(build): changelog-promote emits release.yml-compatible section format

The changelog.d fragment system (#2994) was never exercised by a real cut.
Its promote step wrote "## [version] - date" (two-hash, no tag link), but
every released section — and release.yml's notes extraction
(awk '/^# \[VERSION\]/,/^---$/') — uses a single-hash "# [version](tag) => date".
With the two-hash header the one-hash awk extracts zero lines, so the GitHub
Release would publish with EMPTY notes.

Also: boundary detection searched for the next "## " heading, but version
sections here are single-hash, so the first "## " match landed on a
subheading inside the 3.0.0 section — pulling every release since into the
promoted body. And a stray "----"/"---" rule in [Unreleased] could leak in.

- Match the next version heading at "#" OR "##" + " [" (correct tail boundary).
- Drop horizontal-rule lines from the promoted body.
- Emit "# [version](tag-url) => date" + explicit "---" separators around it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <petera@pai.com>

* chore(release): assemble changelog.d fragments into [4.0.4]

Promote the 83 pending changelog.d fragments (plus prior [Unreleased] content)
into the [4.0.4] release section via tools/changelog-promote.sh, and clear the
fragment folder. Done on develop first (per the release playbook) so develop's
[Unreleased] doesn't go stale and force a back-port after the cut.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <petera@pai.com>

* fix(build): consolidate changelog sections by heading in canonical order

The first promote pass exposed a second defect: when [Unreleased] carries the
same heading twice (develop had two '### Performance' blocks), the merge
appended the fragment bullets to EACH same-named section — double-counting every
performance fragment (e.g. the $getStatusCodes entry appeared twice). It also
emitted sections in [Unreleased] file order with the duplicate intact and
fragment-only sections tacked on last.

merged_sections now combines all bullets for a heading into ONE section and
emits sections in canonical order (Added, Changed, Deprecated, Removed,
Performance, Fixed, Security), existing bullets before fragment bullets.

Regenerated the [4.0.4] section: 116 unique entries (was 124 with 8 dupes),
canonical order, no duplicate headings. Verified zero unique entries lost.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <petera@pai.com>

* docs(build): sync changelog-promote usage header + summary to new format

Address the Reviewer-A nit: the top-of-file usage comment still advertised the
old "## [version] - date" shape and the summary print() used " - " — both now
reflect the single-hash, tag-linked, "=>"-dated section the script emits.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <petera@pai.com>

* test(build): cover new changelog-promote format + section consolidation

Address Reviewer-A (CHANGES_REQUESTED): the format change broke Test 3, which
still asserted the old "## [ver] - date" header — re-anchor it to the
single-hash, tag-linked, "=>"-dated section the script now emits. Add Test 5
covering the merged_sections consolidation: a [Unreleased] body with two
"### Performance" blocks plus a matching *.performance.md fragment must collapse
to one heading in canonical order with each bullet appearing exactly once (the
double-count regression the 4.0.4 cut surfaced). Full suite green (11/11).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Peter Amiri <petera@pai.com>

---------

Signed-off-by: Peter Amiri <petera@pai.com>
Co-authored-by: Peter Amiri <petera@pai.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people