release

name	release
description	Use when the user wants to release a new version. Orchestrates the full release workflow including milestone check, version bump, changelog generation, validation, tagging, and PR creation. Also use when discussing release planning or version management.

Release Workflow (12 Phases)

Phase 1: Milestone Check

• List open milestones via gh api
• Verify 0 open issues in target milestone
• Stop if issues remain (ask user to move/close)

Phase 2: Version Number

• Read current version from pyproject.toml (authoritative)
• Milestone title = target version
• Confirm with user

Phase 3: Create Release Branch

• git checkout -b release/vX.Y.Z from main

Phase 4: Bump Version

Update ALL files (pyproject.toml is authoritative):

1. pyproject.toml — version = "X.Y.Z"
2. src/apple_mail_fast_mcp/__init__.py — __version__ = "X.Y.Z"
3. .claude/CLAUDE.md — **Version:** vX.Y.Z
4. README.md — all version references
5. mcpb/manifest.json — "version": "X.Y.Z" (the .mcpb bundle; check_version_sync.sh enforces it)
6. .claude-plugin/marketplace.json + .claude-plugin/plugin.json — every "version": "X.Y.Z" (the Claude Code plugin; check_version_sync.sh enforces all occurrences)

Phase 5: Generate CHANGELOG

• Commits since last tag: git log v{prev}..HEAD --oneline
• PRs since last release: gh pr list --state merged --search "merged:>YYYY-MM-DD"
• Keep a Changelog format: ## [X.Y.Z] - YYYY-MM-DD
• Categories: Added, Changed, Fixed, Removed

Phase 6: Test Coverage Review

• Run coverage: make coverage
• Compare against fail_under in pyproject.toml
• Audit changed files for adequate coverage

Phase 7: Code Review

• Launch superpowers:code-reviewer against cumulative diff
• Critical issues block release

Phase 8: Documentation Review

• README, CLAUDE.md, CHANGELOG, docs/**, tool docstrings, skills
• The content-drift gate (check_docs.sh, Phase 9) automates the tool-set / removed-name / cross-ref / eval-description-sync parts; this phase is the human read for things it can't check (accuracy, tone, completeness).

Phase 8.5: Refresh derived artifacts (mandatory, #288)

Derived artifacts rot silently between releases — refresh them against the release commit so a stale snapshot can't ship:

1. make eval-descriptions — regenerate the blind-eval tool descriptions; commit if changed. (check_docs.sh also fails on drift here.)
2. Re-capture the benchmark baseline (#216): MAIL_TEST_MODE=true MAIL_TEST_ACCOUNT=<acct> uv run pytest tests/benchmarks/ --run-benchmark --capture-baseline (needs real Mail.app); commit the refreshed baseline.json.
3. Re-run the blind agent eval (#219) and refresh its scored snapshot (needs OPENROUTER_API_KEY); commit.

Steps 2 and 3 are enforced by ./scripts/check_release_artifacts.sh (Phase 9): the benchmark baseline and the eval snapshot are version-stamped, and the gate fails the release if a stamp is stale. If an artifact genuinely can't be refreshed for this release (e.g. a CI/docs-only release), don't skip silently — record a waiver line (with a tracking issue) in release_artifact_waivers.txt. See docs/guides/RELEASE_ARTIFACTS.md. (#356)

Phase 9: Validation

Run ALL checks (stop on failure):

1. ./scripts/check_version_sync.sh
2. ./scripts/check_client_server_parity.sh
3. ./scripts/check_complexity.sh
4. make test
5. make test-e2e — mandatory (requires MAIL_TEST_MODE=true + a test Mail.app account). CI excludes e2e, so this is the only gate that catches a stale e2e failure. A pre-existing failure on main is a release-blocker, not a known issue to ship around (#257).
6. ./scripts/check_dependencies.sh — hard-fails only on advisories in direct deps (fastmcp/imapclient); transitive advisories are warnings (exit 0), surfaced continuously off the release path by .github/workflows/dependency-audit.yml so they don't block a release (#296). A direct-dep advisory still blocks — bump the pin and re-run.
7. ./scripts/check_applescript_safety.sh
8. ./scripts/check_docs.sh — doc/artifact drift gate (tool-set coverage, removed-name, cross-refs, eval-description sync) (#288)
9. ./scripts/check_release_artifacts.sh — fails if the benchmark baseline or eval snapshot isn't version-stamped for this release (Phase 8.5 #2/#3) and isn't waived in release_artifact_waivers.txt (#356)

Phase 10: Commit, Push, PR

• Commit: "release: vX.Y.Z"
• Push: -u origin release/vX.Y.Z
• PR to main via gh pr create

Phase 11: Merge, Tag, Push Tag

• Rebase merge: gh pr merge NNN --rebase --delete-branch
• Tag on main: ./scripts/create_tag.sh vX.Y.Z
• Push tag: git push origin vX.Y.Z
• Verify: git describe --tags --abbrev=0

Phase 12: Close Milestone

• gh api -X PATCH repos/{owner}/{repo}/milestones/{number} -f state=closed

Notes

• CHANGELOG only updated on release branches
• Tags created on main AFTER PR merge
• Use rebase merge (linear history required)
• Each phase has explicit stop conditions — if it fails, stop and report