chore(skill): add cut-release skill for automated semver releases

Adds a project-local skill at .claude/skills/cut-release/ that walks the
agent through a full release: detect commits since the last tag, classify
them with conventional-commit rules to pick the bump tier (major / minor /
patch), bump every version-bearing file in sync, regenerate both
lockfiles, write a curated CHANGELOG section, build the release on a
dedicated branch, tag + push, and bring the release commit back to main.

Split per the sub-agent-builder pattern: SKILL.md as a thin orchestrator,
9 phase files under steps/, 3 reference files for project-shape,
conventional commits, and the CHANGELOG template.

Phase 7 is mostly a no-op now that release.yml auto-publishes — it just
watches the run and verifies isDraft=false. The manual gh release edit
fallback is kept for legacy drafts and CI failures.

Updates .gitignore so .claude/skills/cut-release/ is tracked while the
locally-installed gitnexus skill stays ignored.

Author: delexw

.claude/skills/cut-release/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: cut-release
+description: |
+  Cuts a new versioned release of claude-code-trace by detecting commits since
+  the last tag, classifying them with conventional-commit rules to decide the
+  semver bump (major / minor / patch), bumping every version-bearing file in
+  sync, writing a CHANGELOG entry, building the release on a dedicated branch,
+  tagging + pushing to trigger the GitHub Actions release pipeline, and
+  publishing the resulting draft release on the repo page. Supports BOTH
+  whole-main releases ("everything since v0.5.0") and curated releases ("only
+  the watcher fix, even though main has other unreleased commits") via
+  cherry-pick onto a fresh branch off the previous tag. Use this skill
+  whenever the user mentions cutting, tagging, bumping, or shipping a
+  release — including phrases like "cut a release", "release v1.2.3", "tag and
+  release", "ship the watcher fix", "bump version to next", "release for X
+  only", "publish a release", "do a patch release", or "make a new release".
+  Trigger even when the user does not name the version explicitly — the skill
+  computes it. Also use proactively when the user finishes a unit of work and
+  asks to publish it as a release rather than just merging.
+---
+
+# Cut a Release — `claude-code-trace`
+
+Turns "we should release this" into a tagged, pushed, pipeline-triggered, **publicly
+published** release with a curated CHANGELOG, in a way that survives the project's strict
+pre-commit hook chain and stays honest about what's actually shipping.
+
+The skill is project-local because the steps depend on this repo's specific shape (three
+version files, two lockfiles, GH Actions release on `v*` tag, the spec-drift +
+test-reflection pre-commit hook pair).
+
+---
+
+## Before you start
+
+Read these references on the first invocation in a session — they describe constants the
+phase files refer to.
+
+- `${CLAUDE_SKILL_DIR}/references/project-shape.md` — version files, lockfiles, pre-commit
+  hooks, release pipeline wiring.
+- `${CLAUDE_SKILL_DIR}/references/conventional-commits.md` — how commit prefixes map to
+  semver bump level.
+
+`${CLAUDE_SKILL_DIR}/references/changelog-template.md` is loaded when you reach Phase 4.
+
+---
+
+## Execution
+
+### Phase 1 — Inspect repo state and propose scope
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase1-inspect-and-scope.md` and follow all instructions.
+
+---
+
+### Phase 2 — Build the release branch
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase2-build-release-branch.md` and follow all instructions.
+
+---
+
+### Phase 3 — Bump version files
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase3-bump-versions.md` and follow all instructions.
+
+---
+
+### Phase 4 — Write the CHANGELOG entry
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase4-changelog.md` and follow all instructions.
+
+---
+
+### Phase 5 — Verify, commit, tag
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase5-verify-commit-tag.md` and follow all instructions.
+
+---
+
+### Phase 6 — Push the tag (confirmation gate)
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase6-push-tag.md` and follow all instructions.
+
+---
+
+### Phase 7 — Publish the GitHub release
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase7-publish-github-release.md` and follow all
+instructions.
+
+---
+
+### Phase 8 — Bring the release commit back to `main`
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase8-back-to-main.md` and follow all instructions.
+
+---
+
+### Phase 9 — Clean up
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase9-cleanup.md` and follow all instructions.
+
+---
+
+## Safety guardrails
+
+These hold across every phase. The skill must never do any of them without an explicit
+"yes" from the user in the current turn:
+
+- `git push origin v*` — release-triggering, never reversible cleanly.
+- `gh release edit ... --draft=false` — flips the release public on the repo page.
+- `git push -f` or `--force` to any shared branch.
+- `git branch -D` on an unmerged branch.
+- `--no-verify` to bypass pre-commit hooks — fix the underlying issue instead.
+- Cutting a **major** bump unless the user explicitly asked for it OR a `BREAKING
+CHANGE:` footer / `!:` marker is present AND the user has confirmed they intend the
+  major bump.

.claude/skills/cut-release/references/changelog-template.md

@@ -0,0 +1,92 @@
+# CHANGELOG Template
+
+The repo uses [Keep a Changelog](https://keepachangelog.com/) conventions.
+
+## First-time setup
+
+If `CHANGELOG.md` doesn't yet exist, create it with this header:
+
+```markdown
+# Changelog
+
+All notable changes to claude-code-trace are documented here. Versions follow
+[semantic versioning](https://semver.org/).
+```
+
+Then append the per-release section below.
+
+## Per-release section template
+
+```markdown
+## [X.Y.Z] — YYYY-MM-DD
+
+One paragraph framing what this release is fundamentally about. Speak to a user, not a
+maintainer — explain visible impact, not implementation.
+
+### Added
+
+- **Headline name** ([`<sha7>`](https://github.com/delexw/claude-code-trace/commit/<sha>)).
+  Two or three sentences. Why it exists, what the user sees, any caveat. End with a
+  pointer to verification or docs if useful.
+
+### Fixed
+
+- **Headline name** ([`<sha7>`](https://github.com/delexw/claude-code-trace/commit/<sha>)).
+  What was broken, when it surfaced, how it surfaces now. Avoid jargon-only entries like
+  "fix race condition" — say which user-visible behavior was wrong and is now right.
+
+### Changed
+
+- Internal refactors with no behavior change usually don't belong here. Only mention if
+  the user has to update their own integration (e.g. config file rename).
+
+### Removed
+
+- Anything a user could notice as gone (CLI flag, config key, exported function from a
+  consumed package).
+
+[X.Y.Z]: https://github.com/delexw/claude-code-trace/releases/tag/vX.Y.Z
+```
+
+## Bucket rules
+
+- **Added** for `feat:` commits.
+- **Fixed** for `fix:` / `perf:` commits.
+- **Changed** for `refactor:` / config / build adjustments that the user must notice.
+- **Removed** for deletions of public surface.
+- **Breaking Changes** (new bucket, comes first, before Added) for major releases. Lead
+  with what broke and how the user migrates.
+
+Skip `chore:` / `docs:` / `test:` / `ci:` unless the user specifically asks. They
+clutter the CHANGELOG without informing users.
+
+## Linking
+
+Each bullet **must** link to its commit so readers can dig in:
+
+```
+([`ebb2ca5`](https://github.com/delexw/claude-code-trace/commit/ebb2ca5))
+```
+
+7-character SHAs are enough — git accepts the abbreviation.
+
+The reference-link at the bottom (`[X.Y.Z]: https://...releases/tag/...`) is what GitHub
+uses to make the version header a clickable link in rendered markdown. Keep it.
+
+## Style
+
+Write substantive bullets. Read the diff if the subject is terse — "fix off-by-one" is
+useless to a user, "the picker no longer skips the first session card after a refresh"
+is what they care about. Lean on the "what was broken / what is now right" frame for
+Fixed, "what's new and why" for Added.
+
+## After writing
+
+Always format:
+
+```bash
+npx oxfmt CHANGELOG.md
+```
+
+oxfmt enforces consistent table / code-fence formatting that survives the project's
+`fmt:check` gate.

.claude/skills/cut-release/references/conventional-commits.md

@@ -0,0 +1,46 @@
+# Conventional Commit → Semver Bump
+
+The bump level for a release is the highest tier among the commits the user wants to
+ship. One `feat:` upgrades the whole release to minor; one `feat!:` or breaking-change
+marker upgrades it to major.
+
+| Prefix or marker in commit subject / body        | Bump tier                   | Notes                                                                                |
+| ------------------------------------------------ | --------------------------- | ------------------------------------------------------------------------------------ |
+| `feat:` or `feat(scope):`                        | **minor**                   | new user-facing feature                                                              |
+| `fix:` `fix(scope):`                             | **patch**                   | bug fix                                                                              |
+| `perf:` `perf(scope):`                           | **patch**                   | observable performance improvement                                                   |
+| `refactor:` `refactor(scope):`                   | **patch**                   | internal restructure with no behavior change                                         |
+| `chore:` `docs:` `test:` `ci:` `build:` `style:` | **patch** (or "no release") | usually skip in CHANGELOG; if the whole release is only these, still call it a patch |
+| `!` after type — e.g. `feat!:`, `fix!:`          | **major**                   | breaking change in API or schema                                                     |
+| `BREAKING CHANGE:` footer (anywhere)             | **major**                   | always a major bump                                                                  |
+| Anything else / no convention                    | judge case-by-case          | read the diff, ask the user if unclear                                               |
+
+## Algorithm
+
+1. List commit subjects: `git log $LAST_TAG..HEAD --pretty=format:'%H %s%n%b' --no-merges`
+2. For each commit in the **chosen subset** (linear or curated), classify by the table
+   above.
+3. The release's bump tier = the highest tier observed.
+4. Compute the next version:
+   - **major**: `X.0.0` (e.g. `0.5.1` → `1.0.0`, `1.2.3` → `2.0.0`)
+   - **minor**: `X.Y.0` (e.g. `0.5.1` → `0.6.0`)
+   - **patch**: `X.Y.Z+1` (e.g. `0.5.0` → `0.5.1`)
+5. State the proposed version and ask the user to confirm or override.
+
+## Pre-1.0 caveat
+
+While the version is `0.X.Y` (we are at the time of writing), the project follows
+"`0.minor.patch`" loosely — breaking changes can still bump only the minor instead of
+forcing a 1.0. Defer to the user. Don't auto-promote to `1.0.0` even when a breaking
+marker appears unless the user explicitly asks.
+
+## `tui/package.json` track
+
+The TUI's version moves independently. If the chosen subset contains commits that
+modified files under `tui/`, bump the TUI version by the same tier; otherwise bump only
+its patch number (so its lockfile stays in sync but the user-visible TUI npm version
+ticks gently).
+
+If the subset contains **no** TUI changes at all, you may skip bumping `tui/package.json`
+entirely — but then mention this in the CHANGELOG explicitly so consumers know the TUI
+package didn't release.

.claude/skills/cut-release/references/project-shape.md

@@ -0,0 +1,62 @@
+# Project Shape — `claude-code-trace`
+
+The skill-specific facts the phase files rely on. For everything that's already in the
+codebase, this file points at the source of truth rather than repeating it.
+
+## Read these first if you don't know the codebase
+
+- `AGENTS.md` (symlinked to `CLAUDE.md`) — toolchain commands (`npm run check`, `oxfmt`,
+  `oxlint`, etc.) and the "format + lint + test before committing" rule.
+- `.claude/hooks/pre-commit-spec.sh` and `.claude/hooks/pre-commit.sh` — header comments
+  describe exactly what each hook checks and how the per-session flag bypass works.
+- `.github/workflows/release.yml` — the release pipeline: tag pattern, build matrix,
+  notes extraction, publish step.
+- `.claude/settings.json` — the matcher that wires the hooks into `git commit` calls.
+
+## Version-bearing files (skill-specific rule)
+
+Three files must agree on the next-version string. Nothing in the codebase enforces this
+sync — the skill does.
+
+| File                   | Owns                             | Bumps with                                 |
+| ---------------------- | -------------------------------- | ------------------------------------------ |
+| `package.json` (root)  | Node/TS workspace + binary entry | the Rust crate (lockstep)                  |
+| `src-tauri/Cargo.toml` | Rust crate version               | root `package.json` (lockstep)             |
+| `tui/package.json`     | Terminal UI subpackage           | independently; bumps when TUI code changes |
+
+Root + Cargo move together because the desktop binary the user installs is built from
+both. `tui/package.json` tracks separately because it's shipped as its own npm package.
+
+## Lockfile regen after a version bump
+
+The lockfiles embed the local workspace's version, so they have to be regenerated after
+editing version files — `npm run check` won't fix this on its own. Run:
+
+```bash
+npm install --package-lock-only           # → package-lock.json
+( cd src-tauri && cargo check --offline ) # → src-tauri/Cargo.lock
+```
+
+`--package-lock-only` skips the full reinstall (nothing in `node_modules` needs to
+change) and `--offline` skips the registry round-trip — only the local crate's version
+moved.
+
+## Release pipeline (delegated to CI)
+
+`.github/workflows/release.yml` reads `CHANGELOG.md`, extracts the section matching the
+pushed tag's version, attaches it to the auto-built draft release, and a final
+`publish` job flips the draft to public. See Phase 7 for the verification flow.
+
+This is the source of truth — if the pipeline changes, edit the workflow and update
+Phase 7's narrative, not this file.
+
+## GitHub repo identity
+
+Read once with `git remote get-url origin`; the URL template for commits and releases
+follows from there:
+
+- Commit: `<repo-url>/commit/<sha>`
+- Release: `<repo-url>/releases/tag/v<X.Y.Z>`
+
+The CHANGELOG template (`changelog-template.md`) hardcodes `delexw/claude-code-trace`
+in the link format. If the repo moves, update that file once.

.claude/skills/cut-release/steps/phase1-inspect-and-scope.md

@@ -0,0 +1,62 @@
+# Phase 1 — Inspect repo state and propose scope
+
+Goal: identify the last release, list everything since it, and converge with the user on
+**which subset** of those commits ships in this release plus the resulting version
+string.
+
+## Step 1.1 — Inspect
+
+```bash
+git fetch --tags --quiet
+LAST_TAG=$(git describe --tags --abbrev=0)
+git log "$LAST_TAG"..HEAD --pretty=format:'%h %s' --no-merges
+```
+
+Read each commit's subject (and body when terse) so you can classify by Conventional
+Commit prefix. Refer to `${CLAUDE_SKILL_DIR}/references/conventional-commits.md` for the
+prefix → bump-level table.
+
+## Step 1.2 — Ask the user about scope
+
+Two modes, mutually exclusive:
+
+- **Linear release** — every commit since `$LAST_TAG` ships. Use when main is
+  topic-coherent (e.g. only `fix:` commits since last tag, all about the same area).
+- **Curated release** — only a chosen subset ships, even though main has other
+  unreleased commits piled up. Use when main mixes unrelated work (parser fixes + dep
+  bumps + a feature) and the user wants this release tied to one theme.
+
+Use `AskUserQuestion` to confirm the mode if it's not already clear from context. If the
+user named a topic ("watcher fix only", "the parser cleanups"), interpret that as
+curated mode and pre-select the matching commits by grepping subjects for keywords
+related to the topic — then show your picks for confirmation rather than guessing
+silently.
+
+## Step 1.3 — Decide bump and propose version
+
+Classify the **chosen subset** of commits with the table in `conventional-commits.md`.
+The release's bump tier is the highest tier among those commits. Compute the next
+version:
+
+- **major**: `X.0.0`
+- **minor**: `X.Y.0`
+- **patch**: `X.Y.Z+1`
+
+State the proposal explicitly to the user:
+
+> "I see 1 `feat:` and 3 `fix:` commits in the chosen subset since `v0.5.0` — that's a
+> minor bump → `v0.6.0`. Confirm or override?"
+
+The user may force a specific version (e.g. "release as v0.5.1 even though there's a
+feat — I don't want a minor bump"). Honor it.
+
+## Step 1.4 — Record the decision
+
+Hold three values for the rest of the workflow:
+
+- `$LAST_TAG` — e.g. `v0.5.0`
+- `$NEXT_VERSION` — e.g. `0.5.1` (no `v` prefix in version files; with `v` in tag names)
+- `$SUBSET` — list of commit SHAs that will be cherry-picked, **in their original order
+  on main** (cherry-pick order matters when one commit depends on another)
+
+Proceed to Phase 2.