@skitterbyte/skitterspec 16.10.0 → 17.0.0

package/assets/skills/spec-next/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: spec-next
+description: Build the next unfinished phase of the spec currently in flight on this checkout — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
+---
+
+# /spec-next — build the next phase of the spec in flight
+
+It assumes the workbench is already set up: a spec is **in flight** on this
+checkout, and this skill implements its next unfinished phase. Putting a spec in
+flight — provisioning, moving it to `in-progress`, getting its branch here — is
+`/spec-start`'s job. Re-run this per phase until the spec is done, then
+`/spec-complete`.
+
+## 1. Identify the spec in flight
+
+Resolve **in this order**, and stop at the first that answers:
+
+1. **The live spec of this checkout** — run
+   `skitterspec spec-env live status` and read its `live:` line. `live: yes`
+   names the spec whose branch is checked out here; that is the one to build.
+2. **The worktree you are standing in** — if this session's cwd is inside a
+   spec's worktree, that spec is in flight *for this session*. This is the
+   manual-parallel path: several specs may be provisioned, and a terminal tab
+   opened in one is its own workbench.
+3. **The current branch, in `checkout` mode** — no worktrees exist, so the
+   branch the checkout is on names the spec.
+
+**If none answers, refuse and stop:**
+`no spec in flight — run /spec-start <name> to put one on this checkout`.
+
+**Never fall back to the spec "in context".** A spec discussed in conversation
+is not a spec in flight, and this skill writes real code: building the wrong
+spec's phase produces commits on a branch nobody asked for. The refusal is
+cheap; the mistake is not.
+
+A **name argument** is accepted, but it must *match* the spec in flight — it
+narrows a re-run, it does not select a different spec. A mismatch refuses,
+naming both.
+
+## 2. Pre-flight — commit prior work
+
+Before writing any code for this phase, get the workspace clean:
+
+- **Confirm the last-worked phase is committed.** Run `git status` and
+  `git log --oneline -5`. The most recently *implemented* phase (not necessarily
+  the numerically previous one) should already be committed. If prior-phase work
+  is still uncommitted, **stop and suggest committing it first** (e.g. via
+  `/commit`) so each phase lands as its own reviewable commit — don't build the
+  next phase on top of an uncommitted one. (Skip if this is the first phase —
+  there's nothing prior to commit.)
+
+## 3. Implement the phase
+
+Identify the **first unfinished phase** from the `00-overview.md` phase index,
+then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
+started: set the phase-file heading to `🔄` and its `> **Status:**` to
+`In progress`, and flip the matching row in the overview phase index to `🔄`.
+
+**Then sync with the tracker (only if a provider is installed).** The phase has
+just changed state, so refresh the mirror before the build starts — that is what
+makes the phase show as in progress *while* it is being built rather than only
+once it is over. Without a provider this is a no-op and nothing below changes.
+
+
+
+Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
+
+- Work task by task through the phase file. Make focused edits that match
+  surrounding code.
+- Honour the project's conventions (see `.claude/rules/spec-planning.md` and the
+  rules it links).
+- **Tests are part of the phase, not after it.** Create/extend tests for the
+  work, then run the project's typecheck and test commands. Do not declare the
+  phase done until green.
+- Never hardcode dates in tests; never run destructive commands against a real
+  database — use the project's test database only.
+
+## 4. Record progress
+
+- In the **phase file**: tick completed tasks (`- [x]`), flip its heading to `✅`,
+  and set its `> **Status:**` to `Done`.
+- In **`00-overview.md`**: flip the matching phase-index row to `✅`.
+- If anything changed from the plan (a decision, a deviation, a discovered
+  constraint), add a dated **Changelog** entry in `00-overview.md`.
+- If new work surfaced, add it as tasks to the appropriate phase file (or add a
+  new phase file + index row) rather than doing it silently.
+
+**Then refresh the mirror (only if a provider is installed).** The phase is done
+in the repo now; leaving the tracker to catch up at `/spec-complete` is what makes
+a mirror lag a whole spec behind. Without a provider this is a no-op.
+
+
+
+## 5. Report
+
+Summarise what was implemented, the test result (quote failures if any), and
+which phase is next. Do **not** `git commit` unless the user asks — finish,
+verify, and wait.

package/assets/skills/spec-review/SKILL.md

@@ -8,7 +8,7 @@ description: Re-validate an existing spec against the current codebase — detec
 Specs rot: the code moves on while a spec sits in the backlog or pauses
 mid-build. This skill re-validates a spec against the **current** code and
 rewrites the stale parts so it's safe to act on. It plans only — it does not
-implement anything (that's `/spec-go`).
+implement anything (that's `/spec-next`).
 
 ## 1. Identify the target spec
 
@@ -48,9 +48,9 @@ trust the spec's own wording — verify:
 
 Where the drift forces a choice (the old approach no longer fits, a referenced
 thing is gone, scope is now ambiguous), grill the user like `/spec` Phase A —
-**one question at a time, with a recommended answer** — but scoped tightly to
-the drift. Don't re-litigate decisions that still hold. If you can resolve it by
-reading the code, do that instead of asking.
+**batching independent questions, each with a recommended answer** — but scoped
+tightly to the drift. Don't re-litigate decisions that still hold. If you can
+resolve it by reading the code, do that instead of asking.
 
 ## 4. Update the spec
 
@@ -87,5 +87,5 @@ reading the code, do that instead of asking.
 ## 5. Report
 
 Summarise the drift found, what you changed, any questions still open, and
-whether the spec is now safe to `/spec-go` (or should drop back to `Draft` until
+whether the spec is now safe to `/spec-start` (or should drop back to `Draft` until
 the open questions are resolved). Do **not** `git commit` unless the user asks.

package/assets/skills/spec-start/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: spec-start
+description: Put a spec in flight on this checkout — provision its branch, move it to in-progress, refresh the tracker, then build phase 1. Refuses unless the checkout is on the base branch with nothing already in flight, so it never parks or swaps someone's unfinished work. Use when the user says "/spec-start", "start this spec", or "begin implementing <spec>".
+---
+
+# /spec-start — put a spec in flight
+
+One checkout, one spec in flight. This skill is how a spec gets there:
+provision, move it to `in-progress`, refresh the tracker, then hand straight on
+to `/spec-next` for phase 1. Continuing a spec afterwards is `/spec-next`;
+finishing it is `/spec-complete`.
+
+## 1. The gate — refuse unless the workbench is free
+
+**Check this first, before resolving anything or touching a file.** In
+`worktree` mode run `skitterspec spec-env live status`; in `checkout` mode read
+the current branch. The workbench must be:
+
+- **on the base branch** (`main`, or the configured `baseBranch`), and
+- **clean** — no uncommitted changes.
+
+**If it isn't, relay what is in flight and stop.** Name the spec holding the
+checkout and the three ways out, then end your turn:
+
+- **`/spec-complete`** — it's finished; land it and free the workbench.
+- **`/spec-cancel`** — it isn't wanted; record why and free the workbench.
+- **`/spec-live main`** *(worktree mode)* — park it: the branch goes back to its
+  worktree and stays exactly as it is, ready to resume later.
+
+**Never get past the gate yourself.** Do not stash, do not commit on the
+operator's behalf, do not `/spec-live main` for them, do not switch branches. An
+uncommitted tree, a half-built phase and a rebase are each a decision someone
+must make deliberately — and the cost of guessing is another spec's work moved
+without its author asking. A refusal costs one command; the alternative can cost
+an afternoon.
+
+A dirty tree is refused *with the same words whatever the cause*: the gate does
+not try to judge whether the changes look important.
+
+## 2. Identify the spec
+
+- Use the name/path argument when given.
+- Otherwise use the spec **in context** (the one just created or discussed).
+  Unlike `/spec-next`, that fallback is safe here: this skill starts nothing
+  without the gate above passing, and a wrong guess is caught by the operator
+  before any code is written.
+- Locate it under `specs/` — `specs/backlog/` first, then the other buckets. A
+  spec is a `<name>/` folder whose entry point is `00-overview.md`, with one
+  file per phase beside it (`01-<slug>.md`, `02-…`). Legacy specs may be a bare
+  `<name>.md`, or a `00-overview.md` with inline phases — handle those too.
+- A spec already in `specs/in-progress/` was started before. If its branch is
+  parked in a worktree, this skill brings it back into flight; say so rather
+  than reporting a fresh start.
+
+## 3. Put its branch in this checkout
+
+**Read `mode` from `specs/.core/env.config.json`** (default `worktree`).
+
+### `worktree` mode
+
+1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
+   `to provision, run:` commands it prints and confirm they succeeded. Then run
+   its **`then, in the worktree, run:`** steps in order (file seeding, then
+   `setup`): a fresh worktree has no dependencies and none of the repo's
+   gitignored files, so hooks, typechecks and tests fail until they are there.
+2. **Bring the branch here.** Tell the user to type **`/spec-live <name>`** — it
+   rebases the branch, frees it from the worktree and checks it out in this
+   checkout, which is what makes this session the workbench. It is a user-only
+   command, so you cannot run it: print it, end your turn, and pick up at step 4
+   when they re-run `/spec-start`.
+   **Already here?** If the live check in step 1 showed this spec live, or the
+   branch is already checked out, the move is done — carry straight on.
+3. **A spec the live overlay refuses** — a hotfix, a stateful spec
+   (`Stack: worktree + docker`), or a branch touching migrations — **parks
+   instead.** Do the housekeeping in step 4 with `git -C <worktreePath>`, run
+   `open.command` if configured, print the worktree path, and say to run
+   `/spec-next` from a session there. Relay the engine's refusal reason as it
+   printed it; those guards protect a shared dev instance and are not yours to
+   weaken.
+   **Trust the worktree first.** `spec-env up` wrote the printed `trusted:` root
+   into `.claude/settings.local.json`, but that file will not hot-reload in this
+   session — run `/add-dir <trusted root>` before editing into the worktree, or
+   the first write prompts.
+
+### `checkout` mode
+
+Run `skitterspec spec-env up <name>` and the single `git switch` it prints.
+There is no worktree, no bootstrap, no live step — the checkout is already the
+workbench. Its planner enforces the same gate from the engine side, so relay any
+refusal and stop.
+
+## 4. Move the spec into development
+
+On the branch, in this checkout (or via `git -C <worktreePath>` for a parked
+spec):
+
+- `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
+  already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
+- Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
+- Set **Developer** if it is still `—` (`git config user.name`).
+- Append a **State log** row: `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
+- **Commit it, and push the branch.** One commit, the spec's own — it records the
+  in-progress state for everyone and fires the tracker's automation. Do this
+  *before* the tracker refresh below, so the snapshot that refresh writes is
+  swept up by the phase's own commit rather than left dirty.
+
+A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
+it is well-formed first.
+
+## 5. Bring the spec's dev servers up — confirm before heavy steps
+
+**Only when the project configures host dev servers** (`env.config.json` → a
+non-empty `dev` array). Show what will start — the commands, the ports, any
+Docker stack — and get a yes; on **`--plan`**, print it and stop. On
+confirmation run `skitterspec spec-env dev up <name>`. With none configured this
+is a clean no-op.
+
+To reach the spec at your normal `localhost` URL afterwards, the **user** types
+**`/spec-connect <name>`** (`/spec-connect main` hands the ports back). Never
+invoke it yourself.
+
+## 6. Build phase 1
+
+**Carry straight on into `/spec-next`** in this session: it marks phase 1
+started, refreshes the mirror again, builds it with tests and reports. Do not
+stop and ask the operator to run it — the workbench is set up and they asked to
+start the spec.
+
+## Opt-outs
+
+- **`--plan`** — print the provisioning and dev-server plan, change nothing.
+- **`--no-worktree`** — skip provisioning and build on the current branch. Warn
+  that the work lands wherever you are (usually the base branch); reserve it for
+  a trivial change or an explicit request.
+
+There is no `--here`: `/spec-start` **is** here. It puts the branch in the
+checkout you are in, which is what the old opt-out was reaching for.
+
+## Why there is no tracker seam here
+
+This skill creates no spec and mints no issue, so it has nothing to link — the
+intake and picker steps belong to `/spec`, `/spec-bug` and `/spec-hotfix`. The
+state change it *does* make (the spec moving to `in-progress`) is mirrored by
+the refresh `/spec-next` runs the moment it starts, which pushes the issue state
+and the phase states together. Adding a push here would send the same thing
+twice, one commit apart.

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

@@ -15,7 +15,7 @@ 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`.
+the remaining phases with `/spec-next` 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
@@ -26,9 +26,11 @@ repeatable**: new commits put the branch ahead of base again, and you can run
 ## 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.
+  was provisioned by `/spec-start` — a worktree, or its branch in the checkout under
+  `mode: checkout`). If isolation is absent, there is nothing to land — the spec
+  is authored directly on `main` already. Say so and stop. `spec-env integrate`
+  reads `mode` and emits the matching plan; in checkout mode it rebases in place,
+  switches to base and fast-forwards, all in the one repo.
 - **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
@@ -94,7 +96,7 @@ and continue — the branch has no commits base doesn't already have.
 - 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
+- Point the way forward: `/spec-next` 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": "16.10.0",
+  "version": "17.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

@@ -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,6 +1285,17 @@ 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) {
+  // 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':
@@ -1210,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).
@@ -1229,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,
@@ -1249,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
   }
@@ -1400,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) {
@@ -1423,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`,
   )
 }
@@ -1560,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':