@wipcomputer/wip-release 1.9.67 → 1.9.72

package/REFERENCE.md

@@ -3,15 +3,47 @@
 
 Detailed usage, pipeline steps, flags, auth, and module API.
 
+## Release Tracks
+
+Four release tracks, each with different behavior:
+
+| Track | npm tag | Public code sync | Public release notes | Default notes |
+|-------|---------|-----------------|---------------------|---------------|
+| Alpha | @alpha | No | No (opt in with --release-notes) | Silent |
+| Beta | @beta | No | Yes, prerelease (opt out with --no-release-notes) | Visible |
+| Hotfix | @latest | No | Yes (opt out with --no-release-notes) | Visible |
+| Stable | @latest | Yes, full deploy-public | Yes, full notes | Full deploy |
+
+### Version numbering
+
+- Alpha: `1.9.68-alpha.1`, `1.9.68-alpha.2` (increments on repeat)
+- Beta: `1.9.68-beta.1`, `1.9.68-beta.2` (increments on repeat)
+- Hotfix: normal patch bump (`1.9.67` -> `1.9.68`)
+- Stable: normal bump (patch/minor/major)
+
 ## Usage
 
 Run from inside any repo:
 
 ```bash
+# Stable (existing behavior)
 wip-release patch                    # 1.0.0 -> 1.0.1
 wip-release minor                    # 1.0.0 -> 1.1.0
 wip-release major                    # 1.0.0 -> 2.0.0
 
+# Alpha
+wip-release alpha                    # 1.0.1-alpha.1 (npm @alpha, silent)
+wip-release alpha --release-notes    # 1.0.1-alpha.1 (npm @alpha + prerelease on public)
+
+# Beta
+wip-release beta                     # 1.0.1-beta.1 (npm @beta + prerelease on public)
+wip-release beta --no-release-notes  # 1.0.1-beta.1 (npm @beta, skip notes)
+
+# Hotfix
+wip-release hotfix                   # 1.0.0 -> 1.0.1 (npm @latest + release on public)
+wip-release hotfix --no-release-notes  # skip public release notes
+
+# Common flags
 wip-release patch --notes="fix auth config"   # with changelog note
 wip-release minor --dry-run                    # preview, no changes
 wip-release patch --no-publish                 # bump + tag only
@@ -19,6 +51,8 @@ wip-release patch --no-publish                 # bump + tag only
 
 ## What It Does
 
+### Stable pipeline
+
 ```
   wip-grok: 1.0.0 -> 1.0.1 (patch)
   ────────────────────────────────────────
@@ -28,32 +62,97 @@ wip-release patch --no-publish                 # bump + tag only
   ✓ Committed and tagged v1.0.1
   ✓ Pushed to remote
   ✓ Published to npm
-  ✓ Published to GitHub Packages
+  - GitHub Packages: handled by deploy-public.sh
   ✓ GitHub release v1.0.1 created
   ✓ Published to ClawHub
 
   Done. wip-grok v1.0.1 released.
 ```
 
+### Alpha/beta pipeline
+
+```
+  wip-grok: 1.0.0 -> 1.0.1-alpha.1 (alpha)
+  ────────────────────────────────────────
+  ✓ package.json -> 1.0.1-alpha.1
+  ✓ CHANGELOG.md updated
+  ✓ Committed and tagged v1.0.1-alpha.1
+  ✓ Pushed to remote
+  ✓ Published to npm @alpha
+  - GitHub prerelease: skipped (silent alpha)
+
+  Done. wip-grok v1.0.1-alpha.1 (alpha) released.
+```
+
+### Hotfix pipeline
+
+```
+  wip-grok: 1.0.0 -> 1.0.1 (hotfix)
+  ────────────────────────────────────────
+  ✓ package.json -> 1.0.1
+  ✓ SKILL.md -> 1.0.1
+  ✓ CHANGELOG.md updated
+  ✓ Committed and tagged v1.0.1
+  ✓ Pushed to remote
+  ✓ Published to npm @latest
+  ✓ GitHub release v1.0.1 created on public repo
+  - deploy-public: skipped (hotfix)
+
+  Done. wip-grok v1.0.1 (hotfix) released.
+```
+
 ## Pipeline Steps
 
+### Stable (patch/minor/major)
+
 1. **Bump `package.json`** ... patch, minor, or major
 2. **Sync `SKILL.md`** ... updates version in YAML frontmatter (if file exists)
 3. **Update `CHANGELOG.md`** ... prepends new version entry with date and notes
 4. **Git commit + tag** ... commits changed files, creates `vX.Y.Z` tag
 5. **Push** ... pushes commit and tag to remote
-6. **npm publish** ... publishes to npmjs.com (auth via 1Password)
-7. **GitHub Packages** ... publishes to npm.pkg.github.com
-8. **GitHub release** ... creates release with changelog notes
+6. **npm publish** ... publishes to npmjs.com with @latest (auth via 1Password)
+7. **GitHub Packages** ... handled by deploy-public.sh
+8. **GitHub release** ... creates release on private repo with changelog notes
 9. **ClawHub publish** ... publishes skill to ClawHub (if SKILL.md exists)
+10. **Branch cleanup** ... renames/prunes merged branches
+11. **Worktree cleanup** ... prunes merged worktrees
+
+### Alpha/Beta
+
+1. **Bump `package.json`** ... adds prerelease suffix (-alpha.N / -beta.N)
+2. **Update `CHANGELOG.md`** ... lightweight prerelease entry
+3. **Git commit + tag** ... commits changed files, creates tag
+4. **Push** ... pushes commit and tag to remote
+5. **npm publish** ... publishes with --tag alpha or --tag beta
+6. **GitHub prerelease** ... (beta: on by default, alpha: opt-in with --release-notes)
+
+### Hotfix
+
+1. **Bump `package.json`** ... patch bump (no suffix)
+2. **Sync `SKILL.md`** ... updates version in YAML frontmatter
+3. **Update `CHANGELOG.md`** ... prepends new version entry
+4. **Git commit + tag** ... commits changed files, creates tag
+5. **Push** ... pushes commit and tag to remote
+6. **npm publish** ... publishes with --tag latest
+7. **GitHub release** ... creates release on public repo (opt out with --no-release-notes)
+8. **ClawHub publish** ... publishes skill to ClawHub (if SKILL.md exists)
+9. **No deploy-public** ... code sync is skipped
 
 ## Flags
 
 | Flag | What |
 |------|------|
 | `--notes="text"` | Changelog entry text |
+| `--notes-file=path` | Read release narrative from a markdown file |
+| `--release-notes` | Opt in to public release notes (alpha only) |
+| `--no-release-notes` | Opt out of public release notes (beta, hotfix) |
 | `--dry-run` | Show what would happen, change nothing |
 | `--no-publish` | Bump + tag only, skip npm and GitHub release |
+| `--skip-product-check` | Skip product docs gate (stable only) |
+| `--skip-stale-check` | Skip stale remote branch check (stable only) |
+| `--skip-worktree-check` | Skip worktree guard |
+| `--skip-tech-docs-check` | Skip technical docs check (stable only) |
+| `--skip-coverage-check` | Skip interface coverage check (stable only) |
 
 ## Auth
 
@@ -66,15 +165,26 @@ Requires:
 - `gh` CLI authenticated (for GitHub Packages and releases)
 - `clawhub` CLI authenticated (for ClawHub skill publishing)
 
+## ldm install Integration
+
+The installer checks different npm tags based on the track:
+
+```bash
+ldm install             # checks @latest (stable + hotfix)
+ldm install --beta      # checks @beta tag
+ldm install --alpha     # checks @alpha tag
+```
+
 ## As a Module
 
 ```javascript
