@skitterbyte/skitterspec 16.10.0 → 18.0.0

package/src/env/classify.js

@@ -0,0 +1,91 @@
+'use strict'
+
+/**
+ * Which uncommitted paths belong to ONE spec?
+ *
+ * `/spec-start` refuses a dirty tree because moving another spec's unfinished
+ * work is not ours to do. But the commonest dirty tree there is — the spec you
+ * just authored and are now starting — is not another spec's work at all, and
+ * refusing it costs a round trip through `/commit` on every single start.
+ *
+ * The distinction this module draws is deliberately NOT "does the dirt look
+ * important?" (a judgement, and the gate rightly refuses to make one) but
+ * membership in an exactly-known set: the spec's own folder, plus whatever the
+ * project declares in `spec.companionPaths`. Everything else is foreign, and one
+ * foreign path disqualifies the whole tree.
+ */
+
+const path = require('node:path')
+const { BUCKETS, expandTokens, readFrontmatterField } = require('./resolve.js')
+
+// git reports repo-relative, forward-slashed paths; an untracked directory comes
+// back with a trailing slash. Normalise both away so comparisons are exact.
+function normalize(p) {
+  return String(p || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+}
+
+/**
+ * Expand a `companionPaths` pattern for this spec, or return null when it cannot
+ * be expanded.
+ *
+ * A PATTERN THAT REFERENCES `{identifier}` WHEN NO IDENTIFIER RESOLVES MATCHES
+ * NOTHING, deliberately. Two ordinary situations produce a spec with no id — a
+ * project that never set `branch.identifierField`, and a spec deliberately kept
+ * local, never pushed to a tracker — and in both the file the pattern describes
+ * either does not exist or belongs to some OTHER spec. Expanding `{identifier}`
+ * to a placeholder, or dropping the token, would widen the owned set to a path
+ * this spec has no claim on and sweep another spec's snapshot into its commit.
+ * Being wrong this way costs a refusal the operator can fix with `/commit`; the
+ * other way costs them a file they never staged.
+ */
+function expandCompanion(pattern, spec, config) {
+  const tokens = { slug: spec.slug }
+  if (/\{identifier\}/.test(pattern)) {
+    const field = config && config.branch && config.branch.identifierField
+    const identifier = readFrontmatterField(spec.path, field)
+    if (!identifier) return null
+    tokens.identifier = identifier
+  }
+  return normalize(expandTokens(pattern, tokens))
+}
+
+/**
+ * Split `dirtyPaths` into the ones that belong to `spec` and the ones that do
+ * not. Repo-relative paths in, repo-relative paths out; nothing is read from git
+ * and nothing is written.
+ *
+ * Owned:
+ *   - anything inside `specs/<bucket>/<folder>/` for ANY bucket. Every bucket is
+ *     checked rather than the spec's current one because starting a spec MOVES it
+ *     (backlog → in-progress), so a tree mid-move is dirty in two buckets at once
+ *     and both halves are the same spec's.
+ *   - each expandable `spec.companionPaths` entry.
+ *
+ * @returns {{owned: string[], foreign: string[]}}
+ */
+function classifyDirtyTree(spec, dirtyPaths, config) {
+  const owned = []
+  const foreign = []
+  if (!spec) return { owned, foreign: (dirtyPaths || []).map(normalize).filter(Boolean) }
+
+  const folders = BUCKETS.map((bucket) => `specs/${bucket}/${spec.folder}`)
+  const companions = new Set()
+  for (const pattern of (config && config.spec && config.spec.companionPaths) || []) {
+    const expanded = expandCompanion(pattern, spec, config)
+    if (expanded) companions.add(expanded)
+  }
+
+  for (const raw of dirtyPaths || []) {
+    const p = normalize(raw)
+    if (!p) continue
+    const inFolder = folders.some((f) => p === f || p.startsWith(`${f}/`))
+    if (inFolder || companions.has(p)) owned.push(p)
+    else foreign.push(p)
+  }
+  return { owned, foreign }
+}
+
+module.exports = { classifyDirtyTree, expandCompanion }

package/src/env/config.js

@@ -13,6 +13,9 @@
  *
  * Shape (see specs/.core/env.config.md for field docs):
  *   {
+ *     mode:     "worktree" | "checkout",  // where a spec's branch is built —
+ *               // its own worktree (default), or the primary checkout in place.
+ *               // NOTE: unrelated to `seedFiles.mode`, which is symlink|copy.
  *     worktree: { root, folderPattern },
  *     docker:   { enabled, composeFile, projectNamePattern, portBase,
  *                 portsPerSpec, envFile, backupCommand },
@@ -27,6 +30,9 @@
  *     open:     { command },   // optional, editor/terminal-agnostic opener
  *     registry: ".spec-env/registry.json",
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
+ *     spec:     { companionPaths: [ "path", ... ] },  // paths that belong to a
+ *               // spec alongside its own folder (provider-neutral; {slug} and
+ *               // {identifier} expand); empty = the spec folder only
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
  *     teardown: { deleteRemoteBranch },
@@ -44,6 +50,16 @@ const { join } = require('node:path')
 const CONFIG_FILE = join('specs', '.core', 'env.config.json')
 
 const DEFAULT_CONFIG = Object.freeze({
+  // Where a spec's branch is built. "worktree" gives every spec its own checkout
+  // — parallel specs, `main` left free — at the cost of a terminal session per
+  // spec. "checkout" builds the branch in the primary checkout instead: one spec
+  // at a time, in the terminal you are already sitting in.
+  //
+  // Defaults to "worktree" so no installed repo changes behaviour on upgrade.
+  // Never inferred from whether `dev`/`docker` are configured: a repo with no
+  // dev servers may still want parallel specs, and absence of configuration is
+  // not evidence of intent (see .claude/rules/negative-checks.md).
+  mode: 'worktree',
   worktree: Object.freeze({ root: '../{repo}-wt', folderPattern: '{slug}' }),
   docker: Object.freeze({
     enabled: true,
@@ -77,11 +93,18 @@ const DEFAULT_CONFIG = Object.freeze({
   // 00-overview.md frontmatter field a provider writes the ticket id into (empty
   // = no identifier, so patterns referencing {identifier} fall back to type/slug).
   branch: Object.freeze({ pattern: '{type}/{slug}', identifierField: '' }),
+  // Paths that belong to a spec ALONGSIDE its own `specs/<bucket>/<name>/` folder
+  // — a tracker provider's per-spec snapshot, for instance. Provider-neutral by
+  // design: the base engine must not know that any particular tracker exists, so
+  // the project declares the shape and `{slug}` / `{identifier}` expand exactly as
+  // they do in `branch.pattern` ({identifier} via `branch.identifierField`).
+  // Default: none, so a spec owns only its own folder.
+  spec: Object.freeze({ companionPaths: Object.freeze([]) }),
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
   // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
-  // `spec-env down` does about the branch `/spec-go` pushed: "prompt" (default)
+  // `spec-env down` does about the branch `/spec-start` pushed: "prompt" (default)
   // plans the delete in its own confirm-first section for the skill to ask about,
   // "never" omits it, "always" folds it into the run-blind command list. Only ever
   // planned for a LANDED branch — see teardown.js.
@@ -105,6 +128,7 @@ function isObject(value) {
 // A fresh, deeply-mutable copy of the defaults to merge onto.
 function defaults() {
   return {
+    mode: DEFAULT_CONFIG.mode,
     worktree: { ...DEFAULT_CONFIG.worktree },
     docker: { ...DEFAULT_CONFIG.docker },
     seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
@@ -114,6 +138,7 @@ function defaults() {
     open: { ...DEFAULT_CONFIG.open },
     registry: DEFAULT_CONFIG.registry,
     branch: { ...DEFAULT_CONFIG.branch },
+    spec: { companionPaths: [] },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
     teardown: { ...DEFAULT_CONFIG.teardown },
@@ -257,6 +282,15 @@ function mergeConfig(base, parsed) {
   assign(base, parsed, 'registry', 'string')
   assign(base, parsed, 'baseBranch', 'string')
 
+  // Same treatment as `teardown.deleteRemoteBranch` below, for the same reason:
+  // an unrecognised value falls through to the default rather than erroring or
+  // being taken literally. The fallback direction matters — "worktree" is the
+  // conservative one, so a typo ("Checkout", "in-place") costs an extra terminal
+  // session, never a spec's work landing somewhere the author did not choose.
+  if (parsed.mode === 'worktree' || parsed.mode === 'checkout') {
+    base.mode = parsed.mode
+  }
+
   if (isObject(parsed.guards)) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')
     assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
@@ -273,6 +307,10 @@ function mergeConfig(base, parsed) {
     }
   }
 
+  if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {
+    base.spec.companionPaths = normalizeFileList(parsed.spec.companionPaths)
+  }
+
   if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
     base.live.migrations = normalizeFileList(parsed.live.migrations)
   }

package/src/env/integrate.js

@@ -16,6 +16,11 @@
  *
  * @param {object} spec  resolved spec: { branch, worktreePath, folder, ... }
  * @param {object} config normalised env config (unused today; kept for symmetry).
+ * In CHECKOUT mode there is no worktree: the branch is already checked out in the
+ * primary checkout, so landing is a rebase in place, a switch to base, and the
+ * fast-forward. `planIntegrateCheckout` below covers that; the shape of what it
+ * returns is identical so callers need no second code path.
+ *
  * @param {object} ctx   { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath }
  * @returns {object} { blocked, noop, reason, commands, base, branch }
  */
@@ -43,4 +48,59 @@ function planIntegrate(spec, config, ctx) {
   }
 }
 
-module.exports = { planIntegrate }
+/**
+ * Pure integrate planner for CHECKOUT mode.
+ *
+ * The branch lives in the primary checkout, so `git -C <worktree> rebase` — the
+ * worktree-mode plan — has nothing to address. Landing is three steps in one
+ * repo: rebase onto base, switch to base, fast-forward.
+ *
+ * The switch is what makes this safe to repeat. Leaving the checkout on the spec
+ * branch after landing would mean the next `spec-env up` refuses ("standing on
+ * another spec's branch") for a spec that is finished, and the operator would
+ * have to know to switch back by hand.
+ *
+ * ctx: { dirty, base, aheadOfBase, checkoutPath, onBranch }
+ */
+function planIntegrateCheckout(spec, config, ctx) {
+  const { dirty, base, aheadOfBase, checkoutPath, onBranch } = ctx || {}
+  const branch = spec.branch
+  const result = { blocked: false, noop: false, reason: null, commands: [], base, branch }
+
+  // "Already landed" is answered FIRST, before any refusal. A landed spec needs
+  // no action wherever the checkout happens to be standing — and after a
+  // successful land it is standing on base, so asking "not on the branch" here
+  // would refuse the very spec this just finished landing. /spec-complete calls
+  // integrate again on exactly that state.
+  if (!aheadOfBase) {
+    return { ...result, noop: true }
+  }
+  if (dirty) {
+    return {
+      ...result,
+      blocked: true,
+      reason: 'the checkout has uncommitted changes — commit the completion first',
+    }
+  }
+  // There IS something to land, so where you are standing now matters: the
+  // branch is the checkout in this mode, and landing from elsewhere would
+  // rebase and fast-forward a branch the operator is not looking at.
+  if (onBranch === false) {
+    return {
+      ...result,
+      blocked: true,
+      reason: `the checkout is not on ${branch} — switch to it before landing`,
+    }
+  }
+
+  return {
+    ...result,
+    commands: [
+      `git -C ${checkoutPath} rebase ${base}`,
+      `git -C ${checkoutPath} switch ${base}`,
+      `git -C ${checkoutPath} merge --ff-only ${branch}`,
+    ],
+  }
+}
+
+module.exports = { planIntegrate, planIntegrateCheckout }

package/src/env/live.js

@@ -134,7 +134,11 @@ function migrationsHit(files, patterns) {
  * ctx:
  *   primary        { onBase, branch, baseBranch } — the guard result for the primary checkout
  *   primaryPath    absolute path of the primary checkout (the checkout target)
+ *   inFlight       string|null — folder of the spec holding the primary, from
+ *                  its receipt; null when nothing is recorded (a hand-switched
+ *                  branch), which degrades the message to the branch name
  *   clean          boolean — primary checkout working tree is clean
+ *   worktreeClean  boolean — the SPEC WORKTREE's tree is clean (the rebase runs there)
  *   worktreeExists boolean — the spec's worktree is on disk
  *   base           resolved base branch name (rebase target)
  *   baseMainCommit primary HEAD before the switch (receipt / crash recovery)
@@ -166,9 +170,16 @@ function planTake(spec, config, ctx) {
   //    (or you) already holds the live instance.
   if (!c.primary || !c.primary.onBase) {
     const on = c.primary && c.primary.branch ? c.primary.branch : '(detached)'
+    // Name the SPEC, not just the branch, and name every way out. `/spec-start`
+    // relays this refusal verbatim as its gate, so whatever is missing here is
+    // missing from the operator's only explanation of why they are stuck —
+    // "release it with /spec-live main" alone reads as the sole option when
+    // completing or cancelling the held spec are usually the ones they want.
+    const held = c.inFlight ? `${c.inFlight} (branch ${on})` : on
     return block(
-      `primary checkout is on ${on}, not ${base} — a spec already holds the live ` +
-        'instance; release it with `/spec-live main` first',
+      `primary checkout is on ${on}, not ${base} — ${held} already holds it. ` +
+        'Free the workbench first: `/spec-complete` if it is finished, ' +
+        '`/spec-cancel` if it is not wanted, or `/spec-live main` to park it',
     )
   }
   // 2. Never switch a dirty tree — the checkout is reset back to base on release.
@@ -177,7 +188,20 @@ function planTake(spec, config, ctx) {
   }
   // 3. Need a worktree holding the branch to detach and hand over.
   if (!c.worktreeExists) {
-    return block(`${spec.folder} has no worktree — run \`/spec-go ${spec.folder}\` first`)
+    return block(`${spec.folder} has no worktree — run \`/spec-start ${spec.folder}\` first`)
+  }
+  // 3b. The WORKTREE's own tree, not the primary checkout's. Check 2 above reads
+  //     the checkout we switch INTO; the rebase runs in the worktree, and git
+  //     refuses to rebase over uncommitted changes. Checking only the primary
+  //     let a dirty worktree through to fail at the rebase, where the failure
+  //     was then reported as a merge conflict — a wrong cause for a real
+  //     problem, which is worse than no message. Validate the tree the
+  //     operation actually touches.
+  if (c.worktreeClean === false) {
+    return block(
+      `${spec.folder}'s worktree has uncommitted changes — commit or stash them in ` +
+        `${spec.worktreePath} first (the rebase cannot run over them)`,
+    )
   }
   // 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.

package/src/env/provision.js

@@ -11,6 +11,7 @@
  * no live git/docker.
  */
 
+const { classifyDirtyTree } = require('./classify.js')
 const { portOffset } = require('./registry.js')
 const { renderEnvFile, expandOpenCommand } = require('./render.js')
 const { expandTokens } = require('./resolve.js')
@@ -71,6 +72,126 @@ function seedCommandFor(file, mode) {
   )
 }
 
+
+// Cap a path list in a message: enough to recognise, not a wall of text.
+function listPaths(paths) {
+  const shown = paths.slice(0, 5).join(', ')
+  return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown
+}
+
+/**
+ * Decide what an uncommitted tree means for a provisioning run: commit it, refuse
+ * it, or ignore it.
+ *
+ * `/spec-start` refuses a dirty tree so another spec's unfinished work is never
+ * moved without its author asking. But the commonest dirty tree of all is the
+ * spec you just wrote and are now starting, and refusing THAT costs a round trip
+ * through `/commit` on every start. So the question asked here is not "does this
+ * dirt look important?" — a judgement the gate rightly declines to make — but
+ * membership in an exactly-known set (see `classify.js`). One foreign path
+ * disqualifies the whole tree.
+ *
+ * WHAT WOULD FOOL THIS: `ctx.dirtyPaths` being absent. That is not "the tree is
+ * clean" — it is "nobody looked", which happens on every legacy caller and
+ * whenever git itself could not be read. Either way it is never permission to
+ * commit: with no classification there is no owned set, so no commit is planned.
+ *
+ * Whether it also REFUSES depends on `carriesChanges`, and the asymmetry is the
+ * two modes' actual risk, not an inconsistency:
+ *
+ *   - checkout mode (`carriesChanges`) — `git switch -c` silently carries
+ *     uncommitted work onto the new branch. Unable to see the tree means unable
+ *     to rule that out, so it refuses, exactly as it did before this gate existed.
+ *   - worktree mode — `git worktree add` carries nothing, and forks from a commit
+ *     regardless. Refusing here would fire on a healthy repo whose git we merely
+ *     could not read, which is a cost paid by someone who did nothing wrong. So
+ *     it plans no commit and provisions as before.
+ *
+ * `specOnFork` is the other half, and a POSITIVE signal rather than an absence:
+ * the worktree forks from a specific commit, so a spec absent from it produces a
+ * branch missing the very spec it is for. A clean tree cannot detect that — the
+ * spec may be committed, just somewhere else. `null` means the caller could not
+ * tell (an unreadable git, or a hotfix, which forks from a tag predating its own
+ * spec), and routes to carrying on, never to refusing.
+ *
+ * ctx: { dirtyPaths?, clean?, specOnFork?, specFoundOn?, forkRef?, specUntracked? }
+ * @returns {{blocked: boolean, reason: string|null, commands: string[]}}
+ */
+function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
+  const ok = { blocked: false, reason: null, commands: [], owned: [], verb: null }
+  const c = ctx || {}
+
+  if (!Array.isArray(c.dirtyPaths)) {
+    // Nobody looked: never commit, and refuse only where switching could carry
+    // work we cannot see (see the asymmetry above).
+    if (carriesChanges && c.clean === false) {
+      return {
+        blocked: true,
+        reason:
+          'the primary checkout has uncommitted changes — commit or stash them first' +
+          (carriesChanges ? ' (switching would carry them onto the new branch)' : ''),
+        commands: [],
+        owned: [],
+        verb: null,
+      }
+    }
+    return ok
+  }
+
+  const { owned, foreign } = classifyDirtyTree(spec, c.dirtyPaths, config)
+
+  if (foreign.length) {
+    return {
+      blocked: true,
+      reason:
+        `the primary checkout has uncommitted changes that are not ${spec.folder}'s — ` +
+        'commit or stash them first' +
+        (carriesChanges ? ' (switching would carry them onto the new branch)' : '') +
+        `: ${listPaths(foreign)}`,
+      commands: [],
+    }
+  }
+
+  if (owned.length) {
+    // `add` or `update`? Asked of git (`ctx.specUntracked`, from `git ls-files`)
+    // rather than inferred from the shape of the status output. The inference —
+    // "a bare directory entry means the folder is wholly untracked" — was wrong in
+    // the ordinary case of the FIRST spec in a bucket, where git reports the
+    // bucket as the untracked directory instead. The old inference stays as a
+    // fallback for callers that pass no fact; unknown yields `update`, which is
+    // never a false claim.
+    const isNew =
+      typeof c.specUntracked === 'boolean'
+        ? c.specUntracked
+        : owned.includes(`specs/${spec.bucket}/${spec.folder}`)
+    const verb = isNew ? 'add' : 'update'
+    return {
+      blocked: false,
+      reason: null,
+      owned,
+      verb,
+      commands: [
+        `git add ${owned.map((p) => `"${p}"`).join(' ')}`,
+        `git commit -m "chore(spec): ${verb} ${spec.folder}"`,
+      ],
+    }
+  }
+
+  // Tree is clean. The spec must already be in the base branch's tree, or the
+  // worktree forks without it.
+  if (c.specOnFork === false) {
+    return {
+      blocked: true,
+      reason:
+        `${spec.folder} is not committed in ${c.forkRef || 'the fork point'}` +
+        (c.specFoundOn ? ` — it is on ${c.specFoundOn}` : '') +
+        ' — the worktree would fork without the spec it is for',
+      commands: [],
+    }
+  }
+  return ok
+}
+
 /**
  * Plan a provisioning run.
  *
@@ -83,7 +204,7 @@ function seedCommandFor(file, mode) {
  *                     envContents, openCommand, commands, seedCommands,
  *                     setupCommands, attached }
  */
-function planUp(spec, alloc, config) {
+function planUp(spec, alloc, config, ctx) {
   const { slot, attached } = alloc
 
   // Per-spec escalation: bring Docker up only when this spec's Stack is `docker`,
@@ -143,7 +264,18 @@ function planUp(spec, alloc, config) {
     commands.push(`docker compose --project-name ${spec.projectName} up -d`)
   }
 
+  // The tree gate. A worktree forks from the base branch's tree, so an
+  // uncommitted spec would produce a branch missing the spec it is for — this is
+  // where that gets committed, or refused. Worktree mode had NO clean gate before
+  // this: `git worktree add` does not carry uncommitted changes anywhere, so the
+  // failure surfaced three steps later as a live-overlay refusal naming the wrong
+  // stage. An absent `ctx` means no caller looked, and changes nothing.
+  const gate = planSpecCommit(spec, ctx, config)
+
   return {
+    blocked: gate.blocked,
+    reason: gate.reason,
+    specCommit: gate.owned && gate.owned.length ? { paths: gate.owned, verb: gate.verb } : null,
     worktreePath: spec.worktreePath,
     branch: spec.branch,
     projectName: spec.projectName,
@@ -151,11 +283,70 @@ function planUp(spec, alloc, config) {
     portOffset: offset,
     envContents,
     openCommand,
-    commands,
-    seedCommands,
-    setupCommands,
+    commands: gate.blocked ? [] : [...gate.commands, ...commands],
+    seedCommands: gate.blocked ? [] : seedCommands,
+    setupCommands: gate.blocked ? [] : setupCommands,
     attached,
   }
 }
 
-module.exports = { planUp, seedCommandFor, worktreeCd }
+/**
+ * Plan `spec-env up` in CHECKOUT mode — the branch is built in the primary
+ * checkout and there is no worktree at all.
+ *
+ * Pure: every git fact it needs arrives in `ctx`, and it writes nothing.
+ *
+ * ctx: { current, base, onBase, clean, branchExists }
+ *
+ * What it refuses, and why each is a refusal rather than a warning:
+ *  - a dirty tree, because `git switch -c` CARRIES uncommitted changes onto the
+ *    new branch. That is silent and it is the operator's work, so it is theirs
+ *    to place, not ours.
+ *  - standing on another branch, because switching away from it is a decision
+ *    about someone else's unfinished spec. Being on THIS spec's branch is not a
+ *    refusal — it is the re-run, and the answer is "already attached".
+ *
+ * There is no bootstrap and no opener: the primary checkout already has its
+ * dependencies, and no new session is being opened.
+ */
+function planCheckoutUp(spec, ctx, config) {
+  const base = ctx.base || (config && config.baseBranch) || 'main'
+  const result = {
+    mode: 'checkout',
+    blocked: false,
+    reason: null,
+    attached: false,
+    branch: spec.branch,
+    checkoutPath: ctx.checkoutPath || null,
+    commands: [],
+  }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  // Order matters: report "already attached" before anything else, so a re-run
+  // on the spec's own branch is never refused for a dirty tree it legitimately
+  // has — you are mid-phase, with the phase's own edits in progress.
+  if (ctx.current && ctx.current === spec.branch) {
+    return { ...result, attached: true }
+  }
+  // Same gate as worktree mode, but `git switch -c` genuinely CARRIES uncommitted
+  // work onto the new branch, so the refusal keeps saying so.
+  const gate = planSpecCommit(spec, ctx, config, { carriesChanges: true })
+  if (gate.blocked) return block(gate.reason)
+  if (!ctx.onBase) {
+    return block(
+      `the primary checkout is on ${ctx.current || '(detached)'}, not ${base} — ` +
+        'finish or park that branch first; checkout mode holds one spec at a time',
+    )
+  }
+
+  if (gate.owned && gate.owned.length) {
+    result.specCommit = { paths: gate.owned, verb: gate.verb }
+  }
+  result.commands.push(...gate.commands)
+  result.commands.push(
+    ctx.branchExists ? `git switch ${spec.branch}` : `git switch -c ${spec.branch}`,
+  )
+  return result
+}
+
+module.exports = { planUp, planCheckoutUp, planSpecCommit, seedCommandFor, worktreeCd }

package/src/env/resolve.js

@@ -267,6 +267,7 @@ module.exports = {
   repoInfo,
   expandTokens,
   findSpecFolder,
+  readFrontmatterField,
   readStackField,
   readBaseVersionField,
 }

package/src/env/teardown.js

@@ -105,7 +105,7 @@ function planDown(spec, config, flags, ctx) {
   // different question from ours: it also declines a branch that is ahead of its
   // upstream ref, reporting `not yet merged to refs/remotes/origin/<branch>,
   // even though it is merged to HEAD`. That fires on the ordinary spec flow —
-  // `/spec-go` pushes the branch when it provisions, and the phase commits after
+  // `/spec-start` pushes the branch when it provisions, and the phase commits after
   // it are landed locally rather than pushed — so teardown meets a branch whose
   // every commit is on `main` and `-d` refuses it. `merged` (HEAD is an ancestor
   // of base) already establishes what we actually care about, and establishes it
@@ -122,7 +122,7 @@ function planDown(spec, config, flags, ctx) {
 
   // --- delete the branch on the remote (planned, never run here) ---
   //
-  // `/spec-go` pushes the branch at provision time, so a completed spec otherwise
+  // `/spec-start` pushes the branch at provision time, so a completed spec otherwise
   // leaves a merged branch on the remote forever. Cleaning that up is the goal;
   // doing it safely is the constraint.
   //
@@ -185,4 +185,42 @@ function blocked(reason) {
   }
 }
 
-module.exports = { planDown }
+/**
+ * Pure teardown planner for CHECKOUT mode.
+ *
+ * There is no worktree to remove, no slot and no volumes — the only thing a
+ * finished spec leaves behind is its branch, and the checkout standing on it.
+ *
+ * Order is load-bearing: git refuses to delete the branch you are on, so the
+ * switch to base must come first. It is also what returns the checkout to a
+ * state the next `spec-env up` will accept.
+ *
+ * The same "are these commits recoverable?" question decides `-d` vs `-D`, and
+ * it is asked exactly as worktree-mode teardown asks it — a landed branch is
+ * safe to force-delete because its commits are on base (or under a tag); an
+ * unlanded one is not, and is refused rather than quietly dropped.
+ *
+ * ctx: { dirty, landed, onBranch, base, checkoutPath }
+ */
+function planDownCheckout(spec, config, flags, ctx) {
+  const { dirty, landed, onBranch, base, checkoutPath } = ctx || {}
+  const force = Boolean(flags && flags.force)
+  const result = { mode: 'checkout', blocked: false, reason: null, commands: [], branch: spec.branch }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  if (!force) {
+    if (config.guards.refuseTeardownIfDirty && dirty) {
+      return block('the checkout has uncommitted changes')
+    }
+    if (!landed) {
+      return block(`${spec.branch} is not merged into ${base} — landing it first is what makes the delete safe`)
+    }
+  }
+
+  const commands = []
+  if (onBranch !== false) commands.push(`git -C ${checkoutPath} switch ${base}`)
+  commands.push(`git -C ${checkoutPath} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
+  return { ...result, commands }
+}
+
+module.exports = { planDown, planDownCheckout }