@skitterbyte/skitterspec 12.0.0 → 14.0.0

package/assets/skills/spec-to-main/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: spec-to-main
+description: Land an in-progress spec's branch onto main WITHOUT finishing it — rebase + fast-forward so the work reaches main (to run it in CI / a shared test env), while the worktree stays and the spec stays In Progress. Repeatable — land again as you commit more. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-to-main", "land this on main but keep going", "I need this on main to run tests before finishing", or "merge to main without completing the spec".
+---
+
+# /spec-to-main — land the branch on main, keep the spec open
+
+The **intermediate** landing. `/spec-complete` also lands the branch, but then
+verifies every phase, flips the status to Complete, `git mv`s the spec to
+`complete/`, and tears the environment down. **`/spec-to-main` stops after the
+land**: the worktree stays, the spec stays `In Progress`, and you can land again
+as you add commits.
+
+Use it when a later phase can only be done *after* the current work is on `main` —
+e.g. it needs to run in CI, a deploy pipeline, or a shared test environment that
+builds from `main`. Land what you have, run that step, then come back and finish
+the remaining phases with `/spec-go` and eventually `/spec-complete`.
+
+It reuses the **same engine** as `/spec-complete`'s landing (`spec-env integrate`
+— rebase + fast-forward), so it produces identical linear history. Because a
+fast-forward leaves `base == branch`, the operation is **idempotent and
+repeatable**: new commits put the branch ahead of base again, and you can run
+`/spec-to-main` as many times as you like.
+
+## 0. Preconditions — when this applies
+
+- **Isolation must be on** (`specs/.core/env.config.json` exists **and** the spec
+  is on a worktree provisioned by `/spec-go`). If isolation is absent, there is
+  nothing to land — the spec is authored directly on `main` already. Say so and
+  stop.
+- **Feature / Bug specs only.** A **Hotfix** (`Type: Hotfix`) is built on a
+  release *tag* and cannot fast-forward onto `main` — refuse it and point the user
+  at `/spec-complete` (it lands a hotfix via tag + cherry-pick). Check the header
+  `> **Type:**` before proceeding.
+
+## 1. Identify the target spec
+
+- Use the name/path argument if given, else the spec **in context**. If unclear,
+  ask which spec.
+- Locate its folder under `specs/in-progress/`. Entry point is `00-overview.md`;
+  confirm `> **Status:**` is `In Progress` and `> **Type:**` is `Feature` or
+  `Bug`.
+
+## 2. Require a clean worktree
+
+The land rebases the branch — it refuses a dirty tree. If the worktree has
+uncommitted changes, offer `/commit` and **stop**; don't auto-commit.
+
+**If the spec is live** (you took the running instance with `/spec-live`):
+`integrate` is live-aware — it ends the live session first (releases the branch
+back to base, re-isolates it into its worktree, clears the receipt), then prints
+the landing plan. Commit any live fixes to the branch first; it refuses if the
+primary checkout is dirty, or if a *different* spec holds it (release that one with
+`/spec-live main`).
+
+## 3. Tests must be green before landing
+
+Don't push red to `main`. Run the project's typecheck and test commands **in the
+worktree**; the suite must be **green**. For a **Bug** spec, confirm the
+originally-failing test now passes. If anything is red, stop and report — landing
+broken code onto `main` defeats the purpose.
+
+(Note this is the *worktree* suite. The whole point of this skill is often to run
+a *further* check that only exists on `main` / in CI — that one runs **after** the
+land, in step 5.)
+
+## 4. Land — rebase + fast-forward
+
+Run `skitterspec spec-env integrate <name>` and run the printed commands **in
+order**:
+
+- `git -C <worktree> rebase <base>` — replay the branch onto base.
+- `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
+
+On a **rebase conflict** (non-zero exit), run `git -C <worktree> rebase --abort`,
+relay the conflict, and **stop** — leave the resolution to the user; change
+nothing else.
+
+On a **no-op** ("already landed on `<base>` — nothing to integrate"), just say so
+and continue — the branch has no commits base doesn't already have.
+
+## 5. Re-test on base, then report
+
+- Run the project's test command **from the primary checkout** — base must be
+  **green** after the fast-forward.
+- Add a **Changelog** entry to `00-overview.md` recording the intermediate land
+  and *why*, e.g.
+  `- <YYYY-MM-DD> — Landed intermediate work onto <base> to <run CI / deploy to
+  test env / …>; spec stays In Progress.`
+- Do **NOT**: add a State-log row (status doesn't change), flip any phase/status
+  to Complete, `git mv` the spec, or tear down the worktree/stack. **The spec
+  stays `In Progress` and the worktree stays put.**
+- Report: the base branch, the fast-forward result, and the green base test. It
+  **never pushes** — mention the user can `git push` the base branch themselves to
+  trigger CI / the shared env.
+- Point the way forward: `/spec-go` to continue the remaining phases (you'll keep
+  committing on the same branch and can `/spec-to-main` again), and `/spec-complete`
+  when every phase is genuinely done — it will land the final commits, finalise,
+  and tear down.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "12.0.0",
+  "version": "14.0.0",
   "description": "Spec-driven development for Claude Code — a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",

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
@@ -181,6 +185,19 @@ function specEnvUp(dir, config, specArg) {
   }
   const spec = resolveSpec(specArg, dir, config)
 
+  // Live-safe: if this spec is already live on the primary checkout (its branch was
+  // branch-switched in by `live take`), a `git worktree add` would fail — the branch
+  // is checked out there. Point the operator at the primary checkout rather than
+  // emit a plan that can't run (see spec feat-live-spec-flow).
+  const primaryUp = assertPrimaryOnMain(config, gitReader(dir))
+  if (!primaryUp.onBase && primaryUp.branch === spec.branch) {
+    process.stdout.write(
+      `spec-env up: ${spec.folder} is live in the primary checkout — work there directly ` +
+        '(its branch is checked out), or run `/spec-live main` first to re-isolate its worktree.\n',
+    )
+    return
+  }
+
   // Trust the shared worktree root so edits into the freshly-provisioned worktree
   // don't prompt. One absolute entry (the root) covers every spec; self-heals on
   // every provision for teammates who only cloned and ran /spec-go.
@@ -271,7 +288,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 +312,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 +383,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).
@@ -395,6 +580,33 @@ function specEnvIntegrate(dir, config, specArg) {
       )
       return
     }
+    // Work-loss guard — runs BEFORE the destructive `checkout base` that ends the
+    // live session. Ending the session must leave landable work behind; if it
+    // wouldn't, abort loudly instead of silently finalizing the spec with nothing
+    // landed (see spec feat-live-spec-flow).
+    if (!fs.existsSync(spec.worktreePath)) {
+      process.stdout.write(
+        `spec-env integrate: blocked — ${spec.folder} is live but has no worktree to land ` +
+          `from. Re-isolate it with \`skitterspec spec-env up ${spec.folder}\`, then re-run.\n`,
+      )
+      return
+    }
+    const liveWtGit = gitReader(spec.worktreePath)
+    if (liveWtGit(['symbolic-ref', '--short', 'HEAD']) === null) {
+      // Detached worktree HEAD: any commits ahead of the branch ref (e.g. made by a
+      // non-live-aware /spec-go) would be abandoned by the re-isolate `switch` below.
+      const stranded = liveWtGit(['rev-list', '--count', `${spec.branch}..HEAD`])
+      const head = liveWtGit(['rev-parse', '--short', 'HEAD'])
+      if (stranded !== null && Number(stranded) > 0) {
+        process.stdout.write(
+          `spec-env integrate: blocked — ${stranded} commit(s) are stranded on the detached ` +
+            `HEAD of ${spec.worktreePath} (at ${head}), ahead of ${spec.branch}; re-isolating ` +
+            `would abandon them. Recover with \`git -C ${spec.worktreePath} branch <tmp> ${head}\`, ` +
+            `reconcile onto ${spec.branch}, then re-run.\n`,
+        )
+        return
+      }
+    }
     const co = runGit(dir, ['checkout', base])
     if (!co.ok) {
       process.stdout.write(`spec-env integrate: could not check out ${base} — ${co.err}\n`)
@@ -450,6 +662,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) {
@@ -653,7 +952,7 @@ async function specEnvLive(dir, config, positional) {
   const action = positional[0] || 'status'
   switch (action) {
     case 'status':
-      specEnvLiveStatus(dir, config)
+      specEnvLiveStatus(dir, config, positional[1])
       break
     case 'take':
       await specEnvLiveTake(dir, config, positional[1])
@@ -887,8 +1186,28 @@ async function specEnvLiveAbort(dir, config) {
   )
 }
 
-function specEnvLiveStatus(dir, config) {
+function specEnvLiveStatus(dir, config, specArg) {
   const { onBase, branch, baseBranch } = assertPrimaryOnMain(config, gitReader(dir))
+
+  // Per-spec query (`live status <spec>`): a clear yes/no verdict the /spec-go
+  // skill branches on to decide whether to skip worktree provisioning and work in
+  // the primary checkout. The stable `live:      yes|no` line is the machine seam.
+  if (specArg) {
+    const spec = resolveSpecWithWorktree(dir, config, specArg)
+    const live = !onBase && branch === spec.branch
+    process.stdout.write(
+      `spec-env live status: ${spec.folder}\n` +
+        `  spec:      ${spec.folder}  (branch ${spec.branch})\n` +
+        `  primary:   ${branch || '(detached)'}\n` +
+        `  live:      ${
+          live
+            ? `yes — ${spec.folder} holds the primary checkout; work there`
+            : `no — primary is on ${branch || '(detached)'}`
+        }\n`,
+    )
+    return
+  }
+
   const receipt = readReceipt(dir, config)
   const state = onBase
     ? 'on base — free'
@@ -904,11 +1223,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 +1253,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 +1265,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 +1279,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
 }