| name | version-bump |
| description | Sub-orchestration for phase 2 of a release — cutting the bump branch from the freshly-fetched release target, applying the coordinated version bump, regenerating the changelog, running local release preparation, and landing the bump PR. Sequences six steps, dispatching version-management for the bump itself plus ci-gate-watch, ci-failure-triager, and merge-verifier, and routes on each outcome including the lockfile/diff-hygiene edge. Holds no versioning policy. Dispatched by release-orchestration. |
Version Bump — pipeline only
Phase 2 of a release. Its job: the target version exists on the release target, cleanly. How versions
are chosen, how the bump tool is driven, and what a coordinated bump means are owned by
version-management — this skill dispatches it and routes on the result.
Rule Anchor
- publish.md — "Release State Machine" (this phase's per-step constraints: fresh
base, never hand-edit the lockfile, no unrelated process fixes in a bump PR), "Stop Conditions".
- version-management — all versioning policy and the bump mechanics.
- git-branch.md — branch base freshness, "Merge Landing Verification".
Steps and routing
1. Cut the bump branch from the freshly-fetched release target. Fetch first; a stale local branch is
the failure this step exists to prevent.
| Outcome | Route |
|---|
| Branch cut from the current remote head | Advance to step 2. |
| The remote head moved after the fetch | Repeat step 1 against the new head. |
| The remote head does not contain phase 1's merge | Return REGRESSED — stabilization did not land what it claimed; do not bump on top of it. |
2. Apply the version bump. Dispatch version-management. When package
manifests change, run the project's install so the lockfile is regenerated — never hand-edit it.
| Outcome | Route |
|---|
| Bump produced the expected version + changelog diffs | Advance to step 3. |
| The bump produced no diff | Repeat step 2 after confirming the correct bump entry point was used; if it still produces nothing, return HALT. |
| A changeset is missing for a changed package | Repeat step 2 after adding it — an incomplete changelog is a defect, not a cosmetic issue. |
3. Regenerate the changelog through the generator publish.md names. The rule
requires the bump PR to carry a generated changelog; a hand-written one does not satisfy it.
| Outcome | Route |
|---|
| Regenerated, and the diff matches the bump | Advance to step 4. |
| The generator produced nothing or errored | Repeat step 2 — an empty changelog usually means the bump itself was incomplete. |
4. Run local release preparation. Build, the project's publish-safety scan, and diff hygiene (the
branch contains the bump and nothing else).
| Outcome | Route |
|---|
| All clean | Advance to step 5. |
| Build or the publish-safety scan fails | Dispatch ci-failure-triager; take the triage routing table below. |
| Diff hygiene fails on lockfile churn from step 2 | This is expected output of the bump, not contamination: confirm it is exactly the install's regeneration, keep it, advance. If it is anything more, return to step 1 and re-cut cleanly. |
| Diff hygiene fails on unrelated changes | Remove them from this branch (a Release State Machine constraint) and repeat step 4. If they cannot be separated, return to step 1. |
5. Open the bump PR against the release target and wait for CI on the exact SHA.
| Outcome | Route |
|---|
| Checks not yet conclusive | Dispatch ci-gate-watch and route on its outcome. |
| Green on the exact SHA | Advance to step 6. |
| Red | Dispatch ci-failure-triager; take the triage routing table below. |
| The release target moved under the PR | Return to step 1 — re-cut from the new head rather than merging a stale base. |
6. Merge the bump PR, then verify it landed. Merge only on green, with the approval
git-branch.md requires.
| Outcome | Route |
|---|
Merged → merge-verifier returns MERGE VERIFIED: PASS | Return COMPLETE. |
merge-verifier returns MERGE VERIFIED: FAIL | Merge absent on the remote head → return to step 6. Version files missing or drift swept in → HALT. |
| Approval not given | Return HALT. |
Triage routing (steps 4 and 5)
Identical shape to phase 1's, because the routing belongs to the failure class rather than the phase.
Track triage_attempts per distinct failure signature, cap 2.
| Class returned | Route |
|---|
product defect / CI harness infrastructure | Fix it off this branch (the bump PR stays pure), land it, then return to step 1. |
dependency or lockfile sync | Re-run the install on this branch and repeat step 4 — this class is in-scope for a bump branch. |
test race or flake | Re-run once. Green → return to the dispatching step. Red again → treat as product defect. |
external environment or service | Re-run after the recommended interval, at most twice, then HALT. |
| Validation path does not pass after the fix | Re-triage with the new signature; increment triage_attempts. |
triage_attempts exceeds the cap for one signature | Return HALT. |
Outcome contract
COMPLETE — the target version is on the release target and independently verified as landed.RETRY — re-run the phase from step 1.REGRESSED — the release target no longer contains what phase 1 landed; the caller returns to phase 1.HALT — a stop condition fired, approval is missing, or a cap was exceeded. Name which.