-import { release, detectCurrentVersion, bumpSemver } from '@wipcomputer/wip-release';
+import { release, releasePrerelease, releaseHotfix, detectCurrentVersion, bumpSemver, bumpPrerelease } from '@wipcomputer/wip-release';
 
 const current = detectCurrentVersion('/path/to/repo');
 const next = bumpSemver(current, 'minor');
 console.log(`${current} -> ${next}`);
 
+// Stable release
 await release({
   repoPath: '/path/to/repo',
   level: 'patch',
@@ -82,19 +192,54 @@ await release({
   dryRun: false,
   noPublish: false,
 });
+
+// Alpha prerelease
+await releasePrerelease({
+  repoPath: '/path/to/repo',
+  track: 'alpha',
+  notes: 'testing new feature',
+  dryRun: false,
+  noPublish: false,
+  publishReleaseNotes: false,
+});
+
+// Beta prerelease
+await releasePrerelease({
+  repoPath: '/path/to/repo',
+  track: 'beta',
+  notes: 'beta candidate',
+  dryRun: false,
+  noPublish: false,
+  publishReleaseNotes: true,
+});
+
+// Hotfix
+await releaseHotfix({
+  repoPath: '/path/to/repo',
+  notes: 'critical fix',
+  dryRun: false,
+  noPublish: false,
+  publishReleaseNotes: true,
+});
 ```
 
 ## Exports
 
 | Function | What |
 |----------|------|
-| `release({ repoPath, level, notes, dryRun, noPublish })` | Full pipeline |
+| `release({ repoPath, level, notes, dryRun, noPublish })` | Full stable pipeline |
+| `releasePrerelease({ repoPath, track, notes, dryRun, noPublish, publishReleaseNotes })` | Alpha/beta pipeline |
+| `releaseHotfix({ repoPath, notes, dryRun, noPublish, publishReleaseNotes })` | Hotfix pipeline |
 | `detectCurrentVersion(repoPath)` | Read version from package.json |
-| `bumpSemver(version, level)` | Bump a semver string |
+| `bumpSemver(version, level)` | Bump a semver string (patch/minor/major) |
+| `bumpPrerelease(version, track)` | Bump a prerelease version (alpha/beta) |
 | `syncSkillVersion(repoPath, newVersion)` | Update SKILL.md frontmatter |
 | `updateChangelog(repoPath, newVersion, notes)` | Prepend to CHANGELOG.md |
-| `publishNpm(repoPath)` | Publish to npmjs.com |
+| `publishNpm(repoPath)` | Publish to npmjs.com (@latest) |
+| `publishNpmWithTag(repoPath, tag)` | Publish to npmjs.com with specific tag |
 | `publishGitHubPackages(repoPath)` | Publish to npm.pkg.github.com |
-| `createGitHubRelease(repoPath, newVersion, notes, currentVersion)` | Create GitHub release with rich notes |
+| `createGitHubRelease(repoPath, newVersion, notes, currentVersion)` | Create GitHub release on private repo |
+| `createGitHubPrerelease(repoPath, newVersion, notes)` | Create GitHub prerelease on public repo |
+| `createGitHubReleaseOnPublic(repoPath, newVersion, notes, currentVersion)` | Create GitHub release on public repo |
 | `buildReleaseNotes(repoPath, currentVersion, newVersion, notes)` | Generate detailed release notes |
 | `publishClawHub(repoPath, newVersion, notes)` | Publish skill to ClawHub |

package/SKILL.md

@@ -46,6 +46,8 @@ Local release pipeline. One command bumps version, updates all docs, publishes e
 - Releasing a new version of any @wipcomputer package
 - After merging a PR to main and you need to publish
 - Bumping version + changelog + SKILL.md in one step
+- Publishing alpha or beta prereleases for testing
+- Pushing hotfixes to npm without full deploy-public
 
 **Use --dry-run for:**
 - Previewing what a release would do before committing
@@ -55,18 +57,48 @@ Local release pipeline. One command bumps version, updates all docs, publishes e
 
 ### Do NOT Use For
 
-- Pre-release / alpha versions (not yet supported)
 - Repos without a package.json
 
+## Release Tracks
+
+Four release tracks. Each has different behavior for npm tags, public repo sync, and release notes.
+
+| Track | Command | npm tag | Public code sync | Public release notes |
+|-------|---------|---------|-----------------|---------------------|
+| Alpha | `wip-release alpha` | @alpha | No | No (opt in with --release-notes) |
+| Beta | `wip-release beta` | @beta | No | Yes, prerelease (opt out with --no-release-notes) |
+| Hotfix | `wip-release hotfix` | @latest | No | Yes (opt out with --no-release-notes) |
+| Stable | `wip-release patch/minor/major` | @latest | Yes (deploy-public) | Yes, full notes |
+
+### Version numbering
+
+- Alpha: `1.9.68-alpha.1`, `1.9.68-alpha.2`, etc.
+- Beta: `1.9.68-beta.1`, `1.9.68-beta.2`, etc.
+- Hotfix: normal version bump (patch)
+- Stable: normal version bump (patch/minor/major)
+
 ## API Reference
 
 ### CLI
 
 ```bash
-wip-release patch --notes="fix X"           # full pipeline
+# Stable (existing behavior)
+wip-release patch                           # full pipeline
 wip-release minor --dry-run                 # preview only
 wip-release major --no-publish              # bump + tag only
 wip-release patch --skip-product-check      # skip product docs gate
+
+# Alpha
+wip-release alpha                           # npm @alpha, no public notes
+wip-release alpha --release-notes           # npm @alpha + prerelease notes on public
+
+# Beta
+wip-release beta                            # npm @beta + prerelease notes on public
+wip-release beta --no-release-notes         # npm @beta, skip public notes
+
+# Hotfix
+wip-release hotfix                          # npm @latest + public release notes
+wip-release hotfix --no-release-notes       # npm @latest, skip public notes
 ```
 
 ### Product Docs Gate
@@ -108,9 +140,16 @@ After publishing, wip-release auto-copies SKILL.md to your website as plain text
 ### Module
 
 ```javascript
-import { release, detectCurrentVersion, bumpSemver, syncSkillVersion } from '@wipcomputer/wip-release';
+import { release, releasePrerelease, releaseHotfix, detectCurrentVersion, bumpSemver, bumpPrerelease } from '@wipcomputer/wip-release';
 
+// Stable release
 await release({ repoPath: '.', level: 'patch', notes: 'fix', dryRun: false, noPublish: false });
+
+// Alpha/beta prerelease
+await releasePrerelease({ repoPath: '.', track: 'alpha', notes: 'testing', dryRun: false, noPublish: false, publishReleaseNotes: false });
+
+// Hotfix
+await releaseHotfix({ repoPath: '.', notes: 'critical fix', dryRun: false, noPublish: false, publishReleaseNotes: true });
 ```
 
 ## Troubleshooting

package/cli.js

@@ -5,10 +5,10 @@
  * Release tool CLI. Bumps version, updates docs, publishes.
  */
 
-import { release, detectCurrentVersion, collectMergedPRNotes } from './core.mjs';
+import { release, releasePrerelease, releaseHotfix, detectCurrentVersion, collectMergedPRNotes } from './core.mjs';
 
 const args = process.argv.slice(2);
-const level = args.find(a => ['patch', 'minor', 'major'].includes(a));
+const level = args.find(a => ['patch', 'minor', 'major', 'alpha', 'beta', 'hotfix'].includes(a));
 
 function flag(name) {
   const prefix = `--${name}=`;
@@ -23,6 +23,9 @@ const skipStaleCheck = args.includes('--skip-stale-check');
 const skipWorktreeCheck = args.includes('--skip-worktree-check');
 const skipTechDocsCheck = args.includes('--skip-tech-docs-check');
 const skipCoverageCheck = args.includes('--skip-coverage-check');
+const allowSubToolDrift = args.includes('--allow-sub-tool-drift');
+const wantReleaseNotes = args.includes('--release-notes');
+const noReleaseNotes = args.includes('--no-release-notes');
 const notesFilePath = flag('notes-file');
 let notes = flag('notes');
 // Bug fix #121: use strict check, not truthiness. --notes="" is empty, not absent.
@@ -51,13 +54,15 @@ let notesSource = (notes !== null && notes !== undefined && notes !== '') ? 'fla
     }
     notes = readFileSync(resolved, 'utf8').trim();
     notesSource = 'file';
-  } else if (level) {
+  } else if (level && ['patch', 'minor', 'major', 'hotfix'].includes(level)) {
     // 2. Auto-detect RELEASE-NOTES-v{version}.md (ALWAYS checks, even if --notes provided)
+    // Only for stable levels and hotfix. Alpha/beta skip this.
     try {
       const { detectCurrentVersion, bumpSemver } = await import('./core.mjs');
       const cwd = process.cwd();
       const currentVersion = detectCurrentVersion(cwd);
-      const newVersion = bumpSemver(currentVersion, level);
+      const bumpLevel = level === 'hotfix' ? 'patch' : level;
+      const newVersion = bumpSemver(currentVersion, bumpLevel);
       const dashed = newVersion.replace(/\./g, '-');
       const autoFile = join(cwd, `RELEASE-NOTES-v${dashed}.md`);
       if (existsSync(autoFile)) {
@@ -75,12 +80,13 @@ let notesSource = (notes !== null && notes !== undefined && notes !== '') ? 'fla
   // 2.5. Auto-combine release notes from merged PRs since last tag (#237)
   // Only runs when no single RELEASE-NOTES file was found on disk.
   // Scans git merge history for RELEASE-NOTES files committed on PR branches.
-  if (level && notesSource !== 'file') {
+  if (level && ['patch', 'minor', 'major', 'hotfix'].includes(level) && notesSource !== 'file') {
     try {
       const { collectMergedPRNotes, detectCurrentVersion: dcv, bumpSemver: bs } = await import('./core.mjs');
       const cwd = process.cwd();
       const cv = dcv(cwd);
-      const nv = bs(cv, level);
+      const bumpLevel = level === 'hotfix' ? 'patch' : level;
+      const nv = bs(cv, bumpLevel);
       const combined = collectMergedPRNotes(cwd, cv, nv);
       if (combined) {
         if (flagNotes && flagNotes !== combined.notes) {
@@ -144,27 +150,38 @@ if (!level || args.includes('--help') || args.includes('-h')) {
   console.log(`wip-release ... local release tool${current}
 
 Usage:
-  wip-release patch                    1.0.0 -> 1.0.1
-  wip-release minor                    1.0.0 -> 1.1.0
-  wip-release major                    1.0.0 -> 2.0.0
+  wip-release patch                    1.0.0 -> 1.0.1 (stable)
+  wip-release minor                    1.0.0 -> 1.1.0 (stable)
+  wip-release major                    1.0.0 -> 2.0.0 (stable)
+  wip-release alpha                    1.0.1-alpha.1 (prerelease)
+  wip-release beta                     1.0.1-beta.1 (prerelease)
+  wip-release hotfix                   1.0.0 -> 1.0.1 (hotfix, no deploy-public)
+
+Release tracks:
+  alpha    npm @alpha tag, no public notes (opt in with --release-notes)
+  beta     npm @beta tag, prerelease notes on public (opt out with --no-release-notes)
+  hotfix   npm @latest tag, release notes on public (opt out with --no-release-notes)
+  stable   npm @latest tag, deploy-public, full notes (patch/minor/major)
 
 Flags:
   --notes="description"    Release narrative (what was built and why)
   --notes-file=path        Read release narrative from a markdown file
+  --release-notes          Opt in to public release notes (alpha only)
+  --no-release-notes       Opt out of public release notes (beta, hotfix)
   --dry-run                Show what would happen, change nothing
   --no-publish             Bump + tag only, skip npm/GitHub
   --skip-product-check     Skip product docs check (dev update, roadmap, readme-first)
   --skip-stale-check       Skip stale remote branch check
-  --skip-worktree-check    Skip worktree guard (allow release from worktree)
+  --skip-worktree-check    Skip main-branch + worktree guard (break-glass only)
+  --allow-sub-tool-drift   Allow release even if a sub-tool's files changed since the last tag without a version bump (error by default)
 
-Release notes (REQUIRED, must be a file on disk):
+Release notes (REQUIRED for stable, optional for other tracks):
   1. --notes-file=path          Explicit file path
   2. RELEASE-NOTES-v{ver}.md    In repo root (auto-detected)
   3. Merged PR notes             Auto-combined from git history (#237)
   4. ai/dev-updates/YYYY-MM-DD* Today's dev update (auto-detected)
-  The --notes flag is NOT accepted. Write a file. Commit it on your branch.
-  The file shows up in the PR diff so it can be reviewed before merge.
-  When batching multiple PRs, each PR's RELEASE-NOTES are auto-combined.
+  For stable releases: the --notes flag is NOT accepted. Write a file.
+  For alpha/beta/hotfix: --notes="text" is accepted as a convenience.
 
 Skill publish to website:
   Add .publish-skill.json to repo root: { "name": "my-tool" }
@@ -172,7 +189,7 @@ Skill publish to website:
   After release, SKILL.md is copied to {website}/wip.computer/install/{name}.txt
   and deploy.sh is run to push to VPS.
 
-Pipeline:
+Pipeline (stable):
   1. Bump package.json version
   2. Sync SKILL.md version (if exists)
   3. Update CHANGELOG.md
@@ -181,23 +198,68 @@ Pipeline:
   6. npm publish (via 1Password)
   7. GitHub Packages publish
   8. GitHub release create
-  9. Publish SKILL.md to website (if configured)`);
+  9. Publish SKILL.md to website (if configured)
+
+Pipeline (alpha/beta):
+  1. Bump version with prerelease suffix (-alpha.N / -beta.N)
+  2. npm publish with --tag alpha or --tag beta
+  3. GitHub prerelease (beta default, alpha opt-in)
+
+Pipeline (hotfix):
+  1. Bump patch version (no suffix)
+  2. npm publish with --tag latest
+  3. GitHub release (no deploy-public)`);
   process.exit(level ? 0 : 1);
 }
 
-release({
-  repoPath: process.cwd(),
-  level,
-  notes,
-  notesSource,
-  dryRun,
-  noPublish,
-  skipProductCheck,
-  skipStaleCheck,
-  skipWorktreeCheck,
-  skipTechDocsCheck,
-  skipCoverageCheck,
-}).catch(err => {
-  console.error(`  ✗ ${err.message}`);
-  process.exit(1);
-});
+// Route to the correct release function based on track
+if (level === 'alpha' || level === 'beta') {
+  // Prerelease track: alpha or beta
+  releasePrerelease({
+    repoPath: process.cwd(),
+    track: level,
+    notes,
+    dryRun,
+    noPublish,
+    publishReleaseNotes: level === 'alpha' ? wantReleaseNotes : !noReleaseNotes,
+    skipWorktreeCheck,
+    allowSubToolDrift,
+  }).catch(err => {
+    console.error(`  \u2717 ${err.message}`);
+    process.exit(1);
+  });
+} else if (level === 'hotfix') {
+  // Hotfix track: patch bump, @latest tag, no deploy-public
+  releaseHotfix({
+    repoPath: process.cwd(),
+    notes,
+    notesSource,
+    dryRun,
+    noPublish,
+    publishReleaseNotes: !noReleaseNotes,
+    skipWorktreeCheck,
+    allowSubToolDrift,
+  }).catch(err => {
+    console.error(`  \u2717 ${err.message}`);
+    process.exit(1);
+  });
+} else {
+  // Stable track: patch, minor, major
+  release({
+    repoPath: process.cwd(),
+    level,
+    notes,
+    notesSource,
+    dryRun,
+    noPublish,
+    skipProductCheck,
+    skipStaleCheck,
+    skipWorktreeCheck,
+    skipTechDocsCheck,
+    skipCoverageCheck,
+    allowSubToolDrift,
+  }).catch(err => {
+    console.error(`  \u2717 ${err.message}`);
+    process.exit(1);
+  });
+}

package/core.mjs

@@ -25,7 +25,8 @@ export function detectCurrentVersion(repoPath) {
  * Bump a semver string by level.
  */
 export function bumpSemver(version, level) {
-  const [major, minor, patch] = version.split('.').map(Number);
+  const base = version.replace(/-.*$/, '');
+  const [major, minor, patch] = base.split('.').map(Number);
   switch (level) {
     case 'major': return `${major + 1}.0.0`;
     case 'minor': return `${major}.${minor + 1}.0`;
@@ -34,6 +35,37 @@ export function bumpSemver(version, level) {
   }
 }
 
+/**
+ * Bump a version string for prerelease tracks (alpha, beta).
+ *
+ * If the current version already has the same prerelease prefix,
+ * increment the counter: 1.2.3-alpha.1 -> 1.2.3-alpha.2
+ *
+ * If the current version is a clean release or a different prerelease,
+ * bump patch and start at .1: 1.2.3 -> 1.2.4-alpha.1
+ */
+export function bumpPrerelease(version, track) {
+  // Check if current version already has this prerelease prefix
+  const preMatch = version.match(new RegExp(`^(\\d+\\.\\d+\\.\\d+)-${track}\\.(\\d+)$`));
+  if (preMatch) {
+    // Same track: increment the counter
+    const base = preMatch[1];
+    const counter = parseInt(preMatch[2], 10);
+    return `${base}-${track}.${counter + 1}`;
+  }
+
+  // Strip any existing prerelease suffix to get the base version
+  const baseMatch = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!baseMatch) throw new Error(`Cannot parse version: ${version}`);
+
+  const major = parseInt(baseMatch[1], 10);
+  const minor = parseInt(baseMatch[2], 10);
+  const patch = parseInt(baseMatch[3], 10);
+
+  // Bump patch and start prerelease at .1
+  return `${major}.${minor}.${patch + 1}-${track}.1`;
+}
+
 /**
  * Write new version to package.json.
  */
@@ -200,6 +232,18 @@ export function publishNpm(repoPath) {
   ], { cwd: repoPath, stdio: 'inherit' });
 }
 
