@skitterbyte/skitterspec 12.0.0 → 13.0.0

package/src/cli.js

@@ -39,7 +39,9 @@ const {
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const { planUp } = require('./env/provision.js')
 const { planDown } = require('./env/teardown.js')
+const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
 const { planIntegrate } = require('./env/integrate.js')
+const { planHotfixLand } = require('./env/hotfix.js')
 const { planDev } = require('./env/dev.js')
 const { startProcess, stopProcess, waitHealthy } = require('./env/supervise.js')
 const { renderRoutes, portsInUse, waitListening } = require('./env/proxy.js')
@@ -60,10 +62,12 @@ Usage:
                               specs/.core/env.config.json). Subcommands:
                                 up <spec>         plan a worktree + Docker stack + opener
                                 down <spec>       tear down (guards; --keep-volumes, --force)
+                                prune             reap orphaned test-DB volumes (--older-than <days>)
                                 dev up <spec>     start host dev servers on the spec's ports
                                 dev down <spec>   stop the spec's host dev servers
                                 connect <spec>    expose a spec on the canonical ports (main = off)
                                 integrate <spec>  plan rebase + fast-forward onto the base branch
+                                hotfix land <spec>  tag + cherry-pick a hotfix (--also <tag>)
                                 status            list provisioned specs + port blocks
                                 resolve <spec>    print resolved slug/type/branch/paths
   skitterspec --help          Show this help
