@skitterbyte/skitterspec-jira 0.0.0-stage → 1.0.0

package/src/env/dev.js

@@ -0,0 +1,63 @@
+'use strict'
+
+/**
+ * Pure planner for host dev-process supervision (`spec-env dev up|down`).
+ *
+ * Given a resolved spec and its allocated slot, `planDev` computes — for each
+ * configured `dev` process — its resolved port, the env var to inject, the log
+ * and pid file paths, the expanded health URL, and the canonical `frontPort` a
+ * later proxy (Phase 2) routes to it. No side effects: the CLI's `supervise.js`
+ * does the spawning/killing; this stays unit-testable with no processes.
+ *
+ * Port math: process `i` in the slot's block gets `portBase + slot*portsPerSpec
+ * + i` (reusing the same block the Docker stack draws from — see registry.js).
+ * So host dev servers get a reserved block even on a worktree-only spec.
+ *
+ * Log/pid files live beside the registry (default `.spec-env/`) and are keyed by
+ * the spec **folder** (not the bare slug) so a `feat-foo`/`bug-foo` pair can't
+ * collide — matching how the registry keys slots.
+ */
+
+const path = require('node:path')
+const { portOffset } = require('./registry.js')
+const { expandTokens } = require('./resolve.js')
+
+// The state dir (logs + pids) sits beside the registry file, e.g. `.spec-env`.
+function stateDir(config) {
+  return path.posix.dirname(config.registry) || '.spec-env'
+}
+
+/**
+ * Plan the host dev processes for `spec` at `slot`.
+ *
+ * @returns {object} { slot, portOffset, procs: [{ name, command, port, portVar,
+ *   env, frontPort, logFile, pidFile, health }] } — logFile/pidFile are paths
+ *   relative to the primary checkout root (the CLI resolves them).
+ */
+function planDev(spec, slot, config) {
+  const base = portOffset(slot, config)
+  const dir = stateDir(config)
+  const procs = (config.dev || []).map((entry, i) => {
+    const port = base + i
+    const tokens = {
+      [entry.portVar]: String(port),
+      port: String(port),
+      slug: spec.slug,
+      name: entry.name,
+    }
+    return {
+      name: entry.name,
+      command: expandTokens(entry.command, tokens),
+      port,
+      portVar: entry.portVar,
+      env: { [entry.portVar]: String(port) },
+      frontPort: typeof entry.frontPort === 'number' ? entry.frontPort : null,
+      logFile: `${dir}/logs/${spec.folder}-${entry.name}.log`,
+      pidFile: `${dir}/pids/${spec.folder}-${entry.name}.pid`,
+      health: entry.health ? expandTokens(entry.health, tokens) : null,
+    }
+  })
+  return { slot, portOffset: base, procs }
+}
+
+module.exports = { planDev, stateDir }

package/src/env/hooks.js