+/**
+ * Publish to npm with a specific dist-tag (alpha, beta, latest).
+ */
+export function publishNpmWithTag(repoPath, tag) {
+  const token = getNpmToken();
+  execFileSync('npm', [
+    'publish', '--access', 'public',
+    '--tag', tag,
+    `--//registry.npmjs.org/:_authToken=${token}`
+  ], { cwd: repoPath, stdio: 'inherit' });
+}
+
 /**
  * Publish to GitHub Packages.
  */
@@ -1018,6 +1062,61 @@ export function createGitHubRelease(repoPath, newVersion, notes, currentVersion)
   }
 }
 
+/**
+ * Create a GitHub prerelease on the PUBLIC repo (no code sync).
+ * Used by alpha (opt-in) and beta (default) tracks.
+ */
+export function createGitHubPrerelease(repoPath, newVersion, notes) {
+  const repoSlug = detectRepoSlug(repoPath);
+  if (!repoSlug) throw new Error('Cannot detect repo slug from git remote');
+
+  // Target the public repo (strip -private suffix)
+  const publicSlug = repoSlug.replace(/-private$/, '');
+  const body = notes || `Prerelease ${newVersion}`;
+
+  const tmpFile = join(repoPath, '.release-notes-tmp.md');
+  writeFileSync(tmpFile, body);
+
+  try {
+    execFileSync('gh', [
+      'release', 'create', `v${newVersion}`,
+      '--title', `v${newVersion}`,
+      '--notes-file', '.release-notes-tmp.md',
+      '--prerelease',
+      '--repo', publicSlug
+    ], { cwd: repoPath, stdio: 'inherit' });
+  } finally {
+    try { execFileSync('rm', ['-f', tmpFile]); } catch {}
+  }
+}
+
+/**
+ * Create a GitHub release on the PUBLIC repo (no code sync).
+ * Used by the hotfix track.
+ */
+export function createGitHubReleaseOnPublic(repoPath, newVersion, notes, currentVersion) {
+  const repoSlug = detectRepoSlug(repoPath);
+  if (!repoSlug) throw new Error('Cannot detect repo slug from git remote');
+
+  // Target the public repo (strip -private suffix)
+  const publicSlug = repoSlug.replace(/-private$/, '');
+  const body = buildReleaseNotes(repoPath, currentVersion, newVersion, notes);
+
+  const tmpFile = join(repoPath, '.release-notes-tmp.md');
+  writeFileSync(tmpFile, body);
+
+  try {
+    execFileSync('gh', [
+      'release', 'create', `v${newVersion}`,
+      '--title', `v${newVersion}`,
+      '--notes-file', '.release-notes-tmp.md',
+      '--repo', publicSlug
+    ], { cwd: repoPath, stdio: 'inherit' });
+  } finally {
+    try { execFileSync('rm', ['-f', tmpFile]); } catch {}
+  }
+}
+
 /**
  * Publish skill to ClawHub.
  */
