feat(release): candidate-branch beta builds and the release checklist (#11209)

> Follow-up to #11208 (merged): rebased onto master and ready for
review.

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The release channels promote artifacts along canary → nightly → beta
→ stable, with the happy path being promotion of an existing build
> - When one or two targeted fixes are needed before a beta or stable,
the only options today are waiting for the next nightly or absorbing a
whole day of unrelated master changes
> - The channel model was designed with an escape hatch for exactly
this: short-lived candidate branches carrying only cherry-picked fixes
> - This pull request implements candidate-branch beta builds with full
verification, documents the stable fix path through the
soak-justification gate, and adds the release captain's checklist
> - The benefit is that a surgical fix can ship forward without either
delay or blast radius, with its provenance recorded

## Linked Issues or Issue Description

Refs #11008 — completes the fix-path half of the channel model
introduced there.

**Subsystem affected**

Release automation: `scripts/release.sh`,
`.github/workflows/release.yml`, `doc/RELEASING.md`, new
`doc/RELEASE-CHECKLIST.md`, tests.

**Problem or motivation**

Beta promotion only accepts commits that already shipped as a nightly,
and stable promotion expects a soaked beta. There is no supported way to
ship one or two cherry-picked fixes between lanes: an urgent fix must
wait for the nightly cycle or pull in every unrelated master change from
the day. The original channel design called for candidate branches to
cover this, and they were deferred from the initial implementation.

**Proposed solution**

Candidate-branch beta builds: cut `candidate/beta-<target>` from a
nightly's source commit, cherry-pick the fixes, and dispatch `channel:
beta` with the new `candidate_branch` input. Selection enforces the
naming convention, rejects heads that already shipped as a beta or
predate the candidate tooling, and records the cherry-picked commits in
the job summary. Because candidate heads never went through a canary or
nightly, publication is gated on a full `release-verify` run (promoted
nightlies keep skipping re-verification). The stable fix path
(`candidate/release-<target>` as `source_ref`) works through the
existing soak gate: the justification requirement is the deliberate,
recorded trade-off for shipping unsoaked bits, and is now documented as
such.

## What Changed

- `scripts/release.sh`: `--from-candidate` flag (beta only) waives the
shipped-a-nightly requirement while keeping the duplicate-beta guard
- `.github/workflows/release.yml`: `candidate_branch` dispatch input;
candidate mode in `select_beta` (naming validation, duplicate and
tooling-era rejection, cherry-pick recording); new
`verify_beta_candidate` job gating candidate publishes on full
verification
- `doc/RELEASING.md`: beta fix-path and stable fix-path sections
- `doc/RELEASE-CHECKLIST.md` (new): the release captain's checklist for
all four lanes as built
- Tests: dry-run fixture coverage for `--from-candidate` (waives the
nightly guard, keeps the duplicate guard, rejected outside beta) and
wiring tests for candidate validation plus the verification gate

## Verification

- `node --test` on the four affected suites: 42 pass in total (17 + 25
across the two runs), including the 5 new tests
- `bash -n` on `release.sh`; YAML parse of the workflow
- After merge: exercise the path end to end the first time a real
cherry-picked beta is needed — dispatch with a `candidate/beta-*` branch
and confirm the summary records the picks and verification runs

## Risks

- Candidate builds bypass the smoke-tested-nightly provenance by design;
the compensating controls are full verification before publish, the
post-publish beta smoke, the human `npm-beta` gate, and recorded
cherry-picks
- The stable fix path rides the existing justification mechanism rather
than adding a second bypass — one recorded escape hatch, not two

## Model Used

Claude Fable 5 (`claude-fable-5`, Anthropic) in Claude Code, with
extended thinking and full tool use. All changes model-authored under
human direction.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green (pending — will confirm before
merge)
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(pending — will confirm before merge)
- [x] I will address all Greptile and reviewer comments before
requesting merge

.github/workflows/release.yml

@@ -31,6 +31,10 @@ on:
         description: For nightly, the explicit canary version to promote (empty selects the newest canary on master). For beta, the explicit nightly version to promote (empty selects the newest nightly on master).
         required: false
         type: string
+      candidate_branch:
+        description: (beta) candidate/beta-* branch to build a cherry-picked beta from. Leave empty to promote a nightly. Mutually exclusive with source_version.
+        required: false
+        type: string
       skip_soak_justification:
         description: (stable) Written justification for publishing a stable whose source has not soaked as a beta for 3 days. Leave empty for normal releases.
         required: false
@@ -362,6 +366,7 @@ jobs:
     outputs:
       sha: ${{ steps.select.outputs.sha }}
       nightly_version: ${{ steps.select.outputs.nightly_version }}
+      mode: ${{ steps.select.outputs.mode }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
@@ -373,11 +378,65 @@ jobs:
         id: select
         env:
           EXPLICIT_NIGHTLY_VERSION: ${{ inputs.source_version }}
+          CANDIDATE_BRANCH: ${{ inputs.candidate_branch }}
         run: |
           set -euo pipefail
 
           git fetch origin --tags --prune --quiet
 
+          # Candidate mode: build a cherry-picked beta from a short-lived
+          # candidate branch instead of promoting a nightly.
+          if [ -n "${CANDIDATE_BRANCH:-}" ]; then
+            if [ -n "${EXPLICIT_NIGHTLY_VERSION:-}" ]; then
+              echo "Error: candidate_branch and source_version are mutually exclusive." >&2
+              exit 1
+            fi
+            case "$CANDIDATE_BRANCH" in
+              candidate/beta-*) ;;
+              *)
+                echo "Error: candidate branches must be named candidate/beta-<target> (got: $CANDIDATE_BRANCH)." >&2
+                exit 1
+                ;;
+            esac
+            git fetch origin "$CANDIDATE_BRANCH" --quiet
+            sha="$(git rev-parse --verify "origin/${CANDIDATE_BRANCH}^{commit}" 2>/dev/null || true)"
+            if [ -z "$sha" ]; then
+              echo "Error: candidate branch $CANDIDATE_BRANCH does not exist on origin." >&2
+              exit 1
+            fi
+
+            existing_beta="$(git tag --points-at "$sha" | grep '^beta/v' | head -1 || true)"
+            if [ -n "$existing_beta" ]; then
+              echo "Error: candidate head $sha already shipped as $existing_beta." >&2
+              exit 1
+            fi
+
+            if ! git show "${sha}:scripts/release.sh" | grep -qF -- '--from-candidate'; then
+              echo "Error: candidate head $sha predates candidate-build release tooling; rebase the candidate onto a newer base." >&2
+              exit 1
+            fi
+
+            merge_base="$(git merge-base origin/master "$sha")"
+            echo "mode=candidate" >> "$GITHUB_OUTPUT"
+            echo "sha=$sha" >> "$GITHUB_OUTPUT"
+            echo "nightly_version=" >> "$GITHUB_OUTPUT"
+            {
+              echo "## Beta candidate branch"
+              echo ""
+              echo "- Branch: \`$CANDIDATE_BRANCH\`"
+              echo "- Head: \`$sha\`"
+              echo "- Base (merge-base with master): \`$merge_base\`"
+              echo "- Cherry-picked commits:"
+              echo ""
+              echo '\`\`\`'
+              git log --oneline "${merge_base}..${sha}"
+              echo '\`\`\`'
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          echo "mode=promote" >> "$GITHUB_OUTPUT"
+
           if [ -n "${EXPLICIT_NIGHTLY_VERSION:-}" ]; then
             tag="nightly/v${EXPLICIT_NIGHTLY_VERSION}"
             sha="$(git rev-list -n 1 "$tag" 2>/dev/null || true)"
@@ -425,8 +484,23 @@ jobs:
             echo "- Source nightly: \`$nightly_version\`"
           } >> "$GITHUB_STEP_SUMMARY"
 
-  publish_beta:
+  # Candidate-branch heads are new commits that never went through a canary
+  # or nightly, so they must pass full verification before publishing.
+  # Promoted nightlies were already verified by their canary run and skip it.
+  verify_beta_candidate:
     needs: select_beta
+    if: needs.select_beta.outputs.mode == 'candidate'
+    uses: ./.github/workflows/release-verify.yml
+    with:
+      ref: ${{ needs.select_beta.outputs.sha }}
+
+  publish_beta:
+    needs: [select_beta, verify_beta_candidate]
+    if: >-
+      !cancelled() &&
+      needs.select_beta.result == 'success' &&
+      (needs.verify_beta_candidate.result == 'success' ||
+       (needs.verify_beta_candidate.result == 'skipped' && needs.select_beta.outputs.mode == 'promote'))
     runs-on: ubuntu-latest
     timeout-minutes: 45
     environment: npm-beta
@@ -480,6 +554,9 @@ jobs:
           GITHUB_ACTIONS: "true"
         run: |
           args=(beta --skip-verify)
+          if [ "${{ needs.select_beta.outputs.mode }}" = "candidate" ]; then
+            args+=(--from-candidate)
+          fi
           if [ "${{ inputs.dry_run }}" = "true" ]; then
             args+=(--dry-run)
           fi