@@ -271,7 +275,9 @@ function gitReader(cwd) {
 // the resolved integration branch; `merged` is true when HEAD is already an
 // ancestor of it (fully landed), which lets teardown skip the unpushed guard.
 function worktreeGitState(worktreePath, base) {
-  if (!fs.existsSync(worktreePath)) return { dirty: false, unpushed: false, merged: true }
+  if (!fs.existsSync(worktreePath)) {
+    return { dirty: false, unpushed: false, merged: true, reachableFromTag: false }
+  }
   const git = gitReader(worktreePath)
 
   const status = git(['status', '--porcelain'])
@@ -293,7 +299,13 @@ function worktreeGitState(worktreePath, base) {
   // exits 0 when true; gitReader maps a non-zero exit to null.
   const merged = base != null && git(['merge-base', '--is-ancestor', 'HEAD', base]) !== null
 
-  return { dirty, unpushed, merged }
+  // reachableFromTag = HEAD is captured by a tag (the deploy tag from `hotfix
+  // land`). A hotfix branch is never merged into base, so this is what tells
+  // teardown its commits are safely recoverable.
+  const pointing = git(['tag', '--points-at', 'HEAD'])
+  const reachableFromTag = pointing !== null && pointing.length > 0
+
+  return { dirty, unpushed, merged, reachableFromTag }
 }
 
 // A deterministic-enough compact timestamp for backup filenames (CLI-only; the
@@ -358,6 +370,166 @@ function specEnvDown(dir, config, specArg, flags) {
   process.stdout.write(out.join('\n') + '\n')
 }
 
+// --- prune: reap orphaned per-spec test-DB volumes -------------------------
+
+// Live Docker volumes in the repo namespace (`{repoSlug}_…`). Returns
+// { ok, names }: ok:false means docker is unavailable / errored (non-fatal — the
+// caller reports and skips). The `name=` filter is a substring match, so we
+// re-check the prefix in the pure planner.
+function listRepoVolumes(repoSlug) {
+  try {
+    const out = execFileSync(
+      'docker',
+      ['volume', 'ls', '--format', '{{.Name}}', '--filter', `name=${repoSlug}_`],
+      { stdio: ['ignore', 'pipe', 'pipe'] },
+    )
+      .toString()
+      .trim()
+    const names = out ? out.split('\n').map((s) => s.trim()).filter(Boolean) : []
+    return { ok: true, names }
+  } catch (error) {
+    const err = (error.stderr && error.stderr.toString().trim()) || error.message
+    return { ok: false, names: [], err }
+  }
+}
+
+// Map orphan-candidate volume names → creation epoch-ms via `docker volume
+// inspect`. Unknown/unparseable timestamps stay null (the planner keeps them).
+function volumeCreatedAt(names) {
+  const byName = new Map()
+  if (!names.length) return byName
+  try {
+    const out = execFileSync(
+      'docker',
+      ['volume', 'inspect', '--format', '{{.Name}}\t{{.CreatedAt}}', ...names],
+      { stdio: ['ignore', 'pipe', 'pipe'] },
+    )
+      .toString()
+      .trim()
+    for (const line of out.split('\n')) {
+      const [name, created] = line.split('\t')
+      const ms = created ? Date.parse(created.trim()) : NaN
+      if (name) byName.set(name.trim(), Number.isNaN(ms) ? null : ms)
+    }
+  } catch {
+    // Inspect failed wholesale → treat every candidate as unknown-age (kept).
+  }
+  return byName
+}
+
+// Absolute paths of every checkout git knows about (primary + all worktrees).
+function liveWorktreePaths(dir) {
+  const out = gitReader(dir)(['worktree', 'list', '--porcelain'])
+  const paths = new Set()
+  if (out == null) return paths
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      paths.add(path.resolve(line.slice('worktree '.length).trim()))
+    }
+  }
+  return paths
+}
+
+// Every spec folder name found under specs/* across the given checkout roots.
+// An in-progress spec lives on its *worktree branch*, not the primary checkout,
+// so we must scan the worktrees too — otherwise a live spec's DB looks orphaned.
+function collectSpecFolders(roots) {
+  const folders = new Set()
+  for (const root of roots) {
+    for (const bucket of ['backlog', 'in-progress', 'complete', 'cancelled']) {
+      let entries
+      try {
+        entries = fs.readdirSync(path.join(root, 'specs', bucket), { withFileTypes: true })
+      } catch {
+        continue
+      }
+      for (const entry of entries) if (entry.isDirectory()) folders.add(entry.name)
+    }
+  }
+  return folders
+}
+
+// Resolve every spec folder (found in the primary checkout OR any worktree) to
+// { folder, slug, worktreePath }. `searchDirs` lets resolveSpec locate a spec
+// that was authored on its branch and never committed to the primary checkout.
+function allSpecs(dir, config, worktreePaths) {
+  const searchDirs = [...worktreePaths]
+  const specs = []
+  for (const folder of collectSpecFolders([dir, ...searchDirs])) {
+    try {
+      const spec = resolveSpec(folder, dir, config, { searchDirs })
+      specs.push({ folder: spec.folder, slug: spec.slug, worktreePath: spec.worktreePath })
+    } catch {
+      // Unresolvable folder (not a real spec) — skip.
+    }
+  }
+  return specs
+}
+
+// Prune: reconcile namespace volumes against specs that still have a worktree and
+// print the `docker volume rm` commands for the orphans. Liveness keys off the
+// worktree, NOT the registry (a declined teardown leaves a stale slot behind), so
+// this correctly reaps those and frees their stale slots. Destructive removal is
+// executed by the caller (skill) after confirmation — the CLI only plans + writes
+// the registry, mirroring `spec-env down`.
+function specEnvPrune(dir, config, flags) {
+  const { repoSlug } = repoInfo(dir)
+
+  const vols = listRepoVolumes(repoSlug)
+  if (!vols.ok) {
+    process.stdout.write(
+      `spec-env prune: could not list docker volumes — ${vols.err || 'docker unavailable'}.\n` +
+        'Is Docker running? Nothing pruned.\n',
+    )
+    return
+  }
+
+  const worktrees = liveWorktreePaths(dir)
+  const specs = allSpecs(dir, config, worktrees)
+  const liveSlugs = liveSlugsForSpecs(specs, worktrees)
+
+  const olderThanDays =
+    flags && Number.isFinite(flags.olderThanDays) ? flags.olderThanDays : null
+  let volumes = vols.names
+  let now = null
+  if (olderThanDays != null) {
+    const createdAt = volumeCreatedAt(vols.names)
+    volumes = vols.names.map((name) => ({ name, createdAt: createdAt.get(name) ?? null }))
+    now = Date.now()
+  }
+
+  const plan = planPrune(volumes, liveSlugs, { repoSlug, olderThanDays, now })
+
+  if (!plan.orphans.length) {
+    process.stdout.write(
+      `spec-env prune: no orphaned volumes in ${repoSlug}_* ` +
+        `(${vols.names.length} namespace volume(s), ${liveSlugs.size} live spec(s) protected).\n`,
+    )
+    return
+  }
+
+  // Reconcile the registry: free the slot of any spec whose volume we're reaping.
+  const registry = readRegistry(dir, config)
+  const { registry: nextRegistry, freed } = reconcileRegistry(registry, plan.orphans, repoSlug)
+  if (freed.length) writeRegistry(dir, config, nextRegistry)
+
+  const ageNote = olderThanDays != null ? ` older than ${olderThanDays}d` : ''
+  const out = []
+  out.push(
+    `spec-env prune: ${plan.orphans.length} orphaned volume(s)${ageNote} ` +
+      `(${liveSlugs.size} live spec(s) protected)`,
+  )
+  out.push('')
+  out.push('  orphans:')
+  for (const o of plan.orphans) out.push(`    ${o.name}`)
+  if (freed.length) out.push(`  slots freed:  ${freed.join(', ')}`)
+  out.push('  backup:       none (prune does not back up — orphans have no running DB)')
+  out.push('')
+  out.push('  run these:')
+  for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  process.stdout.write(out.join('\n') + '\n')
+}
+
 // Integrate: land a spec's worktree branch onto the base branch (rebase + ff).
 // Queries git for the facts, prints the plan / block / no-op. The /spec-complete
 // skill executes the printed commands (and aborts a conflicting rebase).
