Released CHANGELOG entries are being edited in place (#2312 rewrote two lines inside the shipped 0.51.12) — decide whether that is sanctioned

[kyle-sexton]

Found by the independent verifier on #2312 (verdict posted at pull/2312#issuecomment-5263261619). The D6 gate that PR shipped is correct — items 1-4 all CONFIRMED. This is about the CHANGELOG.

What happened

#2312 (merged 4e8dd9cc) added ## [0.51.15] correctly — one heading added, zero deleted. But the tail is not byte-identical to the merge parent:

parent tail: 279283 bytes  sha256 8dee13e2…
head   tail: 279698 bytes  sha256 9d29d09b…

Two hunks, both inside the already-released ## [0.51.12] entry:

1. the verify_fix_commit description, changed from "primitive" to "guarantee"
2. the per_page=100 call-site claim

Both corrections are accurate, and both were declared — in the PR body and in the new 0.51.15 entry. The verifier's framing is the right one: declaration is context, not compliance.

Why it is worth settling rather than shrugging at

This file adopts Keep a Changelog, where a released entry is an immutable record of what shipped. Editing one in place means the changelog no longer says what 0.51.12 claimed at the time 0.51.12 shipped — which is the only thing a changelog entry is for. Anyone reconstructing why a downstream consumer behaved a certain way on 0.51.12 now reads corrected text that did not exist then.

It also interacts badly with the absorbed-heading gate this repo just built (#2264 → #2290 → #2327 → #2341). That gate exists precisely because released sections were being silently rewritten by merge-forwards. It checks that headings survive; it does not check that bodies do. So the repo now enforces half of the invariant it decided it wanted, and the other half is unenforced and was violated within hours by a PR whose own subject was factual accuracy.

The decision

Not "revert #2312's corrections" — they are true, and losing them would be worse. The question is which of these the project wants:

1. Released entries are append-only. A correction to a shipped entry goes in the current entry as an explicit erratum ("0.51.12 described X as a primitive; it is a guarantee"), leaving the historical text intact. Highest fidelity, slightly noisier.
2. Declared in-place correction is sanctioned, with a stated rule: the correcting PR must name the edit in its body and in the new entry — which fix(source-control): D6 resolves the push remote instead of hardcoding origin #2312 actually did. Cheaper, and the current de facto behaviour; it just is not written down anywhere.
3. Extend the parity gate to compare released-section bodies, not just headings, and fail on any mutation below the newest heading. Mechanically enforces (1). Note the gate has already broken once on a format variant the corpus did not contain (check-changelog-parity: the #2290 absorption check false-positives on any heading-line edit ([YANKED], dates), and leaves the no-bump and convention-changelog surfaces unpoliced #2327), so a body-level check needs fixtures for reflow, link-reference updates, and typo fixes before it goes anywhere near required status.

My read: (2) is what actually happens, (1) is what the Keep a Changelog adoption implies, and the gap between them is the thing to close — in the convention doc at minimum, and only then in the gate if the project wants it enforced.

Severity

Low. Nothing shipped incorrectly, no consumer is misled about current behaviour, and the corrections improved accuracy. The cost is historical fidelity and an unwritten rule that two lanes could reasonably read differently — which, on a repo where several agents edit the same changelogs concurrently, is exactly the kind of ambiguity that produces the next absorbed section.