@skitterbyte/skitterspec 16.10.0 → 17.0.0

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 }

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 }

package/src/init.js

@@ -423,18 +423,24 @@ function installCore(dir, opts) {
 }
 
 // Activate opt-in per-spec isolation: write specs/.core/env.config.json from the
-// example asset so /spec-go provisions a worktree for every in-progress spec.
+// example asset so /spec-start provisions a worktree for every in-progress spec.
 // Only called when the operator opts in, and never on `update` (adopting isolation
 // is a deliberate choice, not something a re-sync flips on). Idempotent: writeFile
 // never clobbers an existing env.config.json without --force.
-function installIsolation(dir, { enabled }, opts) {
+function installIsolation(dir, { enabled, workspaceMode }, opts) {
   if (!enabled) return
-  copyAsset(
-    dir,
-    path.join('core', 'env.config.json.example'),
-    path.join(dir, 'specs', '.core', 'env.config.json'),
-    opts,
-  )
+  const target = path.join(dir, 'specs', '.core', 'env.config.json')
+  copyAsset(dir, path.join('core', 'env.config.json.example'), target, opts)
+
+  // Only 'checkout' is written; 'worktree' is already what the template says and
+  // what the loader defaults to, so the common path leaves the file untouched.
+  // Guarded by existsSync because copyAsset legitimately declines to overwrite a
+  // config the operator already customized — rewriting it here would undo that.
+  if (workspaceMode === 'checkout' && fs.existsSync(target)) {
+    const parsed = JSON.parse(fs.readFileSync(target, 'utf8'))
+    parsed.mode = 'checkout'
+    fs.writeFileSync(target, `${JSON.stringify(parsed, null, 2)}\n`)
+  }
   trustWorktreeRoot(dir)
 }
 
@@ -673,7 +679,7 @@ function printReport(dir, mode, { diff = false } = {}) {
   const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))
   const isolationNote = isolationOn
     ? 'Per-spec isolation is ON: every in-progress spec gets its own git worktree' +
-      ' at /spec-go (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
+      ' at /spec-start (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
     : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
   // A provider superset ships its own `spec-<provider>-setup` skill; the base
