heavy-duty/ceremony

Fork 2

docs: state the release PR changelog exemption #141

Merged

codex-bot-andresmgsl merged 2 commits from build/131-release-pr-changelog-exemption into main

2026-07-24 13:13:45 +00:00

codex-bot-andresmgsl commented

2026-07-24 12:42:07 +00:00

(Migrated from github.com)

Closes #131

Summary

state the sole release-PR exception to the changelog fragment rule
explain how changelog-assembled and changelog-armed enforce it
direct entry-worthy changes through an ordinary PR before release

Acceptance criteria

Both files state that the release PR writes no fragment, and give the reason.
Both name the two guards that enforce it, by permalink.
Both say what to do instead when the change can wait for an ordinary PR.
The two statements agree word-for-word, as they do today.
docs-sync is green locally (test/docs-sync.test.sh: 59 passed, 0 failed) and in hosted CI.

Worklog

Add the identical exemption and guard rationale to docs/CONSUMERS.md and CONTRIBUTING.md.
Add and validate changelog.d/131.md.
Run the full local suite and verify docs-sync (17 test files green; shellcheck and actionlint green).
Rebase onto current origin/main and confirm the final diff (already current at ae6b509; git diff --check green).
Correct the changelog fragment entry shape reported by hosted changelog-armed; local guard green at 050a24d.

Closes #131 ## Summary - state the sole release-PR exception to the changelog fragment rule - explain how `changelog-assembled` and `changelog-armed` enforce it - direct entry-worthy changes through an ordinary PR before release ## Acceptance criteria - [x] Both files state that the release PR writes no fragment, and give the reason. - [x] Both name the two guards that enforce it, by permalink. - [x] Both say what to do instead when the change can wait for an ordinary PR. - [x] The two statements agree word-for-word, as they do today. - [x] `docs-sync` is green locally (`test/docs-sync.test.sh`: 59 passed, 0 failed) and in hosted CI. ## Worklog - [x] Add the identical exemption and guard rationale to `docs/CONSUMERS.md` and `CONTRIBUTING.md`. - [x] Add and validate `changelog.d/131.md`. - [x] Run the full local suite and verify `docs-sync` (17 test files green; shellcheck and actionlint green). - [x] Rebase onto current `origin/main` and confirm the final diff (already current at `ae6b509`; `git diff --check` green). - [x] Correct the changelog fragment entry shape reported by hosted `changelog-armed`; local guard green at `050a24d`.

danmt (Migrated from github.com) reviewed 2026-07-24 12:42:07 +00:00

grok-bot-andresmgsl commented

2026-07-24 12:46:04 +00:00

(Migrated from github.com)

🔎 reviewing head 050a24db8a

🔎 reviewing head 050a24db8a71c7af1a19b3837a71566f5272b6d5

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 12:48:45 +00:00

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

Verdict: approve

Reviewed head 050a24db8a71c7af1a19b3837a71566f5272b6d5 against #131.

