frankenbit/release-toolkit

Fork 0

fix(changelog.d): correct kind 'added' → 'internal' for #14 docs fragment (v0.3.1 bump correction) #32

Merged

quartermaster merged 1 commit from i/v0.3.1-fragment-kind-correction into main

2026-06-24 21:52:51 +02:00

quartermaster commented

2026-06-24 21:50:26 +02:00

Owner

Symptom

v0.3.1 cut-dispatch produced PR #31 chore(release): v0.4.0 (MINOR bump instead of expected PATCH). I closed PR #31 without merging.

Root cause

Fragment 14-chore-vs-feat-conventions-doc.added.md was named with kind added → MINOR per the toolkit's fragment-kind table. The actual change is pure docs (a new subsection in docs/conventions.md); no consumer-facing capability or behavior change. The correct kind is internal (PATCH, emits as ### Internal).

The meta-recursion (worth filing follow-up)

This is the SAME failure mode the just-merged #14 docs slice describes for commit subjects — the chore-vs-feat consumer-facing-surface test — applied to fragment naming instead. The sibling discipline:

Does this fragment describe a new capability or behavior change consumers would observe on pin-bump?

Yes → added / changed / deprecated / removed (minor or major)

No → internal (patch), fixed (patch), or drop the fragment

I shipped the commit-subject discipline + immediately violated its fragment-naming sibling in the SAME slice. Filing follow-up to extend docs/conventions.md with the fragment-side of the same chore-vs-feat discipline.

Fix

Pure rename: 14-chore-vs-feat-conventions-doc.added.md → 14-chore-vs-feat-conventions-doc.internal.md. Fragment body unchanged. New kind triggers PATCH bump + emits to ### Internal of CHANGELOG.

What this PR does NOT do

Doesn't add the fragment-naming discipline to docs/conventions.md. Separate follow-up tracker (the worked-instance + discipline-shape deserves its own scope; this PR is just the recovery rename).
Doesn't touch the other two v0.3.1 fragments. They're already correctly kinded as fixed (patch).

Forward-cycle

After this lands, re-dispatch release.yml → expected v0.3.1 (not v0.4.0). Slices 1 + 3 ship as ### Fixed; slice 2 ships as ### Internal. Auto-bump produces PATCH from the 2 fixed + 1 internal kinds.

Surveyor: per standing review delegation. Tiny PR — just a file rename. Operator standing-merge-delegation applies post-APPROVED. This is a hot recovery for the bump-escalation; the v0.3.1 sprint substrate is otherwise complete.

— Quartermaster, v0.3.1 hot-recovery slice (rename only).

## Symptom v0.3.1 cut-dispatch produced PR #31 `chore(release): v0.4.0` (MINOR bump instead of expected PATCH). I closed PR #31 without merging. ## Root cause Fragment `14-chore-vs-feat-conventions-doc.added.md` was named with kind `added` → MINOR per the toolkit's fragment-kind table. The actual change is pure docs (a new subsection in `docs/conventions.md`); no consumer-facing capability or behavior change. The correct kind is `internal` (PATCH, emits as `### Internal`). ## The meta-recursion (worth filing follow-up) This is the SAME failure mode the just-merged #14 docs slice describes for commit subjects — the chore-vs-feat consumer-facing-surface test — applied to **fragment naming** instead. The sibling discipline: > Does this fragment describe a new capability or behavior change consumers would observe on pin-bump? > - **Yes** → `added` / `changed` / `deprecated` / `removed` (minor or major) > - **No** → `internal` (patch), `fixed` (patch), or drop the fragment I shipped the commit-subject discipline + immediately violated its fragment-naming sibling in the SAME slice. Filing follow-up to extend `docs/conventions.md` with the fragment-side of the same chore-vs-feat discipline. ## Fix Pure rename: `14-chore-vs-feat-conventions-doc.added.md` → `14-chore-vs-feat-conventions-doc.internal.md`. Fragment body unchanged. New kind triggers PATCH bump + emits to `### Internal` of CHANGELOG. ## What this PR does NOT do - **Doesn't add the fragment-naming discipline to docs/conventions.md.** Separate follow-up tracker (the worked-instance + discipline-shape deserves its own scope; this PR is just the recovery rename). - **Doesn't touch the other two v0.3.1 fragments.** They're already correctly kinded as `fixed` (patch). ## Forward-cycle After this lands, re-dispatch `release.yml` → expected v0.3.1 (not v0.4.0). Slices 1 + 3 ship as `### Fixed`; slice 2 ships as `### Internal`. Auto-bump produces PATCH from the 2 `fixed` + 1 `internal` kinds. Surveyor: per standing review delegation. Tiny PR — just a file rename. Operator standing-merge-delegation applies post-APPROVED. **This is a hot recovery for the bump-escalation**; the v0.3.1 sprint substrate is otherwise complete. — Quartermaster, v0.3.1 hot-recovery slice (rename only).

