factory-release

You're cutting a new release. The user owns the final word at every gate and edits the release notes directly in their preferred editor.

A release is one atomic fact — package.json version, the VERSION file, the git tag, the GitHub Release, and the npm publish all name the same thing. This command's job is to advance them together. Letting any one of them move without the others is the drift this command exists to prevent.

Invocation input: patch, minor, or major. If empty, ask through the host's user-interaction capability or directly in chat.

What to do

1. Pre-flight. Run in parallel:

   • git status --porcelain — must be clean. If dirty, list the files and ask whether to abort or stash.

   • git rev-parse --abbrev-ref HEAD — confirm we're on the default branch (typically main). If not, warn and ask before proceeding.

   • Establish the current version from up to three sources, and detect drift between them:

     • package.json version (if a package.json exists) — the source npm publishes from.
     • VERSION file at repo root (if present).
     • Latest git tag: git describe --tags --abbrev=0 (strip leading v).

     If these disagree, surface all of them explicitly and treat the highest (by semver) as the current base. Drift is exactly what this command exists to close — name it, don't silently pick one. If none exist, treat current as 0.0.0.

2. Compute the new version from the reconciled base:

   • patch: X.Y.Z → X.Y.(Z+1)
   • minor: X.Y.Z → X.(Y+1).0
   • major: X.Y.Z → (X+1).0.0

3. Check for tag collision. git rev-parse v<new-version> 2>/dev/null — if it resolves, fail with a clear message and stop. Don't overwrite an existing tag.

4. Establish the baseline and enumerate the version spans. The breakdown starts from the last published point, not merely the last tag — so versions that were tagged but never shipped still get a changelog entry.

   • Baseline:
     • If this is an npm package (package.json with a name, not private): npm view <name> version → the last version on npm. The baseline ref is its tag v<published> if that tag exists; if the tag is missing, fall back to git describe --tags --abbrev=0 and note the mismatch.
     • Otherwise: baseline = previous tag git describe --tags --abbrev=0. If no tags exist at all, baseline = the initial commit.
   • Enumerate every version boundary from the baseline to HEAD. List tags with git tag --list 'v*' --sort=v:refname, keep those strictly greater than the baseline, and append the new version (v<new-version>, spanning the last existing tag → HEAD). This yields an ordered list of spans: (baseline → v_a), (v_a → v_b), …, (v_last → HEAD as v<new-version>). In the normal no-drift case the baseline IS the last tag, so there's exactly one span and the per-version breakdown collapses to a single block automatically.
   • For each span, gather deterministically (straight from git, no interpretation):
     • Commits: git log <from>..<to> --pretty=format:"%h %s", grouped by Conventional Commits type (feat, fix, refactor, chore, docs, test; anything non-conforming → **other:** with a flag for the user to rewrite).
     • Diffstat: git diff --shortstat <from>..<to> → "N files changed, +X / −Y".
     • Surface map: git diff --name-status <from>..<to>, group changed paths by top-level directory and mark added (+), modified (~), deleted (−), renamed (→). For this kit, skills/, agents/, commands/, and bin/ ARE the public API surface (see the README's Versioning section), so this line is the at-a-glance "what moved in the surface."
   • Identify the dominant theme across the whole span (largest user-facing group, feat > fix > refactor > chore) for the top-level Outcome line.
   • Extract any Linear IDs (<TEAM>-<NUM>) across all spans for the Refs line.

5. Write the draft to a file the user can actually edit. Use the host's filesystem-write capability to create /tmp/factory-kit-release-notes-v<new-version>.md. Auto-fill everything you can; leave clear REFINE markers where judgment is needed. Order version blocks newest-first — this release at the top, older catch-up versions beneath. Shape: