@skitterbyte/skitterspec 16.8.0 → 17.0.0

package/src/cli.js

@@ -37,10 +37,10 @@ const {
   planAbort,
 } = require('./env/live.js')
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
-const { planUp } = require('./env/provision.js')
-const { planDown } = require('./env/teardown.js')
+const { planUp, planCheckoutUp } = require('./env/provision.js')
+const { planDown, planDownCheckout } = require('./env/teardown.js')
 const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
-const { planIntegrate } = require('./env/integrate.js')
+const { planIntegrate, planIntegrateCheckout } = require('./env/integrate.js')
 const { planHotfixLand } = require('./env/hotfix.js')
 const { planDev } = require('./env/dev.js')
 const { startProcess, stopProcess, waitHealthy } = require('./env/supervise.js')
@@ -233,9 +233,63 @@ function specEnvStatus(dir, config) {
 // the /spec-env skill executes (git worktree add, docker compose up, .env,
 // opener). This creates no worktree and starts no stack — the caller runs the
 // printed commands. Keep the output's verb honest about that.
+// `spec-env up` in checkout mode. Gathers the git facts, hands them to the pure
+// planner, and prints the plan or the refusal.
+function specEnvUpCheckout(dir, config, spec) {
+  const git = gitReader(dir)
+  const primary = assertPrimaryOnMain(config, git)
+  const base = resolveBaseBranch(config, git)
+  const status = git(['status', '--porcelain'])
+
+  const plan = planCheckoutUp(
+    spec,
+    {
+      current: primary.branch,
+      base,
+      onBase: primary.onBase,
+      // A null status means git could not be read at all. Treated as NOT clean:
+      // the harmless outcome of being wrong is a refusal the operator can act
+      // on, and the harmful one is carrying their work onto a new branch.
+      clean: status !== null && status.length === 0,
+      branchExists: git(['rev-parse', '--verify', `refs/heads/${spec.branch}`]) !== null,
+      checkoutPath: dir,
+    },
+    config,
+  )
+
+  if (plan.blocked) {
+    process.stdout.write(`spec-env up: blocked — ${plan.reason}.\n`)
+    return
+  }
+
+  const out = [
+    `spec-env up: ${spec.folder} ` +
+      (plan.attached ? '(already on this branch — nothing to do)' : '(plan — nothing created yet)'),
+    '',
+    `  mode:      checkout (branch built in the primary checkout)`,
+    `  checkout:  ${plan.checkoutPath}`,
+    `  branch:    ${plan.branch}`,
+    '  stack:     checkout-only (no worktree, no docker, no port block)',
+  ]
+  if (plan.commands.length) {
+    out.push('')
+    out.push('  to provision, run:')
+    for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  }
+  process.stdout.write(out.join('\n') + '\n')
+}
+
 function specEnvUp(dir, config, specArg) {
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
+  // Checkout mode: the branch is built in the primary checkout, so none of the
+  // worktree machinery below applies — no slot, no trust entry, no bootstrap and
+  // no opener. Handled first precisely so none of that runs by accident.
+  if (config.mode === 'checkout') {
+    specEnvUpCheckout(dir, config, spec)
+    return
+  }
+
   // 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
@@ -251,7 +305,7 @@ function specEnvUp(dir, config, specArg) {
 
   // 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.
+  // every provision for teammates who only cloned and ran /spec-start.
   const worktreeRootAbs = path.dirname(spec.worktreePath)
   const trust = ensureWorktreeDirTrusted(dir, worktreeRootAbs)
 
@@ -295,6 +349,10 @@ function specEnvUp(dir, config, specArg) {
   } else {
     out.push('  stack:     worktree-only (no docker, no port block)')
   }
+  // The loader falls back silently on an unrecognised `mode`, so this line is
+  // the operator's only evidence of which mode actually resolved — print it
+  // whenever it was set explicitly, right or wrong.
+  out.push('  mode:      worktree (each spec gets its own checkout)')
   if (trust.reason === 'malformed') {
     out.push(
       '  trusted:   ! .claude/settings.local.json is not valid JSON — left it;' +
@@ -429,12 +487,45 @@ function compactTimestamp() {
 // when the spec was never provisioned / already torn down. Deliberately does NOT
 // touch the trusted worktree root in .claude/settings.local.json — that entry is
 // the shared parent of every spec's worktree and harmless when empty; removing it
-// would just re-prompt on the next /spec-go (see spec: isolation-trusts-worktree-dir).
+// would just re-prompt on the next /spec-start (see spec: isolation-trusts-worktree-dir).
 function specEnvDown(dir, config, specArg, flags) {
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // A worktree-only spec never held a slot but its worktree still needs removing,
   // so "nothing to do" means neither a slot nor a worktree exists.
+  // Checkout mode first: there is no worktree and no registry slot by design, so
+  // the "not provisioned" guard below would report a live spec as absent.
+  if (config.mode === 'checkout') {
+    const dgit = gitReader(dir)
+    const dbase = resolveBaseBranch(config, dgit)
+    if (dgit(['rev-parse', '--verify', `refs/heads/${spec.branch}`]) === null) {
+      process.stdout.write(`spec-env down: ${spec.folder} has no branch — nothing to do.\n`)
+      return
+    }
+    const dst = dgit(['status', '--porcelain'])
+    const contains = dgit(['branch', '--contains', spec.branch, '--list', dbase])
+    const dplan = planDownCheckout(spec, config, flags, {
+      dirty: dst === null || dst.length > 0,
+      landed: Boolean(contains && contains.trim()),
+      onBranch: dgit(['rev-parse', '--abbrev-ref', 'HEAD']) === spec.branch,
+      base: dbase,
+      checkoutPath: dir,
+    })
+    if (dplan.blocked) {
+      process.stdout.write(
+        `spec-env down: blocked — ${dplan.reason}.\n` +
+          'Re-run with --force to tear down anyway (deletes the branch).\n',
+      )
+      return
+    }
+    const dout = [`spec-env down: ${spec.folder}`, '',
+                  '  mode:      checkout (no worktree, no slot, no volumes)',
+                  `  branch:    ${dplan.branch}`, '', '  run these:']
+    for (const cmd of dplan.commands) dout.push(`    ${cmd}`)
+    process.stdout.write(dout.join('\n') + '\n')
+    return
+  }
+
   const registry = readRegistry(dir, config)
   const hasSlot = Object.prototype.hasOwnProperty.call(registry.slots, spec.folder)
   if (!hasSlot && !fs.existsSync(spec.worktreePath)) {
@@ -566,7 +657,7 @@ function liveWorktreePaths(dir) {
  *     bucket disappears the moment it empties.
  *
  * Three outcomes, never two: resolved → that spec; several candidates and no cwd
- * hint → throw, listing them; none → throw, pointing at /spec-go. *Cannot tell*
+ * hint → throw, listing them; none → throw, pointing at /spec-start. *Cannot tell*
  * never becomes a guess.
  *
  * BLIND SPOT: a spec taken live with `/spec-live` has had its branch moved into
@@ -603,7 +694,7 @@ function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
   if (provisioned.length === 0) {
     throw new Error(
       'no spec given, and no spec has a worktree — name one explicitly, or run ' +
-        '/spec-go to provision it.',
+        '/spec-start to provision it.',
     )
   }
   throw new Error(
@@ -764,6 +855,39 @@ function specEnvIntegrate(dir, config, specArg) {
   const spec = resolveSpecWithWorktree(dir, config, specArg)
   const base = resolveBaseBranch(config, gitReader(dir))
 
+  // Checkout mode short-circuits everything below. The live handling in
+  // particular reads "primary is on the spec's branch" as a live session — true
+  // in worktree mode, and simply where the branch LIVES in checkout mode, so it
+  // would refuse to land a spec sitting exactly where it belongs.
+  if (config.mode === 'checkout') {
+    const cgit = gitReader(dir)
+    const cst = cgit(['status', '--porcelain'])
+    const cahead = cgit(['rev-list', '--count', `${base}..${spec.branch}`])
+    const cplan = planIntegrateCheckout(spec, config, {
+      dirty: cst === null || cst.length > 0,
+      base,
+      aheadOfBase: cahead !== null && Number(cahead) > 0,
+      checkoutPath: dir,
+      onBranch: cgit(['rev-parse', '--abbrev-ref', 'HEAD']) === spec.branch,
+    })
+    if (cplan.blocked) {
+      process.stdout.write(`spec-env integrate: blocked — ${cplan.reason}.\n`)
+      return
+    }
+    if (cplan.noop) {
+      process.stdout.write(
+        `spec-env integrate: ${spec.folder} already landed on ${base} — nothing to integrate.\n`,
+      )
+      return
+    }
+    const cout = [`spec-env integrate: ${spec.folder}`, '', '  mode:      checkout',
+                  `  base:      ${base}`, `  branch:    ${cplan.branch}`, '',
+                  '  run these (abort the rebase on conflict):']
+    for (const cmd of cplan.commands) cout.push(`    ${cmd}`)
+    process.stdout.write(cout.join('\n') + '\n')
+    return
+  }
+
   // Live-aware: if this spec is live on the primary checkout (branch-switched by
   // `live take`), end the live session first — release back to base, re-isolate the
   // branch, clear the receipt — so the normal rebase→ff plan below applies
@@ -798,7 +922,7 @@ function specEnvIntegrate(dir, config, specArg) {
     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.
+      // a build that committed in the worktree) 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) {
@@ -1050,6 +1174,16 @@ function proxyProcFor(config, routesFileAbs) {
 // bundled proxy pointing at that spec's warm dev servers. `connect main` stops
 // the proxy so the primary checkout owns the canonical ports again.
 async function specEnvConnect(dir, config, specArg) {
+  // Both verbs exist to route around the work living somewhere other than the
+  // checkout you are in — a proxy to a second stack, or a temporary branch swap.
+  // Checkout mode closes that gap permanently, so there is nothing to route.
+  if (config.mode === 'checkout') {
+    process.stdout.write(
+      'spec-env connect: not applicable in checkout mode — the spec is built in the ' +
+        'primary checkout, so your dev server already serves it on the canonical ports.\\n',
+    )
+    return
+  }
   const sdir = stateDirLabel(config)
   const abs = (rel) => path.resolve(dir, rel)
   const routesFile = `${sdir}/proxy.json`
@@ -1151,25 +1285,64 @@ const DEPS_RE = /(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.l
 // receipt is advisory metadata. `status` is read-only; `take` performs the switch
 // (release/abort land in a later phase).
 async function specEnvLive(dir, config, positional) {
-  const action = positional[0] || 'status'
+  // Both verbs exist to route around the work living somewhere other than the
+  // checkout you are in — a proxy to a second stack, or a temporary branch swap.
+  // Checkout mode closes that gap permanently, so there is nothing to route.
+  if (config.mode === 'checkout') {
+    process.stdout.write(
+      'spec-env live: not applicable in checkout mode — the spec branch is already ' +
+        'checked out here. `mode: checkout` is the permanent form of what live overlay ' +
+        'does temporarily.\\n',
+    )
+    return
+  }
+  const { action, specArg } = liveGrammar(dir, config, positional)
   switch (action) {
     case 'status':
-      specEnvLiveStatus(dir, config, positional[1])
+      specEnvLiveStatus(dir, config, specArg)
       break
     case 'take':
-      await specEnvLiveTake(dir, config, positional[1])
+      await specEnvLiveTake(dir, config, specArg)
       break
     case 'release':
-      await specEnvLiveRelease(dir, config, positional[1])
+      await specEnvLiveRelease(dir, config, specArg)
       break
     case 'abort':
       await specEnvLiveAbort(dir, config)
       break
     default:
-      process.stdout.write('Usage: skitterspec spec-env live <take|release|abort|status> [spec]\n')
+      process.stdout.write(
+        'Usage: skitterspec spec-env live <spec>|<base branch>|<take|release|abort|status> [spec]\n',
+      )
   }
 }
 
+const LIVE_VERBS = new Set(['status', 'take', 'release', 'abort'])
+
+// The two front doors every doc names — `/spec-live <spec>` and `/spec-live main`
+// — translated to verbs. They live here rather than in the command because
+// `.claude/commands/spec-live.md` relays `$ARGUMENTS` untranslated (it is a
+// pre-executed script, with no model turn to rewrite them); the skill this
+// replaced did the translation itself, which is how these forms came to be
+// documented but unimplemented. `connect` needs no equivalent — its argument was
+// always spec-shaped (`specArg || 'main'`).
+//
+// VERB PRECEDENCE IS DELIBERATE, and so is the order below: the four verbs and
+// the base branch are matched BEFORE the spec-name fallback, so a spec folder
+// that happens to be called `status` cannot silently branch-switch the primary
+// checkout. Such a spec is still reachable — as `live take status`. The literal
+// `main` is honoured even where the base branch is named something else,
+// matching `connect main`, so the muscle memory works in either repo.
+function liveGrammar(dir, config, positional) {
+  const [first, second] = positional
+  if (!first) return { action: 'status', specArg: undefined }
+  if (LIVE_VERBS.has(first)) return { action: first, specArg: second }
+  if (first === 'main' || first === resolveBaseBranch(config, gitReader(dir))) {
+    return { action: 'release', specArg: undefined }
+  }
+  return { action: 'take', specArg: first }
+}
+
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {
@@ -1182,6 +1355,10 @@ async function specEnvLiveTake(dir, config, specArg) {
   const status = primaryGit(['status', '--porcelain'])
   const clean = status !== null && status.length === 0
   const worktreeExists = fs.existsSync(spec.worktreePath)
+  // The tree the rebase actually runs in. Unreadable → treated as dirty: being
+  // wrong that way costs a message, the other way moves work we could not see.
+  const wtStatus = worktreeExists ? gitReader(spec.worktreePath)(['status', '--porcelain']) : ''
+  const worktreeClean = wtStatus !== null && wtStatus.length === 0
   const baseMainCommit = primaryGit(['rev-parse', 'HEAD'])
 
   // Diff base...branch to spot migration / dependency changes (best-effort).
@@ -1201,7 +1378,9 @@ async function specEnvLiveTake(dir, config, specArg) {
   const plan = planTake(spec, config, {
     primary,
     primaryPath: dir,
+    inFlight: (readReceipt(dir, config) || {}).spec || null,
     clean,
+    worktreeClean,
     worktreeExists,
     base,
     baseMainCommit,
@@ -1221,10 +1400,19 @@ async function specEnvLiveTake(dir, config, specArg) {
   // Execute the switch. Rebase first; on conflict, abort and bail (state untouched).
   const reb = runGit(spec.worktreePath, ['rebase', base])
   if (!reb.ok) {
-    runGit(spec.worktreePath, ['rebase', '--abort'])
+    // A rebase fails two ways and they need different answers. It can REFUSE TO
+    // START (unstaged changes, a missing base) — nothing to abort, nothing to
+    // resolve — or start and CONFLICT. Calling both "hit conflicts" sent people
+    // hunting a conflict that did not exist, and `--abort` on a rebase that
+    // never began discarded git's own explanation of what was actually wrong.
+    const started = runGit(spec.worktreePath, ['rebase', '--show-current-patch']).ok
+    if (started) runGit(spec.worktreePath, ['rebase', '--abort'])
     process.stdout.write(
-      `spec-env live take: rebase of ${spec.branch} onto ${base} hit conflicts — ` +
-        `resolve them in ${spec.worktreePath}, then retry.\n`,
+      started
+        ? `spec-env live take: rebase of ${spec.branch} onto ${base} hit conflicts — ` +
+            `resolve them in ${spec.worktreePath}, then retry.\n`
+        : `spec-env live take: rebase of ${spec.branch} onto ${base} could not start — ` +
+            `git said:\n    ${reb.err.split('\n').join('\n    ')}\n`,
     )
     return
   }
@@ -1372,7 +1560,7 @@ async function specEnvLiveAbort(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
+  // Per-spec query (`live status <spec>`): a clear yes/no verdict /spec-start and
   // 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) {
@@ -1395,9 +1583,23 @@ function specEnvLiveStatus(dir, config, specArg) {
   const state = onBase
     ? 'on base — free'
     : `feature in control — not on ${baseBranch}`
+
+  // `in-flight:` is a MACHINE SEAM, like the per-spec `live:` line above, and
+  // `/spec-next` reads it to decide which spec it is allowed to build. It answers
+  // in three states rather than two, because "cannot tell" is real here: a branch
+  // switched by hand carries no receipt, so the spec is unknown even though the
+  // checkout is plainly busy. Reporting that as `none` would invite building the
+  // wrong spec; reporting the branch says what is true and lets the caller stop.
+  const inFlight = onBase
+    ? 'none — the workbench is free'
+    : receipt && receipt.spec
+      ? `${receipt.spec}  (branch ${branch || '(detached)'})`
+      : `unknown  (branch ${branch || '(detached)'} — no receipt; switched by hand?)`
+
   process.stdout.write(
     'spec-env live:\n' +
       `  primary:   ${branch || '(detached)'}  (${state})\n` +
+      `  in-flight: ${inFlight}\n` +
       `  receipt:   ${summarizeReceipt(receipt)}\n`,
   )
 }
@@ -1466,7 +1668,9 @@ async function specEnv(rest) {
           '  [spec] is optional for up/down/dev/integrate/hotfix/resolve and live take:\n' +
           '  omit it and the sole provisioned spec is used (several -> it lists them).\n' +
           '  NOTE connect and live status keep their own meaning for a missing spec:\n' +
-          '  connect disconnects (= main), live status reports on the whole repo.\n',
+          '  connect disconnects (= main), live status reports on the whole repo.\n' +
+          '  connect and live also take a bare spec name: `live <spec>` takes the\n' +
+          '  instance, `live main` (or your base branch) hands it back.\n',
       )
   }
 }
@@ -1530,11 +1734,21 @@ async function run(argv) {
       // Fresh repo (or create-missing): isolation defaults OFF; a flag or an
       // interactive "yes" opts in. Only prompt for isolation on a fresh repo.
       let isolation = opts.isolation === true
+      let workspaceMode = 'worktree'
       if (interactive && !isExistingSetup(dir)) {
         const { promptSetup } = require('./prompts.js')
-        isolation = (await promptSetup({ isolationSeed: isolation })).isolation
+        const answers = await promptSetup({ isolationSeed: isolation })
+        isolation = answers.isolation
+        workspaceMode = answers.mode
       }
-      await init({ dir, force: opts.force, claudeMd: opts.claudeMd, mode: 'init', isolation })
+      await init({
+        dir,
+        force: opts.force,
+        claudeMd: opts.claudeMd,
+        mode: 'init',
+        isolation,
+        workspaceMode,
+      })
       break
     }
     case 'update':

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 },
@@ -44,6 +47,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,
@@ -81,7 +94,7 @@ const DEFAULT_CONFIG = Object.freeze({
   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 +118,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: [] },
@@ -257,6 +271,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')

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

@@ -158,4 +158,61 @@ function planUp(spec, alloc, config) {
   }
 }
 
-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 }
+  }
+  if (!ctx.clean) {
+    return block(
+      'the primary checkout has uncommitted changes — commit or stash them first ' +
+        '(switching would carry them onto the new branch)',
+    )
+  }
+  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',
+    )
+  }
+
+  result.commands.push(
+    ctx.branchExists ? `git switch ${spec.branch}` : `git switch -c ${spec.branch}`,
+  )
+  return result
+}
+
+module.exports = { planUp, planCheckoutUp, seedCommandFor, worktreeCd }