@@ -696,7 +702,7 @@ function printReport(dir, mode, { diff = false } = {}) {
         ' (it discovers your workspace and writes the config), or see' +
         ' specs/.core/SETUP.md.\n'
   process.stdout.write(
-    '\nDone. Skills resolve as /spec, /spec-go, /spec-complete, /spec-cancel,' +
+    '\nDone. Skills resolve as /spec, /spec-start, /spec-next, /spec-complete,' +
       ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
@@ -705,7 +711,10 @@ function printReport(dir, mode, { diff = false } = {}) {
   )
 }
 
-async function init({ dir, force, claudeMd, mode, isolation }) {
+// `mode` here is the INSTALL mode ('init' | 'update'), long-standing and
+// unrelated to the config's own `mode` key — which arrives as `workspaceMode`
+// precisely so the two cannot be confused at a call site.
+async function init({ dir, force, claudeMd, mode, isolation, workspaceMode }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   resetReport()
 
@@ -716,7 +725,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   removeRetiredFiles(dir)
   installCore(dir, { force })
   // Adopting isolation writes the live env.config.json — init only, never update.
-  if (mode !== 'update') installIsolation(dir, { enabled: isolation }, { force })
+  if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
   // Record what we wrote (and migrate a pre-manifest repo) so a later resync can

package/src/prompts.js

@@ -7,7 +7,8 @@
  * test suite never imports the interactive UI.
  *
  * `isolationSeed` pre-fills the per-spec isolation question. Returns
- * `{ isolation }`.
+ * `{ isolation, mode }` — `mode` is only asked when isolation is enabled, and
+ * is `'worktree'` otherwise (the value the config defaults to anyway).
  */
 
 async function promptSetup({ isolationSeed = false } = {}) {
@@ -23,15 +24,42 @@ async function promptSetup({ isolationSeed = false } = {}) {
     {
       type: 'confirm',
       name: 'isolation',
-      message: 'Enable per-spec isolation — a git worktree per spec?',
+      message: 'Enable per-spec isolation — build each spec on its own branch?',
       initial: isolationSeed,
     },
+    {
+      // Only reachable when isolation was accepted: `prev` is the previous
+      // answer, and returning null skips the question entirely.
+      type: (prev) => (prev ? 'select' : null),
+      name: 'mode',
+      message: 'Where should a spec be built?',
+      hint: '- this is the trade, not a preference',
+      initial: 0,
+      choices: [
+        {
+          title: 'Its own worktree (default)',
+          value: 'worktree',
+          description: 'several specs at once, main left free — one terminal session per spec',
+        },
+        {
+          title: 'The checkout you are in',
+          value: 'checkout',
+          description: 'one spec at a time, no second session — your terminal follows the work',
+        },
+      ],
+    },
   ]
 
   const ans = await prompts(questions, { onCancel })
   if (cancelled) throw new Error('Setup cancelled')
 
-  return { isolation: Boolean(ans.isolation) }
+  // Anything other than an explicit 'checkout' resolves to the default, so a
+  // skipped or cancelled-into-default answer can never select the mode that
+  // puts a spec's work in the primary checkout.
+  return {
+    isolation: Boolean(ans.isolation),
+    mode: ans.mode === 'checkout' ? 'checkout' : 'worktree',
+  }
 }
 
 /**

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

@@ -1,190 +0,0 @@
----
-name: spec-go
-description: Promote a spec into active development and build the next phase — provisions its worktree, brings up its host dev servers (confirm first), then implements the phase with tests. Targets a spec by name (arg) or the spec currently in context. Use when the user says "/spec-go", "start this spec", "begin implementing <spec>", or "let's build the next phase".
----
-
-# /spec-go — start (or continue) implementing a spec
-
-The "up" button: it promotes the spec, provisions its worktree, brings its host
-dev servers up on the spec's reserved ports (with your OK), then builds the phase.
-Diverting your browser to the spec is a separate explicit step the **user**
-types — `/spec-connect` (a slash command, not a skill you can invoke).
-
-## 1. Identify the target spec
-
-- If a name/path is given as an argument, use it.
-- Otherwise use the spec **currently in context** (the one just created or
-  discussed). If neither is clear, ask which spec.
-- Locate it by searching `specs/` (check `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** alongside it (`01-<slug>.md`, `02-…`). Legacy specs
-  may be a bare `<name>.md`, or a `00-overview.md` with inline phases — handle
-  those too.
-
-## 2. Move it into development
-
-**Live check first (isolation only).** If per-spec isolation is enabled, before
-provisioning run `skitterspec spec-env live status <name>` and read its `live:`
-line. If it says **`live: yes`**, this spec is already checked out in the
-**primary checkout** (you took it live with `/spec-live`) — **do not provision,
-do not run `spec-env up`, and do not "work in the worktree"**. Its branch lives
-in the primary checkout and its worktree is on a **detached HEAD**, so a commit
-made in the worktree would strand on that detached HEAD and never reach the
-branch. Instead skip the provisioning bullets and step 2b, leave the spec where
-it is, and go straight to **step 4**, implementing the phase **in the primary
-checkout on the branch** — edits and commits there advance the branch, and
-`/spec-complete` lands them. (`spec-env up` refuses while live and says the same.
-To return to an isolated worktree instead, ask the user to type `/spec-live main`
-first, then re-run `/spec-go`.)
-
-**If per-spec isolation is enabled** (`specs/.core/env.config.json` exists), the
-spec **isn't already live** (the check above), and it doesn't already have a
-worktree, provision it **first**, so all the housekeeping below lands on the
-spec's branch and never on `main`:
-
-**Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
-place), skip the provisioning bullets below and build on the current branch — the
-same "in place otherwise" path used when isolation is off. Warn that the work
-will land wherever you currently are (usually `main`); reserve it for a trivial
-change or an explicit request.
-
-- Run `skitterspec spec-env up <name>` (the `spec-env` CLI engine). It is a
-  **planner: it prints commands and creates nothing itself.** Under
-  `to provision, run:` it emits the `git worktree add` on a branch forked from
-  `main` and — only when the spec's `> **Stack:**` header is
-  `worktree + docker` — the Docker bring-up.
-  **Run those commands and confirm they succeeded** before anything below: every
-  later step assumes the worktree exists, and the header line says
-  `(plan — nothing created yet)` precisely because at that point it doesn't.
-  Print the worktree path and the opener command it emits.
-- **Bootstrap the worktree's dependencies.** A fresh worktree has an empty
-  working tree — no installed dependencies, and none of the repo's gitignored
-  files (`.env`, local secret/config overrides) — so git hooks, typechecks,
-  builds and tests fail until they're in place. `spec-env up` prints the
-  project's configured **`then, in the worktree, run:`** commands — run them in
-  order, before doing anything else. Each one begins by `cd`-ing into the
-  worktree, so it works from any cwd and cannot quietly act on the main
-  checkout; if the worktree is missing it prints
-  **`no worktree at … — run the provisioning commands first`** and exits
-  non-zero. Seeing that means the `git worktree add` above didn't run or didn't
-  work — fix that before going on. Those commands are: first any
-  **file seeding** (from `env.config.json` → `seedFiles`), which symlinks or
-  copies the configured gitignored files from the main checkout into the fresh
-  worktree so setup can rely on them; then the **`setup`** commands (e.g. an
-  install command). With neither configured there's nothing to run; add
-  `seedFiles`/`setup` if agents keep stalling on a missing `.env` or dependencies.
-- **Trust the worktree for this session.** The engine wrote the printed
-  `trusted:` root into `.claude/settings.local.json` (gitignored) so future
-  sessions trust it automatically — but that file likely won't hot-reload now,
-  so run `/add-dir <trusted root>` before editing into the worktree, or the
-  first edits will prompt.
-- **Do the rest in the worktree**, on the branch: open it (the printed opener, or
-  a fresh Claude session rooted there) or, staying in this session, act on the
-  worktree path with absolute paths / `git -C <worktreePath>`. The spec move,
-  header edits **and** the phase's code all happen on the branch — so the spec's
-  evolution travels with the code it describes and lands in one PR. `main` changes
-  only when that branch merges (at `/spec-complete`).
-
-Then move the spec (in the worktree when isolated, in place otherwise):
-
-- If it isn't already under `specs/in-progress/`, move the whole spec folder
-  there. **Use `git mv`** to keep history:
-  `git mv "specs/backlog/<name>" "specs/in-progress/<name>"`.
-  `mkdir -p specs/in-progress` first if needed.
-- Update the **Status** header in the entry point:
-  `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
-- Set the **Developer** header field if it's still `—`: use `git config user.name`.
-- Append a **State log** row:
-  `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
-- **When isolated:** commit the move and **push the branch** now — that records
-  the in-progress state for everyone and fires the tracker's automation (when a
-  ticketing provider is linked).
-
-A spec ideally reaches here already `Ready` (written by `/spec`), but `/spec-go`
-works on a `Draft` too — just sanity-check it's well-formed before building.
-
-If the spec is already in `in-progress`, skip the move and implement the **next
-unfinished phase** instead of Phase 1. (When isolated, subsequent `/spec-go` runs
-happen from inside the worktree — where the spec already sits in `in-progress` on
-the branch — and a re-run of `spec-env up` just re-attaches it.)
-
-## 2b. Bring the spec's dev servers up — confirm before heavy steps
-
-**Only when isolation is enabled and the project configures host dev servers**
-(`env.config.json` → a non-empty `dev` array). This is what makes the spec
-runnable — its UI/API on the spec's reserved port block, isolated from `main`.
-
-- **Show the plan and get a yes first.** List what will start: the per-process
-  dev commands, the ports they'll bind (the spec's slot block), and any Docker
-  stack. Don't start heavy processes silently. If the user passed **`--plan`**,
-  print this plan and **stop** (preview only).
-- On confirmation, run `skitterspec spec-env dev up <name>` — it launches each
-  dev process detached on its port, logs to `.spec-env/logs/`, and waits on each
-  `health` check. With no `dev` configured it's a clean no-op; skip this step.
-- **Diverting your browser is a separate step.** To test the spec at your normal
-  `localhost` URL, the **user** types **`/spec-connect <name>`** (exclusive — it
-  exposes this spec on the canonical ports; `/spec-connect main` hands them back).
-  `/spec-go` never seizes the canonical ports on its own. For a **code-only** spec,
-  the lighter **`/spec-live <name>`** reuses the already-running dev server (a
-  branch-switch, no second stack) — `/spec-live main` hands it back. Both are
-  user-only slash commands: tell the user to run one, never try to invoke it.
-
-## 3. 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.)
-
-## 4. 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.
-
-## 5. 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.
-
-
-
-## 6. 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.