Cut Release

cut-release -- assess, sanitize, bump, lint, open PR

This skill drives the release-cut workflow end-to-end on the current

worktree. It STOPS at "PR open"; tagging is the human-gated trigger

that fires the release workflow.

When to use

Trigger this skill on any of these intents:

• "cut a release"
• "ship v0.x" / "ship the release"
• "release prep" / "prepare the release"
• "bump and open the PR"
• "open the release PR"
• "what kind of release do we need now"
• "we have enough merged for a release"
• Any phrasing that ends in opening a release PR.

Do NOT trigger on:

• "tag v0.16.0" -- tagging is the post-merge step the operator runs.
• "publish a blog post" / "draft release notes for the website".
• "what changed since v0.15.0" -- enumeration only, no release.
• "regenerate uv.lock" / raw version-string edits.
• "rollback to v0.15.0" -- release reversal is a different skill.

Companion primitives

The skill DEPENDS on these existing primitives in the same source

tree. Do not duplicate their content; reference them.

• .apm/skills/apm-strategy/SKILL.md -- versioning judgement and

breaking-change lens. Auto-loads via its own trigger on

CHANGELOG.md and release-pipeline edits. Treat it as the

authoritative lens for "is this BREAKING" and "does this

positioning change warrant a migration note".

• .apm/instructions/linting.instructions.md -- canonical

CI-mirror lint chain. Reference; do not re-derive ruff / pylint

command lists in this skill.

• .github/instructions/changelog.instructions.md -- Keep-a-

Changelog format contract. Reference; do not redefine the

format.

Output charset rule

Per .github/instructions/encoding.instructions.md, source files in

this bundle (SKILL.md, assets, scripts) MUST stay in printable ASCII.

The PR body and changelog entries this skill produces are also

written to repo files (CHANGELOG.md, PR body), so they MUST stay

ASCII too. Use -- for em dashes, [!] / [+] / [x] for status

markers, and so on.

Procedure

Run these phases in order. Reload plan.md (the session memento)

at the start of each phase and after every tool return.

Phase 0 -- ground state

• Read the current branch with git rev-parse --abbrev-ref HEAD.

The skill assumes you are on a release-prep branch (or are

willing to create one). If you are on main, STOP and ask the

operator to put you on a branch.

• Resolve the last release tag with git describe --tags --abbrev=0.
• Persist the goal to plan.md:
• Range: <last-tag>..HEAD.
• Acceptance: release PR is open, lint mirror green, no version

bumped beyond what the cycle warrants.

Phase 1 -- enumerate merged PRs

Run scripts/list-changes-since-tag.sh (no arguments). It emits

JSON on stdout: one object per merged PR with fields pr, title,

labels, author, paths_summary, is_user_facing_guess.

The script's heuristic for is_user_facing_guess is

intentionally conservative -- it flags as INTERNAL only when the

diff is fully contained in .apm/, .github/instructions/,

tests/, docs/, or matches chore(repo). Treat the field as a

HINT, not a verdict; the LLM makes the final call per

assets/entry-sanitizer.md.

DO NOT rely on training-recalled PR titles. Truth #5: pretraining

is frozen. Every PR title in the changelog must come from the

script's stdout.

Phase 2 -- pick the bump (B10 CHECKPOINT 1)

Load assets/semver-rubric.md. Walk every PR from Phase 1

against the rubric. The rubric outputs PATCH, MINOR, or

ESCALATE-TO-MAJOR.

Show the operator:

• The chosen bump and the next version number.
• Per-PR rationale (which signal fired).
• The "why patch/minor" one-liner that will go into the PR body.

If the rubric outputs ESCALATE-TO-MAJOR (>= 1.0.0), STOP and

surface the escalation per assets/semver-rubric.md "Major bump"

section. Do not bump to 1.0.0 without explicit operator

confirmation.

Wait for the operator's confirm before continuing.

Phase 3 -- sanitize the changelog (B10 CHECKPOINT 2)

Load assets/entry-sanitizer.md. For each PR classified as

user-facing in Phase 1:

• Choose its section: Added (new feature, new command, new spec),

Changed (behavior change in existing surface), Fixed (bug fix),

Deprecated, Removed, Security, Performance.

• Write ONE entry per PR. Two-sentence cap. "So what" framing.

PR number in parentheses at the end. Preserve by @author for

external contributors.

• Consolidate any pre-existing Unreleased entries that point at

the same PR.

