check-changelog-parity: absorbed-heading preservation is scoped to bumped plugins, so a changelog-only change set and every convention changelog are unpoliced

[kyle-sexton]

Split out of #2327 so that issue can close with #2341, which fixes only its false positives (items 1 and 2). These are #2327 items 3, 4 and 5 — all pre-existing from #2290, none addressed by #2341.

The absorbed-heading check lives inside --check-bump's loop, so it is gated on bumped_candidate[$name] and on [[ "$head_version" != "$fork_version" ]] || continue. Three consequences, each verified against the shipped script on main, copied unmodified into throwaway repos.

1. A changelog-only change set is unpoliced — and this is where the real one hid

base:  ## [0.51.8], ## [0.51.7]      manifest 0.51.8
head:  ## [0.51.8]                   manifest 0.51.8 (untouched)
       (0.51.7's note folded into 0.51.8, its heading deleted)

--check-bump -> EXIT=0

Not hypothetical. Replaying the 60 most recent main commits touching plugins/*/CHANGELOG.md as their own PRs produced zero ABSORBED CHANGELOG HEADING fires — including on 04822fc4, which really did delete ## [0.9.7] from plugins/docs-hygiene/CHANGELOG.md and fold its bullet into ## [0.10.0]. It is invisible because it changed no manifest at all:

$ git diff --name-only 04822fc4^1 04822fc4
.github/workflows/ci.yml
plugins/docs-hygiene/CHANGELOG.md
scripts/check-changelog-parity.sh
scripts/check-changelog-parity.test.sh

"Fix a release note" is the ordinary shape of a changelog-only PR, and it is exactly the shape a bad merge-forward resolution takes.

2. Convention changelogs are unpoliced

docs/conventions/*/CHANGELOG.md are unversioned by any manifest, so --check-bump never reads them — which is precisely why --check-order was given its own whole-file scope (the misordering that produced it shipped in docs/conventions/loop-lane/CHANGELOG.md).

docs/conventions/demo/CHANGELOG.md
base:  ## 2.0.0 — 2026-01-02, ## 1.0.0 — 2026-01-01
head:  ## 3.0.0 — 2026-01-03, ## 1.0.0 — 2026-01-01     <- 2.0.0 absorbed

--check-bump -> EXIT=0

3. The fork-point read is fail-open

git show "$merge_base:$changelog" 2>/dev/null | changelog_versions - inside a process substitution: a git read that genuinely fails yields an empty fork-point set, which reads as "nothing to preserve" and passes. git ls-tree distinguishes the two cases exactly — a path missing from the tree is exit 0 with empty output, an unusable rev is a non-zero exit — where git cat-file -e cannot (it exits 128 for both, so probing with it would fail every change set that adds a changelog).

Shape of a fix

Preservation as its own diff mode over every changed changelog under both roots --check-order sweeps, wired as an additional PR-only step in the existing changelog-parity-gate job so no required-context name changes. It must replace the in-loop check rather than sit beside it — two overlapping absorption checks is the drift the file's own header warns against.

A worked implementation exists on branch fix/2264-changelog-preservation (PR #2298, closed as a duplicate of #2290 before it could land, and not reopenable): 21 tests including [YANKED], heading reformat, whole-file deletion, convention-changelog absorption, a stale-branch false-positive guard, and a forced-gawk SIGPIPE fixture. Swept over 60 replayed main commits, 7789 headings compared, firing on 04822fc4 and nowhere else. It needs rebasing onto #2290 and #2341.

Related

#2264 (the defect), #2290 (the fix that shipped), #2327 (the false positives), #2341 (their repair).

[kyle-sexton]

Carry-over from the #2341 review (thread r3763714089), recorded here rather than patched there because this issue replaces the block in question.

Acceptance criterion for the replacement: the de-duplication guard — a version repeated in the fork-point heading list must be reported once, not once per occurrence — needs a dedicated test. #2341 carries the guard with a comment explaining its intent but no case pins it: all five of its new cases use fork changelogs with unique headings.

--check-order's DUPLICATE CHANGELOG VERSION keeps that state out of well-formed history, but it is a separate required step from --check-bump, and a fork-point changelog carrying a duplicate is exactly what a bad merge-forward produces before anything else notices. The consequence is only a doubled line in a failure message, so it is cosmetic — but the code asserts the intent in a comment, and a comment that no test pins is the kind of claim this repo has been burned by before.

The implementation on fix/2264-changelog-preservation carries the same guard, also untested; whichever branch becomes the replacement should add the case.

[kyle-sexton]

Evidence summary for the #2341 fix now on main (bb817c6c) — author-run, NOT independently verified

Recording this here because the fix merged before an independent verifier returned, and a next lane should know exactly what was and was not checked, and by whom.

Independent verification did not land. Two fresh-context verifier agents were dispatched (one against the closed #2298, one against #2341 at its pinned SHA); neither returned a verdict. Everything below was run by the change's own author, which is the weakest tier of review. Treat it accordingly.

What discriminates the fix (strongest item). The two failure fixtures were run against main's shipped script before the fix existed — so this is a genuine before/after, not a self-confirming test:

fixture	pre-fix main	post-fix
## [1.0.0] → ## [1.0.0] - 2026-01-01 [YANKED]	EXIT=1 ABSORBED CHANGELOG HEADING … ## [1.0.0]	EXIT=0
## [1.0.0] → ## [1.0.0] - 2026-01-01	EXIT=1 ABSORBED CHANGELOG HEADING … ## [1.0.0]	EXIT=0
## [0.51.8] deleted, note folded into ## [0.51.9]	EXIT=1	EXIT=1 (unchanged — the check did not go soft)

Unit suite. PASS=62 FAIL=0; five new cases — dated heading passes, [YANKED] passes, relabel still fails, reformat between the bracketed and unbracketed forms passes, absorbing an unbracketed section is caught.

No new fires on real history. 60 most recent main commits touching plugins/*/CHANGELOG.md replayed as their own PRs (tree at C, base C^1): 59 replayed (cf743d61 could not be checked out), 58 clean, 1 fire — 78dbb10e, reporting UNDOCUMENTED BUMP and three VERSION REGRESSIONs, none from the changed check. Zero ABSORBED CHANGELOG HEADING fires, for the reason this issue exists.

CI. Green on the merged SHA, including the gate's own self-test on ubuntu-24.04 — which matters because the SIGPIPE hazard (#2154/#2159) is gawk-versus-mawk sensitive and a local green on Windows proves nothing about it.

Not checked: the symmetric in-tree revert-proof (restore main's script, keep the new tests, confirm they fail) was refused by a local permission classifier and was not reshaped to get around it. The table above is the same claim by a different route.