@@ -0,0 +1,226 @@
+'use strict'
+
+/**
+ * Register the review-gate hook in the project's Claude Code settings.
+ *
+ * `.claude/settings.json` rather than `settings.local.json`, and the difference
+ * is the point: the trusted-worktree entry is an absolute path and therefore
+ * one machine's business, while this is the project's policy — a phase that
+ * ended owes a verdict — and it should reach everyone who clones the repo. The
+ * command is written with `${CLAUDE_PROJECT_DIR}` so it stays true wherever the
+ * checkout lives, worktrees included.
+ *
+ * Conservative in the same way `trust.js` is: every existing key is preserved,
+ * a file it cannot parse is left exactly as it is, and re-running changes
+ * nothing once the entry is there. Callers own the reporting.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+// `.cjs`, and the extension is load-bearing. This file is copied INTO the target
+// project, where that project's `package.json` decides how node parses a `.js` —
+// so the CommonJS script shipped as `review-gate.js` died on its own first
+// `require` in every `"type": "module"` project, printing a stack trace over
+// every Bash tool call. `.cjs` settles the parse mode at the file, independently
+// of the one file skitterspec does not control.
+const HOOK_STEM = '.claude/hooks/review-gate'
+const HOOK_SCRIPT = `${HOOK_STEM}.cjs`
+const HOOK_COMMAND = `node "\${CLAUDE_PROJECT_DIR}/${HOOK_SCRIPT}"`
+
+// Our script under ANY extension, so a registration naming the retired `.js` is
+// recognised as ours and migrated rather than duplicated. The trailing lookahead
+// is the boundary: without it `review-gate-extra.js` — somebody else's hook —
+// matches on the stem and gets silently rewritten.
+const HOOK_SCRIPT_RE = /[.]claude[/\\]hooks[/\\]review-gate(?:[.][A-Za-z0-9]+)?(?![\w.-])/
+// Seconds. The engine call behind this is one git-free read of a small JSON
+// file, so anything approaching this is a wedge rather than slow work — and a
+// hook that times out fails OPEN, which is the answer we want for a wedge.
+const HOOK_TIMEOUT = 10
+const MATCHER = 'Bash'
+
+/**
+ * Every hook this package registers, as data.
+ *
+ * ONE LIST, so a second hook cannot arrive as a second copy of the merge logic
+ * below — which is where every property this file has earned would have to be
+ * re-derived and one of them forgotten. Each entry supplies only what differs:
+ * the script's stem, the tools it matches, and its timeout.
+ *
+ * The `re` for each is built from its stem with the same boundary lookahead the
+ * review gate's has, so `main-guard-extra.js` — somebody else's hook — is not
+ * silently rewritten as ours.
+ */
+function hookStemRe(stem) {
+  const name = stem.split('/').pop()
+  return new RegExp(`[.]claude[/\\\\]hooks[/\\\\]${name}(?:[.][A-Za-z0-9]+)?(?![\\w.-])`)
+}
+
+const HOOKS = [
+  {
+    key: 'review-gate',
+    stem: HOOK_STEM,
+    matcher: MATCHER,
+    timeout: HOOK_TIMEOUT,
+  },
+  {
+    // Refuses an Edit/Write in the primary checkout while it is on the base
+    // branch. A different matcher from the review gate's, because it guards a
+    // different moment: the first write, before any work exists.
+    key: 'main-guard',
+    stem: '.claude/hooks/main-guard',
+    matcher: 'Edit|Write|NotebookEdit|MultiEdit',
+    timeout: HOOK_TIMEOUT,
+  },
+].map((h) => ({ ...h, script: `${h.stem}.cjs`, re: hookStemRe(h.stem) }))
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function settingsPath(dir) {
+  return path.join(dir, '.claude', 'settings.json')
+}
+
+function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
+}
+
+function commandFor(script) {
+  return `node "\${CLAUDE_PROJECT_DIR}/${script}"`
+}
+
+function hookEntry(hook = HOOKS[0]) {
+  return {
+    matcher: hook.matcher,
+    hooks: [{ type: 'command', command: commandFor(hook.script), timeout: hook.timeout }],
+  }
+}
+
+/**
+ * Is our hook already registered under `PreToolUse`? Pure.
+ *
+ * Matched on the SCRIPT PATH, not on the whole command string. An operator who
+ * added a timeout, wrapped the invocation, or changed the interpreter has
+ * registered our hook their way — re-adding a second copy beside theirs would
+ * run it twice and look like a bug in the gate.
+ */
+function alreadyRegistered(preToolUse, hook = HOOKS[0]) {
+  return registeredHooks(preToolUse, hook).length > 0
+}
+
+// Every hook object under `PreToolUse` whose command names our script, whatever
+// extension it names it under. Pure.
+function registeredHooks(preToolUse, hook = HOOKS[0]) {
+  if (!Array.isArray(preToolUse)) return []
+  const out = []
+  for (const group of preToolUse) {
+    if (!isObject(group) || !Array.isArray(group.hooks)) continue
+    for (const h of group.hooks) {
+      if (isObject(h) && typeof h.command === 'string' && hook.re.test(h.command)) out.push(h)
+    }
+  }
+  return out
+}
+
+/**
+ * Ensure ONE hook is registered in an already-parsed settings object.
+ * Mutates `parsed` in place when it migrates a stale path; returns
+ * `{ changed, reason }` with the same vocabulary as the wrapper below.
+ *
+ * Split out so a second hook could be added without a second copy of this
+ * logic — which is where every property this file has earned (preserve unknown
+ * keys, match on the script PATH, migrate in place, stay idempotent) would have
+ * had to be re-derived, and one of them forgotten.
+ */
+function ensureOneHook(parsed, hook) {
+  const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
+  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+
+  // Registered already — but possibly under a path that no longer exists, since
+  // the script's extension changed. Rewrite the path IN PLACE rather than
+  // replacing the command: an operator who wrapped our hook, added a flag or
+  // changed the interpreter has registered it their way, and the thing that
+  // moved is the file, not their command. Adding a fresh entry beside theirs
+  // would run the gate twice and read as a bug in the gate; leaving the old one
+  // alone would aim the harness at a file this same upgrade retires.
+  const registered = registeredHooks(preToolUse, hook)
+  if (registered.length) {
+    const stale = registered.filter((h) => !h.command.includes(hook.script))
+    if (!stale.length) return { changed: false, reason: 'present' }
+    for (const h of stale) h.command = h.command.replace(hook.re, hook.script)
+    return { changed: true, reason: 'migrated' }
+  }
+
+  parsed.hooks = { ...hooks, PreToolUse: [...preToolUse, hookEntry(hook)] }
+  return { changed: true, reason: 'added' }
+}
+
+/**
+ * Ensure every hook this package ships is registered in `dir`'s project
+ * settings. Idempotent and non-destructive. Returns `{ changed, reason }`:
+ *   - `created`   — no settings file; one was written
+ *   - `added`     — merged into an existing file
+ *   - `migrated`  — registered under a retired path; the path was rewritten
+ *   - `present`   — already registered (no write)
+ *   - `malformed` — the file exists but is not parseable JSON (left untouched)
+ *
+ * WITH SEVERAL HOOKS THE REASON IS THE STRONGEST ONE that applied, in the order
+ * added > migrated > present. A run that added one hook and found the other
+ * already there did change the file, and reporting `present` for it would tell
+ * an operator nothing happened when something did.
+ */
+function ensureHooks(dir) {
+  const file = settingsPath(dir)
+
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      writeSettings(file, { hooks: { PreToolUse: HOOKS.map((h) => hookEntry(h)) } })
+      return { changed: true, reason: 'created' }
+    }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    // Never rewrite a settings file we could not read. It is the operator's
+    // config and everything else in it would be lost.
+    return { changed: false, reason: 'malformed' }
+  }
+  if (!isObject(parsed)) return { changed: false, reason: 'malformed' }
+
+  const reasons = HOOKS.map((h) => ensureOneHook(parsed, h))
+  const changed = reasons.some((r) => r.changed)
+  if (changed) writeSettings(file, parsed)
+
+  for (const rank of ['added', 'migrated', 'present']) {
+    if (reasons.some((r) => r.reason === rank)) return { changed, reason: rank }
+  }
+  return { changed, reason: 'present' }
+}
+
+// The name this shipped under when there was one hook. Kept as an alias rather
+// than renamed away, because it is what an installed `init.js` from an older
+// version calls — and a rename that breaks an upgrade path is not a rename, it
+// is a removal.
+const ensureReviewGateHook = ensureHooks
+
+module.exports = {
+  ensureHooks,
+  ensureReviewGateHook,
+  alreadyRegistered,
+  registeredHooks,
+  hookEntry,
+  settingsPath,
+  HOOKS,
+  HOOK_STEM,
+  HOOK_SCRIPT,
+  HOOK_SCRIPT_RE,
+  HOOK_COMMAND,
+}

