frankenbit/release-toolkit
frankenbit/release-toolkit
15
1
Fork 0
Code Issues 11 Pull requests Projects Releases 106 Packages 1 Wiki Activity Actions

chore(release): v0.21.0 #287

Merged
alex merged 3 commits from release-prep/rolling into main 2026-07-02 17:23:03 +02:00
Conversation 2 Commits 3 Files changed 15 +79 -30
release-bot commented 2026-07-02 14:44:52 +02:00
Member
Copy link

Changelog tooling + release automation: mechanical Cold-Read body linter, fragment template + brevity docs, auto re-pin of toolkit-self wrappers post-cut, and observability fields for cut-timing.

Added

Cold-Read body linter — new reusable-changelog-body-check.yml reusable workflow + scripts/changelog-body-check.sh. Runs 6 mechanical checks on the newest version-block in CHANGELOG.md at PR time: version header + date, standard sections present, forward-reference detection, body length ceiling (5000 chars), bullet/prose consistency, duplicate section headers. Consumers wire it into their pull_request workflow same shape as fragment-check.yml. Toolkit-self dogfood wiring deferred to #290. Closes #282 Layer 1.

Fragment template + brevity docs — new changelog.d/.template.md starter template + docs/conventions.md ### Fragment brevity section. Codifies "outcome + required action in 1-3 sentences" as the human-side density guidance; complements the automated linter. Closes #282 Layer 2.

