@skitterbyte/skitterspec 16.10.0 → 18.0.0

package/src/cli.js

@@ -22,6 +22,7 @@ const {
   resolveBaseBranch,
   resolvePrimaryCheckout,
   assertPrimaryOnMain,
+  currentBranch,
   repoInfo,
   expandTokens,
   splitPrefix,
@@ -37,10 +38,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')
@@ -94,6 +95,11 @@ Usage:
                                 hotfix land <spec>  tag + cherry-pick a hotfix (--also <tag>)
                                 status            list provisioned specs + port blocks
                                 resolve <spec>    print resolved slug/type/branch/paths
+  skitterspec gating <cmd>    Release-gating check (opt-in; needs
+                              specs/.core/gating.config.json). Subcommands:
+                                check [spec]      report specs with no recorded gating
+                                                  decision (--all, --json). Advisory:
+                                                  always exits 0, never blocks.
   skitterspec --help          Show this help
   skitterspec --version       Print version
 
@@ -105,6 +111,8 @@ Options (init / update):
   --diff                   (update) Show the upstream changes each customized
                            file declined, as a unified diff
   --dir <path>             Target project dir (default: positional arg or cwd)
+  --gating                 (init) Adopt release gating: each spec records whether
+                           it ships behind a feature flag
   --no-claude-md           Skip creating/patching CLAUDE.md
   --yes, -y                Accept defaults; skip the interactive setup prompts
   --isolation / --no-isolation        Enable/skip per-spec isolation (a git
@@ -139,6 +147,10 @@ function parse(argv) {
     else if (a === '--yes' || a === '-y') opts.yes = true
     else if (a === '--isolation') opts.isolation = true
     else if (a === '--no-isolation') opts.isolation = false
+    else if (a === '--gating') opts.gating = true
+    else if (a === '--no-gating') opts.gating = false
+    else if (a === '--all') opts.all = true
+    else if (a === '--json') opts.json = true
     else if (a === '--remove-release-tooling') opts.removeReleaseTooling = true
     else if (a === '--resync') opts.resync = true
     else if (a === '--reset') opts.reset = true
@@ -233,9 +245,228 @@ 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.
+
+// git quotes a path containing unusual bytes and C-escapes it. Unquote what we
+// can; anything we cannot parse confidently is returned as-is, which makes it
+// fail the spec-folder comparison and land in `foreign` — a refusal, which is the
+// safe direction to be wrong in.
+function unquotePath(p) {
+  if (!p.startsWith('"') || !p.endsWith('"')) return p
+  try {
+    return JSON.parse(p)
+  } catch {
+    return p
+  }
+}
+
+/**
+ * Repo-relative paths of everything uncommitted. Returns null when git could not
+ * be read at all — the caller must treat that as "nobody looked", never "clean".
+ *
+ * Two prefix-free listings rather than `git status --porcelain`, deliberately.
+ * Porcelain prefixes every path with a two-character status field, and the shared
+ * git reader TRIMS its output — which eats the leading space of the first line
+ * only, so a fixed-offset parse silently returned `EADME.md` for `README.md`.
+ * These emit bare paths, so there is no offset to get wrong. `--others` also
+ * lists untracked files INDIVIDUALLY, where porcelain collapses them into their
+ * topmost untracked directory — reporting a brand-new spec as `specs/backlog/`,
+ * an ancestor attributable to no single spec, and so refusing the very tree this
+ * gate exists to accept. Both were found by running it, not by reading it.
+ */
+function dirtyPaths(git) {
+  const lists = [
+    git(['diff', '--name-only', 'HEAD']),
+    git(['ls-files', '--others', '--exclude-standard']),
+  ]
+  if (lists.every((l) => l === null)) return null
+  const out = []
+  for (const list of lists) {
+    if (!list) continue
+    for (const line of list.split('\n')) {
+      const q = line.trim()
+      if (q) out.push(unquotePath(q))
+    }
+  }
+  return out
+}
+
+// Is this spec new to git? Asked directly, so the commit subject does not depend
+// on the shape of `git status` output.
+function specIsUntracked(dir, git, spec) {
+  const rel = path.relative(dir, spec.path).split(path.sep).join('/')
+  const tracked = git(['ls-files', '--', rel])
+  return tracked === null ? null : tracked.length === 0
+}
+
+/**
+ * Is this spec present in the commit the worktree will fork from?
+ *
+ * A worktree forks from HEAD (`git worktree add -b`), so a spec absent there
+ * yields a branch missing the very spec it is for — and a clean working tree
+ * cannot detect that, because the spec may be perfectly well committed elsewhere.
+ * This asks the positive question rather than inferring it from cleanliness.
+ *
+ * A HOTFIX IS EXEMPT, and not as an edge case: it forks from a released tag
+ * (`spec.baseRef`) that by definition predates the spec describing the fix, so
+ * the spec is *supposed* to be absent there. Checking it would refuse every
+ * hotfix — an accusation aimed squarely at correct behaviour.
+ *
+ * Returns `{ onFork, foundOn }`; `onFork: null` means "cannot tell" (a hotfix, or
+ * a git that would not answer), which the planner routes to carrying on.
+ */
+function specOnForkPoint(dir, git, spec) {
+  if (spec.baseRef) return { onFork: null, foundOn: null }
+  const rel = path.relative(dir, spec.path).split(path.sep).join('/')
+  if (git(['cat-file', '-e', `HEAD:${rel}/00-overview.md`]) !== null) {
+    return { onFork: true, foundOn: null }
+  }
+  // Best-effort: name the branch that does have it, so the refusal is actionable.
+  let foundOn = null
+  const sha = git(['log', '--all', '--format=%H', '-1', '--', rel])
+  if (sha) {
+    const branches = git(['branch', '--contains', sha, '--format=%(refname:short)'])
+    if (branches) foundOn = branches.split('\n').map((b) => b.trim()).filter(Boolean)[0] || null
+  }
+  return { onFork: false, foundOn }
+}
+
+
+// Say what is about to be committed, and why it qualified. The commit is planned
+// on the operator's behalf, so it is never allowed to be a surprise: the paths are
+// listed before the commands that stage them.
+function specCommitLines(plan, folder) {
+  if (!plan.specCommit) return []
+  const out = ['', `  uncommitted, and all of it is ${folder}'s — it will be committed first:`]
+  for (const p of plan.specCommit.paths) out.push(`    ${p}`)
+  return out
+}
+
+// `spec-env up` in checkout mode. Gathers the git facts, hands them to the pure
+// planner, and prints the plan or the refusal.
+
+/**
+ * `skitterspec gating check [spec] [--all] [--json]`
+ *
+ * ADVISORY BY CONSTRUCTION. It reports and exits 0 — always, including when it
+ * finds something. The point of release gating is that the decision is recorded
+ * and reviewable, not that a machine enforces it: a project that has not decided
+ * yet is not broken, and a check that stopped someone's work over a missing
+ * header would be a worse failure than the omission it names.
+ */
+function gatingCheck(dir, argv) {
+  const { opts, positional } = parse(argv)
+  const { checkGating, activeSpecs } = require('./gating.js')
+
+  let specs = null
+  if (positional.length && !opts.all) {
+    const name = path.basename(positional[0])
+    const found = activeSpecs(dir).filter((s) => s.folder === name)
+    if (!found.length) {
+      // Not an accusation: a name that matches no ACTIVE spec is usually a
+      // finished one, which gating never covers anyway.
+      process.stdout.write(`gating: no active spec named ${name} — nothing to check.\n`)
+      return
+    }
+    specs = found
+  }
+
+  const result = checkGating(dir, specs)
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n')
+    return
+  }
+  if (!result.configured) {
+    process.stdout.write('gating: not configured — nothing to check.\n')
+    return
+  }
+  if (!result.findings.length) {
+    process.stdout.write(
+      `gating: ${result.checked} spec(s) checked — every one records a decision.\n`,
+    )
+    return
+  }
+  const lines = []
+  for (const f of result.findings) {
+    lines.push(
+      f.kind === 'missing'
+        ? `  ${f.folder} (${f.bucket}): no Gating: header`
+        : `  ${f.folder} (${f.bucket}): Gating: "${f.raw}" says nothing — a bare "none" is not a reason`,
+    )
+  }
+  lines.push('')
+  lines.push('  decide, then record it on 00-overview.md beside Stack:')
+  lines.push('    > **Gating:** <flag name — or "none: <one-line reason>">')
+  if (result.guidance) lines.push(`  see ${result.guidance}`)
+  process.stdout.write(
+    `gating: ${result.findings.length} of ${result.checked} spec(s) record no decision\n` +
+      lines.join('\n') +
+      '\n',
+  )
+}
+
+function specEnvUpCheckout(dir, config, spec) {
+  const git = gitReader(dir)
+  const primary = assertPrimaryOnMain(config, git)
+  const base = resolveBaseBranch(config, git)
+  const status = git(['status', '--porcelain', '-uall'])
+  const onFork = specOnForkPoint(dir, git, spec)
+
+  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,
+      dirtyPaths: dirtyPaths(git),
+      specOnFork: onFork.onFork,
+      specFoundOn: onFork.foundOn,
+      forkRef: primary.branch || 'HEAD',
+      specUntracked: specIsUntracked(dir, git, spec),
+      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)',
+  ]
+  out.push(...specCommitLines(plan, spec.folder))
+  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 +482,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)
 