@@ -450,6 +622,93 @@ function specEnvIntegrate(dir, config, specArg) {
   process.stdout.write(out.join('\n') + '\n')
 }
 
+// Land a hotfix: tag the branch with the patch-bumped base tag (the prod deploy
+// tag), cherry-pick the fix onto any extra base tags (test/demo lines) and onto
+// the base branch for the next release. Queries git for the facts, prints the plan
+// / block / no-op. The /spec-complete skill runs the printed commands (aborting a
+// cherry-pick on conflict). NEVER pushes — pushing the deploy tag is the operator's.
+function specEnvHotfix(dir, config, positional, flags) {
+  const action = positional[0]
+  const specArg = positional[1]
+  if (action !== 'land' || !specArg) {
+    process.stdout.write('Usage: skitterspec spec-env hotfix land <spec> [--also <tag>]...\n')
+    return
+  }
+
+  // A hotfix may be authored entirely on its branch, so fall back to its worktree.
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
+  if (spec.type !== 'hotfix') {
+    process.stdout.write(
+      `spec-env hotfix land: ${spec.folder} is not a hotfix — needs Type: Hotfix / a hotfix- prefix.\n`,
+    )
+    return
+  }
+  if (!fs.existsSync(spec.worktreePath)) {
+    process.stdout.write(`spec-env hotfix land: ${spec.folder} has no worktree — nothing to land.\n`)
+    return
+  }
+
+  const base = resolveBaseBranch(config, gitReader(dir))
+  const wtGit = gitReader(spec.worktreePath)
+  const status = wtGit(['status', '--porcelain'])
+  const dirty = status !== null && status.length > 0
+  const ahead = wtGit(['rev-list', '--count', `${spec.baseRef}..HEAD`])
+  const aheadOfBase = ahead !== null && Number(ahead) > 0
+  const tagList = wtGit(['tag', '--list'])
+  const existingTags = tagList ? tagList.split('\n').map((s) => s.trim()).filter(Boolean) : []
+
+  // Extra targets: --also flags first, then any config defaults; drop blanks, the
+  // base tag itself, and duplicates.
+  const seen = new Set()
+  const extraTargets = [...(flags.also || []), ...(config.hotfix.targets || [])].filter((t) => {
+    if (!t || t === spec.baseRef || seen.has(t)) return false
+    seen.add(t)
+    return true
+  })
+
+  let plan
+  try {
+    plan = planHotfixLand(spec, config, {
+      worktreeState: { dirty },
+      aheadOfBase,
+      fixRange: `${spec.baseRef}..${spec.branch}`,
+      mainRepoPath: dir,
+      base,
+      extraTargets,
+      existingTags,
+    })
+  } catch (error) {
+    process.stdout.write(`spec-env hotfix land: ${error.message}.\n`)
+    return
+  }
+
+  if (plan.blocked) {
+    process.stdout.write(`spec-env hotfix land: blocked — ${plan.reason}.\n`)
+    return
+  }
+  if (plan.noop) {
+    process.stdout.write(`spec-env hotfix land: ${plan.reason}.\n`)
+    return
+  }
+
+  const out = []
+  out.push(`spec-env hotfix land: ${spec.folder}`)
+  out.push('')
+  out.push(`  base tag:  ${spec.baseRef}`)
+  out.push(`  branch:    ${spec.branch}`)
+  out.push(`  prod tag:  ${plan.prodTag}  (created locally — push to deploy)`)
+  for (const t of plan.targets) {
+    if (t.kind === 'extra') out.push(`  target:    ${t.base} -> ${t.tag}`)
+    if (t.kind === 'main') out.push(`  next rel:  cherry-pick onto ${t.base}`)
+  }
+  out.push('')
+  out.push('  run these (abort a cherry-pick on conflict, resolve, then re-run):')
+  for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  out.push('')
+  out.push(`  then push the deploy tag yourself:  git push origin ${plan.prodTag}`)
+  process.stdout.write(out.join('\n') + '\n')
+}
+
 // Print the resolved identity/coordinates for a single spec.
 function specEnvResolve(dir, config, specArg) {
   if (!specArg) {
@@ -904,11 +1163,13 @@ async function specEnv(rest) {
   const [sub, ...args] = rest
   let dir = process.cwd()
   const positional = []
-  const flags = { keepVolumes: false, force: false }
+  const flags = { keepVolumes: false, force: false, also: [], olderThanDays: null }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--keep-volumes') flags.keepVolumes = true
     else if (args[i] === '--force') flags.force = true
+    else if (args[i] === '--also') flags.also.push(args[++i])
+    else if (args[i] === '--older-than') flags.olderThanDays = Number(args[++i])
     else positional.push(args[i])
   }
   dir = path.resolve(dir)
@@ -932,6 +1193,9 @@ async function specEnv(rest) {
     case 'down':
       specEnvDown(dir, config, positional[0], flags)
       break
+    case 'prune':
+      specEnvPrune(dir, config, flags)
+      break
     case 'dev':
       await specEnvDev(dir, config, positional)
       break
@@ -941,6 +1205,9 @@ async function specEnv(rest) {
     case 'integrate':
       specEnvIntegrate(dir, config, positional[0])
       break
+    case 'hotfix':
+      specEnvHotfix(dir, config, positional, flags)
+      break
     case 'status':
       specEnvStatus(dir, config)
       break
@@ -952,7 +1219,7 @@ async function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|dev|connect|integrate|live|status|resolve> [spec] [--keep-volumes] [--force]\n',
+        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n',
       )
   }
 }

package/src/env/config.js

@@ -31,6 +31,9 @@
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
  *     live:     { migrations: [ "glob", ... ] }  // migration globs → `live take`
  *               // refuses a branch that changes them (code-only v1)
+ *     hotfix:   { bump, cherryPickMain, targets }  // `hotfix land`: patch-bump the
+ *               // deploy tag, also cherry-pick onto the base branch (main), and
+ *               // onto any extra base tags in `targets` (test/demo lines)
  *   }
  */
 