@@ -1224,10 +1323,210 @@ export function checkStaleBranches(repoPath, level) {
 
 // ── Main ────────────────────────────────────────────────────────────
 
+/**
+ * Guard: wip-release must run from the main working tree on the main/master branch.
+ *
+ * Two independent conditions are enforced:
+ *
+ * 1. Linked worktree check: `git rev-parse --git-dir` of a linked worktree
+ *    resolves to a path under `.git/worktrees/...`. If we see that, the caller
+ *    is inside a feature worktree and must switch to the main working tree.
+ * 2. Current branch check: even from the main working tree, `git branch
+ *    --show-current` must be `main` or `master`. If a user checked out a feature
+ *    branch in the main tree, the release would commit to the wrong branch.
+ *
+ * Both conditions bypassable via `--skip-worktree-check` for break-glass scenarios.
+ *
+ * Returns `{ ok: true }` on pass, or `{ ok: false, reason, currentPath, mainPath, branch }`
+ * on fail so the caller can log and return the standard `{ failed: true }` shape.
+ *
+ * Related: `ai/product/bugs/guard/2026-04-05--cc-mini--guard-master-plan.md` Phase 3,
+ * `ai/product/bugs/release-pipeline/2026-04-05--cc-mini--release-pipeline-master-plan.md`
+ * Phase 1. Earlier today a wip-release alpha ran from a worktree branch because
+ * `releasePrerelease` had no worktree check at all and the other two checks did
+ * not cover the "main tree but non-main branch" case. This helper closes both gaps.
+ */
+function enforceMainBranchGuard(repoPath, skipWorktreeCheck) {
+  if (skipWorktreeCheck) {
+    return { ok: true, skipped: true };
+  }
+  try {
+    const gitDir = execFileSync('git', ['rev-parse', '--git-dir'], {
+      cwd: repoPath, encoding: 'utf8'
+    }).trim();
+    if (gitDir.includes('/worktrees/')) {
+      const worktreeList = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+        cwd: repoPath, encoding: 'utf8'
+      });
+      const mainWorktree = worktreeList.split('\n')
+        .find(line => line.startsWith('worktree '));
+      const mainPath = mainWorktree ? mainWorktree.replace('worktree ', '') : '(unknown)';
+      return {
+        ok: false,
+        reason: 'linked-worktree',
+        currentPath: repoPath,
+        mainPath,
+      };
+    }
+    const branch = execFileSync('git', ['branch', '--show-current'], {
+      cwd: repoPath, encoding: 'utf8'
+    }).trim();
+    if (branch && branch !== 'main' && branch !== 'master') {
+      return {
+        ok: false,
+        reason: 'non-main-branch',
+        currentPath: repoPath,
+        branch,
+      };
+    }
+    return { ok: true, branch };
+  } catch {
+    // Git command failed: skip check gracefully so release can still run
+    // in CI or unusual environments where git plumbing is restricted.
+    return { ok: true, skipped: true };
+  }
+}
+
+/**
+ * Validate that sub-tool package.json versions were bumped when their files changed.
+ *
+ * Scans `tools/*\/package.json` in monorepo-style toolboxes. For each sub-tool
+ * whose files changed since the last git tag, verifies the package.json version
+ * differs from the version at that tag. If not, this used to be a WARNING that
+ * let the release proceed, which shipped at least one "committed but never
+ * deployed" bug earlier today (guard 1.9.71 had new code but the same version,
+ * so ldm install ignored the sub-tool on redeploy).
+ *
+ * Phase 8 of the release-pipeline master plan: WARNING becomes ERROR by default.
+ * Callers who genuinely want to proceed without bumping (e.g., a release that
+ * touches sub-tool files in a non-shipping way like CI config) pass
+ * `allowSubToolDrift: true`.
+ *
+ * Returns `{ ok: true }` on pass, `{ ok: false }` if any sub-tool drift was
+ * detected without the allow flag.
+ *
+ * Related: `ai/product/bugs/release-pipeline/2026-04-05--cc-mini--release-pipeline-master-plan.md`
+ * Phase 8.
+ */
+function validateSubToolVersions(repoPath, allowSubToolDrift) {
+  const toolsDir = join(repoPath, 'tools');
+  if (!existsSync(toolsDir)) {
+    return { ok: true };
+  }
+  let lastTag = null;
+  try {
+    lastTag = execFileSync('git', ['describe', '--tags', '--abbrev=0'], {
+      cwd: repoPath, encoding: 'utf8'
+    }).trim();
+  } catch {
+    return { ok: true }; // No prior tag, nothing to compare against
+  }
+  if (!lastTag) return { ok: true };
+
+  let driftDetected = false;
+  let entries;
+  try {
+    entries = readdirSync(toolsDir, { withFileTypes: true });
+  } catch {
+    return { ok: true };
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const subDir = join('tools', entry.name);
+    const subPkgPath = join(toolsDir, entry.name, 'package.json');
+    if (!existsSync(subPkgPath)) continue;
+    try {
+      const diff = execFileSync('git', ['diff', '--name-only', lastTag, 'HEAD', '--', subDir], {
+        cwd: repoPath, encoding: 'utf8'
+      }).trim();
+      if (!diff) continue;
+      const currentSubVersion = JSON.parse(readFileSync(subPkgPath, 'utf8')).version;
+      let oldSubVersion = null;
+      try {
+        oldSubVersion = JSON.parse(
+          execFileSync('git', ['show', `${lastTag}:${subDir}/package.json`], {
+            cwd: repoPath, encoding: 'utf8'
+          })
+        ).version;
+      } catch {}
+      if (currentSubVersion === oldSubVersion) {
+        if (allowSubToolDrift) {
+          console.log(`  ! WARNING (allowed by --allow-sub-tool-drift): ${entry.name} has changed files since ${lastTag} but version is still ${currentSubVersion}`);
+          console.log(`    Changed: ${diff.split('\n').join(', ')}`);
+        } else {
+          console.log(`  \u2717 ${entry.name} has changed files since ${lastTag} but tools/${entry.name}/package.json version is still ${currentSubVersion}.`);
+          console.log(`    Changed: ${diff.split('\n').join(', ')}`);
+          console.log(`    Bump tools/${entry.name}/package.json before releasing, or pass --allow-sub-tool-drift to override.`);
+          console.log('');
+          driftDetected = true;
+        }
+      }
+    } catch {}
+  }
+  return { ok: !driftDetected };
+}
+
+/**
+ * Pre-tag collision check. Returns `{ ok: true }` if no collision, otherwise
+ * `{ ok: false, tag }` with a message logged. Phase 2 of the release-pipeline
+ * master plan: earlier today `wip-release alpha` failed mid-pipeline because
+ * `v1.9.71-alpha.4` and `v1.9.71-alpha.5` existed as local-only tags from
+ * prior failed releases. The release tool has no recovery path; this helper
+ * catches the collision before the bump+commit happens, so the user gets a
+ * clear error and concrete recovery command instead of a mid-pipeline failure.
+ */
+function checkTagCollision(repoPath, newVersion) {
+  const tag = `v${newVersion}`;
+  try {
+    const localTags = execFileSync('git', ['tag', '-l', tag], {
+      cwd: repoPath, encoding: 'utf8'
+    }).trim();
+    if (localTags === tag) {
+      // Tag exists locally. Is it also on remote?
+      try {
+        const remoteTags = execFileSync('git', ['ls-remote', '--tags', 'origin', tag], {
+          cwd: repoPath, encoding: 'utf8'
+        }).trim();
+        if (remoteTags.includes(tag)) {
+          // Tag is on remote: legitimate prior release. Refuse.
+          console.log(`  \u2717 Tag ${tag} already exists on origin (prior release).`);
+          console.log(`    Bump the version manually in package.json or run with a different level.`);
+          console.log('');
+          return { ok: false, tag, reason: 'on-remote' };
+        }
+      } catch {}
+      // Tag exists locally but NOT on remote: stale leftover from a failed release.
+      // Refuse with a concrete recovery command so the user knows this is safe to clean up.
+      console.log(`  \u2717 Tag ${tag} exists locally but not on origin (stale leftover from a prior failed release).`);
+      console.log(`    Safe to delete because it was never pushed. Recover with:`);
+      console.log(`      git tag -d ${tag} && wip-release <track>`);
+      console.log('');
+      return { ok: false, tag, reason: 'stale-local' };
+    }
+  } catch {}
+  return { ok: true };
+}
+
+function logMainBranchGuardFailure(result) {
+  if (result.reason === 'linked-worktree') {
+    console.log(`  \u2717 wip-release must run from the main working tree, not a worktree.`);
+    console.log(`    Current: ${result.currentPath}`);
+    console.log(`    Main working tree: ${result.mainPath}`);
+    console.log(`    Switch to the main working tree and run again:`);
+    console.log(`      cd ${result.mainPath} && wip-release <track>`);
+  } else if (result.reason === 'non-main-branch') {
+    console.log(`  \u2717 wip-release must run on the main branch, not a feature branch.`);
+    console.log(`    Current branch: ${result.branch}`);
+    console.log(`    Switch to main and pull latest:`);
+    console.log(`      git checkout main && git pull && wip-release <track>`);
+  }
+  console.log('');
+}
+
 /**
  * Run the full release pipeline.
  */
