/release

name: release
description: >
  Cut a new release: group Conventional Commits since the last tag,
  append a CHANGELOG section, create a release commit, and add an
  annotated git tag.
  TRIGGER when the user says "cut a release", "tag a release",
  "release v1.2.0", "ship version 1.2.0", "create a release for
  1.2.0", "bump the version to 1.2.0", "make a release",
  "generate a changelog and tag", "what version should I release",
  "what's the next version", "bump minor", "bump major",
  "bump patch", "suggest a version", "/nyann:release".
  Do NOT trigger on "release branch" / "cut a release branch" — that
  is the `new-branch` skill with `--purpose release`. Do NOT trigger
  on "publish to npm" / "push to pypi" — those are package-manager
  operations outside nyann's wedge.

release

Wraps `bin/release.sh`. Default strategy is `conventional-changelog`: walk the commit range since the last matching tag, group commits by Conventional Commits type, prepend a CHANGELOG block, commit the changelog, then annotated-tag `v<version>`.

0. Drift check (quick, non-blocking)

Run `bash bin/session-check.sh --flow=release`. If it produces output, surface the line to the user verbatim. Do not block the flow.

1. Suggest version (when not explicitly provided)

When the user does **not** supply an explicit `--version`, run `bin/recommend-version.sh` to suggest one:

bin/recommend-version.sh --target <cwd> [--tag-prefix <p>]

Show the recommendation to the user:

> Based on commits since `<current>`, I'd suggest **`<recommended>`** > (`<bump>` bump — `<reason>`). Shall I proceed with `<recommended>`, > or would you prefer a different version?

Wait for confirmation before proceeding. The user can accept, override with a different version, or abort.

When the user **does** supply an explicit version (e.g. "release v2.0.0"), skip this step entirely — don't second-guess them.

When the user says "bump minor" / "bump major" / "bump patch", run `recommend-version.sh` to get the current version, then apply the requested bump type (ignore the script's own recommendation). Confirm the computed version with the user before proceeding.

2. Collect inputs

• **`--version <x.y.z>`** — required for `release.sh`. Must be semver

(or `x.y.z-prerelease`). Populated from step 1 when the user accepted the suggestion, or from their explicit input.

• **`--strategy`** — defaults to `conventional-changelog`. Override to

`manual` when the user says "just tag it, skip the changelog". `changesets` / `release-please` are soft-skip values: the script emits a skip record pointing the user at those tools directly.

• **`--changelog <path>`** — defaults to `CHANGELOG.md`. Override when

the repo uses a different file.

• **`--tag-prefix <p>`** — defaults to `v`. Override for monorepos

that namespace tags (`api-v1.2.0`).

• **`--from <ref>`** — defaults to the latest tag matching

`tag_prefix`. Override when the user says "include everything since commit X".

When the repo's active profile has a `release` block, prefer its values over the defaults. Ask before overriding what the profile declares.

3. Pre-flight

• Current tag `<prefix><version>` must not already exist. If it does,

`release.sh` dies with a clear message; relay it.

• Working tree must be clean. Refuse on dirty tree and ask the user

to commit or stash first. (Exception: `--dry-run` skips this gate so the user can preview.)

• Branch doesn't matter — release can cut from any branch (main is

the common case, but patch releases from `release/*` or `hotfix/*` are legitimate).

Pre-action guards

bash bin/pre-action-guard.sh --flow release --target <cwd> [--profile <resolved-profile.json>]

The built-in `clean-tree` guard catches a dirty working tree before `release.sh` would (with a more actionable message). Profiles may add flow-specific guards via `guards.release` — surface those too.

| Exit | Meaning | Action | |---|---|---| | 0 | Pass | Continue | | 3 | Critical guard failed | Refuse to release. Relay the guard's `message` verbatim — the user fixes the underlying issue. `--skip-guards` is available but should be rare for a release. | | 4 | Confirm-severity guard failed | AskUserQuestion: "Proceed with the release?" — explicit confirm. |

Skip this step entirely on `--dry-run` (the user is previewing, not mutating).

4. Dry-run first if uncertain

When the user says "what would a release look like" or the commit range is large (>20 commits), run `--dry-run` first and show the rendered changelog block back to them. Ask for confirmation before the real run.

5. Invoke

bin/release.sh --target <cwd> --version <x.y.z> \
  [--strategy conventional-changelog|manual] \
  [--changelog <path>] [--tag-prefix <p>] \
  [--from <ref>] [--push] [--dry-run] [--yes] \
  [--wait-for-checks] [--no-wait-for-checks] [--allow-no-pr] \
  [--wait-for-checks-timeout <sec>] \
  [--wait-for-checks-interval <sec>] \
  [--bump-manifests] [--gh-release] [--profile <path>]

**Preview-before-mutate:** when `--strategy conventional-changelog` and the run is NOT `--dry-run`, `release.sh` requires `--yes`. Without it, the script prints the rendered CHANGELOG block to stderr and exits 2 so the caller is forced to confirm before the mutation. The intended flow is:

1. Run once with `--dry-run` → show the rendered `changelog` block back to the user and ask if it looks right. 2. If yes, re-run with `--yes` (same args) → actual write + commit.

Skip `--yes` handling for `--strategy manual` (no CHANGELOG write).

`--push` pushes the tag (and the release commit for `conventional-changelog`) to `origin`. Use when the user explicitly says "push the tag" or "publish the release". For quieter flows, skip `--push` and let the user run `git push --follow-tags` themselves.

**CI gate by default:** because a pushed tag is consumed by the marketplace, `--push` enables the CI gate automatically when the origin is a GitHub remote and `gh` i