@@ -272,7 +503,24 @@ function specEnvUp(dir, config, specArg) {
     attached = fs.existsSync(spec.worktreePath)
   }
 
-  const plan = planUp(spec, { slot, attached }, config)
+  // The tree gate: the same facts the checkout planner gets. A worktree forks
+  // from base, so an uncommitted spec would produce a branch without it.
+  const upGit = gitReader(dir)
+  const upStatus = upGit(['status', '--porcelain'])
+  const upOnFork = specOnForkPoint(dir, upGit, spec)
+  const plan = planUp(spec, { slot, attached }, config, {
+    clean: upStatus !== null && upStatus.length === 0,
+    dirtyPaths: dirtyPaths(upGit),
+    specOnFork: upOnFork.onFork,
+    specFoundOn: upOnFork.foundOn,
+    forkRef: spec.baseRef || currentBranch(upGit) || 'HEAD',
+    specUntracked: specIsUntracked(dir, upGit, spec),
+  })
+
+  if (plan.blocked) {
+    process.stdout.write(`spec-env up: blocked — ${plan.reason}.\n`)
+    return
+  }
 
   const out = []
   // `up` is a planner: it prints commands for the caller to run and creates no
@@ -295,6 +543,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;' +
@@ -306,6 +558,7 @@ function specEnvUp(dir, config, specArg) {
         `(${trust.changed ? 'added to' : 'already in'} .claude/settings.local.json)`,
     )
   }