-export async function release({ repoPath, level, notes, notesSource, dryRun, noPublish, skipProductCheck, skipStaleCheck, skipWorktreeCheck, skipTechDocsCheck, skipCoverageCheck }) {
+export async function release({ repoPath, level, notes, notesSource, dryRun, noPublish, skipProductCheck, skipStaleCheck, skipWorktreeCheck, skipTechDocsCheck, skipCoverageCheck, allowSubToolDrift }) {
   repoPath = repoPath || process.cwd();
   const currentVersion = detectCurrentVersion(repoPath);
   const newVersion = bumpSemver(currentVersion, level);
@@ -1237,33 +1536,15 @@ export async function release({ repoPath, level, notes, notesSource, dryRun, noP
   console.log(`  ${repoName}: ${currentVersion} -> ${newVersion} (${level})`);
   console.log(`  ${'─'.repeat(40)}`);
 
-  // -1. Worktree guard: block releases from linked worktrees
-  if (!skipWorktreeCheck) {
-    try {
-      const gitDir = execFileSync('git', ['rev-parse', '--git-dir'], {
-        cwd: repoPath, encoding: 'utf8'
-      }).trim();
-
-      // Linked worktrees have "/worktrees/" in their git-dir path
-      if (gitDir.includes('/worktrees/')) {
-        // Get the main working tree path from `git worktree list`
-        const worktreeList = execFileSync('git', ['worktree', 'list', '--porcelain'], {
-          cwd: repoPath, encoding: 'utf8'
-        });
-        const mainWorktree = worktreeList.split('\n')
-          .find(line => line.startsWith('worktree '));
-        const mainPath = mainWorktree ? mainWorktree.replace('worktree ', '') : '(unknown)';
-
-        console.log(`  \u2717 wip-release must run from the main working tree, not a worktree.`);
-        console.log(`    Current: ${repoPath}`);
-        console.log(`    Main working tree: ${mainPath}`);
-        console.log(`    Switch to the main working tree and run again.`);
-        console.log('');
-        return { currentVersion, newVersion, dryRun: false, failed: true };
-      }
-      console.log('  \u2713 Running from main working tree');
-    } catch {
-      // Git command failed... skip check gracefully
+  // -1. Main-branch guard: block releases from linked worktrees or non-main branches
+  {
+    const guardResult = enforceMainBranchGuard(repoPath, skipWorktreeCheck);
+    if (!guardResult.ok) {
+      logMainBranchGuardFailure(guardResult);
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+    if (!guardResult.skipped) {
+      console.log(`  \u2713 Running from main working tree on ${guardResult.branch ?? 'main'}`);
     }
   }
 
@@ -1572,31 +1853,23 @@ export async function release({ repoPath, level, notes, notesSource, dryRun, noP
     return { currentVersion, newVersion, dryRun: true };
   }
 
+  // 1.25. Pre-bump tag collision check (Phase 2).
+  {
+    const collision = checkTagCollision(repoPath, newVersion);
+    if (!collision.ok) {
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+  }
+
   // 1. Bump package.json
   writePackageVersion(repoPath, newVersion);
   console.log(`  ✓ package.json -> ${newVersion}`);
 
-  // 1.5. Bump sub-tool versions in toolbox repos (tools/*/)
-  const toolsDir = join(repoPath, 'tools');
-  if (existsSync(toolsDir)) {
-    let subBumped = 0;
-    try {
-      const entries = readdirSync(toolsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        const subPkgPath = join(toolsDir, entry.name, 'package.json');
-        if (existsSync(subPkgPath)) {
-          try {
-            const subPkg = JSON.parse(readFileSync(subPkgPath, 'utf8'));
-            subPkg.version = newVersion;
-            writeFileSync(subPkgPath, JSON.stringify(subPkg, null, 2) + '\n');
-            subBumped++;
-          } catch {}
-        }
-      }
-    } catch {}
-    if (subBumped > 0) {
-      console.log(`  ✓ ${subBumped} sub-tool(s) -> ${newVersion}`);
+  // 1.5. Validate sub-tool version bumps (Phase 8: error by default)
+  {
+    const subToolResult = validateSubToolVersions(repoPath, allowSubToolDrift);
+    if (!subToolResult.ok) {
+      return { currentVersion, newVersion, dryRun: false, failed: true };
     }
   }
 
@@ -1900,3 +2173,382 @@ export async function release({ repoPath, level, notes, notesSource, dryRun, noP
 
   return { currentVersion, newVersion, dryRun: false };
 }
+
+// ── Prerelease Track (Alpha / Beta) ────────────────────────────────
+
+/**
+ * Release an alpha or beta prerelease.
+ *
+ * Alpha: npm @alpha, no public release notes by default (opt in with publishReleaseNotes).
+ * Beta:  npm @beta, prerelease notes on public repo by default (opt out with publishReleaseNotes=false).
+ *
+ * No deploy-public. No code sync. No CHANGELOG gate. No product docs gate.
+ * Lightweight: bump version, npm publish with tag, optional GitHub prerelease.
+ */
+export async function releasePrerelease({ repoPath, track, notes, dryRun, noPublish, publishReleaseNotes, skipWorktreeCheck, allowSubToolDrift }) {
+  repoPath = repoPath || process.cwd();
+  const currentVersion = detectCurrentVersion(repoPath);
+  const newVersion = bumpPrerelease(currentVersion, track);
+  const repoName = basename(repoPath);
+
+  console.log('');
+  console.log(`  ${repoName}: ${currentVersion} -> ${newVersion} (${track})`);
+  console.log(`  ${'─'.repeat(40)}`);
+
+  // Main-branch guard: worktree + non-main branch check via shared helper.
+  // Runs before the dry-run short-circuit so preview output from a feature
+  // branch still refuses instead of printing a misleading "would bump" plan.
+  {
+    const guardResult = enforceMainBranchGuard(repoPath, skipWorktreeCheck);
+    if (!guardResult.ok) {
+      logMainBranchGuardFailure(guardResult);
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+    if (!guardResult.skipped) {
+      console.log(`  \u2713 Running from main working tree on ${guardResult.branch ?? 'main'}`);
+    }
+  }
+
+  if (dryRun) {
+    console.log(`  [dry run] Would bump package.json to ${newVersion}`);
+    if (!noPublish) {
+      console.log(`  [dry run] Would npm publish with --tag ${track}`);
+      if (publishReleaseNotes) {
+        console.log(`  [dry run] Would create GitHub prerelease v${newVersion} on public repo`);
+      } else {
+        console.log(`  [dry run] No GitHub prerelease (silent)`);
+      }
+    }
+    console.log('');
+    console.log(`  Dry run complete. No changes made.`);
+    console.log('');
+    return { currentVersion, newVersion, dryRun: true };
+  }
+
+  // 1.25. Pre-bump tag collision check (Phase 2).
+  {
+    const collision = checkTagCollision(repoPath, newVersion);
+    if (!collision.ok) {
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+  }
+
+  // 1. Bump package.json
+  writePackageVersion(repoPath, newVersion);
+  console.log(`  \u2713 package.json -> ${newVersion}`);
+
+  // 1.5. Validate sub-tool version bumps (Phase 8: error by default)
+  {
+    const subToolResult = validateSubToolVersions(repoPath, allowSubToolDrift);
+    if (!subToolResult.ok) {
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+  }
+
+  // 2. Update CHANGELOG.md (lightweight entry)
+  updateChangelog(repoPath, newVersion, notes || `${track} prerelease`);
+  console.log(`  \u2713 CHANGELOG.md updated`);
+
+  // 3. Git commit + tag
+  const msg = `v${newVersion}: ${track} prerelease`;
+  for (const f of ['package.json', 'CHANGELOG.md']) {
+    if (existsSync(join(repoPath, f))) {
+      execFileSync('git', ['add', f], { cwd: repoPath, stdio: 'pipe' });
+    }
+  }
+  execFileSync('git', ['commit', '--no-verify', '-m', msg], { cwd: repoPath, stdio: 'pipe' });
+  execFileSync('git', ['tag', `v${newVersion}`], { cwd: repoPath, stdio: 'pipe' });
+  console.log(`  \u2713 Committed and tagged v${newVersion}`);
+
+  // 4. Push commit + tag
+  try {
+    execSync('git push && git push --tags', { cwd: repoPath, stdio: 'pipe' });
+    console.log(`  \u2713 Pushed to remote`);
+  } catch {
+    console.log(`  ! Push failed. Push manually.`);
+  }
+
+  const distResults = [];
+
+  if (!noPublish) {
+    // 5. npm publish with dist-tag
+    try {
+      publishNpmWithTag(repoPath, track);
+      const pkg = JSON.parse(readFileSync(join(repoPath, 'package.json'), 'utf8'));
+      distResults.push({ target: 'npm', status: 'ok', detail: `${pkg.name}@${newVersion} (tag: ${track})` });
+      console.log(`  \u2713 Published to npm @${track}`);
+    } catch (e) {
+      distResults.push({ target: 'npm', status: 'failed', detail: e.message });
+      console.log(`  \u2717 npm publish failed: ${e.message}`);
+    }
+
+    // 6. GitHub prerelease on public repo (if opted in)
+    if (publishReleaseNotes) {
+      try {
+        createGitHubPrerelease(repoPath, newVersion, notes || `${track} prerelease`);
+        distResults.push({ target: 'GitHub', status: 'ok', detail: `v${newVersion} (prerelease)` });
+        console.log(`  \u2713 GitHub prerelease v${newVersion} created on public repo`);
+      } catch (e) {
+        distResults.push({ target: 'GitHub', status: 'failed', detail: e.message });
+        console.log(`  \u2717 GitHub prerelease failed: ${e.message}`);
+      }
+    } else {
+      console.log(`  - GitHub prerelease: skipped (silent ${track})`);
+    }
+  }
+
+  // Distribution summary
+  if (distResults.length > 0) {
+    console.log('');
+    console.log('  Distribution:');
+    for (const r of distResults) {
+      const icon = r.status === 'ok' ? '\u2713' : '\u2717';
+      console.log(`    ${icon} ${r.target}: ${r.detail}`);
+    }
+  }
+
+  console.log('');
+  console.log(`  Done. ${repoName} v${newVersion} (${track}) released.`);
+  console.log('');
+
+  return { currentVersion, newVersion, dryRun: false };
+}
+
+// ── Hotfix Track ────────────────────────────────────────────────────
+
+/**
+ * Release a hotfix.
+ *
+ * Same as stable patch but: no deploy-public, no code sync.
+ * Publishes to npm @latest, creates GitHub release on public repo (opt out with publishReleaseNotes=false).
+ *
+ * Lighter gates than stable: no product docs check, no stale branch check.
+ * Still runs: worktree guard, license compliance, tests.
+ */
+export async function releaseHotfix({ repoPath, notes, notesSource, dryRun, noPublish, publishReleaseNotes, skipWorktreeCheck, allowSubToolDrift }) {
+  repoPath = repoPath || process.cwd();
+  const currentVersion = detectCurrentVersion(repoPath);
+  const newVersion = bumpSemver(currentVersion, 'patch');
+  const repoName = basename(repoPath);
+
+  console.log('');
+  console.log(`  ${repoName}: ${currentVersion} -> ${newVersion} (hotfix)`);
+  console.log(`  ${'─'.repeat(40)}`);
+
+  // Main-branch guard: worktree + non-main branch check via shared helper
+  {
+    const guardResult = enforceMainBranchGuard(repoPath, skipWorktreeCheck);
+    if (!guardResult.ok) {
+      logMainBranchGuardFailure(guardResult);
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+    if (!guardResult.skipped) {
+      console.log(`  \u2713 Running from main working tree on ${guardResult.branch ?? 'main'}`);
+    }
+  }
+
+  // License compliance gate
+  const configPath = join(repoPath, '.license-guard.json');
+  if (existsSync(configPath)) {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    const licenseIssues = [];
+    const licensePath = join(repoPath, 'LICENSE');
+    if (!existsSync(licensePath)) {
+      licenseIssues.push('LICENSE file is missing');
+    } else {
+      const licenseText = readFileSync(licensePath, 'utf8');
+      if (!licenseText.includes(config.copyright)) {
+        licenseIssues.push(`LICENSE copyright does not match "${config.copyright}"`);
+      }
+    }
+    if (licenseIssues.length > 0) {
+      console.log(`  \u2717 License compliance failed:`);
+      for (const issue of licenseIssues) console.log(`    - ${issue}`);
+      console.log('');
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+    console.log(`  \u2713 License compliance passed`);
+  }
+
+  // Release notes: hotfix accepts --notes flag as convenience (no file-only gate)
+  if (!notes) {
+    console.log(`  ! No release notes provided. Hotfix will have minimal notes.`);
+    notes = 'Hotfix release.';
+  }
+
+  // Run tests if they exist
+  {
+    const toolsDir = join(repoPath, 'tools');
+    const testFiles = [];
+    if (existsSync(toolsDir)) {
+      for (const sub of readdirSync(toolsDir)) {
+        const testPath = join(toolsDir, sub, 'test.sh');
+        if (existsSync(testPath)) testFiles.push({ tool: sub, path: testPath });
+      }
+    }
+    const rootTest = join(repoPath, 'test.sh');
+    if (existsSync(rootTest)) testFiles.push({ tool: '(root)', path: rootTest });
+
+    if (testFiles.length > 0) {
+      let allPassed = true;
+      for (const { tool, path } of testFiles) {
+        try {
+          execFileSync('bash', [path], { cwd: dirname(path), stdio: 'pipe', timeout: 30000 });
+          console.log(`  \u2713 Tests passed: ${tool}`);
+        } catch (e) {
+          allPassed = false;
+          console.log(`  \u2717 Tests FAILED: ${tool}`);
+          const output = (e.stdout || '').toString().trim();
+          if (output) {
+            for (const line of output.split('\n').slice(-5)) console.log(`    ${line}`);
+          }
+        }
+      }
+      if (!allPassed) {
+        console.log('');
+        console.log('  Fix failing tests before releasing.');
+        console.log('');
+        return { currentVersion, newVersion, dryRun: false, failed: true };
+      }
+    }
+  }
+
+  if (dryRun) {
+    console.log(`  [dry run] Would bump package.json to ${newVersion}`);
+    console.log(`  [dry run] Would update CHANGELOG.md`);
+    if (!noPublish) {
+      console.log(`  [dry run] Would npm publish with --tag latest`);
+      if (publishReleaseNotes) {
+        console.log(`  [dry run] Would create GitHub release v${newVersion} on public repo`);
+      } else {
+        console.log(`  [dry run] No GitHub release (--no-release-notes)`);
+      }
+      console.log(`  [dry run] No deploy-public (hotfix)`);
+    }
+    console.log('');
+    console.log(`  Dry run complete. No changes made.`);
+    console.log('');
+    return { currentVersion, newVersion, dryRun: true };
+  }
+
+  // 1.25. Pre-bump tag collision check (Phase 2).
+  {
+    const collision = checkTagCollision(repoPath, newVersion);
+    if (!collision.ok) {
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+  }
+
+  // 1. Bump package.json
+  writePackageVersion(repoPath, newVersion);
+  console.log(`  \u2713 package.json -> ${newVersion}`);
+
+  // 1.5. Validate sub-tool version bumps (Phase 8: error by default)
+  {
+    const subToolResult = validateSubToolVersions(repoPath, allowSubToolDrift);
+    if (!subToolResult.ok) {
+      return { currentVersion, newVersion, dryRun: false, failed: true };
+    }
+  }
+
+  // 2. Sync SKILL.md
+  if (syncSkillVersion(repoPath, newVersion)) {
+    console.log(`  \u2713 SKILL.md -> ${newVersion}`);
+  }
+
+  // 3. Update CHANGELOG.md
+  updateChangelog(repoPath, newVersion, notes);
+  console.log(`  \u2713 CHANGELOG.md updated`);
+
+  // 3.5. Move RELEASE-NOTES-v*.md to _trash/
+  const trashed = trashReleaseNotes(repoPath);
+  if (trashed > 0) {
+    console.log(`  \u2713 Moved ${trashed} RELEASE-NOTES file(s) to _trash/`);
+  }
+
+  // 4. Git commit + tag
+  gitCommitAndTag(repoPath, newVersion, notes);
+  console.log(`  \u2713 Committed and tagged v${newVersion}`);
+
+  // 5. Push commit + tag
+  try {
+    execSync('git push && git push --tags', { cwd: repoPath, stdio: 'pipe' });
+    console.log(`  \u2713 Pushed to remote`);
+  } catch {
+    console.log(`  ! Push failed. Push manually.`);
+  }
+
+  const distResults = [];
+
+  if (!noPublish) {
+    // 6. npm publish with @latest tag
+    try {
+      publishNpmWithTag(repoPath, 'latest');
+      const pkg = JSON.parse(readFileSync(join(repoPath, 'package.json'), 'utf8'));
+      distResults.push({ target: 'npm', status: 'ok', detail: `${pkg.name}@${newVersion}` });
+      console.log(`  \u2713 Published to npm @latest`);
+    } catch (e) {
+      distResults.push({ target: 'npm', status: 'failed', detail: e.message });
+      console.log(`  \u2717 npm publish failed: ${e.message}`);
+    }
+
+    // 7. GitHub release on public repo (not prerelease)
+    if (publishReleaseNotes) {
+      try {
+        createGitHubReleaseOnPublic(repoPath, newVersion, notes, currentVersion);
+        distResults.push({ target: 'GitHub', status: 'ok', detail: `v${newVersion}` });
+        console.log(`  \u2713 GitHub release v${newVersion} created on public repo`);
+      } catch (e) {
+        distResults.push({ target: 'GitHub', status: 'failed', detail: e.message });
+        console.log(`  \u2717 GitHub release failed: ${e.message}`);
+      }
+    } else {
+      console.log(`  - GitHub release: skipped (--no-release-notes)`);
+    }
+
+    // No deploy-public for hotfix
+    console.log(`  - deploy-public: skipped (hotfix)`);
+
+    // 8. ClawHub skill publish
+    const rootSkill = join(repoPath, 'SKILL.md');
+    if (existsSync(rootSkill)) {
+      try {
+        publishClawHub(repoPath, newVersion, notes);
+        const slug = detectSkillSlug(repoPath);
+        distResults.push({ target: 'ClawHub', status: 'ok', detail: `${slug}@${newVersion}` });
+        console.log(`  \u2713 Published to ClawHub: ${slug}`);
+      } catch (e) {
+        distResults.push({ target: 'ClawHub', status: 'failed', detail: e.message });
+        console.log(`  \u2717 ClawHub publish failed: ${e.message}`);
+      }
+    }
+  }
+
+  // Distribution summary
+  if (distResults.length > 0) {
+    console.log('');
+    console.log('  Distribution:');
+    for (const r of distResults) {
+      const icon = r.status === 'ok' ? '\u2713' : '\u2717';
+      console.log(`    ${icon} ${r.target}: ${r.detail}`);
+    }
+  }
+
+  // Write release marker
+  try {
+    const markerDir = join(process.env.HOME || '', '.ldm', 'state');
+    mkdirSync(markerDir, { recursive: true });
+    writeFileSync(join(markerDir, '.last-release'), JSON.stringify({
+      repo: repoName,
+      version: newVersion,
+      timestamp: new Date().toISOString(),
+      track: 'hotfix',
+    }) + '\n');
+  } catch {}
+
+  console.log('');
+  console.log(`  Done. ${repoName} v${newVersion} (hotfix) released.`);
+  console.log('');
+
+  return { currentVersion, newVersion, dryRun: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-release",
-  "version": "1.9.67",
+  "version": "1.9.72",
   "type": "module",
   "description": "One-command release pipeline. Bumps version, updates changelog + SKILL.md, publishes to npm + GitHub.",
   "main": "core.mjs",