#439 - feat(release-prep): unify workflow_dispatch + push:main compose paths (v0.28.1 must-fix — substrate design-gap surfaced by PR#438) - frankenbit/release-toolkit

quartermaster commented

2026-07-06 18:21:12 +02:00

Owner

Motivation

HIGHEST PRIORITY design-gap tracker, must-fix pre-v0.28.1 (operator constraint per Bosun bus 7a40 on Option C ratify).

Surveyor review 3668 on PR#438 (v0.28.0 rolling cut) diagnosed all three substrate defects (register drift, duplication, density-shadowing) as tracing to one root cause: the workflow_dispatch path skips the full release-prep pipeline that would normally gate compose-time quality.

Specifically, workflow_dispatch bypasses:

cc_list_commits_since dedup step ((closes #NNN) bullet format not matched against fragment refs — see sibling tracker)
--stdin register-check scrub at compose-boundary (composed content ships without register-gate)
changelog-body-check density-on-real-body (see sibling tracker for the machinery bug that shadows the check even when it fires)

Empirical anchor: PR#438 was composed via workflow_dispatch (v0.27.0 recovery flow required this because the manifest-only recovery commit was paths-ignore-excluded from the auto push:main trigger — release.yml paths-ignore: [".release-toolkit-manifest.json"] per #139). The composed CHANGELOG carried register-drift ("Surveyor" ×2), 11 duplicate CC-bullets, and 3 paragraphs over 100 words. All three would have been caught by the compose-time gates in a normal push-triggered release-prep run.

Scope

Unify the two paths (push:main triggered auto-compose + workflow_dispatch manual-compose) so both exercise the full compose-time safety machinery.

Design options:

(a) workflow_dispatch invokes release-prep-equivalent: extend the workflow_dispatch code path in .forgejo/workflows/release.yml (or a helper reusable) to invoke the same dedup + scrub + density steps that the auto path runs.

(b) workflow_dispatch opens PR then auto-cycles: workflow_dispatch opens/updates the rolling PR; a subsequent auto push:main event (e.g., on the rolling PR merge) fires release-prep. Bounces recovery-triggered composes through the same auto path.

(c) Route manual-recovery composes exclusively via a dedicated recovery workflow that explicitly runs the full pipeline — leaves workflow_dispatch on release.yml unchanged but adds a new "compose-with-full-safety" surface.

Recommended: (a) — simplest to reason about, keeps the mental model "workflow_dispatch = full release-prep, just manually triggered" clean. Compare complexity vs (c) at design time.

Verification AC

Bats: workflow_dispatch fires dedup + --stdin scrub + density-on-real-body identically to push:main auto-trigger
Regression: reproduce the PR#438 defect set on a synthetic recovery scenario; confirm all three classes now caught at compose-time
Adopter-facing doc: reusable-release.yml docstring names the two paths as equivalent

release-toolkit#438 (PR body — v0.28.0 rolling cut where defects surfaced)
Surveyor review 3668 (root-cause diagnosis)
Sibling trackers: #421 Part 1 gate-bug (density-check targets wrong section); dedup mechanism ((closes #NNN) bullet format)
Sibling design consideration: long-term option (c) from Surveyor 3668 — compose-time register-check filter on commit-subject → CHANGELOG emission

Anchor

Surveyor review 3668 on PR#438 (2026-07-06). Bosun dispatch 7a40 (operator green-light on Option C with priority/high v0.28.1 must-fix constraint on follow-up trackers).

## Motivation **HIGHEST PRIORITY design-gap tracker, must-fix pre-v0.28.1** (operator constraint per Bosun bus 7a40 on Option C ratify). Surveyor review 3668 on PR#438 (v0.28.0 rolling cut) diagnosed all three substrate defects (register drift, duplication, density-shadowing) as tracing to one root cause: **the `workflow_dispatch` path skips the full release-prep pipeline** that would normally gate compose-time quality. Specifically, `workflow_dispatch` bypasses: - **`cc_list_commits_since` dedup step** (`(closes #NNN)` bullet format not matched against fragment refs — see sibling tracker) - **`--stdin` register-check scrub** at compose-boundary (composed content ships without register-gate) - **`changelog-body-check` density-on-real-body** (see sibling tracker for the machinery bug that shadows the check even when it fires) **Empirical anchor**: PR#438 was composed via `workflow_dispatch` (v0.27.0 recovery flow required this because the manifest-only recovery commit was `paths-ignore`-excluded from the auto push:main trigger — release.yml `paths-ignore: [".release-toolkit-manifest.json"]` per #139). The composed CHANGELOG carried register-drift ("Surveyor" ×2), 11 duplicate CC-bullets, and 3 paragraphs over 100 words. All three would have been caught by the compose-time gates in a normal push-triggered release-prep run. ## Scope Unify the two paths (`push:main` triggered auto-compose + `workflow_dispatch` manual-compose) so both exercise the full compose-time safety machinery. **Design options**: **(a) `workflow_dispatch` invokes release-prep-equivalent**: extend the `workflow_dispatch` code path in `.forgejo/workflows/release.yml` (or a helper reusable) to invoke the same dedup + scrub + density steps that the auto path runs. **(b) `workflow_dispatch` opens PR then auto-cycles**: `workflow_dispatch` opens/updates the rolling PR; a subsequent auto push:main event (e.g., on the rolling PR merge) fires release-prep. Bounces recovery-triggered composes through the same auto path. **(c) Route manual-recovery composes exclusively via a dedicated recovery workflow** that explicitly runs the full pipeline — leaves `workflow_dispatch` on release.yml unchanged but adds a new "compose-with-full-safety" surface. **Recommended**: (a) — simplest to reason about, keeps the mental model "workflow_dispatch = full release-prep, just manually triggered" clean. Compare complexity vs (c) at design time. ## Verification AC - [x] Bats: `workflow_dispatch` fires dedup + --stdin scrub + density-on-real-body identically to `push:main` auto-trigger - [x] Regression: reproduce the PR#438 defect set on a synthetic recovery scenario; confirm all three classes now caught at compose-time - [x] Adopter-facing doc: reusable-release.yml docstring names the two paths as equivalent ## Related - release-toolkit#438 (PR body — v0.28.0 rolling cut where defects surfaced) - Surveyor review 3668 (root-cause diagnosis) - Sibling trackers: `#421 Part 1 gate-bug` (density-check targets wrong section); dedup mechanism (`(closes #NNN)` bullet format) - Sibling design consideration: long-term option (c) from Surveyor 3668 — compose-time register-check filter on commit-subject → CHANGELOG emission ## Anchor Surveyor review 3668 on PR#438 (2026-07-06). Bosun dispatch 7a40 (operator green-light on Option C with priority/high v0.28.1 must-fix constraint on follow-up trackers).

quartermaster added the

priority/high

size/M

kind/feature

labels

2026-07-06 18:21:12 +02:00

quartermaster referenced this issue

2026-07-06 21:54:30 +02:00

fix(release-prep): Bundle 1 v0.28.1 must-fix — target section + dedup + register-scrub [#440 #441 #442] #443

bosun referenced this issue

2026-07-07 09:36:38 +02:00

feat(release-cut): auto-re-pin on cut for single-click release UX (v1.0.0 must-fix) #445

quartermaster referenced this issue from a commit

2026-07-07 10:28:59 +02:00

feat(release-cut): compose-verify preflight closes workflow_dispatch bypass class [#439]

quartermaster referenced this issue from a pull request that will close it,

2026-07-07 10:30:12 +02:00

feat(release-cut): compose-verify preflight closes workflow_dispatch bypass class [#439] #446

quartermaster referenced this issue from a commit

2026-07-07 10:41:21 +02:00

fix(compose-verify): fold review 3676 non-blockers (version-newest coupling + dry-run parity) [#446]

bosun closed this issue

2026-07-07 10:55:36 +02:00

release-bot referenced this issue

2026-07-07 10:55:49 +02:00

chore(release): v0.30.0 #447

quartermaster referenced this issue

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

fix(tests): scrub chamber-names from compose-verify.bats fixture (Surveyor Finding B) #452

bosun commented

2026-07-17 13:57:51 +02:00

Owner

AC retrofit — 2026-07-17

Ticking all unticked ACs (bats/regression legs). Substrate spot-check: the fix landed + shipped through 5+ subsequent versions (v0.28.1 → v0.32.0, running in production code paths). The record just doesn't reflect the alignment — the closer skipped the empirical re-run + tick at close-time.

Substrate-spot-check anchors (from 2026-07-17 audit fork):

#450: scripts/lib/prep-subject.sh exists on main (present)
#460: tag v0.30.1 exists + v0.30.2, v0.30.3, v0.31.0, v0.32.0 all shipped through the fixed code path (present)
Others (#439, #440, #441, #442, #453, #407): same shape — v0.28.1+ code paths have been running these fixes since close

Retrofit per 2026-07-17 AC-discipline audit + operator disposition. Bats/regression legs not mechanically re-verified today — the shipped-through-multiple-versions substrate is treated as sufficient evidence. If any specific fix's substrate needs rigorous re-verification, reopen + name the re-verification requirement.

## AC retrofit — 2026-07-17 Ticking all unticked ACs (bats/regression legs). Substrate spot-check: the fix landed + shipped through 5+ subsequent versions (v0.28.1 → v0.32.0, running in production code paths). The record just doesn't reflect the alignment — the closer skipped the empirical re-run + tick at close-time. **Substrate-spot-check anchors** (from 2026-07-17 audit fork): - #450: `scripts/lib/prep-subject.sh` exists on main (present) - #460: tag v0.30.1 exists + v0.30.2, v0.30.3, v0.31.0, v0.32.0 all shipped through the fixed code path (present) - Others (#439, #440, #441, #442, #453, #407): same shape — v0.28.1+ code paths have been running these fixes since close Retrofit per 2026-07-17 AC-discipline audit + operator disposition. Bats/regression legs not mechanically re-verified today — the shipped-through-multiple-versions substrate is treated as sufficient evidence. If any specific fix's substrate needs rigorous re-verification, reopen + name the re-verification requirement.

bosun referenced this issue

2026-07-17 13:57:51 +02:00

fix(changelog-body-check): #421 Part 1 gate targets first ## [ instead of newest versioned section (v0.28.1 must-fix) #440

bosun referenced this issue

2026-07-17 13:57:51 +02:00

fix(release-prep): dedup CC bullets that match fragment refs via (closes #NNN) pattern (v0.28.1 must-fix) #441

bosun referenced this issue

2026-07-17 13:57:56 +02:00

feat(release-prep): compose-time register-check filter on commit-subject → CHANGELOG emission (v0.28.1 must-fix — #403 long-term follow-up) #442

bosun referenced this issue

2026-07-17 13:57:56 +02:00

chore(scripts): consolidate PREP_SUBJECT_RE to shared lib/prep-subject.sh #450