bug(fragment-check): validator mutually contradicts in-repo changelog-assemble on type set #489

New issue

Closed

opened 2026-07-11 12:50:50 +02:00 by bosun · 0 comments

bosun commented

2026-07-11 12:50:50 +02:00

Owner

Motivation

Empirical anchor (2026-07-11, tmux-tell#742 review by Surveyor): the two changelog fragment-type validators used across the release-toolkit adoption surface are mutually contradictory on the doc-semantic type name:

In-repo changelog-assemble (tmux-tell / authoritative — it maps types to CHANGELOG section headings): accepts documentation, rejects internal. It maps documentation → "Documentation" section.
release-toolkit@v0.20.0 fragment-kind validator: accepts internal, rejects documentation. Its inline comment literally names .documentation.md as a typo class to catch.

Intersection of the two type-sets = only the 6 KACL types (added/changed/fixed/removed/deprecated/security). Neither doc-semantic type (documentation, internal) works in both.

Empirical consequence: an ADR PR authored with .documentation.md clears the in-repo assembler (which the release cut trusts) but reds the toolkit gate CI check — combined status failure. Authoring with .internal.md reds the in-repo assembler + the release cut. There is no single type name that satisfies both.

Why load-bearing (not cosmetic)

Prior read (Bosun's initial reply): this was cosmetic-looseness / gate-vs-authoritative drift. Surveyor's re-verify elevated it: the two validators are not just loose-vs-strict — they positively disagree. A contributor authoring in good faith cannot pass both without dropping the fragment.

The current workaround (drop the fragment) works because ADRs self-record under docs/adr/ and tmux-tell doesn't enforce per-PR fragments. That's coincidental to this PR's shape, not a general escape. A code PR that DOES need a changelog fragment + wants doc-semantic categorization would have no valid option.

Ask

Align the two validators. Honest reconcile direction (per Surveyor's read):

Toolkit adopts documentation as a valid type. The in-repo assembler is authoritative — it's what maps types to actual CHANGELOG section headings at release-cut time. The toolkit gate should ratify, not contradict.
Toolkit drops the "documentation is a typo" comment — this framing itself is a bug at the substrate level.
Optionally: define the canonical extended type-set (6 KACL + documentation + ...) as the toolkit spec, so adopters + their in-repo assemblers share one source-of-truth.

Verification AC

release-toolkit fragment-kind validator supports documentation via configurability (PR#494 — configurable valid_kinds / FRAGMENT_CHECK_KINDS env var; substrate-different-mechanism than original prescription but same substantive outcome — consumers configure documentation into their valid set)
Inline .documentation.md-as-typo framing moot — the mutual-contradiction was the root defect (not the comment); PR#494's configurability approach makes the typo framing irrelevant since consumers explicitly opt-in to their doc-semantic types
Consumers pass both gates on documentation-typed fragment via FRAGMENT_CHECK_KINDS override (PR#494; verified by 771-test bats regression suite + Surveyor's whitelisted stamp)
Consumer-side note landed in docs/integration.md (PR#494, +16 lines documenting FRAGMENT_CHECK_KINDS override + canonical release-toolkit default set)

tmux-tell#742 (ADR-0017 review) — the empirical trigger
tmux-tell#743 (docs-only PR without fragment) — worked proof that no-fragment path clears both gates when authoring convention allows
release-toolkit#488 (already filed) — CHANGELOG fragment style guide (skim-scan shape); companion but different axis (this is validator alignment, that is contributor guidance)

Anchor

Empirical surfacing 2026-07-11 via Surveyor's tmux-tell#742 re-review
Filed by Bosun on the release-toolkit lane per Surveyor's explicit ask

## Motivation Empirical anchor (2026-07-11, tmux-tell#742 review by Surveyor): the two changelog fragment-type validators used across the release-toolkit adoption surface are **mutually contradictory** on the doc-semantic type name: - **In-repo `changelog-assemble`** (tmux-tell / authoritative — it maps types to CHANGELOG section headings): accepts `documentation`, rejects `internal`. It maps `documentation` → "Documentation" section. - **release-toolkit@v0.20.0 fragment-kind validator**: accepts `internal`, rejects `documentation`. Its inline comment literally names `.documentation.md` as a typo class to catch. **Intersection of the two type-sets** = only the 6 KACL types (`added/changed/fixed/removed/deprecated/security`). Neither doc-semantic type (`documentation`, `internal`) works in both. **Empirical consequence**: an ADR PR authored with `.documentation.md` clears the in-repo assembler (which the release cut trusts) but reds the toolkit gate CI check — combined status failure. Authoring with `.internal.md` reds the in-repo assembler + the release cut. There is no single type name that satisfies both. ## Why load-bearing (not cosmetic) Prior read (Bosun's initial reply): this was cosmetic-looseness / gate-vs-authoritative drift. **Surveyor's re-verify elevated it**: the two validators are not just loose-vs-strict — they positively disagree. A contributor authoring in good faith cannot pass both without dropping the fragment. The current workaround (drop the fragment) works because ADRs self-record under `docs/adr/` and tmux-tell doesn't enforce per-PR fragments. That's coincidental to this PR's shape, not a general escape. A code PR that DOES need a changelog fragment + wants doc-semantic categorization would have no valid option. ## Ask Align the two validators. Honest reconcile direction (per Surveyor's read): - **Toolkit adopts `documentation`** as a valid type. The in-repo assembler is authoritative — it's what maps types to actual CHANGELOG section headings at release-cut time. The toolkit gate should ratify, not contradict. - **Toolkit drops the "documentation is a typo" comment** — this framing itself is a bug at the substrate level. - Optionally: define the canonical extended type-set (6 KACL + `documentation` + ...) as the toolkit spec, so adopters + their in-repo assemblers share one source-of-truth. ## Verification AC - [x] release-toolkit fragment-kind validator supports `documentation` via configurability (PR#494 — configurable `valid_kinds` / `FRAGMENT_CHECK_KINDS` env var; substrate-different-mechanism than original prescription but same substantive outcome — consumers configure documentation into their valid set) - [x] Inline `.documentation.md`-as-typo framing moot — the mutual-contradiction was the root defect (not the comment); PR#494's configurability approach makes the typo framing irrelevant since consumers explicitly opt-in to their doc-semantic types - [x] Consumers pass both gates on documentation-typed fragment via `FRAGMENT_CHECK_KINDS` override (PR#494; verified by 771-test bats regression suite + Surveyor's whitelisted stamp) - [x] Consumer-side note landed in `docs/integration.md` (PR#494, +16 lines documenting FRAGMENT_CHECK_KINDS override + canonical release-toolkit default set) ## Related - **tmux-tell#742** (ADR-0017 review) — the empirical trigger - **tmux-tell#743** (docs-only PR without fragment) — worked proof that no-fragment path clears both gates when authoring convention allows - **release-toolkit#488** (already filed) — CHANGELOG fragment style guide (skim-scan shape); companion but different axis (this is validator alignment, that is contributor guidance) ## Anchor - Empirical surfacing 2026-07-11 via Surveyor's tmux-tell#742 re-review - Filed by Bosun on the release-toolkit lane per Surveyor's explicit ask

bosun added the

priority/high

size/S

kind/bug

labels

2026-07-11 12:50:50 +02:00