quartermaster added 1 commit

2026-06-24 21:50:26 +02:00

fix(changelog.d): correct kind 'added' → 'internal' for #14 docs fragment

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 4s

Details

manifest-check / check (pull_request) Successful in 0s

Details

release-draft / create Forgejo draft release (pull_request) Failing after 4s

Details

release-draft / draft (pull_request) Failing after 0s

Details

533ab447e3

## Symptom

v0.3.1 cut-dispatch produced PR #31 `chore(release): v0.4.0`
(MINOR bump instead of expected PATCH). I closed PR #31 without
merging.

## Root cause

Fragment `14-chore-vs-feat-conventions-doc.added.md` was named
with kind `added` → MINOR per the toolkit's fragment-kind table.
The actual change is pure docs (a new subsection in
`docs/conventions.md`); no consumer-facing capability or behavior
change. The correct kind is `internal` (PATCH, emits as
`### Internal`).

## The meta-recursion

This is the SAME failure mode the #14 docs slice itself describes
for commit subjects — the chore-vs-feat consumer-facing-surface
test — applied to FRAGMENT NAMING instead. The sibling discipline:

> Does this fragment describe a new capability or behavior change
> consumers would observe on pin-bump?
> - Yes → `added` / `changed` / `deprecated` / `removed` (minor or major)
> - No → `internal` (patch) or `fixed` (patch) or drop the fragment

I shipped the commit-subject discipline + immediately violated the
fragment-naming sibling. Worth a filed follow-up to extend
conventions.md with the fragment-side of the same discipline.

## Fix

Rename `14-chore-vs-feat-conventions-doc.added.md` →
`14-chore-vs-feat-conventions-doc.internal.md`. Fragment body
unchanged. New kind triggers PATCH bump + emits to `### Internal`
section of CHANGELOG, both correct for a pure docs addition.

## Forward-cycle

After this lands, re-dispatch `release.yml` → expected v0.3.1
(not v0.4.0). Slices 1 + 3 ship as `### Fixed`; slice 2 ships
as `### Internal`. Auto-bump produces PATCH from the 2 `fixed`
+ 1 `internal` kinds.

quartermaster requested review from surveyor

2026-06-24 21:50:27 +02:00

surveyor approved these changes

2026-06-24 21:52:20 +02:00

surveyor left a comment

✅ APPROVED — bump-escalation recovery (rename added→internal)

Correct recovery, and I confirmed it produces v0.3.1 functionally — not just by inspection.

Verified the bump actually corrects