@@ -80,6 +83,12 @@ const DEFAULT_CONFIG = Object.freeze({
   // migration files; a branch that changes any of them is treated as stateful and
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
   live: Object.freeze({ migrations: Object.freeze([]) }),
+  // Hotfix landing (`spec-env hotfix land`). `bump` is the version-bump strategy
+  // for the new deploy tag (only "patch" today). `cherryPickMain` also cherry-picks
+  // the fix onto the base branch for the next release (default true). `targets` is
+  // an optional default list of extra base tags to also patch (test/demo lines);
+  // `--also <tag>` on the command adds more at run time. Default: patch, main, none.
+  hotfix: Object.freeze({ bump: 'patch', cherryPickMain: true, targets: Object.freeze([]) }),
 })
 
 function isObject(value) {
@@ -101,6 +110,7 @@ function defaults() {
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
     live: { migrations: [] },
+    hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
 }
 
@@ -248,6 +258,14 @@ function mergeConfig(base, parsed) {
     base.live.migrations = normalizeFileList(parsed.live.migrations)
   }
 
+  if (isObject(parsed.hotfix)) {
+    assign(base.hotfix, parsed.hotfix, 'bump', 'string')
+    assign(base.hotfix, parsed.hotfix, 'cherryPickMain', 'boolean')
+    if (Array.isArray(parsed.hotfix.targets)) {
+      base.hotfix.targets = normalizeFileList(parsed.hotfix.targets)
+    }
+  }
+
   return base
 }
 

package/src/env/hotfix.js

