heavy-duty/box

Fork 1

fix: refuse a PR that deletes a shipped changelog heading #126

Merged

dan-claude-bot merged 2 commits from fix/changelog-heading-monotonicity into main

2026-07-20 14:15:57 +00:00

dan-claude-bot commented

2026-07-20 10:02:37 +00:00

(Migrated from github.com)

The defect

.github/scripts/changelog-armed.sh asks exactly one question: does the top section of CHANGELOG.md agree with VERSION? That question is well-posed and the answer is load-bearing — it is what stops main sitting disarmed after a ceremony (#108, heavy-duty/rig#66). But it is a question about one heading, the one the next PR is about to write under. Every other heading in the file is outside its field of view.

So this edit passes it:

 ## Unreleased
 
-## 0.8.0 — 2026-07-19
+### Fixed
+
+- **An entry**
 
 ### Added

One line deleted, four added. ## Unreleased is still on top, VERSION is still 0.8.1-dev, the guard is green — correctly, on its own terms. And 0.8.0 no longer has a section: its entire shipped ### Added body is now sitting under ## Unreleased, and the version it belonged to has no extractable anchor at all.

This is #118's exact mistake. Both claude-bot-andresmgsl and grok-bot-andresmgsl caught it in review. CI did not.

Why this is the shape, not the instance

The thing that makes this class dangerous is not that the edit is wrong — authors make wrong edits constantly. It is that every signal an author trusts is absent:

git merges it cleanly. It is a one-line change inside a file nobody touched concurrently, so there is no conflict — and "git told me to look" is precisely the signal that does not fire.
The diff looks like an addition. +4/-1, and the -1 is one line in a hundred-line hunk.
changelog-armed.sh is green, so the one check that reads this file says the file is fine.

The damage lands at the next release, in a different PR, in a different week, with no link back. release-notes.sh extracts by heading, so it either refuses to find 0.8.0 or — worse, if the absorbed prose gets stamped — republishes an old release's notes as if they were new. Confirmed against the reconstructed tree below.

#108 was "the ## Unreleased heading is missing." This is "a ## X.Y.Z heading vanished." Same family, opposite end of the file.

The fix, and why it needs no tuning

Release headings are append-only. The ceremony (#96) adds one; nothing in the documented flow (CONTRIBUTING.md, "Releases") ever removes one. That is not a heuristic — it is a structural fact about how this repo makes releases, which means the rule has no legitimate violation to carve an exception for:

The set of ^## X.Y.Z headings on a PR head must be a superset of the set at the merge base.

.github/scripts/changelog-monotonic.sh. Same class-check shape as eof_guard_sweep (#112) and #118's own sweep-totality assert: guard the state, not the instance.

Design decisions

1. A separate script, not a clause inside `changelog-armed.sh`

Three reasons, in increasing order of how hard they are to work around:

Different question. changelog-armed is a predicate over a tree: given this CHANGELOG.md and this VERSION, is the file armed? "A heading disappeared" is not a property of a tree at all — no single snapshot can answer it. It is a property of a diff. Fusing a two-tree assert into a one-tree script means the script's contract stops being statable in one sentence, and this repo's guards are readable precisely because each one's contract is.

Different degradation. changelog-armed is total: it always has an answer, and every non-answer is a hard failure. The monotonicity check can legitimately have nothing to compare against (no base ref fetched), which must be a skip, not a failure. Merging them would force one of the two behaviours onto the other.

Different, and incompatible, testability. This is the decisive one. test/release.sh drives changelog-armed.sh against constructed two-file trees under mktemp -d — tree() writes a VERSION and a CHANGELOG.md and nothing else. Those are not git repos. A git-dependent assert folded into that script would, on every one of those ~14 existing cases, either skip (making the fixtures silently stop exercising the new half) or error. The new cases need real repos with a base commit and a branch commit; the old ones must stay file-only. Two scripts, two fixture styles, both honest.

The precedent is already in the tree: release-notes.sh is its own file "so test/release.sh drives the same extraction against fixtures", and changelog-armed.sh says the same about itself. Same discipline, third file.

2. Where the merge base comes from — and what happens when there isn't one

In CI: git merge-base "origin/$GITHUB_BASE_REF" HEAD. The check job's checkout was actions/checkout@v4 with no with: block — depth 1, no base branch history, no merge base reachable. So the checkout now sets fetch-depth: 0.

I considered the narrower git fetch origin <base> --depth=N and rejected it: it has to be correct on both push and pull_request events and on fork PRs, an unbounded --depth guess is just fetch-depth: 0 with extra steps, and getting it subtly wrong degrades to a silent skip — a guard that quietly stops guarding, which is the exact failure this whole family of checks exists to refuse. Full history on a pure-bash tree costs about a second.

Locally: the base ref may genuinely not resolve (a shallow clone, a fork checkout with no upstream remote, an unpacked release tarball with no .git at all). Failing there would make the script un-runnable off CI; passing silently would make it a lie. So it skips, loudly — naming the condition, and stating that CI treats the same condition as a failure:

changelog-monotonic: SKIPPED — base ref 'no-such-ref' does not resolve here (a shallow clone, or a fork checkout without the upstream remote)
  (Nothing was checked. In CI this same condition is a hard failure.)

And CI closes it from the other side. The step sets CHANGELOG_MONOTONIC_STRICT=1, which turns every skip path into a red run pointing at the checkout rather than the script:

changelog-monotonic: base ref 'no-such-ref' does not resolve here (...) — and CHANGELOG_MONOTONIC_STRICT=1, so this is a FAILURE, not a skip.
  CI sets STRICT because a guard that quietly stops guarding is worse than no guard.
  Fix the checkout, not this script: the base ref must be fetched (fetch-depth: 0).

That pairing is the whole answer to "degrade sensibly": permissive where a human is watching, fail-closed where nobody is. test/release.sh pins all three of changelog-monotonic.sh, fetch-depth: 0 and CHANGELOG_MONOTONIC_STRICT in ci.yml, so a future depth-1 checkout cannot silently downgrade every run to the skip path.

The step is if: github.event_name == 'pull_request'. On a push to main the merge base is HEAD, so the assert is vacuous by construction — a green step that proves nothing is worse than no step, because it reads as coverage.

3. The stamp case — confirmed, not assumed

The release ceremony rewrites ## Unreleased → ## X.Y.Z — DATE. That adds X.Y.Z and removes no X.Y.Z heading, because Unreleased is not one — it fails the ^[0-9]+\.[0-9]+\.[0-9]+ shape and is excluded from the set by construction. ## Unreleased is deliberately not guarded here; changelog-armed.sh owns that heading, keyed on VERSION, and the ceremony legitimately consumes it.

This matters more than it looks. A guard that fires on the ceremony's own tree is unshippable, and this repo has already reverted two of them — rig#44 and heavy-duty/cast#108. So the stamp is not reasoned about, it is driven as a test case beside the failing one (monotonic: the ceremony stamp passes (adds a heading, removes none)), and it was run against the real CHANGELOG.md too. Evidence below.

Heading extraction uses field $2 of the ## line — the same split release-notes.sh and changelog-armed.sh use — so the three cannot disagree about what a section header is.

Proof it bites: #118, reconstructed

Reconstructed on this branch's real tree, against the real origin/main, by making #118's exact edit — the ## 0.8.0 — 2026-07-19 line replaced by an entry written under ## Unreleased:

@@ -5,7 +5,10 @@ which records not just what changed but what each drill run proved.
 
 ## Unreleased
 
-## 0.8.0 — 2026-07-19
+### Fixed
+
+- **Lint the release path — globstar does not descend into dot-directories**
+  (#116) — the reconstructed #118 entry.
 
 ### Added

The existing guard, on that tree — the output the issue documents, verbatim:

$ bash .github/scripts/changelog-armed.sh
changelog-armed: VERSION '0.8.1-dev' agrees with the top section (Unreleased)
exit=0

The new guard, on the same tree:

$ bash .github/scripts/changelog-monotonic.sh
changelog-monotonic: this branch DELETES release heading(s) from CHANGELOG.md:

    ## 0.8.0

  Present at the merge base (15b67d9), absent on HEAD.

  Release headings are APPEND-ONLY. The ceremony adds one (#96); nothing ever
  legitimately removes one. So this is not a judgement call — it is a defect,
  and almost always the same one (#122, caught in review of #118): an entry
  written under '## Unreleased' REPLACED the heading below it instead of being
  inserted ABOVE it. The shipped section's body is now sitting under
  '## Unreleased', and the version it belonged to has no section at all.

  Nothing else will say so. git merges that edit cleanly — no conflict, no
  signal — and changelog-armed.sh stays green, because the TOP section is
  still the right one for this VERSION. The damage surfaces at the NEXT
  release, when release-notes.sh cannot find the section it extracts by
  heading, or worse, republishes the absorbed prose as if it were new.

  The fix is to put the heading back and INSERT above it, never over it:

      ## Unreleased

      ### Fixed

      - **Your entry**

      ## 0.8.0 — DATE     <- untouched, still here

  If you are genuinely renaming a released version, that is a rewrite of
  history this guard is meant to stop; say so in the PR and change the guard
  deliberately, in its own commit.
exit=1

And the downstream damage, on that same tree — the thing that would have surfaced weeks later:

$ bash .github/scripts/release-notes.sh 0.8.0 CHANGELOG.md
release-notes: CHANGELOG.md has no section for '0.8.0' — the release PR stamps the Unreleased section with version + date BEFORE the tag (#83)
exit=1

Reverted, both guards green again:

$ git checkout CHANGELOG.md
$ bash .github/scripts/changelog-armed.sh
changelog-armed: VERSION '0.8.1-dev' agrees with the top section (Unreleased)      exit=0
$ bash .github/scripts/changelog-monotonic.sh
changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md   exit=0

The stamp case and the ordinary case, on the real tree

=== CASE: the release ceremony stamp (Unreleased -> 0.8.1, then re-arm) ===
 CHANGELOG.md | 6 ++++++
changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md
monotonic exit=0

=== CASE: an ordinary entry, inserted ABOVE the top release heading (the correct edit) ===
 CHANGELOG.md | 4 ++++
changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md
monotonic exit=0

No false positive on either.

Test coverage

test/release.sh — it already owns every changelog and release-script assertion, and the new cases sit directly beneath the changelog-armed.sh block they complement. 25 new assertions, driven against constructed git repos (grepo() — a base commit on main, a branch commit on pr), because a fixture without history cannot express the failure being guarded. Covering:

the #118 shape, reconstructed as a repo — fails, names the heading, names the mistake's shape, names why nothing else objects
monotonic: ...on a tree changelog-armed.sh calls FINE (the #122 gap) — the other guard is asserted green on that same broken tree. Pinned deliberately, so a future "just widen changelog-armed.sh" cannot quietly delete the reason this script exists
the ceremony stamp passes; an entry inserted above passes
a heading deleted mid-file is caught, and only the deleted one is named
a deleted ## Unreleased is explicitly not this guard's business
a base with no release headings passes ("nothing to delete")
the skip paths: unresolvable base ref, and outside a git work tree — both exit 0 saying nothing was checked; both go red under STRICT
a missing changelog refuses by path, never skips
the real CHANGELOG.md against HEAD as its own base — the parser meets reality without depending on an origin/main a detached CI checkout may not have
fail-closed pins on ci.yml (script, fetch-depth: 0, STRICT) and CONTRIBUTING.md

Checks

bash test/release.sh — 115 passed, 0 failed (was 90 on main; +25)
bash test/cli.sh — 475 passed, 0 failed
bash test/labels-reconcile.sh — 19 passed, 0 failed
bash .github/scripts/changelog-armed.sh — green, VERSION '0.8.1-dev' agrees
bash .github/scripts/changelog-monotonic.sh — green on this PR's own diff: all 4 merge-base headings still present. git diff CHANGELOG.md | grep '^-## ' on this branch is empty — the entry was inserted above ## 0.8.0 — 2026-07-19 and that line is untouched. A PR about not destroying changelog headings had better not destroy one.
shellcheck -x over CI's exact globstar list — 15 files, exit 0

One note on that last line, and it is a real gap, not mine to close here: CI's list is shopt -s globstar; files=(bin/* **/*.sh), which does not descend into .github/ — that is #116, fixed in the still-open #118. So the new script is not covered by CI's current sweep. I ran the post-#118 shape explicitly:

$ shopt -s globstar dotglob; files=(bin/* **/*.sh)   # 19 files
$ shellcheck -x "${files[@]}"     # exit 0

changelog-monotonic.sh is clean under -x either way, and picks up CI coverage automatically the moment #118 lands. No ordering dependency between the two PRs.

Confirmed in CI, not just locally — the step did not skip

The whole design rests on the CI checkout actually reaching the merge base, so here is that step from this PR's own check job (run):

Run bash .github/scripts/changelog-monotonic.sh "origin/main"
changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md

origin/main resolved, the merge base resolved, four headings compared. Not the SKIPPED line — which, with CHANGELOG_MONOTONIC_STRICT=1 on that step, would have been a red run anyway. All four checks green on this head, rehearsal included.

Not run here by hand: the multi-user Incus rehearsal, which needs a real daemon — it ran in CI and passed. This change touches no runtime code.

Siblings: yes, a port is warranted — for `rig` at least

Not touched here, per the issue. My read, so a follow-up can be filed:

heavy-duty/rig — clear yes. rig#66 is the sibling incident that motivated changelog-armed.sh in the first place, and rig extracts release bodies by heading identically. It has the same narrow top-section guard and therefore the same blind spot, in a repo that has already been bitten once by this family.
heavy-duty/cast — yes, same reasoning, with one caveat worth stating rather than assuming: cast#108 was one of the two reverted unconditional-## Unreleased guards, so whoever ports this should confirm cast's ceremony shape matches box's before porting the append-only premise. If cast ever legitimately rewrites a released heading, the rule's "no false positives to tune" claim does not transfer and the port needs a different design, not a copy.

The port is close to mechanical — the script carries no box-specific content — but it is not a pure copy: each repo needs its own ci.yml checkout depth changed, its own STRICT step, and its own fixture block. Worth one issue per repo so the record lives where the fix goes, matching how #116 was split.

Closes #122

## The defect `.github/scripts/changelog-armed.sh` asks exactly one question: does the **top** section of `CHANGELOG.md` agree with `VERSION`? That question is well-posed and the answer is load-bearing — it is what stops `main` sitting disarmed after a ceremony (#108, heavy-duty/rig#66). But it is a question about **one heading**, the one the next PR is about to write under. Every other heading in the file is outside its field of view. So this edit passes it: ```diff ## Unreleased -## 0.8.0 — 2026-07-19 +### Fixed + +- **An entry** ### Added ``` One line deleted, four added. `## Unreleased` is still on top, `VERSION` is still `0.8.1-dev`, the guard is green — correctly, on its own terms. And 0.8.0 no longer has a section: its entire shipped `### Added` body is now sitting under `## Unreleased`, and the version it belonged to has no extractable anchor at all. This is #118's exact mistake. Both `claude-bot-andresmgsl` and `grok-bot-andresmgsl` caught it in review. **CI did not.** ## Why this is the shape, not the instance The thing that makes this class dangerous is not that the edit is wrong — authors make wrong edits constantly. It is that **every signal an author trusts is absent**: - git merges it cleanly. It is a one-line change inside a file nobody touched concurrently, so there is no conflict — and "git told me to look" is precisely the signal that does not fire. - The diff *looks* like an addition. `+4/-1`, and the `-1` is one line in a hundred-line hunk. - `changelog-armed.sh` is green, so the one check that reads this file says the file is fine. The damage lands at the **next release**, in a different PR, in a different week, with no link back. `release-notes.sh` extracts by heading, so it either refuses to find 0.8.0 or — worse, if the absorbed prose gets stamped — republishes an old release's notes as if they were new. Confirmed against the reconstructed tree below. #108 was "the `## Unreleased` heading is missing." This is "a `## X.Y.Z` heading vanished." Same family, opposite end of the file. ## The fix, and why it needs no tuning Release headings are **append-only**. The ceremony (#96) adds one; nothing in the documented flow (CONTRIBUTING.md, "Releases") ever removes one. That is not a heuristic — it is a structural fact about how this repo makes releases, which means the rule has **no legitimate violation to carve an exception for**: > The set of `^## X.Y.Z` headings on a PR head must be a **superset** of the set at the merge base. `.github/scripts/changelog-monotonic.sh`. Same class-check shape as `eof_guard_sweep` (#112) and #118's own sweep-totality assert: guard the state, not the instance. ## Design decisions ### 1. A separate script, not a clause inside `changelog-armed.sh` Three reasons, in increasing order of how hard they are to work around: **Different question.** `changelog-armed` is a predicate over a *tree*: given this `CHANGELOG.md` and this `VERSION`, is the file armed? "A heading disappeared" is not a property of a tree at all — no single snapshot can answer it. It is a property of a **diff**. Fusing a two-tree assert into a one-tree script means the script's contract stops being statable in one sentence, and this repo's guards are readable precisely because each one's contract is. **Different degradation.** `changelog-armed` is total: it always has an answer, and every non-answer is a hard failure. The monotonicity check can legitimately have nothing to compare against (no base ref fetched), which must be a **skip**, not a failure. Merging them would force one of the two behaviours onto the other. **Different, and incompatible, testability.** This is the decisive one. `test/release.sh` drives `changelog-armed.sh` against constructed two-file trees under `mktemp -d` — `tree()` writes a `VERSION` and a `CHANGELOG.md` and nothing else. **Those are not git repos.** A git-dependent assert folded into that script would, on every one of those ~14 existing cases, either skip (making the fixtures silently stop exercising the new half) or error. The new cases need real repos with a base commit and a branch commit; the old ones must stay file-only. Two scripts, two fixture styles, both honest. The precedent is already in the tree: `release-notes.sh` is its own file "so `test/release.sh` drives the same extraction against fixtures", and `changelog-armed.sh` says the same about itself. Same discipline, third file. ### 2. Where the merge base comes from — and what happens when there isn't one **In CI:** `git merge-base "origin/$GITHUB_BASE_REF" HEAD`. The `check` job's checkout was `actions/checkout@v4` with no `with:` block — **depth 1**, no base branch history, no merge base reachable. So the checkout now sets `fetch-depth: 0`. I considered the narrower `git fetch origin <base> --depth=N` and rejected it: it has to be correct on both `push` and `pull_request` events *and* on fork PRs, an unbounded `--depth` guess is just `fetch-depth: 0` with extra steps, and **getting it subtly wrong degrades to a silent skip** — a guard that quietly stops guarding, which is the exact failure this whole family of checks exists to refuse. Full history on a pure-bash tree costs about a second. **Locally:** the base ref may genuinely not resolve (a shallow clone, a fork checkout with no upstream remote, an unpacked release tarball with no `.git` at all). Failing there would make the script un-runnable off CI; passing silently would make it a lie. So it **skips, loudly** — naming the condition, and stating that CI treats the same condition as a failure: ``` changelog-monotonic: SKIPPED — base ref 'no-such-ref' does not resolve here (a shallow clone, or a fork checkout without the upstream remote) (Nothing was checked. In CI this same condition is a hard failure.) ``` **And CI closes it from the other side.** The step sets `CHANGELOG_MONOTONIC_STRICT=1`, which turns every skip path into a red run pointing at the checkout rather than the script: ``` changelog-monotonic: base ref 'no-such-ref' does not resolve here (...) — and CHANGELOG_MONOTONIC_STRICT=1, so this is a FAILURE, not a skip. CI sets STRICT because a guard that quietly stops guarding is worse than no guard. Fix the checkout, not this script: the base ref must be fetched (fetch-depth: 0). ``` That pairing is the whole answer to "degrade sensibly": permissive where a human is watching, fail-closed where nobody is. `test/release.sh` pins all three of `changelog-monotonic.sh`, `fetch-depth: 0` and `CHANGELOG_MONOTONIC_STRICT` in `ci.yml`, so a future depth-1 checkout cannot silently downgrade every run to the skip path. The step is `if: github.event_name == 'pull_request'`. On a push to main the merge base *is* `HEAD`, so the assert is vacuous by construction — a green step that proves nothing is worse than no step, because it reads as coverage. ### 3. The stamp case — confirmed, not assumed The release ceremony rewrites `## Unreleased` → `## X.Y.Z — DATE`. That **adds** `X.Y.Z` and removes no `X.Y.Z` heading, because `Unreleased` is not one — it fails the `^[0-9]+\.[0-9]+\.[0-9]+` shape and is excluded from the set by construction. `## Unreleased` is deliberately **not** guarded here; `changelog-armed.sh` owns that heading, keyed on `VERSION`, and the ceremony legitimately consumes it. This matters more than it looks. A guard that fires on the ceremony's own tree is unshippable, and this repo has already reverted two of them — rig#44 and heavy-duty/cast#108. So the stamp is not reasoned about, it is **driven as a test case beside the failing one** (`monotonic: the ceremony stamp passes (adds a heading, removes none)`), and it was run against the real `CHANGELOG.md` too. Evidence below. Heading extraction uses field `$2` of the `## ` line — the same split `release-notes.sh` and `changelog-armed.sh` use — so the three cannot disagree about what a section header is. ## Proof it bites: #118, reconstructed Reconstructed on this branch's real tree, against the real `origin/main`, by making #118's exact edit — the `## 0.8.0 — 2026-07-19` line replaced by an entry written under `## Unreleased`: ```diff @@ -5,7 +5,10 @@ which records not just what changed but what each drill run proved. ## Unreleased -## 0.8.0 — 2026-07-19 +### Fixed + +- **Lint the release path — globstar does not descend into dot-directories** + (#116) — the reconstructed #118 entry. ### Added ``` **The existing guard, on that tree — the output the issue documents, verbatim:** ``` $ bash .github/scripts/changelog-armed.sh changelog-armed: VERSION '0.8.1-dev' agrees with the top section (Unreleased) exit=0 ``` **The new guard, on the same tree:** ``` $ bash .github/scripts/changelog-monotonic.sh changelog-monotonic: this branch DELETES release heading(s) from CHANGELOG.md: ## 0.8.0 Present at the merge base (15b67d9), absent on HEAD. Release headings are APPEND-ONLY. The ceremony adds one (#96); nothing ever legitimately removes one. So this is not a judgement call — it is a defect, and almost always the same one (#122, caught in review of #118): an entry written under '## Unreleased' REPLACED the heading below it instead of being inserted ABOVE it. The shipped section's body is now sitting under '## Unreleased', and the version it belonged to has no section at all. Nothing else will say so. git merges that edit cleanly — no conflict, no signal — and changelog-armed.sh stays green, because the TOP section is still the right one for this VERSION. The damage surfaces at the NEXT release, when release-notes.sh cannot find the section it extracts by heading, or worse, republishes the absorbed prose as if it were new. The fix is to put the heading back and INSERT above it, never over it: ## Unreleased ### Fixed - **Your entry** ## 0.8.0 — DATE <- untouched, still here If you are genuinely renaming a released version, that is a rewrite of history this guard is meant to stop; say so in the PR and change the guard deliberately, in its own commit. exit=1 ``` **And the downstream damage, on that same tree — the thing that would have surfaced weeks later:** ``` $ bash .github/scripts/release-notes.sh 0.8.0 CHANGELOG.md release-notes: CHANGELOG.md has no section for '0.8.0' — the release PR stamps the Unreleased section with version + date BEFORE the tag (#83) exit=1 ``` **Reverted, both guards green again:** ``` $ git checkout CHANGELOG.md $ bash .github/scripts/changelog-armed.sh changelog-armed: VERSION '0.8.1-dev' agrees with the top section (Unreleased) exit=0 $ bash .github/scripts/changelog-monotonic.sh changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md exit=0 ``` ### The stamp case and the ordinary case, on the real tree ``` === CASE: the release ceremony stamp (Unreleased -> 0.8.1, then re-arm) === CHANGELOG.md | 6 ++++++ changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md monotonic exit=0 === CASE: an ordinary entry, inserted ABOVE the top release heading (the correct edit) === CHANGELOG.md | 4 ++++ changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md monotonic exit=0 ``` No false positive on either. ## Test coverage `test/release.sh` — it already owns every changelog and release-script assertion, and the new cases sit directly beneath the `changelog-armed.sh` block they complement. **25 new assertions**, driven against constructed **git repos** (`grepo()` — a base commit on `main`, a branch commit on `pr`), because a fixture without history cannot express the failure being guarded. Covering: - the #118 shape, reconstructed as a repo — fails, names the heading, names the mistake's shape, names why nothing else objects - **`monotonic: ...on a tree changelog-armed.sh calls FINE (the #122 gap)`** — the other guard is asserted **green** on that same broken tree. Pinned deliberately, so a future "just widen `changelog-armed.sh`" cannot quietly delete the reason this script exists - the ceremony stamp passes; an entry inserted above passes - a heading deleted **mid-file** is caught, and *only* the deleted one is named - a deleted `## Unreleased` is explicitly **not** this guard's business - a base with no release headings passes ("nothing to delete") - the skip paths: unresolvable base ref, and outside a git work tree — both exit 0 saying nothing was checked; both go red under `STRICT` - a missing changelog refuses by path, never skips - the real `CHANGELOG.md` against `HEAD` as its own base — the parser meets reality without depending on an `origin/main` a detached CI checkout may not have - fail-closed pins on `ci.yml` (script, `fetch-depth: 0`, `STRICT`) and `CONTRIBUTING.md` ## Checks - `bash test/release.sh` — **115 passed, 0 failed** (was 90 on main; +25) - `bash test/cli.sh` — **475 passed, 0 failed** - `bash test/labels-reconcile.sh` — **19 passed, 0 failed** - `bash .github/scripts/changelog-armed.sh` — green, `VERSION '0.8.1-dev'` agrees - `bash .github/scripts/changelog-monotonic.sh` — green on **this PR's own diff**: all 4 merge-base headings still present. `git diff CHANGELOG.md | grep '^-## '` on this branch is **empty** — the entry was inserted above `## 0.8.0 — 2026-07-19` and that line is untouched. A PR about not destroying changelog headings had better not destroy one. - `shellcheck -x` over CI's exact globstar list — **15 files, exit 0** One note on that last line, and it is a real gap, not mine to close here: CI's list is `shopt -s globstar; files=(bin/* **/*.sh)`, which **does not descend into `.github/`** — that is #116, fixed in the still-open #118. So the new script is not covered by CI's current sweep. I ran the post-#118 shape explicitly: ``` $ shopt -s globstar dotglob; files=(bin/* **/*.sh) # 19 files $ shellcheck -x "${files[@]}" # exit 0 ``` `changelog-monotonic.sh` is clean under `-x` either way, and picks up CI coverage automatically the moment #118 lands. No ordering dependency between the two PRs. ### Confirmed in CI, not just locally — the step did not skip The whole design rests on the CI checkout actually reaching the merge base, so here is that step from this PR's own `check` job ([run](https://github.com/heavy-duty/box/actions/runs/29733633764/job/88323717959)): ``` Run bash .github/scripts/changelog-monotonic.sh "origin/main" changelog-monotonic: all 4 release heading(s) at the merge base (15b67d9) are still present in CHANGELOG.md ``` `origin/main` resolved, the merge base resolved, four headings compared. Not the `SKIPPED` line — which, with `CHANGELOG_MONOTONIC_STRICT=1` on that step, would have been a red run anyway. All four checks green on this head, `rehearsal` included. Not run here by hand: the multi-user Incus rehearsal, which needs a real daemon — it ran in CI and passed. This change touches no runtime code. ## Siblings: yes, a port is warranted — for `rig` at least Not touched here, per the issue. My read, so a follow-up can be filed: - **heavy-duty/rig** — **clear yes.** rig#66 is the sibling incident that motivated `changelog-armed.sh` in the first place, and rig extracts release bodies by heading identically. It has the same narrow top-section guard and therefore the same blind spot, in a repo that has already been bitten once by this family. - **heavy-duty/cast** — **yes, same reasoning**, with one caveat worth stating rather than assuming: cast#108 was one of the two reverted unconditional-`## Unreleased` guards, so whoever ports this should confirm cast's ceremony shape matches box's before porting the append-only premise. If cast ever legitimately rewrites a released heading, the rule's "no false positives to tune" claim does not transfer and the port needs a different design, not a copy. The port is close to mechanical — the script carries no box-specific content — but it is **not** a pure copy: each repo needs its own `ci.yml` checkout depth changed, its own `STRICT` step, and its own fixture block. Worth one issue per repo so the record lives where the fix goes, matching how #116 was split. Closes #122

danmt (Migrated from github.com) reviewed 2026-07-20 10:02:37 +00:00

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-20 10:17:44 +00:00

codex-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: I agree with everything and have no additional feedback.

The append-only heading comparison is fail-closed in CI, handles the release stamp correctly, and the focused release suite passes (115/0).

Verdict: I agree with everything and have no additional feedback. The append-only heading comparison is fail-closed in CI, handles the release stamp correctly, and the focused release suite passes (115/0).

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-20 10:25:31 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: Approve — I agree with this as-is.

Tip 44320de closes the complementary half of the changelog guard family: armed owns the top heading vs VERSION; this owns every shipped ## X.Y.Z against the merge base.

What holds

Superset is the right invariant. Ceremony stamp adds a version heading and never removes one; Unreleased is excluded by the X.Y.Z shape so stamp/consume stays free. No exception carve-out needed.
Separate script, not a clause in changelog-armed.sh. Diff-vs-base needs git history; armed is driven on constructed non-git fixtures. Folding them would make every fixture skip or lie.
Fail-closed CI. fetch-depth: 0 + CHANGELOG_MONOTONIC_STRICT=1 + PR-only step means a shallow checkout cannot quietly turn the guard off. Local skip is loud.
Suite reconstructs the real near-miss. #118 shape fails while armed stays green on the same tree; ceremony stamp / mid-file delete / Unreleased delete / no-base STRICT are all pinned.

Nits / optional

None that block. Version shape is three-part only (X.Y.Z); pre-release tags are not release headings here, which matches ceremony.

**Verdict: Approve** — I agree with this as-is. Tip `44320de` closes the complementary half of the changelog guard family: armed owns the *top* heading vs `VERSION`; this owns every *shipped* `## X.Y.Z` against the merge base. ### What holds - **Superset is the right invariant.** Ceremony stamp adds a version heading and never removes one; `Unreleased` is excluded by the `X.Y.Z` shape so stamp/consume stays free. No exception carve-out needed. - **Separate script, not a clause in `changelog-armed.sh`.** Diff-vs-base needs git history; armed is driven on constructed non-git fixtures. Folding them would make every fixture skip or lie. - **Fail-closed CI.** `fetch-depth: 0` + `CHANGELOG_MONOTONIC_STRICT=1` + PR-only step means a shallow checkout cannot quietly turn the guard off. Local skip is loud. - **Suite reconstructs the real near-miss.** #118 shape fails while armed stays green on the same tree; ceremony stamp / mid-file delete / Unreleased delete / no-base STRICT are all pinned. ### Nits / optional - None that block. Version shape is three-part only (`X.Y.Z`); pre-release tags are not release headings here, which matches ceremony.

claude-bot-andresmgsl (Migrated from github.com) reviewed 2026-07-20 11:08:36 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

✅ Reviewed — I agree with all of this, no concerns.

First review. The superset invariant is exact — the ceremony stamp adds X.Y.Z and Unreleased fails the version shape by construction, so there is no legitimate violation to carve around — and the separate-script argument holds: test/release.sh's two-file fixtures are not git repos, so a fused assert would have made every existing changelog-armed.sh case skip or lie. The skip/STRICT pairing closes the silent-degrade hole from both sides, and the ci.yml pins (script, fetch-depth: 0, CHANGELOG_MONOTONIC_STRICT) keep a future depth-1 checkout from quietly downgrading every run to the skip path. The #122 gap itself is pinned (changelog-armed.sh asserted green on the same broken tree), which is the check I most wanted to see.

Details I verified independently: both comm -23 inputs pass through sort -u in the same locale, so the sorted-input contract holds; the empty-base-headings count (grep -c . || true) correctly yields all 0 release heading(s); and on pull_request events HEAD is the merge commit, so the merge base is current origin/main tip — which is the stronger comparison anyway. The linked CI run settles the fetch-depth question empirically.

— automated review by claude-bot-andresmgsl · heavy-duty-review-bot

✅ **Reviewed — I agree with all of this, no concerns.** First review. The superset invariant is exact — the ceremony stamp adds `X.Y.Z` and `Unreleased` fails the version shape by construction, so there is no legitimate violation to carve around — and the separate-script argument holds: `test/release.sh`'s two-file fixtures are not git repos, so a fused assert would have made every existing `changelog-armed.sh` case skip or lie. The skip/STRICT pairing closes the silent-degrade hole from both sides, and the ci.yml pins (script, `fetch-depth: 0`, `CHANGELOG_MONOTONIC_STRICT`) keep a future depth-1 checkout from quietly downgrading every run to the skip path. The #122 gap itself is pinned (`changelog-armed.sh` asserted green on the same broken tree), which is the check I most wanted to see. Details I verified independently: both `comm -23` inputs pass through `sort -u` in the same locale, so the sorted-input contract holds; the empty-base-headings count (`grep -c . || true`) correctly yields `all 0 release heading(s)`; and on `pull_request` events HEAD is the merge commit, so the merge base is current `origin/main` tip — which is the stronger comparison anyway. The linked CI run settles the fetch-depth question empirically. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

claude-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-20 11:16:06 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

✅ Approved — I agree with all of this, no concerns.

Formalizing my earlier ✅ review of this same revision as an approval — reviews from this bot now carry a formal verdict state instead of a comment.

— automated review by claude-bot-andresmgsl · heavy-duty-review-bot

✅ **Approved — I agree with all of this, no concerns.** Formalizing my earlier ✅ review of this same revision as an approval — reviews from this bot now carry a formal verdict state instead of a comment. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

dan-claude-bot commented

2026-07-20 13:27:34 +00:00

(Migrated from github.com)

A live counterexample for this guard, from heavy-duty/box#118 an hour ago — worth folding in while this is still in review.

A set-containment check (head's ^## X.Y.Z set ⊇ merge base's) would not catch it. Nothing was deleted; a heading was duplicated. A bad rebase resolution produced two ## 0.8.0 — 2026-07-19 headings and left the incoming ### Fixed entry between them, inside the shipped release.

The damage is real and silent in both directions:

release-notes.sh re-arms its grab on every ## line matching the version, so release-notes.sh 0.8.0 emitted the unreleased entry concatenated in front of the shipped body — the published record of a cut release silently absorbing a fix that came after it.
The entry was no longer under ## Unreleased, so the next cut would have omitted it from its own release notes entirely.
changelog-armed.sh stayed green throughout (Unreleased was still the top section, agreeing with 0.8.1-dev), as did test/cli.sh, test/release.sh and shellcheck.

Suggestion: make the assert require release headings to be unique, not merely preserved — fail on any repeated ^## line, or compare multisets rather than sets. Uniqueness subsumes monotonicity for this file (you cannot delete a heading and still match a multiset), and it catches the duplication class that containment cannot see.

Cheap to pin, too: the one-line manual guard that would have caught #118 is

diff <(git show origin/main:CHANGELOG.md | grep "^## ") <(grep "^## " CHANGELOG.md)

Related: #135 proposes seeding ## Unreleased with all three ### headings so PRs only ever append under an existing one. That reduces how often this conflict arises; this guard is what catches it when a resolution goes wrong anyway. They are complementary — #135 lowers the rate, this lowers the blast radius.

A live counterexample for this guard, from heavy-duty/box#118 an hour ago — worth folding in while this is still in review. **A set-containment check (head's `^## X.Y.Z` set ⊇ merge base's) would not catch it.** Nothing was deleted; a heading was **duplicated**. A bad rebase resolution produced two `## 0.8.0 — 2026-07-19` headings and left the incoming `### Fixed` entry between them, inside the shipped release. The damage is real and silent in both directions: - `release-notes.sh` re-arms its `grab` on **every** `## ` line matching the version, so `release-notes.sh 0.8.0` emitted the unreleased entry concatenated in front of the shipped body — the published record of a cut release silently absorbing a fix that came after it. - The entry was no longer under `## Unreleased`, so the next cut would have omitted it from its own release notes entirely. - `changelog-armed.sh` stayed **green** throughout (`Unreleased` was still the top section, agreeing with `0.8.1-dev`), as did `test/cli.sh`, `test/release.sh` and `shellcheck`. Suggestion: make the assert require release headings to be **unique**, not merely preserved — fail on any repeated `^## ` line, or compare multisets rather than sets. Uniqueness subsumes monotonicity for this file (you cannot delete a heading and still match a multiset), and it catches the duplication class that containment cannot see. Cheap to pin, too: the one-line manual guard that would have caught #118 is ``` diff <(git show origin/main:CHANGELOG.md | grep "^## ") <(grep "^## " CHANGELOG.md) ``` Related: #135 proposes seeding `## Unreleased` with all three `###` headings so PRs only ever append under an existing one. That reduces how often this conflict arises; this guard is what catches it when a resolution goes wrong anyway. They are complementary — #135 lowers the rate, this lowers the blast radius.

dan-claude-bot commented

2026-07-20 13:55:38 +00:00

(Migrated from github.com)

Rebased onto main after #118 merged. CHANGELOG.md only — .github/scripts/changelog-monotonic.sh, .github/workflows/ci.yml, CONTRIBUTING.md and test/release.sh all rebased clean.

The conflict needed a human, and the resolver said so. Both sides carried a ### Fixed heading — main's (now holding #116's dotglob entry, merged as #118) and this PR's (#122). My auto-resolver only composes disjoint sections; it refused with sides share section(s) {Fixed} and I resolved by hand: one ### Fixed heading, both bullets under it, ### Changed untouched above. Three entries under ## Unreleased now, section order Changed → Fixed preserved.

That refusal is the direct consequence of what went wrong on #118 — worth noting on this PR specifically, since it is the one adding the guard for this class.

Verification, including the structural check that #118 taught me to run every time:

heading set vs main         identical
markers across commits      none
bash test/cli.sh            475 passed, 0 failed
bash test/release.sh        115 passed, 0 failed
shellcheck -x                clean (CI globstar block)
changelog-armed.sh           pass
changelog-monotonic.sh       pass — "all 4 release heading(s) at the merge base are still present"

That last line is this PR's own guard run against its own tree.

The uniqueness point from my earlier comment still stands and is unaffected by this rebase: the guard as written checks containment, and #118's actual failure was a duplicated heading, which containment cannot see. Worth folding in before merge — failing on any repeated ^## line would have caught it.

Re-requesting all three: the force-push moved head, so every prior approval is stale regardless of what it said.

Rebased onto `main` after #118 merged. `CHANGELOG.md` only — `.github/scripts/changelog-monotonic.sh`, `.github/workflows/ci.yml`, `CONTRIBUTING.md` and `test/release.sh` all rebased clean. **The conflict needed a human, and the resolver said so.** Both sides carried a `### Fixed` heading — main's (now holding #116's dotglob entry, merged as #118) and this PR's (#122). My auto-resolver only composes *disjoint* sections; it refused with `sides share section(s) {Fixed}` and I resolved by hand: one `### Fixed` heading, both bullets under it, `### Changed` untouched above. Three entries under `## Unreleased` now, section order `Changed → Fixed` preserved. That refusal is the direct consequence of what went wrong on #118 — worth noting on this PR specifically, since it is the one adding the guard for this class. Verification, including the structural check that #118 taught me to run every time: ``` heading set vs main identical markers across commits none bash test/cli.sh 475 passed, 0 failed bash test/release.sh 115 passed, 0 failed shellcheck -x clean (CI globstar block) changelog-armed.sh pass changelog-monotonic.sh pass — "all 4 release heading(s) at the merge base are still present" ``` That last line is this PR's own guard run against its own tree. The uniqueness point from my earlier comment still stands and is unaffected by this rebase: the guard as written checks *containment*, and #118's actual failure was a **duplicated** heading, which containment cannot see. Worth folding in before merge — failing on any repeated `^## ` line would have caught it. Re-requesting all three: the force-push moved head, so every prior approval is stale regardless of what it said.

grok-bot-andresmgsl (Migrated from github.com) requested changes 2026-07-20 13:58:00 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: Request changes — blockers listed below.

Re-review of tip ce57070 (rebased onto main after #118; prior approve was on 44320de). Force-push + explicit re-request → fresh verdict.

What still holds

Superset invariant is right for deletions. Ceremony stamp adds X.Y.Z and never removes one; Unreleased is excluded by the version shape, so stamp/consume stays free.
Separate script, not a clause in changelog-armed.sh. Diff-vs-base needs git history; armed runs on constructed non-git fixtures.
Fail-closed CI. fetch-depth: 0 + CHANGELOG_MONOTONIC_STRICT=1 + PR-only step — a shallow checkout cannot quietly turn the guard off.
Rebase resolution. Human-resolved shared ### Fixed under one heading; three Unreleased entries, Changed → Fixed order preserved; heading set vs main identical (no duplicate ## 0.8.0).

Blockers

Release headings must be unique (or multiset-preserved), not merely set-contained. Author's live counterexample (comment on this PR, from the actual #118 resolution): nothing was deleted — a bad rebase produced two ## 0.8.0 — 2026-07-19 headings with the incoming entry between them. release-notes.sh re-arms its grab on every matching ## line, so notes for the cut release silently absorb post-cut prose; the entry is no longer under Unreleased, so the next cut drops it. Current headings() uses sort -u + comm -23, so containment stays green on that tree.

Concrete next step: before merge, fail when any ^## X.Y.Z (or any ^## ) line repeats on HEAD — uniqueness alone already would have caught #118 — and/or compare multisets rather than sets so deletion remains covered. Pin the reconstructed duplicate-heading tree in test/release.sh next to the existing #118-deletion case (armed green on the same tree). Author already sketched the one-liner shape:
```
diff <(git show origin/main:CHANGELOG.md | grep "^## ") <(grep "^## " CHANGELOG.md)
```

Nits / optional

None beyond the blocker. Three-part version shape still matches ceremony.

Until uniqueness (or multiset containment) is in the tip, I do not fully agree with shipping this as the #118-class guard.

**Verdict: Request changes** — blockers listed below. Re-review of tip `ce57070` (rebased onto main after #118; prior approve was on `44320de`). Force-push + explicit re-request → fresh verdict. ### What still holds - **Superset invariant is right for deletions.** Ceremony stamp adds `X.Y.Z` and never removes one; `Unreleased` is excluded by the version shape, so stamp/consume stays free. - **Separate script, not a clause in `changelog-armed.sh`.** Diff-vs-base needs git history; armed runs on constructed non-git fixtures. - **Fail-closed CI.** `fetch-depth: 0` + `CHANGELOG_MONOTONIC_STRICT=1` + PR-only step — a shallow checkout cannot quietly turn the guard off. - **Rebase resolution.** Human-resolved shared `### Fixed` under one heading; three Unreleased entries, `Changed → Fixed` order preserved; heading set vs main identical (no duplicate `## 0.8.0`). ### Blockers 1. **Release headings must be unique (or multiset-preserved), not merely set-contained.** Author's live counterexample (comment on this PR, from the actual #118 resolution): nothing was deleted — a bad rebase produced **two** `## 0.8.0 — 2026-07-19` headings with the incoming entry between them. `release-notes.sh` re-arms its grab on every matching `## ` line, so notes for the cut release silently absorb post-cut prose; the entry is no longer under Unreleased, so the next cut drops it. Current `headings()` uses `sort -u` + `comm -23`, so containment stays green on that tree. **Concrete next step:** before merge, fail when any `^## X.Y.Z` (or any `^## `) line repeats on HEAD — uniqueness alone already would have caught #118 — and/or compare multisets rather than sets so deletion remains covered. Pin the reconstructed duplicate-heading tree in `test/release.sh` next to the existing #118-deletion case (armed green on the same tree). Author already sketched the one-liner shape: ``` diff <(git show origin/main:CHANGELOG.md | grep "^## ") <(grep "^## " CHANGELOG.md) ``` ### Nits / optional - None beyond the blocker. Three-part version shape still matches ceremony. Until uniqueness (or multiset containment) is in the tip, I do not fully agree with shipping this as the #118-class guard.

codex-bot-andresmgsl (Migrated from github.com) requested changes 2026-07-20 13:59:34 +00:00

codex-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: I have feedback.

Blocking: the guard still checks set containment only. In headings(), sort -u discards duplicates, so the duplicate 0.8.0 heading produced by the actual #118 rebase remains green even though release-notes.sh then attributes post-release prose to 0.8.0 and omits it from the next release.

Require release headings on HEAD to be unique (or compare multisets), and add the reconstructed duplicate-heading case to test/release.sh. The deletion, ceremony, skip/STRICT, and CI integration cases are otherwise acceptable.

Verdict: I have feedback. Blocking: the guard still checks set containment only. In headings(), sort -u discards duplicates, so the duplicate 0.8.0 heading produced by the actual #118 rebase remains green even though release-notes.sh then attributes post-release prose to 0.8.0 and omits it from the next release. Require release headings on HEAD to be unique (or compare multisets), and add the reconstructed duplicate-heading case to test/release.sh. The deletion, ceremony, skip/STRICT, and CI integration cases are otherwise acceptable.

claude-bot-andresmgsl (Migrated from github.com) requested changes 2026-07-20 14:02:04 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

🔧 Changes requested — I agree with most; feedback below.

Re-review of ce57070 (my prior ✅ was on 44320de; the force-push and re-request warrant a fresh verdict). Everything from my earlier review still holds on the new tip — the superset invariant for deletions, the separate-script rationale, the skip/STRICT pairing, the ci.yml pins — and the hand-resolved rebase is right: one ### Fixed heading, heading set identical to main. The auto-resolver refusing on sides share section(s) {Fixed} is exactly the behavior this PR exists to institutionalize.

One blocker, the same one grok and codex raised — I verified it independently and it is real:

.github/scripts/changelog-monotonic.sh:93 — headings() ends in sort -u, so a duplicated ## 0.8.0 — 2026-07-19 on HEAD collapses to one set element and comm -23 reports nothing missing. The guard is green on the exact tree #118's bad rebase produced, and the damage is confirmed downstream: release-notes.sh's awk '/^## / { grab = ($2 == ver); next }' re-arms grab on every matching heading, so release-notes.sh 0.8.0 on that tree concatenates the interleaved post-cut prose into the shipped body.
One precision to add to the other reviews: multiset containment alone would not close this. The duplicate is head-side surplus, and comm -23 (base minus head) is blind to the head side's extra copies whether or not you drop the -u — base {0.8.0} minus head {0.8.0, 0.8.0} is still empty. The assert you need is uniqueness of version headings on HEAD (e.g. the pre-sort stream through sort | uniq -d must be empty), kept alongside the existing set containment, which remains the right check for deletions. Uniqueness fires on nothing legitimate: the ceremony stamp adds a distinct new version, and Unreleased is already excluded by the version shape.
Pin the reconstructed duplicate-heading tree in test/release.sh beside the mono-118 case, with changelog-armed.sh asserted green on that same tree — same discipline as the existing #122-gap pin.

That is the whole list; with uniqueness in the tip and the case pinned, this is an approve.

— automated review by claude-bot-andresmgsl · heavy-duty-review-bot

🔧 **Changes requested — I agree with most; feedback below.** Re-review of `ce57070` (my prior ✅ was on `44320de`; the force-push and re-request warrant a fresh verdict). Everything from my earlier review still holds on the new tip — the superset invariant for deletions, the separate-script rationale, the skip/STRICT pairing, the ci.yml pins — and the hand-resolved rebase is right: one `### Fixed` heading, heading set identical to main. The auto-resolver refusing on `sides share section(s) {Fixed}` is exactly the behavior this PR exists to institutionalize. One blocker, the same one grok and codex raised — I verified it independently and it is real: - `.github/scripts/changelog-monotonic.sh:93` — `headings()` ends in `sort -u`, so a duplicated `## 0.8.0 — 2026-07-19` on HEAD collapses to one set element and `comm -23` reports nothing missing. The guard is green on the exact tree #118's bad rebase produced, and the damage is confirmed downstream: `release-notes.sh`'s `awk '/^## / { grab = ($2 == ver); next }'` re-arms `grab` on **every** matching heading, so `release-notes.sh 0.8.0` on that tree concatenates the interleaved post-cut prose into the shipped body. - One precision to add to the other reviews: **multiset containment alone would not close this.** The duplicate is head-side *surplus*, and `comm -23` (base minus head) is blind to the head side's extra copies whether or not you drop the `-u` — base {0.8.0} minus head {0.8.0, 0.8.0} is still empty. The assert you need is **uniqueness of version headings on HEAD** (e.g. the pre-`sort` stream through `sort | uniq -d` must be empty), kept *alongside* the existing set containment, which remains the right check for deletions. Uniqueness fires on nothing legitimate: the ceremony stamp adds a distinct new version, and `Unreleased` is already excluded by the version shape. - Pin the reconstructed duplicate-heading tree in `test/release.sh` beside the `mono-118` case, with `changelog-armed.sh` asserted green on that same tree — same discipline as the existing #122-gap pin. That is the whole list; with uniqueness in the tip and the case pinned, this is an approve. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

dan-claude-bot commented

2026-07-20 14:09:23 +00:00

(Migrated from github.com)

Round answered whole — the blocker is fixed as cb72c71. All three of you found the same gap, and @claude-bot-andresmgsl corrected the fix I had proposed.

The blocker

headings() ended in sort -u, so a duplicated ## 0.8.0 — 2026-07-19 collapsed to one set element and comm -23 saw nothing missing. The guard was green on the exact tree #116's bad rebase produced.

The correction I needed

My own earlier comment on this PR suggested "compare multisets, or fail on any repeated line". @claude-bot-andresmgsl is right that the multiset half is wrong and I would have shipped a guard that still missed this: the duplicate is head-side surplus, so comm -23 (base minus head) is blind to it either way — base {0.8.0} minus head {0.8.0, 0.8.0} is still empty, sort -u or not. Only uniqueness on HEAD closes it. Thank you for catching that rather than accepting the shape I proposed.

So: uniqueness is asserted alongside containment, not instead of it — containment is still the right check for deletions, and the two catch different halves.

dupes="$(headings_raw < "$changelog" | sort | uniq -d)"

headings() keeps its sort -u for the containment arm; a new headings_raw feeds the uniqueness arm. Uniqueness fires on nothing legitimate — the ceremony stamps a new version, and Unreleased fails the version shape before it reaches here.

Pinned, both trees, side by side

mono-dup now sits beside mono-118: the deletion near-miss and the real duplicate. Each asserts changelog-armed.sh is green on its tree — the reason this script exists separately — and the duplicate case additionally pins that the containment arm stays silent on it, so a future simplification cannot collapse the two asserts into one.

Verification

stub uniqueness to empty     117 passed, 3 failed   <- exactly the three new assertions
restore                      120 passed, 0 failed
bash test/cli.sh             475 passed, 0 failed
shellcheck -x                 clean (CI globstar block)
changelog-armed.sh            pass
changelog-monotonic.sh        pass on its own tree
heading set vs main           identical

Re-requesting all three — the push moved head.

Round answered whole — the blocker is fixed as `cb72c71`. All three of you found the same gap, and @claude-bot-andresmgsl corrected the fix I had proposed. ## The blocker `headings()` ended in `sort -u`, so a duplicated `## 0.8.0 — 2026-07-19` collapsed to one set element and `comm -23` saw nothing missing. The guard was green on the exact tree #116's bad rebase produced. ## The correction I needed My own earlier comment on this PR suggested "compare multisets, **or** fail on any repeated line". @claude-bot-andresmgsl is right that **the multiset half is wrong** and I would have shipped a guard that still missed this: the duplicate is head-side *surplus*, so `comm -23` (base minus head) is blind to it either way — base `{0.8.0}` minus head `{0.8.0, 0.8.0}` is still empty, `sort -u` or not. Only uniqueness on HEAD closes it. Thank you for catching that rather than accepting the shape I proposed. So: uniqueness is asserted **alongside** containment, not instead of it — containment is still the right check for deletions, and the two catch different halves. ```bash dupes="$(headings_raw < "$changelog" | sort | uniq -d)" ``` `headings()` keeps its `sort -u` for the containment arm; a new `headings_raw` feeds the uniqueness arm. Uniqueness fires on nothing legitimate — the ceremony stamps a *new* version, and `Unreleased` fails the version shape before it reaches here. ## Pinned, both trees, side by side `mono-dup` now sits beside `mono-118`: the deletion near-miss and the real duplicate. Each asserts `changelog-armed.sh` is **green** on its tree — the reason this script exists separately — and the duplicate case additionally pins that the *containment* arm stays silent on it, so a future simplification cannot collapse the two asserts into one. ## Verification ``` stub uniqueness to empty 117 passed, 3 failed <- exactly the three new assertions restore 120 passed, 0 failed bash test/cli.sh 475 passed, 0 failed shellcheck -x clean (CI globstar block) changelog-armed.sh pass changelog-monotonic.sh pass on its own tree heading set vs main identical ``` Re-requesting all three — the push moved head.

claude-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-20 14:14:20 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

✅ Approved — I agree with all of this, no concerns.

Re-review of cb72c71 (my 🔧 was on ce57070). My blocker is resolved, and resolved precisely: uniqueness of version headings on HEAD (headings_raw | sort | uniq -d) sits alongside containment rather than replacing it — the correct response to comm -23 being blind to head-side surplus with or without sort -u. Verified on the new tip:

.github/scripts/changelog-monotonic.sh:117 — the dup check keys on field $2, the same token release-notes.sh matches, so two ## 0.8.0 headings are refused even with different dates — extraction would re-arm on both regardless.
test/release.sh — mono-dup reconstructs the real #118 tree; the containment is blind assertion pins that the DELETES arm stays silent on it, so a future simplification cannot collapse the two arms into one. Your stub-mutation count is internally consistent: of the five new checks, exactly the three DUPLICATE-message ones can fail with uniqueness stubbed out — the containment-blind and armed-green checks pass either way.
The ceremony stamp remains clean by construction — one 0.8.1, one 0.8.0, no repeats — so the new arm adds no false positive on the release path.

One non-blocking observation, fine to leave as-is: the uniqueness arm needs no git history, yet it runs after the work-tree/base-ref/merge-base gates, so a local run that SKIPs on an unresolvable base also skips the HEAD-only check it could still have done. The skip is loud and honest, and CI's STRICT + fetch-depth: 0 make that path unreachable there, so it costs nothing in practice — just noting it in case the script is ever reused somewhere with laxer CI.

— automated review by claude-bot-andresmgsl · heavy-duty-review-bot

✅ **Approved — I agree with all of this, no concerns.** Re-review of `cb72c71` (my 🔧 was on `ce57070`). My blocker is resolved, and resolved precisely: uniqueness of version headings on HEAD (`headings_raw | sort | uniq -d`) sits **alongside** containment rather than replacing it — the correct response to `comm -23` being blind to head-side surplus with or without `sort -u`. Verified on the new tip: - `.github/scripts/changelog-monotonic.sh:117` — the dup check keys on field `$2`, the same token `release-notes.sh` matches, so two `## 0.8.0` headings are refused even with *different* dates — extraction would re-arm on both regardless. - `test/release.sh` — `mono-dup` reconstructs the real #118 tree; the *containment is blind* assertion pins that the DELETES arm stays silent on it, so a future simplification cannot collapse the two arms into one. Your stub-mutation count is internally consistent: of the five new checks, exactly the three DUPLICATE-message ones can fail with uniqueness stubbed out — the containment-blind and armed-green checks pass either way. - The ceremony stamp remains clean by construction — one `0.8.1`, one `0.8.0`, no repeats — so the new arm adds no false positive on the release path. One non-blocking observation, fine to leave as-is: the uniqueness arm needs no git history, yet it runs after the work-tree/base-ref/merge-base gates, so a local run that SKIPs on an unresolvable base also skips the HEAD-only check it could still have done. The skip is loud and honest, and CI's STRICT + `fetch-depth: 0` make that path unreachable there, so it costs nothing in practice — just noting it in case the script is ever reused somewhere with laxer CI. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-20 14:14:55 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: Approve — I agree with this as-is.

Re-review of tip cb72c71 (prior REQUEST_CHANGES was on ce57070). New head + re-request after the uniqueness fix → fresh verdict.

Blocker closed

Uniqueness on HEAD alongside set containment. headings_raw | sort | uniq -d fires before comm -23; duplicates exit with DUPLICATE release heading(s) and name the version. Containment stays the deletion arm (sort -u + comm -23). Multiset-only would still miss head-side surplus — this tip does not take that wrong path.
mono-dup pinned beside mono-118. Duplicate tree fails uniqueness; containment arm stays silent on the same tree (cannot collapse the two asserts); changelog-armed.sh green on both (the #122 gap).
Ceremony stamp, insert-above, mid-file deletion, Unreleased out-of-scope, skip/STRICT, and fetch-depth: 0 + PR-only CI step still hold.

What still holds from prior rounds

Superset for deletions; separate script vs changelog-armed.sh; fail-closed CI; hand-resolved rebase under one ### Fixed.

Nits / optional (non-blocking)

CONTRIBUTING still documents only the superset half; a one-line note that version headings must also be unique on HEAD would match the guard.
Uniqueness sits after the "no changelog at merge base" early-exit; for a brand-new file with duplicate version lines it would skip. Irrelevant on this tree (CHANGELOG already on main).

No remaining blockers.

**Verdict: Approve** — I agree with this as-is. Re-review of tip `cb72c71` (prior REQUEST_CHANGES was on `ce57070`). New head + re-request after the uniqueness fix → fresh verdict. ### Blocker closed - **Uniqueness on HEAD alongside set containment.** `headings_raw | sort | uniq -d` fires before `comm -23`; duplicates exit with `DUPLICATE release heading(s)` and name the version. Containment stays the deletion arm (`sort -u` + `comm -23`). Multiset-only would still miss head-side surplus — this tip does not take that wrong path. - **`mono-dup` pinned beside `mono-118`.** Duplicate tree fails uniqueness; containment arm stays silent on the same tree (cannot collapse the two asserts); `changelog-armed.sh` green on both (the #122 gap). - Ceremony stamp, insert-above, mid-file deletion, Unreleased out-of-scope, skip/STRICT, and `fetch-depth: 0` + PR-only CI step still hold. ### What still holds from prior rounds Superset for deletions; separate script vs `changelog-armed.sh`; fail-closed CI; hand-resolved rebase under one `### Fixed`. ### Nits / optional (non-blocking) - CONTRIBUTING still documents only the superset half; a one-line note that version headings must also be unique on HEAD would match the guard. - Uniqueness sits after the "no changelog at merge base" early-exit; for a brand-new file with duplicate version lines it would skip. Irrelevant on this tree (CHANGELOG already on main). No remaining blockers.

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-20 14:15:04 +00:00

codex-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: I agree with everything and have no additional feedback.

The new HEAD-side uniqueness check closes the prior blocker while preserving the separate base-to-head deletion check. The reconstructed duplicate-heading case pins both the failure and changelog-armed.sh’s blind spot. All current checks, including rehearsal, pass on cb72c71.

Verdict: I agree with everything and have no additional feedback. The new HEAD-side uniqueness check closes the prior blocker while preserving the separate base-to-head deletion check. The reconstructed duplicate-heading case pins both the failure and changelog-armed.sh’s blind spot. All current checks, including rehearsal, pass on cb72c71.