heavy-duty/box

Fork 1

docs(changelog): one line per entry, and a pass over the whole file #147

Merged

dan-claude-bot merged 2 commits from docs/changelog-one-line into main

2026-07-21 14:43:50 +00:00

dan-claude-bot commented

2026-07-21 13:55:51 +00:00

(Migrated from github.com)

A house rule, and the pass that makes the file obey it.

The rule: every changelog entry is one line. Say what changed, cite the
issue, stop. The reasoning — why it was wrong, how it was found, what it cost,
what it implies — belongs in the PR body and the commit message, which is where
anyone chasing it already goes. CHANGELOG.md answers one question: what is
different in this version.

Documented as a new ## Changelog entries section in CONTRIBUTING.md, directly
above ## Releases.

The pass

CHANGELOG.md: 1302 lines → 180. Every entry in every section, including
the shipped ones.

Before:

- **`state:needs-human` no longer waits on the cron to become true** (#141)
  — the labels workflow now also wakes on `pull_request_target: labeled` and
  `unlabeled`, and the author sets `state:needs-human` themselves when handing
  a PR to the maintainer.

  A review landing was never a trigger. There is no
  `pull_request_review_target`, and on fork PRs — which is all of them here —
  `pull_request_review` runs with a read-only token and cannot label anything.
  [...25 more lines...]

After:

- `state:needs-human` is set at handoff, not by the cron (#141)

What was preserved, and how it was checked

The mechanical risks here are heading loss and entry loss. Both are asserted,
not eyeballed:

Invariant	Check	Result
No `##` heading added, removed, altered or reordered	`git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '`	no output at all
One entry out per entry in	`grep -c '^- '` before/after	73 → 75 (+1 from the stacked fix PR, +1 for the rule itself)
Every shipped section still extracts	`release-notes.sh` 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0	all non-empty
Intro prose	unchanged	byte-identical

That first row is the load-bearing one — changelog-monotonic.sh fails the
build if a ## X.Y.Z heading disappears, and release-notes.sh extracts by
exact heading match, so the published release bodies depend on those lines
surviving verbatim. They do.

Subheading grouping (### Added / ### Changed / ### Fixed) and entry order
are preserved. No section had duplicate subheadings to merge.

Two judgement calls

One BREAKING: marker was added that the file did not have — on the
#123 template rename (claude → claude-box, …). The entry's own text says
rig's roles are a hard cut with no aliases and that a pre-rename spelling
produces a failed mint, which is breaking by any reading; rig marks the same
change the same way. The 0.5.0 debrand was deliberately not marked,
because that section's intro explicitly promises everything legacy-facing is
honored forever.
Secondary refs buried mid-essay were dropped, headline refs all kept.
(#141) survives; the heavy-duty/rig#97 cited three paragraphs into its
body does not. The linked issue carries the rest — that is the point of
citing it.

Consequence worth stating

The GitHub release bodies already published for 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0
were generated from the old prose, so they no longer match this file. Re-pushing
them from the rewritten sections is queued as a follow-up once this lands.

A house rule, and the pass that makes the file obey it. **The rule: every changelog entry is one line.** Say what changed, cite the issue, stop. The reasoning — why it was wrong, how it was found, what it cost, what it implies — belongs in the PR body and the commit message, which is where anyone chasing it already goes. `CHANGELOG.md` answers one question: what is different in this version. Documented as a new `## Changelog entries` section in CONTRIBUTING.md, directly above `## Releases`. ## The pass `CHANGELOG.md`: **1302 lines → 180**. Every entry in every section, including the shipped ones. Before: ```markdown - **`state:needs-human` no longer waits on the cron to become true** (#141) — the labels workflow now also wakes on `pull_request_target: labeled` and `unlabeled`, and the author sets `state:needs-human` themselves when handing a PR to the maintainer. A review landing was never a trigger. There is no `pull_request_review_target`, and on fork PRs — which is all of them here — `pull_request_review` runs with a read-only token and cannot label anything. [...25 more lines...] ``` After: ```markdown - `state:needs-human` is set at handoff, not by the cron (#141) ``` ## What was preserved, and how it was checked The mechanical risks here are heading loss and entry loss. Both are asserted, not eyeballed: | Invariant | Check | Result | |---|---|---| | No `## ` heading added, removed, altered or reordered | `git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '` | **no output at all** | | One entry out per entry in | `grep -c '^- '` before/after | 73 → 75 (+1 from the stacked fix PR, +1 for the rule itself) | | Every shipped section still extracts | `release-notes.sh` 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0 | all non-empty | | Intro prose | unchanged | byte-identical | That first row is the load-bearing one — `changelog-monotonic.sh` fails the build if a `## X.Y.Z` heading disappears, and `release-notes.sh` extracts by exact heading match, so the published release bodies depend on those lines surviving verbatim. They do. Subheading grouping (`### Added` / `### Changed` / `### Fixed`) and entry order are preserved. No section had duplicate subheadings to merge. ## Two judgement calls 1. **One `BREAKING:` marker was added that the file did not have** — on the #123 template rename (`claude` → `claude-box`, …). The entry's own text says rig's roles are a hard cut with no aliases and that a pre-rename spelling produces a failed mint, which is breaking by any reading; rig marks the same change the same way. The 0.5.0 debrand was deliberately **not** marked, because that section's intro explicitly promises everything legacy-facing is honored forever. 2. **Secondary refs buried mid-essay were dropped**, headline refs all kept. `(#141)` survives; the `heavy-duty/rig#97` cited three paragraphs into its body does not. The linked issue carries the rest — that is the point of citing it. ## Consequence worth stating The GitHub release bodies already published for 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0 were generated from the old prose, so they no longer match this file. Re-pushing them from the rewritten sections is queued as a follow-up once this lands.

danmt (Migrated from github.com) reviewed 2026-07-21 13:55:51 +00:00

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

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

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

Why

Same house rule + full pass. CONTRIBUTING.md documents one-line entries above ## Releases.
Invariants hold: no ## heading churn; 73→75 bullets (+ stacked #146 fix + the rule); subheading groups and entry order preserved; shipped 0.8.0…0.5.0 still extract; CI green including rehearsal.
BREAKING: on the #123 template rename is justified (hard cut, no aliases — matches rig). 0.5.0 debrand correctly left unmarked.
Stacked base includes the #146 ceremony-tree release-suite fix — right place for it before a release PR.

@ 683217e

**Verdict: Approve** — I agree with this as-is. ### Why - Same house rule + full pass. `CONTRIBUTING.md` documents one-line entries above `## Releases`. - Invariants hold: no `## ` heading churn; 73→75 bullets (+ stacked #146 fix + the rule); subheading groups and entry order preserved; shipped 0.8.0…0.5.0 still extract; CI green including rehearsal. - `BREAKING:` on the #123 template rename is justified (hard cut, no aliases — matches rig). 0.5.0 debrand correctly left unmarked. - Stacked base includes the #146 ceremony-tree release-suite fix — right place for it before a release PR. @ 683217e

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

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

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

I re-ran the invariants independently from the diff rather than trusting the table: zero ## heading lines added or removed, zero ### subheading lines touched, and entry lines go 73 → 75 — exactly the stacked #146 entry plus the rule's own. The rewritten one-liners I sampled are faithful (surface-first, headline refs kept) and the added BREAKING: on the #123 template rename is right by the entry's own text — a failed mint on the old spelling is breaking, and it matches rig's treatment of the same change. The CONTRIBUTING ## Changelog entries section is the rule stated once with a good/bad pair, which is all it needs. The test/release.sh hunk is #146, already reviewed there. Re-pushing the shipped release bodies as a follow-up is the right sequencing.

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

✅ **Approved — I agree with all of this, no concerns.** I re-ran the invariants independently from the diff rather than trusting the table: zero `## ` heading lines added or removed, zero `### ` subheading lines touched, and entry lines go 73 → 75 — exactly the stacked #146 entry plus the rule's own. The rewritten one-liners I sampled are faithful (surface-first, headline refs kept) and the added `BREAKING:` on the #123 template rename is right by the entry's own text — a failed mint on the old spelling is breaking, and it matches rig's treatment of the same change. The CONTRIBUTING `## Changelog entries` section is the rule stated once with a good/bad pair, which is all it needs. The `test/release.sh` hunk is #146, already reviewed there. Re-pushing the shipped release bodies as a follow-up is the right sequencing. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-21 14:17:27 +00:00

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

Verdict: I agree with everything and have no additional feedback. The full pass preserves release headings and entry count, accurately marks the hard template rename as breaking, and the stacked functional fix and all current checks are acceptable.

dan-claude-bot commented

2026-07-21 14:29:17 +00:00

(Migrated from github.com)

@danmt — round 1 closed, all three bots approving with no changes requested. Handing this over.

What it does

Adopts the one-line changelog rule (your call this cycle), documents it in CONTRIBUTING.md as ## Changelog entries above ## Releases, and applies the full pass: CHANGELOG.md 1302 lines → 180, every entry in every section including the shipped ones.

The rule: say what changed, cite the issue, stop. Rationale lives in the PR body and commit message.

Round history

One round, three approvals, zero changes requested, no nits:

Reviewer	Verdict	Substance
`grok-bot-andresmgsl`	APPROVED	invariants hold; `BREAKING:` on #123 justified; 0.5.0 debrand correctly left unmarked
`claude-bot-andresmgsl`	APPROVED	re-ran the invariants independently from the diff rather than trusting my table — zero `##` lines touched, 73 → 75 entries
`codex-bot-andresmgsl`	APPROVED	no additional feedback

Verification

The two destructive risks are asserted, not eyeballed:

Invariant	Check	Result
No `##` heading added/removed/altered/reordered	`git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '`	no output at all
One entry out per entry in	`grep -c '^- '`	73 → 75 (+1 stacked #146, +1 the rule)
Shipped sections still extract	`release-notes.sh` 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0	all non-empty
CI	check, scope, rehearsal, reconcile	green

That first row is load-bearing — changelog-monotonic.sh fails the build if a ## X.Y.Z heading disappears, and release-notes.sh extracts published release bodies by exact heading match.

Payoff: box's 0.9.0 section now extracts 45 lines where the old prose would have published 580.

Two things for your judgement

I added one BREAKING: marker the file never had — on the #123 template rename (claude → claude-box). The entry's own text calls it a hard cut with no aliases where a pre-rename spelling produces a failed mint, and rig marks the same change the same way. Both bots that commented on it agreed, but it is me adding a claim the source did not make, so it is yours to veto — one line to revert. I deliberately did not mark the 0.5.0 debrand, because that section's intro explicitly promises everything legacy-facing is honored forever.
Secondary refs buried mid-essay were dropped, headline refs all kept. (#141) survives; a heavy-duty/rig#97 cited three paragraphs into a body does not.

Consequence, queued as follow-up

The GitHub release bodies already published for 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0 were generated from the old prose and no longer match this file. Re-pushing them from the rewritten sections is queued once this lands — flagging so it is a decision you have seen, not a surprise.

Ordering

#146 fix → #147 (this) → #148 release: 0.9.0. Sits on #146; wants to land second.

@danmt — round 1 closed, all three bots approving with no changes requested. Handing this over. ## What it does Adopts the one-line changelog rule (your call this cycle), documents it in `CONTRIBUTING.md` as `## Changelog entries` above `## Releases`, and applies the full pass: **`CHANGELOG.md` 1302 lines → 180**, every entry in every section including the shipped ones. The rule: say what changed, cite the issue, stop. Rationale lives in the PR body and commit message. ## Round history One round, three approvals, zero changes requested, no nits: | Reviewer | Verdict | Substance | |---|---|---| | `grok-bot-andresmgsl` | APPROVED | invariants hold; `BREAKING:` on #123 justified; 0.5.0 debrand correctly left unmarked | | `claude-bot-andresmgsl` | APPROVED | **re-ran the invariants independently from the diff** rather than trusting my table — zero `## ` lines touched, 73 → 75 entries | | `codex-bot-andresmgsl` | APPROVED | no additional feedback | ## Verification The two destructive risks are asserted, not eyeballed: | Invariant | Check | Result | |---|---|---| | No `## ` heading added/removed/altered/reordered | `git diff origin/main -- CHANGELOG.md \| grep -E '^[-+]## '` | **no output at all** | | One entry out per entry in | `grep -c '^- '` | 73 → 75 (+1 stacked #146, +1 the rule) | | Shipped sections still extract | `release-notes.sh` 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0 | all non-empty | | CI | check, scope, rehearsal, reconcile | green | That first row is load-bearing — `changelog-monotonic.sh` fails the build if a `## X.Y.Z` heading disappears, and `release-notes.sh` extracts published release bodies by exact heading match. Payoff: box's 0.9.0 section now extracts **45 lines** where the old prose would have published **580**. ## Two things for your judgement 1. **I added one `BREAKING:` marker the file never had** — on the #123 template rename (`claude` → `claude-box`). The entry's own text calls it a hard cut with no aliases where a pre-rename spelling produces a failed mint, and rig marks the same change the same way. Both bots that commented on it agreed, but it is me adding a claim the source did not make, so it is yours to veto — one line to revert. I deliberately did **not** mark the 0.5.0 debrand, because that section's intro explicitly promises everything legacy-facing is honored forever. 2. **Secondary refs buried mid-essay were dropped**, headline refs all kept. `(#141)` survives; a `heavy-duty/rig#97` cited three paragraphs into a body does not. ## Consequence, queued as follow-up The GitHub release bodies already published for 0.8.0 / 0.7.0 / 0.6.0 / 0.5.0 were generated from the old prose and no longer match this file. Re-pushing them from the rewritten sections is queued once this lands — flagging so it is a decision you have seen, not a surprise. ## Ordering `#146 fix` → `#147 (this)` → `#148 release: 0.9.0`. Sits on #146; wants to land second.