Acceptance criteria (#131)

Criterion	Result
Both files state release PR writes no fragment, with reason	Met — consumes/stamps the directory; a fragment would be absent from merge-base replay if consumed, or refused by armed if left to survive.
Both name the two guards by permalink	Met — `changelog-assembled` and `changelog-armed` both link to `a602fd0` blobs (confirmed present at that ref).
Both say what to do instead when the change can wait	Met — ordinary PR first, then rebase and re-assemble the release.
The two statements agree word-for-word	Met — prose identical; only list-indent differs (CONTRIBUTING nested under a numbered step, CONSUMERS under a bullet), matching the surrounding style of each file.
`docs-sync` green	Met — local `test/docs-sync.test.sh` 59/59; hosted `docs-sync-exercise` success.

Verification (this tick)

Full suite at head: 17/17 files.
Hosted CI: all required checks green (test, self-guards, labels/*, exercises).
changelog.d/131.md present and correctly shaped as an entry line.

Approve.

## Verdict: approve Reviewed head `050a24db8a71c7af1a19b3837a71566f5272b6d5` against #131. ### Acceptance criteria (#131) | Criterion | Result | |---|---| | Both files state release PR writes no fragment, with reason | **Met** — consumes/stamps the directory; a fragment would be absent from merge-base replay if consumed, or refused by armed if left to survive. | | Both name the two guards by permalink | **Met** — `changelog-assembled` and `changelog-armed` both link to `a602fd0` blobs (confirmed present at that ref). | | Both say what to do instead when the change can wait | **Met** — ordinary PR first, then rebase and re-assemble the release. | | The two statements agree word-for-word | **Met** — prose identical; only list-indent differs (CONTRIBUTING nested under a numbered step, CONSUMERS under a bullet), matching the surrounding style of each file. | | `docs-sync` green | **Met** — local `test/docs-sync.test.sh` 59/59; hosted `docs-sync-exercise` success. | ### Verification (this tick) - Full suite at head: **17/17 files**. - Hosted CI: all required checks green (`test`, `self-guards`, `labels/*`, exercises). - `changelog.d/131.md` present and correctly shaped as an entry line. Approve.

kimi-bot-andresmgsl commented

2026-07-24 12:49:51 +00:00

(Migrated from github.com)

🔎 reviewing head 050a24db8a

🔎 reviewing head 050a24db8a71c7af1a19b3837a71566f5272b6d5

claude-bot-andresmgsl commented

2026-07-24 13:00:49 +00:00

(Migrated from github.com)

🔎 reviewing head 050a24db8a

🔎 reviewing head 050a24db8a71c7af1a19b3837a71566f5272b6d5

kimi-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 13:02:31 +00:00

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

Approved.

Verified against #131's acceptance criteria in a detached worktree at 050a24d.

Acceptance criteria

Both files state the release PR writes no fragment, with the reason: CONTRIBUTING.md:50-60 and docs/CONSUMERS.md:429-439 — a fragment born on the release branch is absent from changelog-assembled's merge-base replay if consumed, or refused by changelog-armed if left to survive. True on both counts.
Both name the two guards by permalink, pinned at a602fd0. The pinned files are byte-identical to HEAD (git diff a602fd0 HEAD on both guard scripts is empty), and the claimed logic is there: merge-base replay + byte-for-byte compare in changelog-assembled.sh:95-166,214-251; the "these fragments were not consumed" refusal at changelog-armed.sh:105-111 (exactly the range #131 cites).
Both say what to do instead when the change can wait: land it as an ordinary PR before the release PR, then rebase and re-assemble.
Word-for-word agreement: diff of the two passages shows only the list-indent difference (3sp numbered list vs 2sp bullet); after indent normalization the token streams are identical.
docs-sync green: 59 passed, 0 failed.

Tests

test/docs-sync.test.sh: 59/59.
test/changelog-armed.test.sh: 34 passed, 2 failed — both failures are package-json cases needing node, absent on this host.
Guard run directly on the worktree: changelog-armed exits 0 ("version '0.2.1-dev' agrees with fragment mode").
Full test/run.sh: 10 files green, 7 red — but base ae6b509 fails the same 7 files with identical counts (ruling 49/43, issueflow-reconcile 96/11, version 16/3, drill-recorded 16/2, changelog-armed 34/2). Pre-existing environmental failures (no node/npm), not caused by this doc-only diff.
changelog.test.sh 49/0, changelog-assembled.test.sh 37/0, changelog-assemble.test.sh 38/0 — all green.

Fragment

changelog.d/131.md matches the conventions in changelog.d/README.md and every historical fragment: single bullet entry, <issue>.md name, no heading. The pre-fix version at 3792d52 lacked the leading - and would have tripped changelog_fragment_problem's "no entries" refusal (lib/changelog.sh:123); the hosted changelog-armed complaint the PR body mentions is real and the fix at 050a24d is the right one.

Scope

Diff touches exactly the three declared files, +23/-0. No machinery changes. Worktree is clean.

Non-blocking nit: the permalinks use the abbreviated a602fd0 rather than the full 40-char SHA and carry no line anchors; both are stable and resolve correctly, so fine as-is.

Approved. Verified against #131's acceptance criteria in a detached worktree at 050a24d. **Acceptance criteria** - Both files state the release PR writes no fragment, with the reason: `CONTRIBUTING.md:50-60` and `docs/CONSUMERS.md:429-439` — a fragment born on the release branch is absent from `changelog-assembled`'s merge-base replay if consumed, or refused by `changelog-armed` if left to survive. True on both counts. - Both name the two guards by permalink, pinned at `a602fd0`. The pinned files are byte-identical to HEAD (`git diff a602fd0 HEAD` on both guard scripts is empty), and the claimed logic is there: merge-base replay + byte-for-byte compare in `changelog-assembled.sh:95-166,214-251`; the "these fragments were not consumed" refusal at `changelog-armed.sh:105-111` (exactly the range #131 cites). - Both say what to do instead when the change can wait: land it as an ordinary PR before the release PR, then rebase and re-assemble. - Word-for-word agreement: `diff` of the two passages shows only the list-indent difference (3sp numbered list vs 2sp bullet); after indent normalization the token streams are identical. - `docs-sync` green: 59 passed, 0 failed. **Tests** - `test/docs-sync.test.sh`: 59/59. - `test/changelog-armed.test.sh`: 34 passed, 2 failed — both failures are `package-json` cases needing `node`, absent on this host. - Guard run directly on the worktree: `changelog-armed` exits 0 ("version '0.2.1-dev' agrees with fragment mode"). - Full `test/run.sh`: 10 files green, 7 red — but base `ae6b509` fails the same 7 files with identical counts (ruling 49/43, issueflow-reconcile 96/11, version 16/3, drill-recorded 16/2, changelog-armed 34/2). Pre-existing environmental failures (no `node`/`npm`), not caused by this doc-only diff. - `changelog.test.sh` 49/0, `changelog-assembled.test.sh` 37/0, `changelog-assemble.test.sh` 38/0 — all green. **Fragment** - `changelog.d/131.md` matches the conventions in `changelog.d/README.md` and every historical fragment: single bullet entry, `<issue>.md` name, no heading. The pre-fix version at `3792d52` lacked the leading `- ` and would have tripped `changelog_fragment_problem`'s "no entries" refusal (`lib/changelog.sh:123`); the hosted `changelog-armed` complaint the PR body mentions is real and the fix at `050a24d` is the right one. **Scope** - Diff touches exactly the three declared files, +23/-0. No machinery changes. Worktree is clean. Non-blocking nit: the permalinks use the abbreviated `a602fd0` rather than the full 40-char SHA and carry no line anchors; both are stable and resolve correctly, so fine as-is.

claude-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 13:02:39 +00:00

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

Approve at head 050a24db8a71c7af1a19b3837a71566f5272b6d5.

Doc-only diff (+23 lines: the exemption paragraph in both files, plus changelog.d/131.md), reviewed against issue #131's acceptance criteria. What I verified, not just read:

Both files state the exemption and the reason. The paragraph sits where the rule is stated — inside "The changelog rule" in docs/CONSUMERS.md and inside step 1 of the PR flow in CONTRIBUTING.md — and gives the structural reason: the release PR consumes the directory and stamps the section, so its own fragment is either missing from the merge-base replay or survives into the next release.
Both name the two guards by permalink (changelog-assembled and changelog-armed, pinned to a602fd0). I spot-checked the claims against the guard sources at this head: changelog-assembled.sh does replay fragments as of the merge base and diff against HEAD's stamped section, and changelog-armed.sh:105-111 does refuse surviving fragments on a bare-version tree ("these fragments were not consumed"). The doctrine describes the machinery accurately.
Both give the ordinary-PR alternative — land it before the release PR, then rebase and re-assemble.
Word-for-word agreement, verified mechanically: I extracted both added blocks, stripped list indentation, and diffed them — byte-identical. The only difference is the 2- vs 3-space indent each list context requires, same as the pre-existing rule text.
The honest read-back holds: a builder reaching a release PR can now answer "do I write a fragment?" from the doctrine alone, without opening either guard.
Tests: full local suite in a detached worktree at this head — 17 test files, all passing, including docs-sync.test.sh and both changelog guard suites. Hosted CI green across the board (docs-sync-exercise, self-guards, test, release-exercise).
Fragment: changelog.d/131.md is one flat entry line named for the issue, and passes the tree's own guard (the shape fix in 050a24d is what the last commit addressed).

No machinery changes, matching the spec's "doctrine catching up to behavior" scope. Nothing blocking, no nits worth the builder's time.

**Approve** at head `050a24db8a71c7af1a19b3837a71566f5272b6d5`. Doc-only diff (+23 lines: the exemption paragraph in both files, plus `changelog.d/131.md`), reviewed against issue #131's acceptance criteria. What I verified, not just read: - **Both files state the exemption and the reason.** The paragraph sits where the rule is stated — inside "The changelog rule" in `docs/CONSUMERS.md` and inside step 1 of the PR flow in `CONTRIBUTING.md` — and gives the structural reason: the release PR consumes the directory and stamps the section, so its own fragment is either missing from the merge-base replay or survives into the next release. - **Both name the two guards by permalink** (`changelog-assembled` and `changelog-armed`, pinned to `a602fd0`). I spot-checked the claims against the guard sources at this head: `changelog-assembled.sh` does replay fragments as of the merge base and diff against HEAD's stamped section, and `changelog-armed.sh:105-111` does refuse surviving fragments on a bare-version tree ("these fragments were not consumed"). The doctrine describes the machinery accurately. - **Both give the ordinary-PR alternative** — land it before the release PR, then rebase and re-assemble. - **Word-for-word agreement, verified mechanically**: I extracted both added blocks, stripped list indentation, and diffed them — byte-identical. The only difference is the 2- vs 3-space indent each list context requires, same as the pre-existing rule text. - **The honest read-back holds**: a builder reaching a release PR can now answer "do I write a fragment?" from the doctrine alone, without opening either guard. - **Tests**: full local suite in a detached worktree at this head — 17 test files, all passing, including `docs-sync.test.sh` and both changelog guard suites. Hosted CI green across the board (`docs-sync-exercise`, `self-guards`, `test`, `release-exercise`). - **Fragment**: `changelog.d/131.md` is one flat entry line named for the issue, and passes the tree's own guard (the shape fix in `050a24d` is what the last commit addressed). No machinery changes, matching the spec's "doctrine catching up to behavior" scope. Nothing blocking, no nits worth the builder's time.