fix(scripts): the absorbed-heading check fails OPEN on a git error, and misses unbumped plugins and convention changelogs

[kyle-sexton]

PR #2290 closed #2264 by adding an ABSORBED CHANGELOG HEADING check to --check-bump. The
motivating case is genuinely caught — verified below as a control, so this is a hardening issue,
not a regression report.

Three residual holes, all reproduced against the real script copied unmodified out of origin/main.

Probe results

CONTROL   (bump absorbs 0.51.8)                     rc=1 :: ABSORBED CHANGELOG HEADING: alpha lost release section heading(s) ...
GAP 1     (heading dropped, NO manifest bump)       rc=0 :: Every plugin whose version changed ... has a '## [<version>]' entry.
GAP 2     (CONVENTION heading dropped)              rc=0 :: Every plugin whose version changed ... has a '## [<version>]' entry.
FAIL-OPEN (same absorb + git show CHANGELOG fails)  rc=0 :: Every plugin whose version changed ... has a '## [<version>]' entry.

1. Fail-open: process substitution discards git show's exit status

scripts/check-changelog-parity.sh at HEAD:

missing_headings="$(
  comm -23 \
    <(git show "$merge_base:$changelog" 2>/dev/null | changelog_bracket_headings - | sort) \
    <(changelog_bracket_headings "$changelog" | sort)
)"

<(git show …) is process substitution, so a git show failure is invisible: the base heading
list arrives empty, comm -23 reports nothing missing, and the gate passes without having checked.
2>/dev/null additionally hides the reason.

This is the exact pattern the same file's own header forbids, in prose, for this reason — the
diff_paths block a few lines above reads:

Read the change set's touched paths via COMMAND substitution, not process substitution: this gate
is a required CI merge check, and a git failure here must fail loud, never silently pass. Process
substitution swallows git's exit status …

The argument was already written down; the new code does the thing it argues against.

Reproduced by fault injection, not by inspection. A git shim on PATH fails git show only
for a path ending in CHANGELOG.md, so manifest resolution and every existing bump check still work
and only the preservation read breaks. The identical change set that the control catches (rc=1)
then passes:

# $D/bin/git
if [[ "${1:-}" == show && "${2:-}" == *CHANGELOG.md ]]; then
  echo "simulated object-store failure" >&2
  exit 128
fi
exec /usr/bin/git "$@"

FAIL-OPEN (same absorb + git show CHANGELOG fails)  rc=0

Fix: read the base blob with command substitution (or into a temp file) and check the status.
"Changelog absent at the merge base" must stay distinguishable from "git failed" — probe with
git cat-file -e "$merge_base:$changelog" first, since a changelog that is simply new in the
change set is a legitimate pass, and conflating the two either red-lines every new plugin or
restores the fail-open.

2. Scope: the check only runs for plugins whose manifest changed

It sits inside the per-manifest loop guarded by [[ -n "${bumped_candidate[$name]:-}" ]], so a
change set that edits a CHANGELOG and deletes a heading without touching plugin.json is never
examined. That is the quieter hiding place: the absorbed-heading resolution does not require a bump
to occur in the same commit.

GAP 1 (heading dropped, NO manifest bump)  rc=0

--check-bump already computes merge_base and diff_paths, so scoping preservation to the
changelogs the change set touched — rather than to bumped manifests — is a small change that
covers strictly more while still never red-lining a branch for a heading some earlier change
removed.

3. Scope: convention changelogs are entirely uncovered

changelog_bracket_headings matches only ^## \[x.y.z\], and the manifest loop only ever visits
plugins/*/. docs/conventions/*/CHANGELOG.md uses the ## 1.2.3 — date form and is unversioned by
any manifest, so it is invisible on both counts — even though --check-order explicitly scopes those
files and the file's own comment says convention changelogs are in scope "precisely because that is
where it shipped" (the loop-lane 6.0.0 → 3.1.1 → 5.0.0 → 4.0.0 incident).

GAP 2 (CONVENTION heading dropped)  rc=0

The file already has changelog_versions(), which goes through rendered_lines and matches every
heading form the repo uses — plugin, convention, and two-component. Using it for both sides would
close this and keep one reader across all modes, which is the stated design intent
("One tracker, not three, so the modes cannot drift").

Note on comm

comm requires sorted input and PR #2290 does sort both sides, so it is correct as written. Flagged
only so a later reader does not "simplify" the sort away — dropping it would silently produce wrong
answers while still exiting 0.

Reproduction

The probe script builds four disposable git repos, copies the real script in unmodified from
origin/main, and prints the table above. Fixtures for all three gaps plus the control were written
and executed; happy to attach them to a PR if someone picks this up.

Related

• check-changelog-parity: a merge-forward that absorbs the predecessor release section passes all three modes — deleted headings are unpoliced #2264 — closed by fix(scripts): reject absorbed changelog release headings (#2264) #2290; this is residual hardening, and the motivating case it fixed stays fixed
• fix(ci): close the reverse direction of the changelog-parity gate #2154 / fix(ci): stop has_heading's early exit from SIGPIPE-failing the parity gate #2159 — the SIGPIPE regression in this same gate, and the reason its header argues against
  status-swallowing pipelines in the first place

[kyle-sexton]

Status re-probed against main after #2341 landed (fix(scripts): key the absorbed-heading check on the version, not the line). Same four-case probe, real script copied unmodified out of
origin/main:

CONTROL   (bump absorbs 0.51.8)                     rc=1 :: ABSORBED CHANGELOG HEADING ...
GAP 1     (heading dropped, NO manifest bump)       rc=0
GAP 2     (CONVENTION heading dropped)              rc=0
FAIL-OPEN (same absorb + git show CHANGELOG fails)  rc=0

What #2341 fixed: the check now reads both sides through changelog_versions, so it shares the
one heading reader with --check and --check-order and compares versions rather than raw lines.
That closes the reader-drift concern and is a real improvement.

All three of this issue's rows remain open. In particular the fail-open survived the rewrite,
because the pattern moved rather than went away — scripts/check-changelog-parity.sh:448 at HEAD:

mapfile -t fork_heading_versions < <(git show "$merge_base:$changelog" 2>/dev/null | changelog_versions -)

mapfile < <(…) is still process substitution, so git show's exit status is still discarded (and
2>/dev/null still hides the reason). A git show failure yields an empty base-heading array,
nothing reads as missing, and the gate passes without having checked — reproduced above by the same
fault injection as before, where the identical change set the control catches at rc=1 passes at
rc=0.

The fix is unchanged from the original write-up: read the base blob with command substitution (or
into a temp file), check the status, and keep "changelog absent at the merge base" distinguishable
from "git failed" with a git cat-file -e probe first — a changelog that is simply new in the change
set must stay a legitimate pass.

Rows 2 and 3 (unbumped plugins; convention changelogs in the ## 1.2.3 — date form) are also
unchanged — the check still sits inside the bumped_candidate-gated per-manifest loop, which never
visits either.

[kyle-sexton]

Fully addressed on main — no open PR required.

• Fail-open git read: scripts/check-changelog-parity.sh now probes with git ls-tree and reads base blobs via command substitution with exit-status checks (merged in fix(scripts): add --check-preserved for changelog heading deletions #2370, commit 494e312).
• Unbumped-plugin / touched-changelog scope: --check-preserved walks touched_changelogs from the branch diff (plugin + convention paths), not only bumped manifests.
• Convention changelogs: docs/conventions/*/CHANGELOG.md is in the diff-path case and changelog_versions handles all heading forms.

The motivating absorbed-heading case from #2264/#2290 remains caught; this issue's three residual gaps are closed by the above.