package/src/env/hotfix.js

@@ -0,0 +1,385 @@
+'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')
+const { afterLandFor } = require('./integrate.js')
+
+/**
+ * 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 release tag's parts: `<prefix><major>.<minor>.<patch>[-<suffix>]`. A
+// `hotfix.N` suffix is kept apart from every other one, because the two sort on
+// opposite sides of their base (see compareTags). Null for anything else.
+const TAG = /^(\D*)(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/
+function parseTag(tag) {
+  const m = TAG.exec(String(tag || '').trim())
+  if (!m) return null
+  const [, prefix, major, minor, patch, suffix = null] = m
+  const hotfix = suffix && /^hotfix\.(\d+)$/.exec(suffix)
+  return {
+    prefix,
+    core: [Number(major), Number(minor), Number(patch)],
+    root: `${prefix}${major}.${minor}.${patch}`,
+    hotfix: hotfix ? Number(hotfix[1]) : null,
+    suffix: hotfix ? null : suffix,
+  }
+}
+
+/**
+ * Order two release tags: X.Y.Z-rc.N < X.Y.Z < X.Y.Z-hotfix.N < X.Y.(Z+1).
+ *
+ * This is skittership's rule and git's `version:refname` with a hotfix suffix
+ * configured to sort after its base, so the two tools never disagree about
+ * which tag is newer. A hotfix is a later build OF X.Y.Z; every other suffix is
+ * a pre-release BEFORE it, as in semver. Hotfix numbers compare numerically
+ * (`-hotfix.10` after `-hotfix.9`); other suffixes compare as strings. An
+ * unparseable tag sorts first, so it can never be mistaken for the newest.
+ */
+function compareTags(a, b) {
+  const x = parseTag(a)
+  const y = parseTag(b)
+  if (!x || !y) return (x ? 1 : 0) - (y ? 1 : 0)
+  for (let i = 0; i < 3; i++) {
+    if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i]
+  }
+  // Rank within one core: pre-release (0) < the release itself (1) < hotfix (2).
+  const rank = (t) => (t.suffix ? 0 : t.hotfix === null ? 1 : 2)
+  if (rank(x) !== rank(y)) return rank(x) - rank(y)
+  if (x.hotfix !== null) return x.hotfix - y.hotfix
+  if (x.suffix) return x.suffix < y.suffix ? -1 : x.suffix > y.suffix ? 1 : 0
+  return 0
+}
+
+/**
+ * The next `<root>-hotfix.<N>` for a base tag: N is one above the highest
+ * `<root>-hotfix.*` among `existingTags`, else 1. The root is the base with any
+ * hotfix suffix stripped, so a hotfix on `v36.4.0-hotfix.2` continues that
+ * line. A later `X.Y.(Z+1)` is neither a collision nor counted — it is another
+ * release line entirely. Same rule as skittership's release-hotfix.
+ */
+function nextHotfixTag(baseTag, existingTags) {
+  const base = parseTag(baseTag)
+  if (!base) {
+    throw new Error(
+      `hotfix: cannot derive a hotfix tag from "${baseTag}" — need <prefix>MAJOR.MINOR.PATCH`,
+    )
+  }
+  if (base.suffix) {
+    throw new Error(
+      `hotfix: base tag "${baseTag}" is a pre-release — a hotfix needs a released version`,
+    )
+  }
+  let n = base.hotfix || 0
+  for (const t of existingTags || []) {
+    const p = parseTag(t)
+    if (p && p.root === base.root && p.hotfix !== null && p.hotfix > n) n = p.hotfix
+  }
+  return `${base.root}-hotfix.${n + 1}`
+}
+
+const BUMPS = ['patch', 'hotfix-suffix']
+
+// The tag `hotfix.bump` asks for. An unknown strategy throws rather than
+// falling back to `patch`: a typo there would otherwise cut the wrong release
+// line and say nothing.
+function nextTag(baseTag, existingTags, bump = 'patch') {
+  if (bump === 'patch') return bumpPatch(baseTag)
+  if (bump === 'hotfix-suffix') return nextHotfixTag(baseTag, existingTags)
+  throw new Error(`unknown hotfix.bump "${bump}" — use one of: ${BUMPS.join(', ')}`)
+}
+
+// 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[],
+ *                          released?, push?: boolean, pushed?: boolean, remote?,
+ *                          fixCommits?: string[],
+ *                          carry?: { strategy: 'inplace'|'worktree'|'dirty', path,
+ *                                    tmpPath?, commits: string[] } }
+ * @returns {object} { blocked, noop, reason, commands, afterLand, 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: [],
+    steps: [],
+    afterLand: afterLandFor(null),
+    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
+  // What a target cherry-picks: the fix commits by sha when the caller listed
+  // them (the version commit already left out), else the bare range. The
+  // range form is what this planner always emitted and what pure callers that
+  // list nothing still get.
+  const fixPick = Array.isArray(c.fixCommits) && c.fixCommits.length ? c.fixCommits : [fixRange]
+  const commands = []
+  const targets = []
+  // What the engine runs (hotfixland.js). `commands` stays beside it as the
+  // human-readable spelling of the same thing, for `--plan` and the tests.
+  const steps = []
+  const bump = hotfixCfg.bump || 'patch'
+  const releaseWith = String(hotfixCfg.releaseWith || '').trim()
+
+  // 1. Prod line: release the hotfix branch head (already baseRef + fix). No push.
+  //    Three ways, decided here so the runner never has to: a release already
+  //    cut on an earlier run and still at HEAD is reused, never re-cut; a
+  //    project's `releaseWith` command cuts it and says which tag it made; or
+  //    the built-in tagger tags HEAD with the `hotfix.bump` strategy's tag.
+  let prodTag = null
+  if (c.released && c.released.tag) {
+    prodTag = c.released.tag
+    taken.add(prodTag)
+    steps.push({ kind: 'release', via: 'recorded', tag: prodTag, release: c.released })
+  } else if (releaseWith) {
+    // The tag is the command's to choose and is unknown until it has run, so
+    // there is nothing to check a collision against here — the command refuses
+    // a tag that exists, and the runner refuses one a target also planned.
+    commands.push(`(cd ${spec.worktreePath} && ${releaseWith})`)
+    steps.push({ kind: 'release', via: 'command', command: releaseWith, cwd: spec.worktreePath })
+  } else {
+    prodTag = nextTag(baseRef, c.existingTags, bump)
+    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}`)
+    steps.push({
+      kind: 'release',
+      via: 'tag',
+      tag: prodTag,
+      cwd: spec.worktreePath,
+      baseTag: baseRef,
+      branch,
+    })
+  }
+  targets.push({ kind: 'prod', base: baseRef, tag: prodTag })
+
+  // 2. Publish the prod line: the branch first, then the tag, because the tag
+  //    push is what starts the deploy. BEFORE anything is carried to main, so a
+  //    declined or failed push never leaves main carrying a fix whose tag was
+  //    never published. Three cases: the tag is already on the remote (a
+  //    hand-run push, honoured on its positive signal); the operator consented
+  //    (`--push`); or neither, and the run holds here with the commands printed.
+  const remote = c.remote || 'origin'
+  if (c.pushed) {
+    steps.push({ kind: 'push', via: 'remote', remote, branch, cwd: spec.worktreePath })
+  } else if (c.push) {
+    steps.push({ kind: 'push', via: 'push', remote, branch, cwd: spec.worktreePath })
+  } else {
+    steps.push({ kind: 'push', via: 'hold', remote, branch, cwd: spec.worktreePath })
+  }
+
+  // 3. Extra targets: cherry-pick the fix onto a throwaway worktree at each tag,
+  //    re-tag with its own bump, then remove the worktree + temp branch (the
+  //    commits survive under the new tag, so `-D` is safe for the throwaway branch).
+  //    TAG-ONLY, deliberately: `releaseWith` is the prod line's. Running a
+  //    project's release per target would need a hotfix/ branch and a clean
+  //    tree for each one, and one failing half-way leaves a line half-released.
+  const wtRoot = path.dirname(spec.worktreePath)
+  for (const t of c.extraTargets || []) {
+    // Counted against `taken`, so two targets on one root get successive
+    // hotfix numbers rather than colliding on the same one.
+    const tag = nextTag(t, [...taken], bump)
+    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 ${fixPick.join(' ')}`,
+      `git -C ${tmpPath} tag ${tag}`,
+      `git worktree remove ${tmpPath}`,
+      `git branch -D ${tmpBranch}`,
+    )
+    const root = c.mainRepoPath
+    steps.push({
+      kind: 'target',
+      base: t,
+      tag,
+      worktreePath: tmpPath,
+      argvs: [
+        ['-C', root, 'worktree', 'add', tmpPath, '-b', tmpBranch, t],
+        ['-C', tmpPath, 'cherry-pick', ...fixPick],
+        ['-C', tmpPath, 'tag', tag],
+        ['-C', root, 'worktree', 'remove', tmpPath],
+        ['-C', root, 'branch', '-D', tmpBranch],
+      ],
+    })
+    targets.push({ kind: 'extra', base: t, tag, worktreePath: tmpPath })
+  }
+
+  // 4. Cherry-pick the fix onto the base branch (main) for the next release.
+  //    Only then does the primary checkout gain anything, so only then do the
+  //    after-land commands apply — a prod-only land leaves main untouched.
+  let afterLand = result.afterLand
+  if (hotfixCfg.cherryPickMain !== false) {
+    // THE CARRY IS A LIST OF COMMITS, NOT A RANGE. A releasing command leaves
+    // a version commit on the branch (package.json, CHANGELOG, RELEASES), and
+    // main's version line never moves on a hotfix — so the caller hands over
+    // `baseRef..branch` minus that commit and minus what `git cherry` says main
+    // already has. The spec's own completion commits stay in it: that is how
+    // the completed spec reaches main. Without a list (pure callers), the old
+    // range form, run in place.
+    const carry = c.carry || { strategy: 'inplace', path: c.mainRepoPath, commits: null }
+    const picks = carry.commits || [fixRange]
+    commands.push(
+      carry.strategy === 'worktree'
+        ? `git worktree add ${carry.tmpPath} ${c.base} && git -C ${carry.tmpPath} cherry-pick ${picks.join(' ')}`
+        : `git -C ${carry.path} cherry-pick ${picks.join(' ')}`,
+    )
+    steps.push({
+      kind: 'carry',
+      base: c.base,
+      strategy: carry.strategy,
+      cwd: carry.path || c.mainRepoPath,
+      root: c.mainRepoPath,
+      tmpPath: carry.tmpPath || null,
+      commits: picks,
+    })
+    targets.push({ kind: 'main', base: c.base })
+    afterLand = afterLandFor(config, c.mainRepoPath)
+  }
+
+  return { ...result, commands, steps, afterLand, prodTag, targets, fixRange }
+}
+
+/**
+ * Plan `spec-env hotfix finish`: the teardown a hotfix waits for until its
+ * deploy is out.
+ *
+ * A hotfix branch is needed until the release it cut is confirmed — a failed
+ * deploy cuts the next `-hotfix.N` from the same branch — so `/spec-complete`
+ * lands and keeps the worktree, and this is the later step that removes it.
+ *
+ * THREE GUARDS, every one a positive signal, and every failing one named:
+ *   - a clean tree — anything uncommitted would go with the worktree;
+ *   - a release tag at HEAD — the land actually released what is here;
+ *   - the branch on the remote at HEAD — a copy exists after `branch -D`.
+ *     A remote that cannot be asked is "cannot tell", which refuses: deleting
+ *     the only copy of a deployed fix is not the safe way to be wrong.
+ *
+ * DELIBERATELY NO "MERGED INTO MAIN" GUARD: the version commit never reaches
+ * main, so the branch is never an ancestor of it and `-d` would always refuse.
+ * And DELIBERATELY NO `--force` — the guards are the point of the verb, and
+ * `spec-env down --force` already exists for anyone who means to override them.
+ *
+ * state: { dirty, tagsAtHead: string[], head, remoteHead: string|null|undefined,
+ *          remote, mainRepoPath, hasSlot }
+ *   remoteHead: the branch's sha on the remote; null = not there;
+ *               undefined = the remote could not be asked.
+ */
+function planHotfixFinish(spec, state) {
+  const s = state || {}
+  const remote = s.remote || 'origin'
+  const reasons = []
+  if (s.dirty) reasons.push('the worktree has uncommitted changes')
+  const releaseTag = (s.tagsAtHead || []).find((t) => parseTag(t) !== null) || null
+  if (!releaseTag) {
+    reasons.push('no release tag at HEAD — run `spec-env hotfix land` first')
+  }
+  if (s.remoteHead === undefined) {
+    reasons.push(`cannot tell whether ${spec.branch} is on ${remote} — the remote did not answer`)
+  } else if (s.remoteHead === null) {
+    reasons.push(`${spec.branch} is not on ${remote} — push it (\`hotfix land --push\`)`)
+  } else if (s.head && s.remoteHead !== s.head) {
+    reasons.push(`${remote}/${spec.branch} is not at HEAD — push the branch first`)
+  }
+  // A Docker stack has volumes and a slot that only `down` knows how to free.
+  if (s.hasSlot) {
+    reasons.push(`${spec.folder} holds a Docker stack — tear it down with \`spec-env down\``)
+  }
+  if (reasons.length) return { blocked: true, reasons, releaseTag, argvs: [] }
+  const root = s.mainRepoPath
+  return {
+    blocked: false,
+    reasons: [],
+    releaseTag,
+    argvs: [
+      ['-C', root, 'worktree', 'remove', spec.worktreePath],
+      // -D, not -d: the branch is never merged into main (see above), and its
+      // commits are on the remote and under the release tag.
+      ['-C', root, 'branch', '-D', spec.branch],
+    ],
+  }
+}
+
+module.exports = {
+  bumpPatch,
+  compareTags,
+  nextHotfixTag,
+  nextTag,
+  BUMPS,
+  tagSlug,
+  planHotfixLand,
+  planHotfixFinish,
+}