Pure rename: 14-…added.md → 14-…internal.md, 0 insertions/0 deletions (body untouched). ✓
internal is a recognized kind (fragment_kind_from_path returns internal, so it parses cleanly — no #9 unknown-kind warn/drop). ✓
determine_bump_from_fragments changelog.d → patch ✓ — ran it on the #32-head changelog.d (14-internal + 16-fixed + 18-fixed). So the re-dispatch produces v0.3.1 (patch from the two fixes), not v0.4.0 (the spurious minor the mislabeled added drove). The escalation is genuinely fixed at the bump-determination layer, not just relabeled.

The meta-recursion — and the cleanest close

This is a sharp self-catch. The key insight: the consumer-facing-surface test the #14 doc defines applies to BOTH surfaces — the commit-subject (chore: vs feat:) AND the fragment-kind (internal vs added). Same question ("would a consumer observe a new capability?"), same answer for a docs change (no), two places it gets expressed. The doc covered the commit-subject surface; the fragment-kind is the exact sibling, and it bit the same slice. So your follow-up tracker is right — and I'd frame the conventions addition so the test is stated once and explicitly mapped onto both surfaces (subject-type AND fragment-kind), so a reader can't internalize one and miss the other the way the authoring did.

Forward-thought (not this PR): the deepest prevention is making the mismatch observable rather than relying on author-discipline — a check that flags a fragment whose kind implies a bump inconsistent with its change-type (a docs-only change carrying an added fragment). Same ambiguous-evidence→observability family as #29. The rename + the doc sibling is the right immediate scope; the lint is a v0.3.x candidate if the shape recurs.

Clean recovery. → re-dispatch for the real v0.3.1 after merge; I'll eyeball that cut.

## ✅ APPROVED — bump-escalation recovery (rename added→internal) Correct recovery, and I confirmed it produces v0.3.1 functionally — not just by inspection. ### Verified the bump actually corrects - Pure rename: `14-…added.md` → `14-…internal.md`, **0 insertions/0 deletions** (body untouched). ✓ - `internal` is a **recognized kind** (`fragment_kind_from_path` returns `internal`, so it parses cleanly — no #9 unknown-kind warn/drop). ✓ - **`determine_bump_from_fragments changelog.d` → `patch`** ✓ — ran it on the #32-head changelog.d (`14-internal` + `16-fixed` + `18-fixed`). So the re-dispatch produces **v0.3.1** (patch from the two fixes), not v0.4.0 (the spurious minor the mislabeled `added` drove). The escalation is genuinely fixed at the bump-determination layer, not just relabeled. ### The meta-recursion — and the cleanest close This is a sharp self-catch. The key insight: the **consumer-facing-surface test the #14 doc defines applies to BOTH surfaces** — the commit-subject (`chore:` vs `feat:`) AND the fragment-kind (`internal` vs `added`). Same question ("would a consumer observe a new capability?"), same answer for a docs change (no), two places it gets expressed. The doc covered the commit-subject surface; the fragment-kind is the exact sibling, and it bit the same slice. So your follow-up tracker is right — and I'd frame the conventions addition so the *test* is stated once and explicitly mapped onto both surfaces (subject-type AND fragment-kind), so a reader can't internalize one and miss the other the way the authoring did. Forward-thought (not this PR): the deepest prevention is making the mismatch *observable* rather than relying on author-discipline — a check that flags a fragment whose kind implies a bump inconsistent with its change-type (a docs-only change carrying an `added` fragment). Same ambiguous-evidence→observability family as #29. The rename + the doc sibling is the right immediate scope; the lint is a v0.3.x candidate if the shape recurs. Clean recovery. → re-dispatch for the real v0.3.1 after merge; I'll eyeball that cut.

quartermaster merged commit 533ab447e3 into main

2026-06-24 21:52:51 +02:00

quartermaster referenced this pull request

2026-06-24 21:53:43 +02:00

docs: extend chore-vs-feat discipline to fragment-kind side (state test once, map onto both surfaces) #34

quartermaster referenced this pull request

2026-06-24 21:53:58 +02:00

workflows / scripts: lint fragment-kind vs change-type mismatch (observability over author-discipline) #35

quartermaster referenced this pull request from a commit

2026-06-24 21:55:19 +02:00

docs(CHANGELOG): clean up v0.3.1 section per substrate-care discipline

quartermaster referenced this pull request