Auto re-pin of toolkit-self consumer wrappers — reusable-release.yml now auto-re-pins release.yml + manifest-check.yml + fragment-check.yml to the just-cut tag as part of post-cut bookkeeping. Bundled with the bake-reset commit so both land atomically. Obsoletes the manual re-pin PR that check-self-bootstrap.yml (#124) previously fired as a reminder for. External consumers are unaffected — the auto-re-pin targets toolkit-self only; if [[ -f ... ]] guard skips non-existent files. Closes #283.

cut_complete.ms_total + path — the cut_complete JSON event now carries ms_total (total cut wall-clock in integer milliseconds) and path (the alpha/gamma push-path). Off the workflow path (direct draft-release.sh invocation, or platform date lacking %N) both fields degrade to empty — the same graceful-degradation contract as api_call's ms. Completes the JSON-logging taxonomy from #159. (Part 2 of #204.)

Changed

check-self-bootstrap.yml scope narrowed — now fires only when the auto re-pin (#283) fails, not as a "human forgot" reminder. Consumers who relied on this check as a manual-re-pin nudge should transition to the auto re-pin flow; check-self-bootstrap.yml stays as a substrate-failure fail-safe.

docs/integration.md post-#172 migration note — corrected to reflect empirically-observed Forgejo behavior: undeclared inputs to workflow_call reusables are silently ignored. The lazy-leave shape (bump @<ref> past #172, forget to drop toolkit_ref:) runs cleanly. Dropping the stale input is a hygiene fix, not a correctness fix. Closes #250.

Fixed

Fragment-check baked ref stuck at main for v0.20.0 consumers — v0.20.0 shipped reusable-changelog-fragment-check.yml with BUILD_BAKED_TOOLKIT_REF: 'main' because reusable-release.yml's three runtime bake-reset loops (added in #278) only listed the two pre-existing reusables. Impact for consumers pinning @v0.20.0 on the fragment-check wrapper: .release-toolkit scripts checked out at main (the baked value) rather than v0.20.0 — substrate drift class. Upgrade action: re-pin fragment-check to @v0.21.0 (the normal post-cut re-pin) to resolve. Extended tests/workflows.bats bake-marker guard now walks reusable-release.yml's runtime loops so the class can't reintroduce. (Fold-in from #283 work.)

Auto re-pin loops corrupted external consumer wrappers — without a toolkit-self gate, the auto re-pin (new in #283) would rewrite release.yml / manifest-check.yml / fragment-check.yml on any external consumer's checkout, breaking their pin state and their next CI run's reusable resolution. Both path-α and path-γ auto re-pin loops are now gated on if [[ -f .forgejo/workflows/reusable-release.yml ]] (the toolkit-self detection). Caught pre-merge; no external consumer was affected in the wild.

Cold-Read linter dogfood wrapper mis-scoped pre-cut — the toolkit-self dogfood wrapper for the Cold-Read body linter was dropped from #289 because the pre-v0.21.0 window has no consistent pin target (@main breaks single-ref-alignment; @v0.21.0-rc.N doesn't yet contain the reusable). Deferred to #290 (post-v0.21.0-cut fold), same pattern as #281.

Internal

update-doc-version-refs.sh self-git add removed — release-prep.sh's #236 auto-stage sweeps hook-modified tracked files, so the belt-and-suspenders self-stage from #251 is redundant. Closes #253.

Removed / Deprecated

None.

Upgrade

No action required for consumers on @v0.20.0 unless the Fragment-check baked-ref bug (see Fixed) applies — re-pin fragment-check.yml to @v0.21.0 in that case. The Cold-Read body linter and fragment template are opt-in.

Changelog tooling + release automation: mechanical Cold-Read body linter, fragment template + brevity docs, auto re-pin of toolkit-self wrappers post-cut, and observability fields for cut-timing. ### Added **Cold-Read body linter** — new `reusable-changelog-body-check.yml` reusable workflow + `scripts/changelog-body-check.sh`. Runs 6 mechanical checks on the newest version-block in `CHANGELOG.md` at PR time: version header + date, standard sections present, forward-reference detection, body length ceiling (5000 chars), bullet/prose consistency, duplicate section headers. Consumers wire it into their `pull_request` workflow same shape as `fragment-check.yml`. Toolkit-self dogfood wiring deferred to #290. Closes #282 Layer 1. **Fragment template + brevity docs** — new `changelog.d/.template.md` starter template + `docs/conventions.md` `### Fragment brevity` section. Codifies "outcome + required action in 1-3 sentences" as the human-side density guidance; complements the automated linter. Closes #282 Layer 2. **Auto re-pin of toolkit-self consumer wrappers** — `reusable-release.yml` now auto-re-pins `release.yml` + `manifest-check.yml` + `fragment-check.yml` to the just-cut tag as part of post-cut bookkeeping. Bundled with the bake-reset commit so both land atomically. Obsoletes the manual re-pin PR that `check-self-bootstrap.yml` (#124) previously fired as a reminder for. External consumers are unaffected — the auto-re-pin targets toolkit-self only; `if [[ -f ... ]]` guard skips non-existent files. Closes #283. **`cut_complete.ms_total` + `path`** — the `cut_complete` JSON event now carries `ms_total` (total cut wall-clock in integer milliseconds) and `path` (the `alpha`/`gamma` push-path). Off the workflow path (direct `draft-release.sh` invocation, or platform `date` lacking `%N`) both fields degrade to empty — the same graceful-degradation contract as `api_call`'s `ms`. Completes the JSON-logging taxonomy from #159. (Part 2 of #204.) ### Changed **`check-self-bootstrap.yml` scope narrowed** — now fires only when the auto re-pin (#283) fails, not as a "human forgot" reminder. Consumers who relied on this check as a manual-re-pin nudge should transition to the auto re-pin flow; `check-self-bootstrap.yml` stays as a substrate-failure fail-safe. **`docs/integration.md` post-#172 migration note** — corrected to reflect empirically-observed Forgejo behavior: undeclared inputs to `workflow_call` reusables are silently ignored. The lazy-leave shape (bump `@<ref>` past #172, forget to drop `toolkit_ref:`) runs cleanly. Dropping the stale input is a hygiene fix, not a correctness fix. Closes #250. ### Fixed **Fragment-check baked ref stuck at `main` for v0.20.0 consumers** — v0.20.0 shipped `reusable-changelog-fragment-check.yml` with `BUILD_BAKED_TOOLKIT_REF: 'main'` because `reusable-release.yml`'s three runtime bake-reset loops (added in #278) only listed the two pre-existing reusables. **Impact for consumers pinning `@v0.20.0` on the fragment-check wrapper**: `.release-toolkit` scripts checked out at `main` (the baked value) rather than `v0.20.0` — substrate drift class. **Upgrade action**: re-pin fragment-check to `@v0.21.0` (the normal post-cut re-pin) to resolve. Extended `tests/workflows.bats` bake-marker guard now walks `reusable-release.yml`'s runtime loops so the class can't reintroduce. (Fold-in from #283 work.) **Auto re-pin loops corrupted external consumer wrappers** — without a toolkit-self gate, the auto re-pin (new in #283) would rewrite `release.yml` / `manifest-check.yml` / `fragment-check.yml` on any external consumer's checkout, breaking their pin state and their next CI run's reusable resolution. Both path-α and path-γ auto re-pin loops are now gated on `if [[ -f .forgejo/workflows/reusable-release.yml ]]` (the toolkit-self detection). Caught pre-merge; no external consumer was affected in the wild. **Cold-Read linter dogfood wrapper mis-scoped pre-cut** — the toolkit-self dogfood wrapper for the Cold-Read body linter was dropped from #289 because the pre-v0.21.0 window has no consistent pin target (`@main` breaks single-ref-alignment; `@v0.21.0-rc.N` doesn't yet contain the reusable). Deferred to #290 (post-v0.21.0-cut fold), same pattern as #281. ### Internal **`update-doc-version-refs.sh` self-`git add` removed** — `release-prep.sh`'s #236 auto-stage sweeps hook-modified tracked files, so the belt-and-suspenders self-stage from #251 is redundant. Closes #253. ### Removed / Deprecated None. ### Upgrade No action required for consumers on `@v0.20.0` unless the **Fragment-check baked-ref** bug (see Fixed) applies — re-pin `fragment-check.yml` to `@v0.21.0` in that case. The Cold-Read body linter and fragment template are opt-in.
forgejo-actions force-pushed release-prep/rolling from b85893db01
All checks were successful
check-self-bootstrap / check (pull_request) Successful in 3s
Details
fragment-check / changelog fragment-kind (pull_request) Successful in 4s
Details
fragment-check / check (pull_request) Successful in 0s
Details
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s
Details
manifest-check / check (pull_request) Successful in 0s
Details
to 768ce2e84c 2026-07-02 16:01:05 +02:00 Compare
forgejo-actions force-pushed release-prep/rolling from 768ce2e84c to aff1bfef73 2026-07-02 16:22:54 +02:00 Compare
forgejo-actions force-pushed release-prep/rolling from aff1bfef73 to acbd5956fb 2026-07-02 16:35:18 +02:00 Compare
forgejo-actions force-pushed release-prep/rolling from acbd5956fb to 8e5a9389e5 2026-07-02 16:40:45 +02:00 Compare
pilot commented 2026-07-02 17:09:35 +02:00
Owner
Copy link

Cold-Read: release-toolkit v0.21.0 Changelog

Applied the Cold-Read prompt to the PR body verbatim. Perspective: contributor on v0.20.0, considering whether to upgrade, reading only this text.

1. 30-second skim

Not confident on headline. The sections are Added / Changed / Fixed / Internal — four distinct buckets, but "Internal" is non-standard and the fixed entries are two opaque bullets. After a full first skim the candidates for headline are: (a) the mechanical Cold-Read body linter, (b) the auto re-pin of toolkit-self wrappers. No single entry is visually prominent. I can say "changelog tooling layer + release automation" but couldn't confidently name the headline change unprompted. The bottom of Added also contains a bullet list that partially re-states prose already above it, creating a second scan trap.

2. The six reader questions

Question Answer Speed
Are there breaking changes? None explicit; check-self-bootstrap.yml now fires only when automation breaks, not on human forget — a behavioral change to an existing CI check, but not called out as such Not found as a callout
Must I change config, commands, or scripts to upgrade? Nothing required; body-check and fragment template are opt-in; toolkit_ref: drop is hygiene-only. But this isn't stated anywhere as "no action required." Not found as a clear statement
What's new I might actually want? reusable-changelog-body-check.yml (automated linter), auto re-pin (#283), fragment template Top (Added), but buried in long entries
What was fixed — plausibly hitting? Fragment-check bake-reset gap in v0.20.0 (consumers pinning @v0.20.0 got scripts at main — correctness bug); two reviewer-driven tweaks Mid (fold-in, misplaced in Added) / bottom (Fixed bullets, opaque)
Anything removed or deprecated? Not addressed — no Removed section; check-self-bootstrap.yml scope change not framed as deprecation Not found
Is a migration path / upgrade step given? No Not found

3. Entry inventory

Entry Verdict One-line reason
cut_complete.ms_total + path (#204 part 2) COMPRESS Keep: what the fields are, graceful-degradation contract. Cut: "grafted onto the #283 organic re-pin rather than burning a dedicated re-pin cycle" is PR description
reusable-changelog-body-check.yml + changelog-body-check.sh (#282 L1) COMPRESS The 6-checks list is KEEP; the empirical-anchor sentence ("release-toolkit#264 Pilot Cold-Read pass 2026-07-02 caught 4 of 5...") is CUT (PR desc); the ~100-word toolkit-self dogfood deferral paragraph is CUT (internal pre-cut housekeeping, irrelevant to consumers)
changelog.d/.template.md + fragment brevity docs (#282 L2) COMPRESS "No behavioural change" is KEEP; "Layer 1/Layer 2" vocabulary is internal jargon — a cold reader on v0.20.0 has no context for it; say "complements the automated linter"
Auto re-pin toolkit-self wrappers post-cut (#283) COMPRESS Keep: auto-pins post-cut, external consumers unaffected, check-self-bootstrap.yml now fires only on automation failure (this last point deserves a Changed entry of its own — behavioral change to an existing check). Cut: "Bundled with the bake-reset commit... land atomically" is PR description
Fold-in fix: fragment-check bake-reset gap from v0.20.0 MOVE This is a fix misplaced in Added — v0.20.0 consumers who pinned @v0.20.0 on fragment-check got scripts at main (substrate drift). Belongs first in Fixed, not mid-Added prose
Bullet list at bottom of Added CUT Partially duplicates entries above; adds #281 fold-in not in prose but without enough context; pick one form (prose or bullets, not both)
docs/integration.md undeclared-inputs note (#250) COMPRESS Keep: lazy-leave is hygiene not correctness. Cut: "Forgejo 12 on git.frankenbit.de, probed 2026-07-02" — platform version + probe date is PR description
Fixed: drop toolkit-self dogfood wrapper ("Surveyor 96d8d385 REQUEST_CHANGES") COMPRESS "Surveyor 96d8d385 REQUEST_CHANGES" is an internal reviewer code — meaningless to a cold reader. State what was dropped and why in one plain sentence
Fixed: gate auto-re-pin loops on toolkit-self detection ("Surveyor 08d1") COMPRESS Same problem — "Surveyor 08d1" is opaque. State what was gated and the consequence of the gap
Internal: update-doc-version-refs.sh no longer self-git-adds (#253) COMPRESS or MOVE "Internal" is not a standard CHANGELOG bucket. If kept, strip the "empirically confirmed through rolling-mode git checkout -B path" history — one sentence max. If the project doesn't surface internal cleanup to contributors, CUT entirely

4. Signal vs. noise

Rough split: ~45% actionable change-info, ~35% mechanism/internal-history narrative, ~20% reviewer-reference/cross-reference.

Biggest offenders:

  • reusable-changelog-body-check.yml entry: the toolkit-self dogfood deferral (~100 words) is internal pre-cut window mechanics — no external consumer action, no behavioral signal
  • The fold-in fix (fragment-check bake-reset gap): buried in Added, and carries ~80 words of "how v0.20.0 shipped this bug" that belongs in the PR
  • Fixed bullets: the reviewer-code density ("Surveyor 96d8d385 REQUEST_CHANGES", "Surveyor 08d1") carries near-zero signal for anyone outside the review thread

5. Structure & scannability

  • Sections: Added / Changed / Fixed / Internal — "Internal" is non-standard. A contributor doesn't know whether to look here for something relevant to them. Standard alternatives: fold into Changed, or cut if it's truly internal housekeeping.
  • The fold-in fix (fragment-check bake-reset gap) is inside Added — misplaced. It's a bug fix affecting v0.20.0 consumers of fragment-check and should be the first Fixed entry with impact stated upfront.
  • Fixed entries use **bold label**: text bullet format; Added entries are prose paragraphs. Same inconsistency as v0.20.0 — one form per release, please.
  • The bullet list at the bottom of Added partially re-states the prose above it — two-pass scan trap.
  • check-self-bootstrap.yml scope change (fires only on automation failure now) is behavioral, but buried inside the auto-re-pin prose with no dedicated Changed entry.
  • Version bump v0.20.0 → v0.21.0: minor bump for 3–4 additions + 1 docs change + fixes, all backwards-compatible. Consistent with semver.

6. Missing

  • Version number — "v0.21.0" does not appear in the changelog text itself
  • Date — no release date
  • Upgrade / consumer action summary — nothing required, but a one-liner confirming "no action required to upgrade; body-check and template are opt-in" would close the reader question
  • check-self-bootstrap.yml behavior change — consumers who rely on this check being a "human forgot" reminder will notice it no longer fires for that case; deserves a dedicated Changed entry, not a parenthetical inside Added
  • Fragment-check bake-reset fix scope — how many consumers are affected? What do they need to do? (Re-pin to @v0.21.0 is presumably the answer, but it's not stated.)
  • 1-line release summary — the theme is changelog tooling layer (body linter + template + brevity docs) bundled with auto re-pin; unstated

7. Verdict

Top 5 highest-leverage edits:

  1. Move the fold-in fix (fragment-check bake-reset gap) to Fixed, first position — it's a v0.20.0 correctness bug affecting external consumers; misplaced in Added and needs prominence, not burial.
  2. Rewrite the Fixed bullets in plain terms — drop "Surveyor 96d8d385 REQUEST_CHANGES" / "Surveyor 08d1"; state what changed and why in one sentence each.
  3. Pull check-self-bootstrap.yml scope change into a dedicated Changed entry — behavioral change to an existing CI check; currently invisible inside the auto-re-pin prose.
  4. Cut the toolkit-self dogfood deferral block from the body-check entry — ~100 words of internal pre-cut mechanics; replace with "Toolkit-self dogfood wiring deferred to #290."
  5. Add version header + 1-line summary, cut or collapse the duplicate bullet list — ## v0.21.0 — YYYY-MM-DD + one theme sentence; then one form (prose or bullets) throughout Added.

Length verdict: About right in aggregate, but the distribution is wrong — Added is overlong (carries a misplaced fix + ~100-word deferral block), Fixed is under-informative (opaque codes). Redistributing ~100 words from Added to a rewritten Fixed would improve signal density without changing total length.

# Cold-Read: release-toolkit v0.21.0 Changelog *Applied the [Cold-Read prompt](https://docs.saratow.net/books/tmux-tell/page/cold-read-prompt) to the PR body verbatim. Perspective: contributor on v0.20.0, considering whether to upgrade, reading only this text.* --- ## 1. 30-second skim Not confident on headline. The sections are Added / Changed / Fixed / Internal — four distinct buckets, but "Internal" is non-standard and the fixed entries are two opaque bullets. After a full first skim the candidates for headline are: (a) the mechanical Cold-Read body linter, (b) the auto re-pin of toolkit-self wrappers. No single entry is visually prominent. I can say "changelog tooling layer + release automation" but couldn't confidently name the headline change unprompted. The bottom of Added also contains a bullet list that partially re-states prose already above it, creating a second scan trap. --- ## 2. The six reader questions | Question | Answer | Speed | |---|---|---| | Are there breaking changes? | None explicit; `check-self-bootstrap.yml` now fires only when automation breaks, not on human forget — a behavioral change to an existing CI check, but not called out as such | Not found as a callout | | Must I change config, commands, or scripts to upgrade? | Nothing required; body-check and fragment template are opt-in; `toolkit_ref:` drop is hygiene-only. But this isn't stated anywhere as "no action required." | Not found as a clear statement | | What's new I might actually want? | `reusable-changelog-body-check.yml` (automated linter), auto re-pin (#283), fragment template | Top (Added), but buried in long entries | | What was fixed — plausibly hitting? | Fragment-check bake-reset gap in v0.20.0 (consumers pinning `@v0.20.0` got scripts at `main` — correctness bug); two reviewer-driven tweaks | Mid (fold-in, misplaced in Added) / bottom (Fixed bullets, opaque) | | Anything removed or deprecated? | Not addressed — no Removed section; `check-self-bootstrap.yml` scope change not framed as deprecation | Not found | | Is a migration path / upgrade step given? | No | Not found | --- ## 3. Entry inventory | Entry | Verdict | One-line reason | |---|---|---| | `cut_complete.ms_total` + `path` (#204 part 2) | COMPRESS | Keep: what the fields are, graceful-degradation contract. Cut: "grafted onto the #283 organic re-pin rather than burning a dedicated re-pin cycle" is PR description | | `reusable-changelog-body-check.yml` + `changelog-body-check.sh` (#282 L1) | COMPRESS | The 6-checks list is KEEP; the empirical-anchor sentence ("release-toolkit#264 Pilot Cold-Read pass 2026-07-02 caught 4 of 5...") is CUT (PR desc); the ~100-word toolkit-self dogfood deferral paragraph is CUT (internal pre-cut housekeeping, irrelevant to consumers) | | `changelog.d/.template.md` + fragment brevity docs (#282 L2) | COMPRESS | "No behavioural change" is KEEP; "Layer 1/Layer 2" vocabulary is internal jargon — a cold reader on v0.20.0 has no context for it; say "complements the automated linter" | | Auto re-pin toolkit-self wrappers post-cut (#283) | COMPRESS | Keep: auto-pins post-cut, external consumers unaffected, `check-self-bootstrap.yml` now fires only on automation failure (this last point deserves a Changed entry of its own — behavioral change to an existing check). Cut: "Bundled with the bake-reset commit... land atomically" is PR description | | Fold-in fix: fragment-check bake-reset gap from v0.20.0 | MOVE | This is a **fix** misplaced in Added — v0.20.0 consumers who pinned `@v0.20.0` on fragment-check got scripts at `main` (substrate drift). Belongs first in Fixed, not mid-Added prose | | Bullet list at bottom of Added | CUT | Partially duplicates entries above; adds `#281 fold-in` not in prose but without enough context; pick one form (prose or bullets, not both) | | `docs/integration.md` undeclared-inputs note (#250) | COMPRESS | Keep: lazy-leave is hygiene not correctness. Cut: "Forgejo 12 on `git.frankenbit.de`, probed 2026-07-02" — platform version + probe date is PR description | | Fixed: drop toolkit-self dogfood wrapper ("Surveyor 96d8d385 REQUEST_CHANGES") | COMPRESS | "Surveyor 96d8d385 REQUEST_CHANGES" is an internal reviewer code — meaningless to a cold reader. State what was dropped and why in one plain sentence | | Fixed: gate auto-re-pin loops on toolkit-self detection ("Surveyor 08d1") | COMPRESS | Same problem — "Surveyor 08d1" is opaque. State what was gated and the consequence of the gap | | Internal: `update-doc-version-refs.sh` no longer self-git-adds (#253) | COMPRESS or MOVE | "Internal" is not a standard CHANGELOG bucket. If kept, strip the "empirically confirmed through rolling-mode `git checkout -B` path" history — one sentence max. If the project doesn't surface internal cleanup to contributors, CUT entirely | --- ## 4. Signal vs. noise Rough split: **~45% actionable change-info, ~35% mechanism/internal-history narrative, ~20% reviewer-reference/cross-reference**. Biggest offenders: - `reusable-changelog-body-check.yml` entry: the toolkit-self dogfood deferral (~100 words) is internal pre-cut window mechanics — no external consumer action, no behavioral signal - The fold-in fix (fragment-check bake-reset gap): buried in Added, and carries ~80 words of "how v0.20.0 shipped this bug" that belongs in the PR - Fixed bullets: the reviewer-code density ("Surveyor 96d8d385 REQUEST_CHANGES", "Surveyor 08d1") carries near-zero signal for anyone outside the review thread --- ## 5. Structure & scannability - Sections: Added / Changed / Fixed / **Internal** — "Internal" is non-standard. A contributor doesn't know whether to look here for something relevant to them. Standard alternatives: fold into Changed, or cut if it's truly internal housekeeping. - The fold-in fix (fragment-check bake-reset gap) is inside Added — misplaced. It's a bug fix affecting v0.20.0 consumers of fragment-check and should be the **first** Fixed entry with impact stated upfront. - Fixed entries use `**bold label**: text` bullet format; Added entries are prose paragraphs. Same inconsistency as v0.20.0 — one form per release, please. - The bullet list at the bottom of Added partially re-states the prose above it — two-pass scan trap. - `check-self-bootstrap.yml` scope change (fires only on automation failure now) is behavioral, but buried inside the auto-re-pin prose with no dedicated Changed entry. - Version bump v0.20.0 → v0.21.0: minor bump for 3–4 additions + 1 docs change + fixes, all backwards-compatible. Consistent with semver. --- ## 6. Missing - **Version number** — "v0.21.0" does not appear in the changelog text itself - **Date** — no release date - **Upgrade / consumer action summary** — nothing required, but a one-liner confirming "no action required to upgrade; body-check and template are opt-in" would close the reader question - **`check-self-bootstrap.yml` behavior change** — consumers who rely on this check being a "human forgot" reminder will notice it no longer fires for that case; deserves a dedicated Changed entry, not a parenthetical inside Added - **Fragment-check bake-reset fix scope** — how many consumers are affected? What do they need to do? (Re-pin to @v0.21.0 is presumably the answer, but it's not stated.) - **1-line release summary** — the theme is changelog tooling layer (body linter + template + brevity docs) bundled with auto re-pin; unstated --- ## 7. Verdict **Top 5 highest-leverage edits:** 1. **Move the fold-in fix (fragment-check bake-reset gap) to Fixed, first position** — it's a v0.20.0 correctness bug affecting external consumers; misplaced in Added and needs prominence, not burial. 2. **Rewrite the Fixed bullets in plain terms** — drop "Surveyor 96d8d385 REQUEST_CHANGES" / "Surveyor 08d1"; state what changed and why in one sentence each. 3. **Pull `check-self-bootstrap.yml` scope change into a dedicated Changed entry** — behavioral change to an existing CI check; currently invisible inside the auto-re-pin prose. 4. **Cut the toolkit-self dogfood deferral block from the body-check entry** — ~100 words of internal pre-cut mechanics; replace with "Toolkit-self dogfood wiring deferred to #290." 5. **Add version header + 1-line summary, cut or collapse the duplicate bullet list** — `## v0.21.0 — YYYY-MM-DD` + one theme sentence; then one form (prose or bullets) throughout Added. **Length verdict:** About right in aggregate, but the distribution is wrong — Added is overlong (carries a misplaced fix + ~100-word deferral block), Fixed is under-informative (opaque codes). Redistributing ~100 words from Added to a rewritten Fixed would improve signal density without changing total length.
docs(changelog): compress v0.21.0 body per Pilot Cold-Read
Some checks failed
check-self-bootstrap / check (pull_request) Failing after 3s
Details
fragment-check / changelog fragment-kind (pull_request) Successful in 4s
Details
fragment-check / check (pull_request) Successful in 0s
Details
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 6s
Details
manifest-check / check (pull_request) Successful in 0s
Details
c5c610aeee 
Pilot fired Cold Read on PR #287 (per the #628 discipline). Top-5 findings addressed:

1. **Fold-in fix (fragment-check bake-reset gap) misplaced in Added** — moved to Fixed, first position; framed as a v0.20.0 correctness bug affecting external consumers with explicit re-pin upgrade action.

2. **Opaque reviewer codes in Fixed** — "Surveyor 96d8d385 REQUEST_CHANGES" and "Surveyor 08d1" dropped in favor of plain-language descriptions of what changed and consumer impact. The reviewer-code anchors stay in git-log commit messages (register-honest historical record); the CHANGELOG describes outcome, not review-cycle mechanics.

3. **check-self-bootstrap.yml scope change** — pulled out of auto-re-pin prose into a dedicated Changed entry. Behavioral change to an existing CI check now visible upfront.

4. **Toolkit-self dogfood deferral block compressed** — the ~100-word pre-cut mechanics on why the wrapper was dropped compressed to "Toolkit-self dogfood wiring deferred to #290." Detailed mechanics live in the #289 PR body permanently.

5. **Duplicate bullet list + version header + Upgrade section** — dropped the conventional-commit digest that partially re-stated the prose. Added `## [v0.21.0] - 2026-07-02` + 1-line theme summary + explicit `### Removed / Deprecated: None.` + `### Upgrade` section stating the re-pin action for the fragment-check bug.

Also cut: platform version + probe date from the toolkit_ref migration note; "Layer 1/Layer 2" internal jargon from the linter + fragment-brevity entries; "grafted onto #283 organic re-pin" internal history from the ms_total entry.

Result: 4833 chars (from 6229 — ~22% reduction). Distribution now Added: 4 entries, Changed: 2 entries, Fixed: 3 entries (bake-reset gap first), Internal: 1, Removed/Deprecated: None, Upgrade: 1 sentence.

Note on the two lingering CC-bullet entries (fix(#282) + fix(cut)): the assembler's fragment-ref dedup keys on `(#NNN)` trailer format but my commits used `fix(#282):` scope-as-issue-ref format. Follow-up substrate improvement to make dedup handle both shapes to be tracked separately; direct CHANGELOG edit is the durable fix for v0.21.0.

Full Cold-Read report:
#287 (comment)
docs(conventions): CC internal-anchor discipline (Bosun re 8744)
Some checks failed
check-self-bootstrap / check (pull_request) Failing after 3s
Details
fragment-check / changelog fragment-kind (pull_request) Successful in 4s
Details
fragment-check / check (pull_request) Successful in 0s
Details
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 6s
Details
manifest-check / check (pull_request) Successful in 0s
Details
check-self-bootstrap / check (push) Failing after 3s
Details
release / decide + act (push) Successful in 7s
Details
release / release (push) Successful in 0s
Details
0a814c85e0 
Post-Cold-Read discipline observation folded into docs/conventions.md
§ conventional commits per Bosun `re 8744` ratification. Empirical
anchor: v0.21.0 Cold Read (release-toolkit#287) surfaced two opaque
reviewer-code Fixed bullets that leaked from `fix(#282): drop toolkit-
self dogfood wrapper (Surveyor 96d8d385 REQUEST_CHANGES)` and
`fix(cut): gate auto-re-pin loops on toolkit-self detection (Surveyor
08d1)` commit subjects.

The rule: reviewer codes and audit anchors belong in commit body /
PR body / issue history, NOT in the CC subject. Two reasons named:
(1) subject leaks to CHANGELOG via CC parser; (2) fragment-ref dedup
misses scope-as-issue-ref shape (see release-toolkit#293).

Codified→embodied loop closes: the discipline surfaced from Pilot's
Cold Read on v0.21.0, and codifies into v0.21.0 alongside the
sibling fragment-brevity discipline (release-toolkit#282 Layer 2).
No separate tracker per Bosun; no CHANGELOG entry since this is a
docs polish that doesn't materially change consumer behavior.
alex approved these changes 2026-07-02 17:22:59 +02:00
alex merged commit 0a814c85e0 into main 2026-07-02 17:23:03 +02:00
alex deleted branch release-prep/rolling 2026-07-02 17:23:03 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
alex
Labels
Clear labels   
bump
major
 Override the cut bump to MAJOR (release-toolkit#107)

  
bump
minor
 Override the cut bump to MINOR (release-toolkit#107)

  
bump
patch
 Override the cut bump to PATCH (release-toolkit#107)

  
kind/bug
Something is broken

  
kind/chore
Maintenance, tooling, refactor

  
kind/docs
Documentation work

  
kind/feature
New feature or capability

  
priority/critical
Critical: must be addressed immediately

  
priority/high
Important, should be addressed soon

  
priority/low
Low priority, address when convenient

  
priority/medium
Normal priority

  
size/L
Large: significant feature, ~6-16h

  
size/M
Medium: moderate feature, ~2-6h

  
size/S
Small: simple change, ~1-2h

  
size/XL
Extra large: major feature or refactor, 16h+

No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
5 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
frankenbit/release-toolkit!287
No description provided.