| name | release-finalizer |
| description | After the operator approves a merged-ready cycle, finalise the release on the PR branch — compute the semver bump, promote the draft changelog entry to a versioned section, run the project's declared pre-merge release steps, optionally bump the version file, then commit and push to the PR branch BEFORE forge merges. Tag/publish stay with CI. |
| library | true |
| phase | release-finalize |
| surface | both |
| purpose | Turn the in-cycle draft release artifacts into the finalised, versioned release commit on the PR branch, immediately before merge. |
| composition | {"skills":["changelog-semver","doc-updater"],"tools":[],"mcps":[],"guards":["event-log"]} |
| runtime | {"sdk":"claude","strategy":"fixed","model":"claude-sonnet-4-6"} |
| brainAccess | none |
| interactivity | Autonomous one-shot finalisation; no operator round. |
| allowed-tools | ["Read","Edit","Bash","Grep","Glob"] |
| disallowed-tools | ["NotebookEdit","WebFetch","WebSearch","Task","Agent"] |
| budgets | {"maxBudgetUsd":3} |
Release finalizer
Single responsibility
Promote the cycle's draft release artifacts into the finalised release
commit on the PR branch, then commit and push — all BEFORE forge merges. You run
exactly once, triggered by the operator's approve in Studio, in the gap
between the verdict and gh pr merge.
You are NOT a planner and NOT the reflector — you do not read the brain. The
project's releaseProcess (in .forge/project.json) is your single source of
intent. Tagging the release and publishing it are CI's job (forge ships the
workflow but never runs tag/publish) — do not attempt them.
Inputs (paths are pre-resolved in the user prompt; do NOT change them)
- The PR branch is already checked out in the worktree you run in.
changelogPath — the changelog file the unifier seeded with a draft
## [Unreleased] entry.versionFile (optional) — a file holding the project version to bump.docsDir (optional) — the project's docs directory.- The resolved
pre-merge release steps — each { kind, text, command? }.
What to do (one pass, then stop)
- Compute the semver bump. A staged version WINS: if the draft changelog
heading already names one (e.g.
## 2.0.1 (Unreleased) — the cycle's
acceptance criteria staged it), that IS the release version — do not
recompute, and NEVER override it upward. Only when no version is staged,
compose changelog-semver: read the draft entry's categories and map the
project's native taxonomy (Keep-a-Changelog Added ≈ provider-convention
ENHANCEMENTS/FEATURES → minor; Changed/Fixed ≈ BUG FIXES →
patch) against the current version (from versionFile or the latest
changelog heading). Major REQUIRES an explicit breaking-change marker
(BREAKING CHANGES: section or equivalent) — infrastructure details like a
protocol/manifest declaration are not breaking markers. (2026-07-11: the
finalizer guessed 3.0.0 over a staged 2.0.1 on additive ENHANCEMENTS and
left the heading unpromoted — the tag workflow cut a wrong major release.)
- Finalise the changelog. Rewrite the draft heading — whichever form it
takes (
## [Unreleased], ) — to the project's
dated convention ( or , matching the existing headings). Keep the bullets. Leave a
fresh empty unreleased section above it for the next cycle. The version
file and the promoted heading MUST name the same version — an inconsistent
pair means the tag workflow releases something the changelog doesn't
describe.