• Drop INTERNAL PRs entirely (the script flagged most of them;

the rubric in entry-sanitizer.md confirms).

• Mark BREAKING entries with BREAKING: prefix.

Rewrite the CHANGELOG.md [Unreleased] block in place:

## [Unreleased]

## [X.Y.Z] - YYYY-MM-DD

### Added
...
### Changed
...
### Fixed
...

Keep an empty [Unreleased] placeholder above the new version

heading. The date is today (read from the operator's environment,

not recall).

Show the operator the unified diff against CHANGELOG.md. Wait for

confirm before continuing.

Phase 4 -- bump version files

Run scripts/bump-version.sh <new-version>. The script edits

pyproject.toml (the version = "..." line in [project]) and

runs uv lock to refresh uv.lock. It prints a unified diff to

stdout for human review.

If the script exits non-zero, surface the error and STOP -- do not

continue with a partial bump.

Phase 5 -- verify lint mirror (S4 gate; B10 CHECKPOINT 3 on fail)

Run scripts/verify-lint-mirror.sh. It mirrors the four CI lint

steps from .apm/instructions/linting.instructions.md verbatim

(ruff check, ruff format --check, pylint R0801, auth-signals).

If it passes (exit 0), proceed to Phase 6.

If it fails (exit 1), STOP. Surface the failures to the operator.

Common cures:

• ruff diagnostics -- run `uv run --extra dev ruff check src/

tests/ --fix and uv run --extra dev ruff format src/ tests/`.

• pylint R0801 -- duplication landed via a recent main commit;

merge main first, then re-run.

• auth-signals -- consult scripts/lint-auth-signals.sh output.

Do NOT push or open the PR until lint is green. The PR description

will claim CI is green; that claim must hold.

Phase 6 -- commit, push, open PR

• git add CHANGELOG.md pyproject.toml uv.lock.
• git commit -m "chore: release vX.Y.Z" -m "<short body>".

The body mirrors prior release commits (#1410, #1454, #1526):

one paragraph naming what was bumped and the lint-mirror

confirmation, plus the "post-merge: tag vX.Y.Z" reminder.

Include the standard Co-authored-by trailer.

• git push -u origin HEAD.
• Compose the PR body from assets/pr-body-template.md,

substituting {version} (unprefixed, e.g. 0.16.1 -- used by

CHANGELOG.md and pyproject.toml), {tag} (v-prefixed, e.g.

v0.16.1 -- used by the post-merge git tag block, since the

release workflow's stable-release regex requires the v prefix

per .github/workflows/build-release.yml), {date},

{bump_rationale}, and (if BREAKING) {breaking_summary}.

• `gh pr create --base main --head <branch> --title

"chore: release vX.Y.Z" --body-file <tmpfile>`.

• Echo the PR URL.
• Surface the post-merge step explicitly: "Post-merge: tag

vX.Y.Z to trigger the release workflow." Do NOT tag.

Phase 7 -- update plan and exit

Mark each plan.md todo as done. The session ends here. Tagging is

the operator's decision and lives outside this skill.

Anti-patterns this skill refuses

• TAGGING. Tagging is a separate, human-gated step. If asked to

tag inside this session, decline and remind the operator that

the release workflow expects git tag vX.Y.Z && git push --tags

after PR merge.

• BUMP-TO-MAJOR-UNPROMPTED. 0.x -> 1.0.0 is a positioning

decision. ESCALATE per assets/semver-rubric.md.

• HAND-ROLLED PR TITLES. Every changelog entry must be backed by

a PR title from scripts/list-changes-since-tag.sh stdout. No

recall.

• CHATTY GATE. Three operator checkpoints, no more (version pick,

sanitized changelog, lint-fail recovery). Do not ask per-PR or

per-section.

• PARTIAL PUSH. If lint fails, do not push. The release PR

asserts green CI; pushing red breaks the contract.

• SKIPPED LINT. Do not skip Phase 5 even if the diff looks

trivial. The lint mirror catches code-duplication drift on the

merge commit, which is invisible to a local diff inspection.

Boundary

This skill does NOT:

• Tag the release.
• Run the test suite or build PyInstaller binaries.
• Publish a GitHub Release body, blog post, or announcement.
• Decide whether a release should happen -- the operator decided

that by activating this skill.

• Bump to >= 1.0.0 without explicit operator confirmation.
• Review code quality or test coverage (use apm-review-panel

before activating this skill if a recent PR needs review).