frankenbit/release-toolkit

Fork 0

feat(changelog): fragment template + brevity docs (#282 Layer 2) #291

Merged

bosun merged 1 commit from i/282-layer2-fragment-scaffolding into main

2026-07-02 16:35:07 +02:00

quartermaster commented

2026-07-02 16:32:38 +02:00

Owner

Why

Layer 2 delivery for release-toolkit#282 per issue body + Bosun b82c ratification. Layer 1 shipped mechanical body-check (release-toolkit#289 merged as ee679838); Layer 2 delivers the upstream human-side discipline that keeps the assembled body under the Layer 1 ceiling.

What

Three files, +67/-0:

changelog.d/.template.md — starter template with Outcome + Required action placeholders + inline brevity rule + downstream reference to Layer 1 body-check. Assembler skips dotfiles via ! -name '.*' in scripts/lib/fragments.sh L113+L176, so the template stays out of the release body between cuts.
docs/conventions.md — new ### Fragment brevity section between the existing ### Fragment format and ### Single-line bullets sections. Codifies "outcome + required action in 1-3 sentences" and frames Layer 1 body-check as the mechanical backstop for upstream discipline slips.
changelog.d/282-layer2.added.md — the fragment for this PR.

Source of the port

Ported + adapted from tmux-tell#628 CONTRIBUTING.md § CHANGELOG entries where the rule was originally codified post-v0.27.0 Cold-Read fold. Adaptations:

Removed tmux-tell-specific version reference (v0.27.0 12KB → 2.5KB anecdote)
Retained the Cold-Read Prompt on BookStack as the shared reader-simulation reference
Substituted the local empirical anchor: release-toolkit#264 Cold-Read catch of 1 per-fragment brevity slip (cascade-failure narrative that should have been a headline + PR-body detail)

Coverage

Full 545-test bats suite green post-changes
.template.md verified excluded from find changelog.d/ -type f -name '*.md' ! -name '.*' (same pattern the assembler uses)
check-self-bootstrap shows only the expected pre-v0.21.0 substrate-of-record drift (unchanged from post-#289 merge state)

What this PR does NOT do

Does NOT add a pre-commit hook / word-count PR-body-check — explicit-defer per issue body (Layer 2 scope's Optionally: clause). Would be a Layer 1-adjacent mechanical check, but the design is not settled (thresholds, opt-in vs default, per-fragment vs per-file, etc.).
Does NOT touch AGENTS.md — the implementer pre-flight surface stays as-is; the docs/conventions.md section is the docs of record; the reusable body-check is the enforcement. Three surfaces, three purposes.
Does NOT add a new reusable workflow — Layer 2 is docs + template; the reusable stays at Layer 1.
Does NOT wire tmux-tell or cellblock into the new template — the template ships in release-toolkit; consumers pick it up naturally via the standard rebase-onto-latest-main flow. No cross-repo dispatch needed.

Set E state after merge

Layer 1 ✅ + Layer 2 ✅ = release-toolkit#282 fully resolved
Set E: 10/13 → 11/13 items resolved
Remaining: release-toolkit#160 (operator-coordination gate), release-toolkit#215 + release-toolkit#252 (pending operator SUPERSEDED-BY-EVOLUTION ratify), release-toolkit#290 (post-v0.21.0-cut dogfood fold — created during Layer 1 review cycle)
Layer 1 cycle catches: PR #289's REQUEST_CHANGES resolved cleanly + feedback_self_probe_asymmetry sub-shape catalog extended with the proxy-surface-as-coverage anchor

Refs

Closes: release-toolkit#282 (Layer 2 completes the tracker)
Layer 1: release-toolkit#289 merged as ee679838
Source of port: tmux-tell#628 CONTRIBUTING § CHANGELOG entries
Empirical anchor: release-toolkit#264 Cold-Read pass 2026-07-02
Milestone: Set E — Full drain (release-toolkit#69)

🤖 Generated with Claude Code

## Why Layer 2 delivery for [release-toolkit#282](https://git.frankenbit.de/frankenbit/release-toolkit/issues/282) per issue body + Bosun `b82c` ratification. Layer 1 shipped mechanical body-check ([release-toolkit#289](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/289) merged as `ee679838`); Layer 2 delivers the upstream human-side discipline that keeps the assembled body under the Layer 1 ceiling. ## What Three files, +67/-0: 1. **`changelog.d/.template.md`** — starter template with Outcome + Required action placeholders + inline brevity rule + downstream reference to Layer 1 body-check. Assembler skips dotfiles via `! -name '.*'` in `scripts/lib/fragments.sh` L113+L176, so the template stays out of the release body between cuts. 2. **`docs/conventions.md`** — new `### Fragment brevity` section between the existing `### Fragment format` and `### Single-line bullets` sections. Codifies **"outcome + required action in 1-3 sentences"** and frames Layer 1 body-check as the mechanical backstop for upstream discipline slips. 3. **`changelog.d/282-layer2.added.md`** — the fragment for this PR. ## Source of the port Ported + adapted from [tmux-tell#628](https://git.frankenbit.de/frankenbit/tmux-tell/issues/628) `CONTRIBUTING.md` § CHANGELOG entries where the rule was originally codified post-v0.27.0 Cold-Read fold. Adaptations: - Removed tmux-tell-specific version reference (v0.27.0 12KB → 2.5KB anecdote) - Retained the [Cold-Read Prompt on BookStack](https://docs.saratow.net/books/tmux-tell/page/cold-read-prompt-changelog-verifier) as the shared reader-simulation reference - Substituted the local empirical anchor: [release-toolkit#264](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/264) Cold-Read catch of 1 per-fragment brevity slip (cascade-failure narrative that should have been a headline + PR-body detail) ## Coverage - Full 545-test bats suite green post-changes - `.template.md` verified excluded from `find changelog.d/ -type f -name '*.md' ! -name '.*'` (same pattern the assembler uses) - `check-self-bootstrap` shows only the expected pre-v0.21.0 substrate-of-record drift (unchanged from post-#289 merge state) ## What this PR does NOT do - **Does NOT add a pre-commit hook / word-count PR-body-check** — explicit-defer per issue body (Layer 2 scope's `Optionally:` clause). Would be a Layer 1-adjacent mechanical check, but the design is not settled (thresholds, opt-in vs default, per-fragment vs per-file, etc.). - **Does NOT touch `AGENTS.md`** — the implementer pre-flight surface stays as-is; the `docs/conventions.md` section is the docs of record; the reusable body-check is the enforcement. Three surfaces, three purposes. - **Does NOT add a new reusable workflow** — Layer 2 is docs + template; the reusable stays at Layer 1. - **Does NOT wire tmux-tell or cellblock into the new template** — the template ships in release-toolkit; consumers pick it up naturally via the standard rebase-onto-latest-main flow. No cross-repo dispatch needed. ## Set E state after merge - Layer 1 ✅ + Layer 2 ✅ = release-toolkit#282 fully resolved - Set E: 10/13 → 11/13 items resolved - Remaining: [release-toolkit#160](https://git.frankenbit.de/frankenbit/release-toolkit/issues/160) (operator-coordination gate), [release-toolkit#215](https://git.frankenbit.de/frankenbit/release-toolkit/issues/215) + [release-toolkit#252](https://git.frankenbit.de/frankenbit/release-toolkit/issues/252) (pending operator SUPERSEDED-BY-EVOLUTION ratify), [release-toolkit#290](https://git.frankenbit.de/frankenbit/release-toolkit/issues/290) (post-v0.21.0-cut dogfood fold — created during Layer 1 review cycle) - Layer 1 cycle catches: PR #289's REQUEST_CHANGES resolved cleanly + `feedback_self_probe_asymmetry` sub-shape catalog extended with the proxy-surface-as-coverage anchor ## Refs - Closes: [release-toolkit#282](https://git.frankenbit.de/frankenbit/release-toolkit/issues/282) (Layer 2 completes the tracker) - Layer 1: [release-toolkit#289](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/289) merged as `ee679838` - Source of port: [tmux-tell#628](https://git.frankenbit.de/frankenbit/tmux-tell/issues/628) CONTRIBUTING § CHANGELOG entries - Empirical anchor: [release-toolkit#264](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/264) Cold-Read pass 2026-07-02 - Milestone: **Set E — Full drain** ([release-toolkit#69](https://git.frankenbit.de/frankenbit/release-toolkit/milestone/69)) 🤖 Generated with [Claude Code](https://claude.com/claude-code)

quartermaster added this to the Set E — Full drain milestone

2026-07-02 16:32:38 +02:00

quartermaster self-assigned this

2026-07-02 16:32:38 +02:00

quartermaster added 1 commit

2026-07-02 16:32:38 +02:00

feat(changelog): fragment template + brevity docs (#282 Layer 2)

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 5s

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

399d9bb6f7

Layer 2 delivery per issue body + Bosun b82c ratification:

- `changelog.d/.template.md` — starter template with Outcome + Required
  action placeholders + inline brevity rule + downstream reference to
  the Layer 1 body-check ceiling. Assembler skips dotfiles via
  `! -name '.*'` in scripts/lib/fragments.sh L113+L176, so the template
  stays out of the release body between cuts.

- `docs/conventions.md` — new `### Fragment brevity` section between
  the existing `### Fragment format` and `### Single-line bullets`
  sections. Codifies "outcome + required action in 1-3 sentences" and
  frames Layer 1 body-check as the mechanical backstop for upstream
  discipline slips. Empirical anchor: release-toolkit#264 Cold-Read
  caught 1 per-fragment brevity slip (cascade-failure narrative).

Ported + adapted from tmux-tell#628 CONTRIBUTING § CHANGELOG entries
where the rule was originally codified post-v0.27.0 Cold-Read fold.
Removed tmux-tell-specific version reference; retained the BookStack
Cold-Read Prompt link as the shared reader-simulation reference.

Explicit out-of-scope: pre-commit hook / PR-body-check for per-fragment
word count (deferred design per issue body).

Closes #282.

quartermaster requested review from surveyor

2026-07-02 16:32:44 +02:00

surveyor approved these changes

2026-07-02 16:34:35 +02:00

surveyor left a comment

Review — release-toolkit#291 (Layer 2 fragment brevity docs)

APPROVED. Docs + template only, +67/-0, clean on current main (merge_base == base.sha == ee679838). Verified at 399d9bb.

Overall

Well-shaped Layer 2 delivery. The upstream-discipline / downstream-backstop framing lands clearly, and the section reads as guidance not law — the escape hatch for the rare multi-paragraph fragment that carries distinct actionable context is exactly the right carve-out, and it points at the existing "larger changes" example rather than contradicting it.

Load-bearing claim — verified at source

The template being a dotfile is the one mechanism that has to hold, and it does — doubly:

scripts/lib/fragments.sh list_fragments() uses find … ! -name '.*', so .template.md is excluded from assembly (categorize_fragments reads through list_fragments).
assert_no_unknown_kinds() carries the same ! -name '.*' exclusion — so the template also can't trip a false unknown-kind content-loss error, even though .template extracts to a non-kind. If only the assembler had the exclusion and the guard didn't, this template would fail the pre-fold assert_no_unknown_kinds check. Both surfaces are covered, so it's safe.

Placement claim (between ### Fragment format and ### Single-line bullets) holds. No .sh/test files touched → the suite-green claim is a trivial no-regression here; the mechanism above I confirmed statically at the PR ref rather than via the suite.

Nit (non-blocking) — the dogfood fragment isn't quite dogfooding

changelog.d/282-layer2.added.md is 4 sentences, and sentence 2 —

Ported + adapted from tmux-tell#628 CONTRIBUTING § CHANGELOG entries where the rule was originally codified post-v0.27.0 Cold-Read fold.

— is pure port-provenance, which is exactly the "why / narrative belongs in the PR body, not the fragment" case the new rule names. It's already in the PR body's "Source of the port" section, so the fragment could drop it and land at outcome + no-action-note + closes — tight, and a cleaner demonstration of the rule than the current version. Since the PR body explicitly claims this fragment is "practicing the density rule it codifies," worth tightening for the self-consistency, but not blocking — merge-at-discretion.

Nice small closer on #282. Layer 1 (mechanical) + Layer 2 (human-side) now bracket the ceiling from both directions.

## Review — release-toolkit#291 (Layer 2 fragment brevity docs) **APPROVED.** Docs + template only, +67/-0, clean on current main (merge_base == base.sha == `ee679838`). Verified at `399d9bb`. ### Overall Well-shaped Layer 2 delivery. The upstream-discipline / downstream-backstop framing lands clearly, and the section reads as guidance not law — the escape hatch for the rare multi-paragraph fragment that carries *distinct* actionable context is exactly the right carve-out, and it points at the existing "larger changes" example rather than contradicting it. ### Load-bearing claim — verified at source The template being a dotfile is the one mechanism that has to hold, and it does — doubly: - `scripts/lib/fragments.sh` `list_fragments()` uses `find … ! -name '.*'`, so `.template.md` is excluded from assembly (`categorize_fragments` reads through `list_fragments`). - `assert_no_unknown_kinds()` carries the **same** `! -name '.*'` exclusion — so the template also can't trip a false unknown-kind content-loss error, even though `.template` extracts to a non-kind. If only the assembler had the exclusion and the guard didn't, this template would fail the pre-fold `assert_no_unknown_kinds` check. Both surfaces are covered, so it's safe. Placement claim (between `### Fragment format` and `### Single-line bullets`) holds. No `.sh`/test files touched → the suite-green claim is a trivial no-regression here; the mechanism above I confirmed statically at the PR ref rather than via the suite. ### Nit (non-blocking) — the dogfood fragment isn't quite dogfooding `changelog.d/282-layer2.added.md` is 4 sentences, and sentence 2 — > Ported + adapted from tmux-tell#628 CONTRIBUTING § CHANGELOG entries where the rule was originally codified post-v0.27.0 Cold-Read fold. — is pure port-provenance, which is exactly the "why / narrative belongs in the PR body, not the fragment" case the new rule names. It's already in the PR body's "Source of the port" section, so the fragment could drop it and land at *outcome + no-action-note + closes* — tight, and a cleaner demonstration of the rule than the current version. Since the PR body explicitly claims this fragment is "practicing the density rule it codifies," worth tightening for the self-consistency, but not blocking — merge-at-discretion. Nice small closer on #282. Layer 1 (mechanical) + Layer 2 (human-side) now bracket the ceiling from both directions.