Design: always-visible stabilize preview for prerelease graduation (standing PR)

[goosewobbler]

Design spike (2026-07). Correcting the framing: the escalation bugs this was scoped around are already fixed, so the remaining work is a UX/graduation feature, not a bug fix.

The bugs are already fixed

• Bug: standing-PR label overrides don't compose bump:* + prerelease into a pre* bump (prerelease packages can't escalate to a new major line) #335 (escalation) — CLOSED. The standing-PR override path now composes the pre* bump: standing-pr.ts:714 does bump && prerelease ? \pre${bump}` : bump, matching composeBumpFromLabels(the label→bump SSOT inlabel-utils.ts, shared with the gate path). So scope:x+bump:major+ prerelease on an already-prerelease baseline correctly yields2.0.0-next.0, not 1.1.1-next.2`.
• Prerelease versioning bumps base + resets counter (1.0.0-next.3 → 1.1.0-next.0) instead of incrementing (→ 1.0.0-next.4) #500 (fixed base) — CLOSED. While the base is unshipped, changes increment -next.N rather than re-bumping the base and resetting the counter.

So the escalation mechanics work. What's left is the graduation UX — the sampo-derived "always-visible stabilize preview" that makes graduating a prerelease a one-action step and guarantees the stable changelog captures the full prerelease history.

Remaining scope

1. Always-visible stabilize preview. Alongside the prerelease state, surface "what would the stable release look like right now" — the graduated version(s) + the accumulated stable changelog — so a maintainer graduates with one action instead of reconstructing intent.
2. Graduation history accumulation. Specify how interim prerelease notes (1.0.0-next.0..N) roll up into the stable 1.0.0 changelog at graduation, so nothing is lost.

Design options (sketch)

• Option A — in-PR region (lean). A "Stabilize" region in the existing standing-PR body, beside the rk-pre/rk-grad channel toggles and the summary-region (summary-region.ts, already premajor-aware). Graduation = tick rk-grad / merge. Reuses all existing standing-PR / marker / manifest machinery; one control plane, one source of truth.
• Option B — parallel Stabilize PR (sampo's model). A second always-current PR showing the stable graduation; graduation = merge that PR. Cleaner "one-click merge" semantics, but doubles the PR surface plus marker/manifest bookkeeping, concurrency, and refresh logic.
• Lean: A. The standing PR is already a rich control plane; a region is far less machinery than a second managed PR. Revisit B only if the one-click-merge UX proves decisive.

Constraints to preserve (the reason to capture this now)

• composeBumpFromLabels stays the SSOT. The stabilize preview computes the graduated version from the same helper — don't fork the label→bump logic.
• Epic: agent-grade CLI contract — uniform JSON envelope, error codes, changed reporting, structured plan output #544 (CLI contract, 0.42.0) adds structured --json plan output. The stabilize preview is naturally another projection of the same VersionOutput (the graduated variant) — design the plan surface so a "stabilized" view is derivable, not bolted on afterward.
• Epic: changesets-compatible change-file support + migrate --from-changesets #545 (change files, 0.43.0) adds change files as a version-calc input. Graduation-history rollup must include change-file-derived entries, not just commit-derived ones.
• Fixed-base model (Prerelease versioning bumps base + resets counter (1.0.0-next.3 → 1.1.0-next.0) instead of incrementing (→ 1.0.0-next.4) #500). The graduated version = strip the prerelease suffix from the current base (not a re-bump); reconcile with "the base advances only at graduation."

Recommendation

With the escalation bug fixed, the urgent driver is gone — this is now a UX enhancement, not a bug fix. It's appropriately at 0.45.0 (📋 lifecycle) and genuinely optional: the value is "graduation is one action + a guaranteed-complete stable changelog"; the cost is a new standing-PR region + history-rollup plumbing. Detailed design should wait until #544/#545 land (they reshape the plan surface and version inputs this builds on) so it doesn't design against a moving target; this spike captures the direction and the constraints above so that later work is cheap and isn't foreclosed by #544/#545.

Open prioritization question: now that the bugs are fixed, is the stabilize-preview UX worth a 0.45.0 slot, or does it drop to 🔭 later until a consumer actually asks for it? Recommend deciding that when 0.44.0 is in flight, with the constraints above already protected.