release

# Release

Use this skill when the user wants changelog text, release notes, or a `CHANGELOG.md` update for Agent Safehouse.
This skill is also the canonical local release workflow for Agent Safehouse.

Historical changelog sections are append-only by default.
Do not rewrite, normalize, or reformat older release entries to match a newer structure unless the user explicitly asks for a changelog migration or cleanup pass.

This skill is responsible for proposing the next release version from the last published release.
The repo-root `VERSION` file is the canonical version source for Agent Safehouse.
Write the selected version into `VERSION` and into the new `CHANGELOG.md` heading unless the user explicitly gives a different target version.
Default to a stable release. Only choose a prerelease version such as `-rc.N` or `-beta.N` when the user explicitly asks for a prerelease.
If the user explicitly gives the target version, honor it even if the default SemVer analysis would have chosen a different bump. In that case, note briefly in the dry run that the version came from an explicit user override.

## Workflow

1. Resolve the baseline release.
   If the user gives a starting version, use it.
   Otherwise:
   - Prefer the latest published stable GitHub release tag from `gh release list --exclude-drafts --exclude-pre-releases`.
   - Ignore draft releases.
   - Ignore prereleases such as `-rc`, `-beta`, and other hyphenated SemVer suffixes unless the user explicitly asks to prepare a prerelease.
   - If GitHub release metadata is unavailable, fall back to the latest stable SemVer git tag.

2. Decide the next SemVer version from the release range.
   Start from the resolved baseline release and choose:
   - `major` for breaking changes, incompatible CLI behavior, removed capabilities, changed defaults that are likely to break existing setups, or sandbox/policy tightening that requires user action to restore a previously supported workflow.
   - `minor` for backward-compatible new features, new integrations, new profiles, new user-visible capabilities, or meaningful expansions of supported workflows.
   - `patch` for bug fixes, non-breaking sandbox/profile corrections, docs, tests, internal cleanup, and other maintenance-only changes.
   - If the range mixes features and fixes but nothing breaking, choose `minor`.
   - If the range is ambiguous and there is no clear breaking change or new feature, choose `patch`.
   - If you choose `major`, explicitly state why in the drafted release notes.
   - If the user explicitly asks for a prerelease, first choose the target stable version using the rules above, then append the requested prerelease suffix such as `-rc.1` or `-beta.1`.
   - If the user explicitly asks for another prerelease in the same series, increment that series from the latest matching non-draft prerelease tag or release, for example `1.4.0-rc.1` to `1.4.0-rc.2`.

3. Collect git context directly.
   Default the target ref to `HEAD` unless the user specifies another tag or commit.
   Treat `dist/` as generated output, not release-note source of truth.
   Do not load `dist/` diffs or `dist/` files into context while evaluating customer-visible changes, choosing the version bump, or drafting changelog bullets.
   Evaluate the original source changes in the rest of the repo instead, especially `bin/`, `bin/lib/`, `profiles/`, `scripts/`, `tests/`, and docs.
   Start with:
   - `git log --reverse --no-merges <from-ref>..<to-ref> --format='%h %s'`
   - `git log --reverse --merges <from-ref>..<to-ref> --format='%h %s'`
   - `git diff --stat <from-ref>..<to-ref> -- . ':(exclude)dist/**'`
   - `git diff --dirstat=files,0 <from-ref>..<to-ref> -- . ':(exclude)dist/**'`
   - `git diff --name-only <from-ref>..<to-ref> -- 'profiles/**/*.sb' 'profiles/*.sb'`
   - `git diff --name-only <from-ref>..<to-ref> -- . ':(exclude)dist/**'`
   Only look at `dist/` after confirmation, during the regeneration and verification stage.

4. Review anything ambiguous before writing notes.
   Use `git show --stat <sha>` or `git diff <from-ref>..<to-ref> -- <path>` for commits that are not obvious from the subject line.
   When a commit touches both source files and `dist/`, review only the source files and do not open the generated `dist/` portion.
   For any changed sandbox profile, inspect the actual diff before summarizing it.
   Also collect contributor context for shipped work:
   - Extract merged PR numbers from commit subjects, merge commits, or `gh pr list --state merged ...` when needed.
   - Use `gh pr view <num> --json number,title,author,url,closingIssuesReferences`.
   - For any linked or clearly relevant issue, use `gh issue view <num> --json number,title,author,url`.
   - Prefer crediting external contributors and issue reporters whose merged PRs or closed issues directly map to shipped changes in this release.
   - Do not include open issues or unmerged PRs in `Thanks` unless the user explicitly asks.
   - If the user explicitly asks to include a specific PR or issue in `Thanks`, include it even when it is still open or unmerged.
   - Do not thank the release author for their own PRs or issues unless the user explicitly asks.

5. Draft changelog bullets in this order:
   - `### Upgrade Notes`
   - `### Features`
   - `### Bug Fixes`
   - `### Chores`
   - `### Misc`
   - `### Thanks`
   - `### Changed Sandboxing Profiles`

6. Keep the changelog high signal.
   - Use `Upgrade Notes` only for changes that require user action, verification, migration, reinstall steps, or awareness of a compatibility/default change.
   - If a change is breaking or likely to surprise existing users, put the actionable guidance in `Upgrade Notes`.
   - Start an upgrade note with `Breaking:` when the change is intentionally incompatible.
   - Do not repeat the same customer-facing point across multiple sections unless the extra context is genuinely useful.
   - Prefer user-visible behavior, compatibility, and install/release