+  out.push(...specCommitLines(plan, spec.folder))
   out.push('')
   out.push('  to provision, run:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
@@ -429,12 +682,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 +852,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 +889,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 +1050,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 +1117,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 +1369,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 +1480,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 +1550,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 +1573,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 +1595,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 +1755,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 +1778,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`,
   )
 }
@@ -1513,6 +1882,14 @@ async function run(argv) {
 
   const [cmd, ...rest] = argv
 
+  if (cmd === 'gating') {
+    const [sub, ...gArgs] = rest
+    const gDir = process.cwd()
+    if (sub === 'check') gatingCheck(gDir, gArgs)
+    else process.stdout.write('Usage: skitterspec gating check [spec] [--all] [--json]\n')
+    return
+  }
+
   if (cmd === 'spec-env') {
     await specEnv(rest)
     return
@@ -1560,11 +1937,24 @@ 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'
+      let gating = opts.gating === true
       if (interactive && !isExistingSetup(dir)) {
         const { promptSetup } = require('./prompts.js')
-        isolation = (await promptSetup({ isolationSeed: isolation })).isolation
+        const answers = await promptSetup({ isolationSeed: isolation, gatingSeed: gating })
+        isolation = answers.isolation
+        workspaceMode = answers.mode
+        gating = answers.gating
       }
-      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,
+        gating,
+      })
       break
     }
     case 'update':