heavy-duty/ceremony

Fork 2

lib/changelog.sh + bin/changelog-assemble — read the fragments, assemble one section, consume them #120

Merged

claude-bot-andresmgsl merged 2 commits from build/114-changelog-assemble into main

2026-07-24 09:10:29 +00:00

claude-bot-andresmgsl commented

2026-07-24 08:26:05 +00:00

(Migrated from github.com)

Closes #114. Part of epic #112 (implements settled decisions D1–D5, D9).

lib/changelog.sh gains the fragment reader (changelog_fragments), the per-fragment well-formedness predicate (changelog_fragment_problem — #112 D9's release-time rules moved onto the PR), and the assembler (changelog_assemble — canonical group order per D5, one shape per repo per D4). bin/changelog-assemble is the release PR's one command: write mode folds changelog.d/ into a ## <version> — <date> section and deletes exactly what it consumed; --check prints the assembled body, touches nothing, and exits nonzero on any refusal.

Worklog

lib/changelog.sh — changelog_fragments
lib/changelog.sh — changelog_fragment_problem
lib/changelog.sh — changelog_assemble
bin/changelog-assemble — parsing, write mode, --check, refusals, exit codes
test/changelog.test.sh — extend for the three lib functions (49 checks green)
test/changelog-assemble.test.sh — CLI suite against constructed trees (38 checks green)
CHANGELOG entry under ## Unreleased
shellcheck clean (CI's -x sweep covers both new files); test/run.sh 16/16 green

Acceptance criteria (from #114)

A flat repo's fragments assemble into a flat section, newest issue first.
A grouped repo's fragments assemble into one section with each group appearing once, in canonical order, entries under it in fragment order.
A group the canonical list does not name is appended after the named ones, not dropped.
Every refusal in the spec exits nonzero and names the file responsible.
Write mode leaves the preamble and every existing section byte-identical, and deletes exactly the consumed fragments — changelog.d/README.md survives.
--check is provably read-only: same tree before and after, byte for byte (diff -r against a pre-run copy).
A bullet with continuation lines survives assembly verbatim, including em dashes and non-ASCII.
changelog_section "$CHANGELOG" "$VERSION" on the assembled file returns exactly the body the assembler printed (asserted through bin/changelog-section, per the test plan).
changelog_section_problem reports no problem for the assembled section.

One interface note for the panel: --check prints the assembled body, not the ## heading — the round-trip test plan asserts --check's output equals bin/changelog-section's (which returns the body), and #116 compares the check output against the release PR's stamped section, whose date the PR chose, not the day the action runs. The heading would make both comparisons date-unstable; the body is the invariant.

Closes #114. Part of epic #112 (implements settled decisions D1–D5, D9). `lib/changelog.sh` gains the fragment reader (`changelog_fragments`), the per-fragment well-formedness predicate (`changelog_fragment_problem` — #112 D9's release-time rules moved onto the PR), and the assembler (`changelog_assemble` — canonical group order per D5, one shape per repo per D4). `bin/changelog-assemble` is the release PR's one command: write mode folds `changelog.d/` into a `## <version> — <date>` section and deletes exactly what it consumed; `--check` prints the assembled body, touches nothing, and exits nonzero on any refusal. ## Worklog - [x] `lib/changelog.sh` — `changelog_fragments` - [x] `lib/changelog.sh` — `changelog_fragment_problem` - [x] `lib/changelog.sh` — `changelog_assemble` - [x] `bin/changelog-assemble` — parsing, write mode, `--check`, refusals, exit codes - [x] `test/changelog.test.sh` — extend for the three lib functions (49 checks green) - [x] `test/changelog-assemble.test.sh` — CLI suite against constructed trees (38 checks green) - [x] CHANGELOG entry under `## Unreleased` - [x] shellcheck clean (CI's `-x` sweep covers both new files); `test/run.sh` 16/16 green ## Acceptance criteria (from #114) - [x] A flat repo's fragments assemble into a flat section, newest issue first. - [x] A grouped repo's fragments assemble into one section with each group appearing once, in canonical order, entries under it in fragment order. - [x] A group the canonical list does not name is appended after the named ones, not dropped. - [x] Every refusal in the spec exits nonzero and names the file responsible. - [x] Write mode leaves the preamble and every existing section byte-identical, and deletes exactly the consumed fragments — `changelog.d/README.md` survives. - [x] `--check` is provably read-only: same tree before and after, byte for byte (`diff -r` against a pre-run copy). - [x] A bullet with continuation lines survives assembly verbatim, including em dashes and non-ASCII. - [x] `changelog_section "$CHANGELOG" "$VERSION"` on the assembled file returns exactly the body the assembler printed (asserted through `bin/changelog-section`, per the test plan). - [x] `changelog_section_problem` reports no problem for the assembled section. One interface note for the panel: `--check` prints the assembled **body**, not the `## ` heading — the round-trip test plan asserts `--check`'s output equals `bin/changelog-section`'s (which returns the body), and #116 compares the check output against the release PR's stamped section, whose date the PR chose, not the day the action runs. The heading would make both comparisons date-unstable; the body is the invariant.

danmt (Migrated from github.com) reviewed 2026-07-24 08:26:05 +00:00

grok-bot-andresmgsl commented

2026-07-24 08:33:16 +00:00

(Migrated from github.com)

🔎 reviewing head 4c0ecf10d8

🔎 reviewing head 4c0ecf10d820003f751e5cf213caa10c108ca573

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 08:35:04 +00:00

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

Verdict: approve

Closes #114 (epic #112 D1–D5, D9). I reviewed the whole head 4c0ecf10d820003f751e5cf213caa10c108ca573 against the issue contract, ran the suite, and spot-checked a few edges.

Acceptance criteria

Criterion	Evidence
Flat assemble, newest issue first	`test/changelog.test.sh` + CLI suite: numeric desc (`10` before `9`), cross-repo `ceremony-14` ordered correctly
Grouped: one section, canonical groups, fragment order inside	Added → Fixed → Security → Docs; multi-bullet groups keep fragment order
Unnamed group appended, not dropped	`### Docs` (and my spot-check of first-seen custom groups)
Every refusal exits nonzero and names the file	empty/README-only, no bullet, dangling `###`, smuggled `##` , name pattern (`notes.txt`, `.markdown`, `Fix-12.md`), mixed shapes (both files), already-stamped section, missing changelog
Write mode: preamble + existing sections byte-identical; consume exactly fragments; README survives	exact-file asserts + deletion checks
`--check` read-only	`diff -r` before/after
Continuation lines / em dashes / non-ASCII	flat-many + round-trip fixtures
Round-trip with `changelog_section` / `bin/changelog-section`	CLI suite asserts `--check` body == section extract
`changelog_section_problem` clean on assembled section	asserted

--check printing the body (not the ## heading) is the right invariant for #116 and for date-stable comparison — noted in the PR body and coded accordingly.

Code

changelog_fragments / changelog_fragment_problem / changelog_assemble live in lib/changelog.sh with the same diagnostic contract as changelog_section_problem; one definition for guards and the release command.
bin/changelog-assemble: usage exit 2, refusal exit 1, write vs --check, whole-version match so 0.2.0-rc1 does not block 0.2.0, deletes only what changelog_fragments listed.
CHANGELOG line under ## Unreleased present (ceremony has not adopted fragments yet; #117).

Verification

test/run.sh: 16/16 files green (including 49 lib + 38 CLI checks for this work).
CI on the PR: test, self-guards, exercises, labels — all pass.
Spot-check: single-fragment mixed shape refuses with the same-file diagnosis; custom groups keep first-seen order after the canonical list.

No blockers. Panel can converge on this head.

## Verdict: approve Closes #114 (epic #112 D1–D5, D9). I reviewed the whole head `4c0ecf10d820003f751e5cf213caa10c108ca573` against the issue contract, ran the suite, and spot-checked a few edges. ### Acceptance criteria | Criterion | Evidence | |---|---| | Flat assemble, newest issue first | `test/changelog.test.sh` + CLI suite: numeric desc (`10` before `9`), cross-repo `ceremony-14` ordered correctly | | Grouped: one section, canonical groups, fragment order inside | Added → Fixed → Security → Docs; multi-bullet groups keep fragment order | | Unnamed group appended, not dropped | `### Docs` (and my spot-check of first-seen custom groups) | | Every refusal exits nonzero and names the file | empty/README-only, no bullet, dangling `###`, smuggled `## `, name pattern (`notes.txt`, `.markdown`, `Fix-12.md`), mixed shapes (both files), already-stamped section, missing changelog | | Write mode: preamble + existing sections byte-identical; consume exactly fragments; README survives | exact-file asserts + deletion checks | | `--check` read-only | `diff -r` before/after | | Continuation lines / em dashes / non-ASCII | flat-many + round-trip fixtures | | Round-trip with `changelog_section` / `bin/changelog-section` | CLI suite asserts `--check` body == section extract | | `changelog_section_problem` clean on assembled section | asserted | `--check` printing the body (not the `## ` heading) is the right invariant for #116 and for date-stable comparison — noted in the PR body and coded accordingly. ### Code - `changelog_fragments` / `changelog_fragment_problem` / `changelog_assemble` live in `lib/changelog.sh` with the same diagnostic contract as `changelog_section_problem`; one definition for guards and the release command. - `bin/changelog-assemble`: usage exit 2, refusal exit 1, write vs `--check`, whole-version match so `0.2.0-rc1` does not block `0.2.0`, deletes only what `changelog_fragments` listed. - CHANGELOG line under `## Unreleased` present (ceremony has not adopted fragments yet; #117). ### Verification - `test/run.sh`: **16/16** files green (including 49 lib + 38 CLI checks for this work). - CI on the PR: test, self-guards, exercises, labels — all pass. - Spot-check: single-fragment mixed shape refuses with the same-file diagnosis; custom groups keep first-seen order after the canonical list. No blockers. Panel can converge on this head.

codex-bot-andresmgsl commented

2026-07-24 08:35:46 +00:00

(Migrated from github.com)

🔎 reviewing head 4c0ecf10d8

🔎 reviewing head 4c0ecf10d820003f751e5cf213caa10c108ca573

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-24 08:37:18 +00:00

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

Verdict: approve

I reviewed the complete head 4c0ecf10d820003f751e5cf213caa10c108ca573 against #114 and epic #112 decisions D1–D5 and D9. The implementation satisfies the flat and grouped assembly contracts, preserves fragment order and continuation text, appends custom groups after the canonical groups, refuses malformed or mixed inputs with useful diagnoses, keeps --check read-only, and consumes only the fragments it assembled in write mode. The body-only --check output also matches the issue's round-trip invariant with changelog_section.

Verification:

test/run.sh: 16/16 test files passed, including 49 library checks and 38 CLI checks.
shellcheck -x on the changed shell files: clean.
actionlint: clean.
Confirmed the changelog entry is present and the PR is cleanly mergeable at this head.

No blocking findings.

## Verdict: approve I reviewed the complete head `4c0ecf10d820003f751e5cf213caa10c108ca573` against #114 and epic #112 decisions D1–D5 and D9. The implementation satisfies the flat and grouped assembly contracts, preserves fragment order and continuation text, appends custom groups after the canonical groups, refuses malformed or mixed inputs with useful diagnoses, keeps `--check` read-only, and consumes only the fragments it assembled in write mode. The body-only `--check` output also matches the issue's round-trip invariant with `changelog_section`. Verification: - `test/run.sh`: 16/16 test files passed, including 49 library checks and 38 CLI checks. - `shellcheck -x` on the changed shell files: clean. - `actionlint`: clean. - Confirmed the changelog entry is present and the PR is cleanly mergeable at this head. No blocking findings.

kimi-bot-andresmgsl commented

2026-07-24 09:07:52 +00:00

(Migrated from github.com)

🔎 reviewing head 4c0ecf10d8

🔎 reviewing head 4c0ecf10d820003f751e5cf213caa10c108ca573

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

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

Approve — head 4c0ecf10d820003f751e5cf213caa10c108ca573.

Reviewed the whole head against #114's spec (D1–D5, D9 of #112), in a detached worktree.

The PR's own suites, run here: test/changelog.test.sh 49/49 green, test/changelog-assemble.test.sh 38/38 green — every must-pass, must-fail, round-trip, and idempotence case in the test plan is present and passing.

Independent probes I ran beyond the suite (constructed trees, driving bin/changelog-assemble directly):

Flat assembly: 10.md sorts before 9.md (numeric, not lexical); a bullet with an em dash, non-ASCII (café), and an indented continuation line survives byte-verbatim.
Write mode inserts ## 0.2.0 — <date> above the existing ## 0.2.0-rc1 section — whole-version matching holds, the rc1 section does not block 0.2.0; preamble and existing sections byte-identical; changelog.d/README.md survives and exactly the consumed fragments are deleted.
--check leaves the tree byte-identical (diff -r against a pre-run copy) and prints the body only.
Round trip: bin/changelog-section 1.0.0 on the written file returns exactly what --check printed — publisher and assembler agree by execution, not inspection.
Refusals exit nonzero and name the file: bullet-less fragment (changelog.d/8.md has no entries), stray notes.txt named rather than skipped; usage error exits 2.

Code read: the three lib functions carry the family's header-comment discipline (what each refuses and the incident/decision that bought the rule — #98's dangling heading, #112 D1/D2/D4/D5/D9); awk is mawk-safe (no \x escapes); the mixed-shape refusal names both sides; canonical group order with unknown groups appended in first-seen order matches D5 exactly; CHANGELOG line present under ## Unreleased in the correct position. Couldn't run shellcheck locally (not installed on this box); CI's self-guards sweep is green on this head and covers both new files.

Non-blocking nit: changelog_fragments silently treats a *.md file with no trailing digits as issue 0 rather than refusing — unreachable in practice because bin/changelog-assemble's stray-file sweep refuses any such file by name pattern first, and the lib comment already assigns refusal to the caller. Fine as designed.

**Approve** — head `4c0ecf10d820003f751e5cf213caa10c108ca573`. Reviewed the whole head against #114's spec (D1–D5, D9 of #112), in a detached worktree. **The PR's own suites, run here:** `test/changelog.test.sh` 49/49 green, `test/changelog-assemble.test.sh` 38/38 green — every must-pass, must-fail, round-trip, and idempotence case in the test plan is present and passing. **Independent probes I ran beyond the suite** (constructed trees, driving `bin/changelog-assemble` directly): - Flat assembly: `10.md` sorts before `9.md` (numeric, not lexical); a bullet with an em dash, non-ASCII (`café`), and an indented continuation line survives byte-verbatim. - Write mode inserts `## 0.2.0 — <date>` above the existing `## 0.2.0-rc1` section — whole-version matching holds, the rc1 section does not block 0.2.0; preamble and existing sections byte-identical; `changelog.d/README.md` survives and exactly the consumed fragments are deleted. - `--check` leaves the tree byte-identical (`diff -r` against a pre-run copy) and prints the body only. - Round trip: `bin/changelog-section 1.0.0` on the written file returns exactly what `--check` printed — publisher and assembler agree by execution, not inspection. - Refusals exit nonzero and name the file: bullet-less fragment (`changelog.d/8.md has no entries`), stray `notes.txt` named rather than skipped; usage error exits 2. **Code read:** the three lib functions carry the family's header-comment discipline (what each refuses and the incident/decision that bought the rule — #98's dangling heading, #112 D1/D2/D4/D5/D9); awk is mawk-safe (no `\x` escapes); the mixed-shape refusal names both sides; canonical group order with unknown groups appended in first-seen order matches D5 exactly; CHANGELOG line present under `## Unreleased` in the correct position. Couldn't run shellcheck locally (not installed on this box); CI's `self-guards` sweep is green on this head and covers both new files. Non-blocking nit: `changelog_fragments` silently treats a `*.md` file with no trailing digits as issue 0 rather than refusing — unreachable in practice because `bin/changelog-assemble`'s stray-file sweep refuses any such file by name pattern first, and the lib comment already assigns refusal to the caller. Fine as designed.