@@ -0,0 +1,133 @@
+'use strict'
+
+/**
+ * Pure landing planner for `spec-env hotfix land`.
+ *
+ * A hotfix is built on an old release tag (its `Base version`), so it can't be
+ * fast-forwarded onto `main` like an ordinary spec (that's `integrate.js`).
+ * Instead `planHotfixLand` emits the exact side-effect-free, **never-pushing**
+ * commands to:
+ *   1. tag the hotfix branch head with the patch-bumped base tag (the prod deploy
+ *      tag — the branch head already is baseRef + the fix);
+ *   2. for each extra target tag, cherry-pick the fix onto a throwaway worktree at
+ *      that tag and re-tag it with its own patch bump (test/demo release lines);
+ *   3. cherry-pick the fix onto the base branch (main) for the next release.
+ *
+ * It performs no side effects — the caller (the CLI) probes git for `dirty` /
+ * `aheadOfBase` / `existingTags` / `mainRepoPath` and supplies them, keeping this
+ * deterministic and unit-testable with no live git. Conflict handling lives in the
+ * skill (run a cherry-pick, abort on non-zero exit, hand back), mirroring
+ * `integrate.js` — the planner never reasons about conflicts.
+ */
+
+const path = require('node:path')
+
+/**
+ * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
+ * non-digit prefix (e.g. `v` → `v33.16.5`) and drops any pre-release/build suffix
+ * (`-rc1`, `+build`). Throws on a tag with no `MAJOR.MINOR.PATCH` core.
+ */
+function bumpPatch(tag) {
+  const m = /^(\D*)(\d+)\.(\d+)\.(\d+)(?:.*)$/.exec(String(tag || '').trim())
+  if (!m) {
+    throw new Error(
+      `hotfix: cannot bump a patch version from tag "${tag}" — need <prefix>MAJOR.MINOR.PATCH`,
+    )
+  }
+  const [, prefix, major, minor, patch] = m
+  return `${prefix}${major}.${minor}.${Number(patch) + 1}`
+}
+
+// A filesystem/branch-safe slug derived from a tag (`v30.2.1` → `v30-2-1`).
+function tagSlug(tag) {
+  return String(tag)
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/**
+ * @param {object} spec  resolved hotfix spec: { slug, branch, worktreePath, baseRef, ... }
+ * @param {object} config normalised env config (reads `config.hotfix`).
+ * @param {object} ctx   { worktreeState:{dirty}, aheadOfBase, fixRange, mainRepoPath,
+ *                          base, extraTargets: string[], existingTags: string[] }
+ * @returns {object} { blocked, noop, reason, commands, prodTag, targets, branch, base }
+ */
+function planHotfixLand(spec, config, ctx) {
+  const c = ctx || {}
+  const branch = spec.branch
+  const baseRef = spec.baseRef
+  const hotfixCfg = (config && config.hotfix) || { cherryPickMain: true, targets: [] }
+  const result = {
+    blocked: false,
+    noop: false,
+    reason: null,
+    commands: [],
+    prodTag: null,
+    targets: [],
+    branch,
+    base: c.base,
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // A hotfix must carry the tag it forked from — everything below bumps from it.
+  if (!baseRef) {
+    return block('spec has no Base version — not a hotfix, or the header is missing')
+  }
+  // The completion edits (status flip, git mv) must be committed before landing.
+  if (c.worktreeState && c.worktreeState.dirty) {
+    return block('worktree has uncommitted changes — commit the completion first')
+  }
+  // Nothing on the branch beyond the base tag → nothing to land.
+  if (!c.aheadOfBase) {
+    return { ...result, noop: true, reason: `no commits on ${branch} beyond ${baseRef} — nothing to land` }
+  }
+
+  // Track tags we'd create so we never plan a collision (with an existing tag, or
+  // between the prod tag and a target tag).
+  const taken = new Set(c.existingTags || [])
+  const fixRange = c.fixRange
+  const commands = []
+  const targets = []
+
+  // 1. Prod line: tag the hotfix branch head (already baseRef + fix). No push.
+  const prodTag = bumpPatch(baseRef)
+  if (taken.has(prodTag)) {
+    return block(`tag ${prodTag} already exists — bump the base version or delete the stale tag`)
+  }
+  taken.add(prodTag)
+  commands.push(`git -C ${spec.worktreePath} tag ${prodTag}`)
+  targets.push({ kind: 'prod', base: baseRef, tag: prodTag })
+
+  // 2. Extra targets: cherry-pick the fix onto a throwaway worktree at each tag,
+  //    re-tag with its own patch bump, then remove the worktree + temp branch (the
+  //    commits survive under the new tag, so `-D` is safe for the throwaway branch).
+  const wtRoot = path.dirname(spec.worktreePath)
+  for (const t of c.extraTargets || []) {
+    const tag = bumpPatch(t)
+    if (taken.has(tag)) {
+      return block(`tag ${tag} (for target ${t}) already exists — resolve it before landing`)
+    }
+    taken.add(tag)
+    const slug = `${spec.slug}-onto-${tagSlug(t)}`
+    const tmpBranch = `hotfix/${slug}`
+    const tmpPath = path.join(wtRoot, slug)
+    commands.push(
+      `git worktree add ${tmpPath} -b ${tmpBranch} ${t}`,
+      `git -C ${tmpPath} cherry-pick ${fixRange}`,
+      `git -C ${tmpPath} tag ${tag}`,
+      `git worktree remove ${tmpPath}`,
+      `git branch -D ${tmpBranch}`,
+    )
+    targets.push({ kind: 'extra', base: t, tag, worktreePath: tmpPath })
+  }
+
+  // 3. Cherry-pick the fix onto the base branch (main) for the next release.
+  if (hotfixCfg.cherryPickMain !== false) {
+    commands.push(`git -C ${c.mainRepoPath} cherry-pick ${fixRange}`)
+    targets.push({ kind: 'main', base: c.base })
+  }
+
+  return { ...result, commands, prodTag, targets, fixRange }
+}
+
+module.exports = { bumpPatch, tagSlug, planHotfixLand }

package/src/env/live.js

@@ -179,21 +179,30 @@ function planTake(spec, config, ctx) {
   if (!c.worktreeExists) {
     return block(`${spec.folder} has no worktree — run \`/spec-go ${spec.folder}\` first`)
   }
-  // 4. v1 is code-only: refuse a stateful spec (Stack: worktree + docker)…
+  // 4. A hotfix is built on an old release tag; checking its branch out under the
+  //    running dev server risks schema/DB drift breaking the shared instance.
+  //    Always refuse, regardless of Stack — test it in isolation via /spec-connect.
+  if (spec.type === 'hotfix') {
+    return block(
+      `${spec.folder} is a hotfix (built on an old release tag) — live overlay ` +
+        'could break the running instance; use `/spec-connect` to test it in isolation',
+    )
+  }
+  // 5. v1 is code-only: refuse a stateful spec (Stack: worktree + docker)…
   if (spec.stack === 'docker') {
     return block(
       `${spec.folder} is stateful (Stack: worktree + docker) — live overlay is ` +
         'code-only; use `/spec-connect` for a Docker-backed spec',
     )
   }
-  // 5. …and refuse a branch that changes migrations (would mutate the shared DB).
+  // 6. …and refuse a branch that changes migrations (would mutate the shared DB).
   if (c.migrationsHit) {
     return block(
       `${spec.folder}'s branch changes migrations — live overlay is code-only; ` +
         'use `/spec-connect`',
     )
   }
-  // 6. Verify-only: a dev server must be listening to hot-reload the switch.
+  // 7. Verify-only: a dev server must be listening to hot-reload the switch.
   if (c.serverUp === false) {
     return block(
       `no dev server listening on canonical port(s) ${(c.canonicalPorts || []).join(', ')} — ` +

package/src/env/provision.js

@@ -94,10 +94,14 @@ function planUp(spec, alloc, config) {
 
   const commands = []
   // Fresh branch → -b; attach an existing branch/slot → plain form (never clobber).
+  // A hotfix forks its fresh branch from a release tag (`spec.baseRef`, e.g.
+  // `v33.16.4`) instead of base HEAD — so the fix is built on the exact commit
+  // line prod runs. Attaching an existing branch ignores baseRef (already forked).
+  const forkPoint = !attached && spec.baseRef ? ` ${spec.baseRef}` : ''
   commands.push(
     attached
       ? `git worktree add ${spec.worktreePath} ${spec.branch}`
-      : `git worktree add ${spec.worktreePath} -b ${spec.branch}`,
+      : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
   )
   if (wantsDocker) {
     commands.push(`docker compose --project-name ${spec.projectName} up -d`)