Release Flow

Drive the end-to-end release flow. Only one explicit user approval is required: merging the Release PR (CLAUDE.md mandates manual review). Everything else runs automatically after the pre-flight checks pass.

Release trigger conditions (Conventional Commits)

release-please routes commits to packages by scope and file path. The commit prefix determines the bump:

Scope MUST match a package component (e.g. runnel, silo) declared in release-please-config.json. Commits lacking matching scope or a file path under packages/<scope>/ will not trigger a release for that package.

Before starting, scan the commits in dev vs main. If none carry a release-triggering prefix (feat / fix / ! / BREAKING CHANGE), stop and tell the user no release will be generated.

Step 1: Pre-flight

Check and stop if any condition fails (unless noted):

• Current branch is dev. If not, ask before switching.
• Working tree is clean.
• dev is ahead of origin/main (git fetch origin main && git log origin/main..dev --oneline --no-merges).
• At least one commit has a release-triggering prefix.
• No conflicting open dev→main PR that belongs to a different flow (reuse if it exists for this release).

Step 2: Create (or reuse) the dev→main PR

If an open PR from dev to main already exists, reuse it. Otherwise:

Step 2.1: Collect closing keywords from dev-only PRs

GitHub's auto-close only fires for closing keywords in the default branch merge PR body. Feature PRs carry Closes #N in their own body, but those never reach main directly. Aggregate them into the dev→main PR body so referenced issues auto-close on merge.

# Extract PR numbers from commits in origin/main..dev (merge commit "#NNN" and squash "(#NNN)")
PRS=$(git log origin/main..dev --oneline | grep -oE "#[0-9]+" | sort -u | tr -d '#')

# Pull closing keywords from each PR body and normalize to "Closes #N"
CLOSES=$(for pr in $PRS; do
  gh pr view "$pr" --json body --jq '.body' \
    | grep -oiE "(close[sd]?|fix(e[sd])?|resolve[sd]?) +#[0-9]+" \
    | grep -oE "#[0-9]+"
done | sort -u | sed 's/^/Closes /')

Inspect $CLOSES before embedding — exclude any issue that should stay open (e.g. tracking issues referenced informally).

Step 2.2: Create the PR

gh pr create --base main --head dev --title "release: dev → main" --body "$(cat <<EOF
## Summary

<one line per non-merge commit, grouped by package>

## Release Notes

<expected version bumps, or "no bumps expected">

## Closes

$CLOSES

## Test plan

- [x] dev CI green
- [ ] main PR CI green
- [ ] release-please Release PR generated
EOF
)"

If $CLOSES is empty, omit the ## Closes section.

Step 3: Wait for CI on the dev→main PR

gh pr checks <pr-number> --watch

On failure, stop and report — do not retry blindly.

Step 4: Merge the dev→main PR (merge commit)

Use --merge, never --squash — release-please must see individual Conventional Commits on main.

gh pr merge <pr-number> --merge

Do not delete dev (long-lived branch).

Step 5: Wait for release-please to open the Release PR

The Release workflow runs on push to main and (if releasable commits exist) opens a chore: release main PR.

gh run watch <release-workflow-run-id> --exit-status
gh pr list --base main --state open --label "autorelease: pending"

If no Release PR appears:

• All commits were non-releasing prefixes → expected, inform and stop.
• Otherwise → inspect the Release workflow logs and report.

Step 6: Present the Release PR and ask for approval (REQUIRED)

Show the PR title, body (CHANGELOG preview), and changed files. Explicitly ask the user to approve before merging. Never auto-merge even if CI is green — CLAUDE.md requires manual review.

gh pr view <release-pr-number> --json title,body,files

Step 6.1: Verify autorelease: pending label

The post-release workflow (tag generation / build-and-commit / sync-dev) uses the autorelease: pending label on the squash-merge commit to recognize it as a Release PR merge. Without this label, post-release jobs do not run and no tag / GitHub Release is generated.

release-please-action usually attaches the label when creating the Release PR, but it can silently fail (e.g. GitHub API errors resolving old PR global IDs). Verify before Step 7:

gh pr view <release-pr-number> --json labels --jq '.labels[].name'

If autorelease: pending is missing, ask the user before adding it (do not auto-edit without confirmation). On approval:

gh pr edit <release-pr-number> --add-label "autorelease: pending"
gh pr view <release-pr-number> --json labels --jq '.labels[].name'

Re-confirm the label is present before proceeding to Step 7.

Step 7: Merge the Release PR (squash)

After user approval:

gh pr merge <release-pr-number> --squash

Step 8: Wait for post-release jobs

The Release workflow runs again on the squash-merge commit and executes three jobs in sequence:

1. release-please — creates tags + GitHub Releases
2. build-and-commit — rebuilds dist/ and commits to main
3. sync-dev — merges main → dev (opens a PR if conflicts arise)

gh run watch <workflow-run-id> --exit-status
gh run view <workflow-run-id> --json jobs --jq '.jobs[] | {name, conclusion}'

Confirm all three succeeded. If sync-dev opened a conflict PR instead of fast-forwarding, surface it to the user.

Step 9: Sync local dev

git checkout dev
git pull --ff-only origin dev

Final report

• Released packages and versions (gh release list --limit 5)
• Any follow-up PRs (sync-dev conflicts, etc.)
• Local dev state