@skitterbyte/skitterspec 17.0.0 → 19.0.0

package/src/cli.js

@@ -3,7 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const { execFileSync } = require('child_process')
-const { init, resync, reset, isExistingSetup } = require('./init.js')
+const { init, resync, reset, checkSync, isExistingSetup } = require('./init.js')
 const {
   detectReleaseTooling,
   removeReleaseTooling,
@@ -20,12 +20,18 @@ const {
 const {
   resolveSpec,
   resolveBaseBranch,
+  liveWorktreePaths,
+  collectSpecFolders,
+  allSpecs,
   resolvePrimaryCheckout,
   assertPrimaryOnMain,
+  currentBranch,
   repoInfo,
   expandTokens,
   splitPrefix,
+  BUCKETS,
 } = require('./env/resolve.js')
+const building = require('./env/building.js')
 const {
   readReceipt,
   writeReceipt,
@@ -37,14 +43,48 @@ const {
   planAbort,
 } = require('./env/live.js')
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
+const {
+  rawGitReader,
+  collectReview,
+  renderReviewPage,
+  renderReviewBlock,
+  reviewOutPath,
+  reviewFileUrl,
+  reviewUrlPath,
+  reviewPublishPath,
+  readReviewUrl,
+  publishedPageNotice,
+  reviewServerNotice,
+  renderReviewFragment,
+  resolveReader,
+  writeReviewPage,
+  reviewNotesPath,
+  readNotes,
+  writeNotes,
+  validateNotesBlob,
+  judgeVerdict,
+  appendDecision,
+  annotateLastDecision,
+  readPending,
+  writePending,
+  claimPending,
+  describePending,
+  pendingAge,
+  reviewPendingPath,
+  validateResolutions,
+  mergeNotes,
+  applyResolutions,
+} = require('./env/review.js')
 const { planUp, planCheckoutUp } = require('./env/provision.js')
+const { classifyDirtyTree } = require('./env/classify.js')
 const { planDown, planDownCheckout } = require('./env/teardown.js')
 const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.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')
-const { renderRoutes, portsInUse, waitListening } = require('./env/proxy.js')
+const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
+const { renderRoutes, portsInUse, portsInUseOn, waitListening } = require('./env/proxy.js')
+const { mintToken, servableSpecs, engineVersionFor, staleServer } = require('./env/serve.js')
 
 const pkg = require('../package.json')
 
@@ -80,7 +120,8 @@ Usage:
                               — non-interactively it just adds anything missing.
   skitterspec update [dir]    Resync managed files to the latest, keeping your
                               edits (--force to overwrite). Leaves specs/ + live
-                              .core config alone.
+                              .core config alone. --check reports what it would
+                              change and writes nothing.
   skitterspec spec-env <cmd>  Per-spec isolation engine (opt-in; needs
                               specs/.core/env.config.json). Subcommands:
                                 up <spec>         print the plan to provision a worktree +
@@ -93,7 +134,16 @@ Usage:
                                 integrate <spec>  plan rebase + fast-forward onto the base branch
                                 hotfix land <spec>  tag + cherry-pick a hotfix (--also <tag>)
                                 status            list provisioned specs + port blocks
+                                review <spec>     write an HTML page of the spec's diff
+                                                  (--branch for the whole spec; --out, --json)
+                                                  (--notes <json> merges a review pass back;
+                                                   --resolve <json> records what was done)
                                 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 +155,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
@@ -130,6 +182,7 @@ function parse(argv) {
     resync: false,
     reset: false,
     diff: false,
+    check: false,
   }
   const positional = []
   for (let i = 0; i < argv.length; i++) {
@@ -139,10 +192,15 @@ 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
     else if (a === '--diff') opts.diff = true
+    else if (a === '--check') opts.check = true
     else if (a === '--dir') opts.dir = argv[++i]
     else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
     else positional.push(a)
@@ -203,7 +261,7 @@ async function cleanupReleaseTooling(dir, opts) {
  * the harmless direction for a read-only report.
  */
 function specEnvStatus(dir, config) {
-  const worktreePaths = liveWorktreePaths(dir)
+  const worktreePaths = liveWorktreePaths(gitReader(dir))
   const provisioned = allSpecs(dir, config, worktreePaths)
     .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
     // The primary checkout is itself in `git worktree list`; a spec is
@@ -230,16 +288,203 @@ function specEnvStatus(dir, config) {
 }
 
 // Plan a provision: allocate the slot, persist the registry, and print the plan
-// 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
+// the /spec-env skill executes (git worktree add, docker compose up, .env).
+// 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 }
+  // Ask about EVERY bucket, by folder name — never about `spec.path`.
+  //
+  // A spec's folder is its identity; which bucket holds it is a property of the
+  // ref you are asking about, and the two legitimately disagree: `/spec-start`
+  // moves a spec to `in-progress` on its own branch while the base still shows
+  // `backlog`. Worse, resolution PREFERS the worktree, so `spec.path` routinely
+  // points outside this repo entirely (`../<repo>-wt/<slug>/specs/...`) — a path
+  // no `cat-file` or `log` can ever match, which turned every in-flight spec
+  // into "not committed" and silently emptied the `it is on <branch>` hint too.
+  const rels = BUCKETS.map((bucket) => `specs/${bucket}/${spec.folder}`)
+  for (const rel of rels) {
+    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', '--', ...rels])
+  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 []
+  // "all of it" is a claim about the whole tree, and it stops being true the
+  // moment somebody else's work is sitting there too.
+  const head = (plan.untouched || []).length
+    ? `uncommitted, and this much of it is ${folder}'s — it will be committed first:`
+    : `uncommitted, and all of it is ${folder}'s — it will be committed first:`
+  const out = ['', `  ${head}`]
+  for (const p of plan.specCommit.paths) out.push(`    ${p}`)
+  return out
+}
+
+// What the run is deliberately leaving alone. Printed rather than swallowed,
+// because provisioning beside somebody else's uncommitted work is a fact the
+// operator should be told — and never printed as a warning, because it is not
+// one: a worktree carries nothing, and the spec commit above names its own paths.
+function untouchedLines(plan) {
+  const untouched = plan.untouched || []
+  if (!untouched.length) return []
+  const out = ['', `  not this spec's — left untouched (${untouched.length}):`]
+  for (const p of untouched) 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'])
+  const status = git(['status', '--porcelain', '-uall'])
+  const onFork = specOnForkPoint(dir, git, spec)
 
   const plan = planCheckoutUp(
     spec,
@@ -251,6 +496,11 @@ function specEnvUpCheckout(dir, config, spec) {
       // 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,
     },
@@ -271,6 +521,7 @@ function specEnvUpCheckout(dir, config, spec) {
     `  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:')
@@ -283,8 +534,8 @@ 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.
+  // worktree machinery below applies — no slot, no trust entry and no bootstrap.
+  // Handled first precisely so none of that runs by accident.
   if (config.mode === 'checkout') {
     specEnvUpCheckout(dir, config, spec)
     return
@@ -303,6 +554,27 @@ function specEnvUp(dir, config, specArg) {
     return
   }
 
+  // READ THE TREE BEFORE WRITING ANYTHING INTO IT.
+  //
+  // The report below divides the uncommitted tree into this spec's paths and
+  // everyone else's, and "everyone else's" means *the operator's* — work that
+  // was here before this command ran. Anything this command writes must
+  // therefore be invisible to that read, or `up` reports its own output as
+  // somebody's unfinished business.
+  //
+  // It did exactly that: the trust write below creates
+  // .claude/settings.local.json, and a clean checkout then reported
+  // "not this spec's — left untouched (1)" naming that very file. It went
+  // unnoticed for as long as it did because git reads ~/.config/git/ignore as
+  // its global excludes with no core.excludesFile setting needed, and the
+  // author's happened to list that path — so git never mentioned the file on
+  // the one machine the suite ever ran on. The first CI runner disagreed.
+  const upGit = gitReader(dir)
+  const upStatus = upGit(['status', '--porcelain'])
+  const upDirtyPaths = dirtyPaths(upGit)
+  const upOnFork = specOnForkPoint(dir, upGit, spec)
+  const upSpecUntracked = specIsUntracked(dir, upGit, spec)
+
   // 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-start.
@@ -326,7 +598,21 @@ 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, all of them read
+  // above — before this command wrote anything of its own into the tree.
+  const plan = planUp(spec, { slot, attached }, config, {
+    clean: upStatus !== null && upStatus.length === 0,
+    dirtyPaths: upDirtyPaths,
+    specOnFork: upOnFork.onFork,
+    specFoundOn: upOnFork.foundOn,
+    forkRef: spec.baseRef || currentBranch(upGit) || 'HEAD',
+    specUntracked: upSpecUntracked,
+  })
+
+  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
@@ -364,10 +650,11 @@ function specEnvUp(dir, config, specArg) {
         `(${trust.changed ? 'added to' : 'already in'} .claude/settings.local.json)`,
     )
   }
+  out.push(...specCommitLines(plan, spec.folder))
+  out.push(...untouchedLines(plan))
   out.push('')
   out.push('  to provision, run:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
-  if (plan.openCommand) out.push(`    ${plan.openCommand}`)
   // Seed files first (setup may depend on them), then the setup commands —
   // both run in the worktree, under one heading.
   const worktreeSteps = [...plan.seedCommands, ...plan.setupCommands]
@@ -488,6 +775,31 @@ function compactTimestamp() {
 // 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-start (see spec: isolation-trusts-worktree-dir).
+/**
+ * Gather the facts `reviewServerNotice` needs, and ask it what to say.
+ *
+ * `othersServed` counts the specs the server would still have work for once
+ * this one is gone. Evaluated BEFORE the teardown commands run — the worktree
+ * is still on disk at this point — so the spec being torn down is excluded by
+ * name rather than by waiting for it to disappear.
+ */
+function reviewServerNoticeFor(dir, config, folder) {
+  const sdir = stateDirLabel(config)
+  const proc = serveProcFor(config, path.resolve(dir, `${sdir}/review-serve.json`), { root: dir })
+  const pid = readPid(path.resolve(dir, proc.pidFile))
+  let othersServed = 0
+  try {
+    othersServed = servableSpecs(dir, config, gitReader(dir)).filter(
+      (sp) => sp.folder !== folder,
+    ).length
+  } catch {
+    // Cannot tell how many are left — so say nothing rather than tell someone
+    // to stop a server other specs may still need (negative-checks rule 4).
+    return []
+  }
+  return reviewServerNotice({ running: Boolean(pid && isAlive(pid)), othersServed })
+}
+
 function specEnvDown(dir, config, specArg, flags) {
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
@@ -522,6 +834,10 @@ function specEnvDown(dir, config, specArg, flags) {
                   '  mode:      checkout (no worktree, no slot, no volumes)',
                   `  branch:    ${dplan.branch}`, '', '  run these:']
     for (const cmd of dplan.commands) dout.push(`    ${cmd}`)
+    // Checkout mode has no worktree, but a published page outlives it just the
+    // same — the two modes must not disagree about what is left behind.
+    dout.push(...publishedPageNotice(readReviewUrl(reviewOutPath(dir, spec.folder))))
+    dout.push(...reviewServerNoticeFor(dir, config, spec.folder))
     process.stdout.write(dout.join('\n') + '\n')
     return
   }
@@ -570,6 +886,10 @@ function specEnvDown(dir, config, specArg, flags) {
     out.push('  remote branch — confirm with the user first:')
     for (const cmd of plan.remoteCommands) out.push(`    ${cmd}`)
   }
+  // The one survivor. Read through `readReviewUrl` rather than by building the
+  // path, and reported after the commands because it is not one of them.
+  out.push(...publishedPageNotice(readReviewUrl(reviewOutPath(dir, spec.folder))))
+  out.push(...reviewServerNoticeFor(dir, config, spec.folder))
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -621,17 +941,6 @@ function volumeCreatedAt(names) {
 }
 
 // Absolute paths of every checkout git knows about (primary + all worktrees).
-function liveWorktreePaths(dir) {
-  const out = gitReader(dir)(['worktree', 'list', '--porcelain'])
-  const paths = new Set()
-  if (out == null) return paths
-  for (const line of out.split('\n')) {
-    if (line.startsWith('worktree ')) {
-      paths.add(path.resolve(line.slice('worktree '.length).trim()))
-    }
-  }
-  return paths
-}
 
 /**
  * The spec to act on when the caller named none.
@@ -667,8 +976,20 @@ function liveWorktreePaths(dir) {
  * git keeps listing it as prunable. That over-reports rather than under-reports,
  * so the failure is an ambiguity error, never a wrong spec.
  */
-function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
-  const worktreePaths = liveWorktreePaths(dir)
+/**
+ * The same resolution as `soleProvisionedSpec`, returned as DATA rather than
+ * thrown: `{ folder }` when exactly one answer, `{ candidates }` when several,
+ * `{}` when none has a worktree.
+ *
+ * It exists because `liveGrammar` has to tell "several worktrees" from "no
+ * worktrees" and act differently on each, and the only other way to do that is
+ * to pattern-match the wording of an Error — which makes a message nobody
+ * thought was load-bearing into API. One implementation, two presentations:
+ * `soleProvisionedSpec` below is a thin wrapper that turns the two empty-handed
+ * cases into the exact errors every other subcommand already relies on.
+ */
+function provisionedSpecChoice(dir, config, cwd = process.cwd()) {
+  const worktreePaths = liveWorktreePaths(gitReader(dir))
   const provisioned = allSpecs(dir, config, worktreePaths)
     .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
     // The primary checkout is itself in `git worktree list`; a spec is
@@ -687,20 +1008,26 @@ function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
   const inside = provisioned
     .filter((s) => here === s.wt || here.startsWith(s.wt + path.sep))
     .sort((a, b) => b.wt.length - a.wt.length)[0]
-  if (inside) return inside.folder
+  if (inside) return { folder: inside.folder }
 
   // 2. Otherwise only an unambiguous set answers.
-  if (provisioned.length === 1) return provisioned[0].folder
-  if (provisioned.length === 0) {
+  if (provisioned.length === 1) return { folder: provisioned[0].folder }
+  return { candidates: provisioned.map((s) => s.folder) }
+}
+
+function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
+  const { folder, candidates } = provisionedSpecChoice(dir, config, cwd)
+  if (folder) return folder
+  if (!candidates.length) {
     throw new Error(
       'no spec given, and no spec has a worktree — name one explicitly, or run ' +
         '/spec-start to provision it.',
     )
   }
   throw new Error(
-    `no spec given, and ${provisioned.length} specs have worktrees — name the one ` +
+    `no spec given, and ${candidates.length} specs have worktrees — name the one ` +
       `you mean, or run this from inside one:\n` +
-      provisioned.map((s, i) => `  ${i + 1}. ${s.folder}`).join('\n'),
+      candidates.map((f, i) => `  ${i + 1}. ${f}`).join('\n'),
   )
 }
 
@@ -727,47 +1054,30 @@ function resolveSpecWithWorktree(dir, config, specArg) {
     expandTokens(config.worktree.root, wtTokens),
     expandTokens(config.worktree.folderPattern, wtTokens),
   )
-  const searchDirs = [...new Set([worktreeGuess, ...liveWorktreePaths(dir)])].filter(
+  const searchDirs = [...new Set([worktreeGuess, ...liveWorktreePaths(gitReader(dir))])].filter(
     (p) => p !== dir,
   )
-  return resolveSpec(specArg, dir, config, { searchDirs })
+  // This spec's OWN worktree is preferred over the primary checkout, not merely a
+  // fallback to it. `/spec-start` moves a spec to `in-progress` on the spec's own
+  // branch, so the primary checkout goes on reporting `backlog` for the whole
+  // life of the spec — and the same stale file supplies `Stack:` and
+  // `Base version:`, so escalating a spec to docker by editing its header in the
+  // worktree was invisible to `spec-env up`.
+  //
+  // WHAT WOULD FOOL THIS: only this spec's own worktree is promoted, never the
+  // other entries in `searchDirs`. Those are other specs' checkouts, and letting
+  // one of them answer for this spec would swap one wrong branch's view for
+  // another's. A worktree left behind by a declined teardown can still answer
+  // with a stale bucket — that is a leftover to prune, not a lookup to distrust.
+  const preferDirs = worktreeGuess === dir ? [] : [worktreeGuess]
+  return resolveSpec(specArg, dir, config, { searchDirs, preferDirs })
 }
 
 // Every spec folder name found under specs/* across the given checkout roots.
-// An in-progress spec lives on its *worktree branch*, not the primary checkout,
-// so we must scan the worktrees too — otherwise a live spec's DB looks orphaned.
-function collectSpecFolders(roots) {
-  const folders = new Set()
-  for (const root of roots) {
-    for (const bucket of ['backlog', 'in-progress', 'complete', 'cancelled']) {
-      let entries
-      try {
-        entries = fs.readdirSync(path.join(root, 'specs', bucket), { withFileTypes: true })
-      } catch {
-        continue
-      }
-      for (const entry of entries) if (entry.isDirectory()) folders.add(entry.name)
-    }
-  }
-  return folders
-}
 
 // Resolve every spec folder (found in the primary checkout OR any worktree) to
 // { folder, slug, worktreePath }. `searchDirs` lets resolveSpec locate a spec
 // that was authored on its branch and never committed to the primary checkout.
-function allSpecs(dir, config, worktreePaths) {
-  const searchDirs = [...worktreePaths]
-  const specs = []
-  for (const folder of collectSpecFolders([dir, ...searchDirs])) {
-    try {
-      const spec = resolveSpec(folder, dir, config, { searchDirs })
-      specs.push({ folder: spec.folder, slug: spec.slug, worktreePath: spec.worktreePath })
-    } catch {
-      // Unresolvable folder (not a real spec) — skip.
-    }
-  }
-  return specs
-}
 
 // Prune: reconcile namespace volumes against specs that still have a worktree and
 // print the `docker volume rm` commands for the orphans. Liveness keys off the
@@ -775,7 +1085,37 @@ function allSpecs(dir, config, worktreePaths) {
 // this correctly reaps those and frees their stale slots. Destructive removal is
 // executed by the caller (skill) after confirmation — the CLI only plans + writes
 // the registry, mirroring `spec-env down`.
+/**
+ * Delete a review-server pidfile whose process is gone.
+ *
+ * A LIVE pid is left strictly alone: `isAlive` is the positive signal, and the
+ * file merely existing proves nothing — a crashed server leaves one behind,
+ * which is the whole case this reaps. Being wrong in the other direction would
+ * mean deleting the record of a server that is still listening, so the unknown
+ * case (unreadable file, failed unlink) does nothing at all.
+ */
+function reapStaleServePid(dir, config) {
+  const proc = serveProcFor(config, path.resolve(dir, `${stateDirLabel(config)}/review-serve.json`), { root: dir })
+  const file = path.resolve(dir, proc.pidFile)
+  const pid = readPid(file)
+  if (!pid || isAlive(pid)) return null
+  try {
+    fs.rmSync(file, { force: true })
+  } catch {
+    return null
+  }
+  return pid
+}
+
 function specEnvPrune(dir, config, flags) {
+  // Before the docker section, deliberately: a stale pidfile is not docker's
+  // business, and every branch below can return early.
+  const reapedPid = reapStaleServePid(dir, config)
+  if (reapedPid) {
+    process.stdout.write(
+      `spec-env prune: reaped a stale review-server pidfile (pid ${reapedPid} is gone).\n`,
+    )
+  }
   const { repoSlug } = repoInfo(dir)
 
   const vols = listRepoVolumes(repoSlug)
@@ -787,7 +1127,7 @@ function specEnvPrune(dir, config, flags) {
     return
   }
 
-  const worktrees = liveWorktreePaths(dir)
+  const worktrees = liveWorktreePaths(gitReader(dir))
   const specs = allSpecs(dir, config, worktrees)
   const liveSlugs = liveSlugsForSpecs(specs, worktrees)
 
@@ -1078,9 +1418,93 @@ function specEnvHotfix(dir, config, positional, flags) {
   process.stdout.write(out.join('\n') + '\n')
 }
 
+// What the primary checkout has GAINED right now, by content. `dir` is already
+// anchored on the primary checkout by the dispatcher, so this reads the tree the
+// build must not be writing into. See env/building.js for why this is two
+// content-based queries rather than one `status --porcelain`.
+function primaryPaths(dir) {
+  const git = gitReader(dir)
+  return building.mergePaths(
+    git(['diff', '--name-only', 'HEAD']),
+    git(['ls-files', '--others', '--exclude-standard']),
+  )
+}
+
+// `--record-primary`: stamp the baseline a later --assert-primary-clean reads.
+function recordPrimary(dir, config, r) {
+  const file = building.baselinePath(dir, config)
+  const baseline = building.buildBaseline({
+    spec: r.folder,
+    worktreePath: r.worktreePath,
+    primary: dir,
+    paths: primaryPaths(dir),
+  })
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(baseline, null, 2) + '\n')
+  const n = baseline.paths.length
+  process.stdout.write(
+    `spec-env resolve: baseline recorded for ${r.folder}\n` +
+      `  primary:   ${dir}\n` +
+      `  worktree:  ${r.worktreePath}\n` +
+      `  dirty now: ${n === 0 ? 'nothing' : `${n} path(s) — these will not be reported later`}\n`,
+  )
+}
+
+// `--assert-primary-clean`: did the build write into the primary checkout?
+//
+// THREE OUTCOMES, NOT TWO. It accuses only on `leaked`; `unknown` reports what
+// blinded it and exits 0, because a baseline that is missing or belongs to
+// another spec is an absence, and an absence is not evidence
+// (`.claude/rules/negative-checks.md` rules 1 and 4). The blind spots this
+// cannot see are named on `compare()` in env/building.js.
+function assertPrimaryClean(dir, config, r) {
+  const file = building.baselinePath(dir, config)
+  let baseline = null
+  try {
+    baseline = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    baseline = null
+  }
+  const result = building.compare(baseline, primaryPaths(dir), {
+    spec: r.folder,
+    worktreePath: r.worktreePath,
+    primary: dir,
+  })
+
+  if (result.verdict === 'leaked') {
+    // States the OBSERVATION, not the attribution. All this knows is that the
+    // primary checkout gained these paths since the baseline — it cannot know
+    // who wrote them, and in practice another session writing a backlog spec
+    // into the primary looks identical to a leaked build write. Both readings
+    // get a next step, so being wrong about which one costs a re-record rather
+    // than someone deleting work that was never a leak.
+    throw new Error(
+      `${result.paths.length} path(s) appeared in the PRIMARY checkout since the baseline:\n` +
+        result.paths.map((p) => `    ${p}`).join('\n') +
+        `\n  primary:  ${dir}` +
+        `\n  worktree: ${r.worktreePath}` +
+        '\n  if this build wrote them, move them into the worktree before committing.' +
+        '\n  if something else did, re-run --record-primary and carry on.',
+    )
+  }
+  if (result.verdict === 'unknown') {
+    process.stdout.write(
+      `spec-env resolve: cannot tell — ${result.reason}.\n` +
+        '  no leak is being claimed; run --record-primary before the build to enable this check.\n',
+    )
+    return
+  }
+  process.stdout.write(
+    `spec-env resolve: primary checkout clean for ${r.folder}\n` +
+      `  nothing was written into ${dir}\n`,
+  )
+}
+
 // Print the resolved identity/coordinates for a single spec.
-function specEnvResolve(dir, config, specArg) {
+function specEnvResolve(dir, config, specArg, flags = {}) {
   const r = resolveSpecWithWorktree(dir, config, specArg)
+  if (flags.recordPrimary) return recordPrimary(dir, config, r)
+  if (flags.assertPrimaryClean) return assertPrimaryClean(dir, config, r)
   process.stdout.write(
     `spec:       ${r.folder} (${r.bucket})\n` +
       `type/slug:  ${r.type} / ${r.slug}\n` +
@@ -1090,6 +1514,637 @@ function specEnvResolve(dir, config, specArg) {
   )
 }
 
+/**
+ * `skitterspec spec-env stage [<spec>] [--json]`
+ *
+ * Which uncommitted paths belong to this spec, and which belong to someone else?
+ *
+ * `classifyDirtyTree` has answered that since the `/spec-start` gate was written,
+ * but only `spec-env up` could reach it — so every skill that commits a spec
+ * hand-wrote `git add specs/` instead, staging a DIRECTORY. With more than one
+ * session writing into `specs/` at once that sweeps a colleague's in-progress
+ * spec into this spec's commit, under this spec's ticket trailer. This verb is
+ * how a skill asks instead of guessing.
+ *
+ * IT ACCUSES NOBODY. `foreign` is not a complaint and not a refusal — it is the
+ * list of paths to leave alone. Nothing here exits non-zero and nothing here
+ * writes.
+ *
+ * `owned` IS THE SPEC'S DOCUMENTS, NEVER ITS CODE. A phase's own implementation
+ * lands in `foreign` — correctly, and this is the point: the commits this verb
+ * exists to bound are the lifecycle ones (`chore(spec): complete <name>`), which
+ * carry a status flip and a folder move and nothing else. A caller that staged
+ * `owned` expecting a phase's work would commit the spec file alone and think it
+ * had committed the feature.
+ *
+ * WHICH TREE IT READS: the one the caller is standing in, resolved from the
+ * invocation cwd rather than from `dir` (which every subcommand re-anchors on
+ * the primary checkout so worktree paths and the registry resolve identically).
+ * That distinction is the whole point here: `/spec-complete` and `/spec-cancel`
+ * run INSIDE the spec's worktree and must be told about that tree, while
+ * `/spec-start` runs in the primary checkout and must be told about that one.
+ * Re-anchoring would silently answer about the wrong checkout, so the tree read
+ * is printed rather than assumed.
+ */
+function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
+
+  // The git root CONTAINING the caller, not the primary checkout. `git ls-files`
+  // is scoped to its cwd, so reading from a subdirectory would list only that
+  // subdirectory's untracked files and report the rest of the spec as absent.
+  const git = gitReader(invokedFrom)
+  const tree = git(['rev-parse', '--show-toplevel']) || invokedFrom
+  const paths = dirtyPaths(gitReader(tree))
+
+  // Three states, not two (`.claude/rules/negative-checks.md` rule 4). A null
+  // here is "nobody could look", never "clean" — so it must not become an empty
+  // owned set, which a caller would stage happily and commit as nothing.
+  if (paths === null) {
+    if (flags.json) {
+      process.stdout.write(
+        JSON.stringify({
+          spec: spec.folder,
+          tree,
+          owned: null,
+          foreign: null,
+          error: 'git could not be read',
+        }) + '\n',
+      )
+      return
+    }
+    process.stdout.write(
+      `spec-env stage: ${spec.folder} — git could not be read at ${tree}, so nothing was classified.\n` +
+        '  This is not "clean": stage nothing on the strength of it.\n',
+    )
+    return
+  }
+
+  const { owned, foreign } = classifyDirtyTree(spec, paths, config)
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ spec: spec.folder, tree, owned, foreign }) + '\n')
+    return
+  }
+
+  const out = [
+    `spec-env stage: ${spec.folder} — ${owned.length} owned, ${foreign.length} foreign`,
+    `  tree:  ${tree}`,
+  ]
+  // An empty list is omitted rather than printed under its heading: a heading
+  // with nothing beneath it reads as a finding.
+  if (owned.length) {
+    out.push('', `  owned (${spec.folder}'s — safe to commit):`)
+    for (const p of owned) out.push(`    ${p}`)
+  }
+  if (foreign.length) {
+    out.push('', '  foreign (not this spec\'s — leave them alone):')
+    for (const p of foreign) out.push(`    ${p}`)
+  }
+  if (!owned.length && !foreign.length) {
+    out.push('', '  nothing uncommitted.')
+  }
+  process.stdout.write(out.join('\n') + '\n')
+}
+
+/**
+ * Write a self-contained HTML review of a spec's diff.
+ *
+ * Read entirely through `git -C <worktreePath>` — the caller's shell never moves,
+ * which is the whole point: the work being reviewed lives in a worktree, and the
+ * terminal is somewhere else (often a phone). Two shapes: the uncommitted working
+ * tree (the default — "what did this phase just do") and `--branch` (everything
+ * since the base branch — "what does this whole spec do").
+ */
+// How a judged verdict reads on the `notes:` line. The refused case leads with
+// the word `refused` rather than burying it after the reason, because the one
+// thing the reader must take away is that the approval did not happen.
+function verdictSaid(v) {
+  if (!v.honoured) return `commit refused — ${v.reason}`
+  // A committing verdict names what it hands off to, because that is the next
+  // thing that will happen to the repo and the reader should see it coming.
+  if (v.effective === 'commit') return `committing with ${v.commitWith}`
+  if (v.effective === 'commit-continue') return `committing with ${v.commitWith}, then the next phase`
+  if (v.effective === 'changes') return 'changes requested'
+  return 'discuss first'
+}
+
+async function specEnvReview(dir, config, specArg, flags) {
+  // An unknown name throws here rather than falling back to the branch: a review
+  // of the wrong spec looks exactly like a review of the right one.
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
+
+  // The worktree is what we read; without it there is nothing to say. This is an
+  // absence that means something — `git worktree list` is the same source that
+  // resolved the path — so it is safe to act on.
+  if (!fs.existsSync(spec.worktreePath)) {
+    process.stdout.write(
+      `spec-env review: ${spec.folder} has no worktree at ${spec.worktreePath} — ` +
+        'run /spec-start to provision it.\n',
+    )
+    return
+  }
+
+  const git = rawGitReader(spec.worktreePath)
+  const trimmed = gitReader(spec.worktreePath)
+
+  let mode = 'working'
+  let ref = 'HEAD'
+  let base = null
+
+  // WHICH BASE THE BRANCH VIEW MEASURES FROM. A hotfix forks its worktree from a
+  // release tag rather than the base branch, so the range that answers "what
+  // does this spec change" starts at that tag — `spec.baseRef`, read from the
+  // `> **Base version:**` header, and null for every other spec type.
+  //
+  // Measuring a hotfix from the base branch is wrong in two ways at once: the
+  // header says `since main`, which is not where the work started, and when the
+  // tag is not an ancestor of the base branch (a release line that never merged
+  // back) the range widens to include commits the hotfix never touched.
+  //
+  // Lazy, so the common working-tree path pays nothing for it.
+  const reviewBase = () => spec.baseRef || resolveBaseBranch(config, trimmed)
+
+  if (flags.branch) {
+    base = reviewBase()
+    const mergeBase = trimmed(['merge-base', base, 'HEAD'])
+    // Cannot tell → do nothing. A missing merge-base means the branch and the
+    // base share no history (a fresh repo, an unfetched base); diffing against
+    // the base tip anyway would report every file in the project as changed.
+    if (!mergeBase) {
+      process.stdout.write(
+        `spec-env review: no merge-base between ${base} and ${spec.branch} — ` +
+          'cannot compute the branch range (fetch the base branch?).\n',
+      )
+      return
+    }
+    ref = mergeBase
+    mode = 'branch'
+  }
+
+  // The sidecar is keyed to the page's path, so resolve that first — `--out`
+  // moves both together.
+  const out = reviewOutPath(dir, spec.folder, flags.out)
+  const stored = readNotes(out, spec.folder)
+  let notes = stored.notes
+  let merged = null
+  let sentVerdict = null
+  let claimed = null
+
+  // A CLAIM IS A DELIVERY MECHANISM, not a second kind of review. It lifts a
+  // pass out of the holding area and hands it to exactly the same merge a
+  // pasted blob goes through, so nothing downstream can tell — or behave
+  // differently — by how the pass arrived.
+  if (flags.claim) {
+    const heldRead = readPending(out, spec.folder)
+    if (heldRead.corrupt) {
+      // Same rule as the notes sidecar: a file we cannot parse is not "nothing
+      // pending", and claiming against it must refuse rather than find nothing.
+      process.stdout.write(
+        `spec-env review: ${reviewPendingPath(out)} is not readable JSON — ` +
+          'move it aside rather than losing the passes it holds.\n',
+      )
+      return
+    }
+    const result = claimPending(heldRead.pending, String(flags.claim).trim())
+    if (!result.pass) {
+      // NO FALLBACK, EVER. Not "the only one", not "the most recent" — either
+      // would let a pass nobody read out reach the review, which is the whole
+      // thing the code exists to prevent. And it names nothing: listing the
+      // pending codes would hand a guesser the answer.
+      process.stdout.write(
+        `spec-env review: no pending pass with that code` +
+          `${result.count ? ` (${result.count} waiting)` : ''}\n`,
+      )
+      return
+    }
+    // Validated on the way in as well as on the way out. The blob has been
+    // through a socket and sat on disk, so it is untrusted input twice over.
+    let parsed
+    try {
+      parsed = validateNotesBlob(result.pass.blob, spec.folder)
+    } catch (err) {
+      process.stdout.write(`spec-env review: ${err.message}\n`)
+      return
+    }
+    notes = mergeNotes(notes, parsed, new Date().toISOString())
+    writeNotes(out, notes)
+    // Spent by the claim, so the same code cannot be claimed twice.
+    writePending(out, result.pending)
+    sentVerdict = parsed.verdict
+    claimed = {
+      code: result.pass.code,
+      at: result.pass.at || null,
+      remaining: result.count,
+      accepted: parsed.accepted.length,
+      unaccepted: parsed.unaccepted.length,
+      comments: parsed.comments.length,
+    }
+    merged = { accepted: claimed.accepted, unaccepted: claimed.unaccepted, comments: claimed.comments }
+  }
+
+  // The other half of a confirmation: a pass the operator says is not theirs.
+  // Left in the store it is reported on every render until they stop reading the
+  // line — which is how the real one gets waved away too.
+  let dropped = null
+  if (flags.drop) {
+    const heldRead = readPending(out, spec.folder)
+    if (heldRead.corrupt) {
+      process.stdout.write(
+        `spec-env review: ${reviewPendingPath(out)} is not readable JSON — ` +
+          'move it aside rather than losing the passes it holds.\n',
+      )
+      return
+    }
+    // Same match and the SAME SILENCE as a claim. A drop that listed the codes
+    // it could not find would hand a guesser exactly what the claim withholds.
+    const result = claimPending(heldRead.pending, String(flags.drop).trim())
+    if (!result.pass) {
+      process.stdout.write(
+        `spec-env review: no pending pass with that code` +
+          `${result.count ? ` (${result.count} waiting)` : ''}\n`,
+      )
+      return
+    }
+    writePending(out, result.pending)
+    // Nothing is merged, and the notes sidecar is not touched.
+    dropped = { code: result.pass.code, remaining: result.count }
+  }
+
+  if (flags.notes) {
+    // Refuse rather than write over notes we could not read: an unreadable
+    // sidecar is a whole review pass, and overwriting it is unrecoverable.
+    if (stored.corrupt) {
+      process.stdout.write(
+        `spec-env review: ${reviewNotesPath(out)} is not readable JSON — ` +
+          'move it aside and re-paste, rather than losing what it holds.\n',
+      )
+      return
+    }
+    let blob
+    try {
+      blob = JSON.parse(fs.readFileSync(path.resolve(flags.notes), 'utf8'))
+    } catch (err) {
+      process.stdout.write(`spec-env review: notes blob: not valid JSON (${err.message})\n`)
+      return
+    }
+    let parsed
+    try {
+      parsed = validateNotesBlob(blob, spec.folder)
+    } catch (err) {
+      // Nothing has been written at this point, and nothing will be.
+      process.stdout.write(`spec-env review: ${err.message}\n`)
+      return
+    }
+    // MERGED BEFORE THE VERDICT IS JUDGED, and written either way. The notes
+    // are good work even when the verdict that came with them is one we cannot
+    // honour; dropping them would punish the mistake twice, and the reader
+    // would have to re-read the diff to write them again.
+    notes = mergeNotes(notes, parsed, new Date().toISOString())
+    writeNotes(out, notes)
+    sentVerdict = parsed.verdict
+    merged = {
+      accepted: parsed.accepted.length,
+      unaccepted: parsed.unaccepted.length,
+      comments: parsed.comments.length,
+    }
+  }
+
+  let resolvedNow = null
+  if (flags.resolve) {
+    if (stored.corrupt) {
+      process.stdout.write(
+        `spec-env review: ${reviewNotesPath(out)} is not readable JSON — ` +
+          'move it aside and re-paste, rather than losing what it holds.\n',
+      )
+      return
+    }
+    // Nothing recorded means every id would be unknown. Say that once, rather
+    // than listing every id back as a mistake, and write no sidecar for it.
+    if (!stored.present && !flags.notes) {
+      process.stdout.write(
+        `spec-env review: no notes recorded for ${spec.folder} — nothing to resolve.\n`,
+      )
+      return
+    }
+    let list
+    try {
+      list = validateResolutions(JSON.parse(fs.readFileSync(path.resolve(flags.resolve), 'utf8')))
+    } catch (err) {
+      process.stdout.write(`spec-env review: ${err.message}\n`)
+      return
+    }
+    const result = applyResolutions(notes, list, new Date().toISOString())
+    notes = result.notes
+    writeNotes(out, notes)
+    resolvedNow = { applied: result.applied, unknown: result.unknown }
+  }
+
+  // AFTER the merge and AFTER any resolutions, so the count the approval is
+  // judged against is the one that is true now. A note raised and answered in
+  // the same invocation is not an open note.
+  //
+  // Said nothing about when no verdict was sent: a blob without one behaves as
+  // it always did, and gains no key in either output.
+  let verdictReport = null
+  if (sentVerdict) {
+    const judged = judgeVerdict(sentVerdict, notes)
+    if (judged.honoured) {
+      // The log is appended only for a verdict that was ACTED ON. A refused
+      // approval did not happen, and recording it as history would leave a
+      // trail of decisions the repo never took.
+      notes = appendDecision(notes, { verdict: judged.effective, at: new Date().toISOString() })
+      writeNotes(out, notes)
+    }
+    verdictReport = {
+      sent: judged.sent,
+      effective: judged.effective,
+      honoured: judged.honoured,
+      reason: judged.reason,
+      // `openCount` rather than the bare word: a dotted property of that name
+      // is what the removed opener used, and `assets-spec-start-one-path`
+      // guards the engine against it coming back under any spelling.
+      openCount: judged.openCount,
+      openFiles: judged.openFiles,
+      // Named here so the skill that routes on the verdict does not have to
+      // read the config itself — one answer, from the engine that owns it.
+      commitWith: config.review.commitWith,
+    }
+  }
+
+  // What the last decision PRODUCED — written after the thing it asked for has
+  // happened, which is why it is a separate invocation rather than part of the
+  // verdict above. Nothing reads it back; it is history for the page to show.
+  let outcomeSaid = null
+  if (flags.outcome) {
+    const result = annotateLastDecision(notes, flags.outcome)
+    if (result.annotated) {
+      notes = result.notes
+      writeNotes(out, notes)
+      outcomeSaid = flags.outcome
+    } else {
+      // Says so rather than inventing a decision to hang it on. An outcome with
+      // no decision behind it is a record of something nobody chose.
+      process.stdout.write('spec-env review: no decision to record an outcome against — ignored\n')
+    }
+  }
+
+  // Information, never a prompt. Nothing counts these to decide anything and
+  // nothing refuses over them — the same rule the marks have lived under since
+  // `feat-review-round-trip`.
+  //
+  // DESCRIBED, not counted. The code is here so a skill can name it without
+  // opening the store: an agent that still has to read `.pending.json` to find
+  // a code will read it, and the rule against claiming unasked becomes a
+  // request rather than a discipline.
+  const waiting = describePending(readPending(out, spec.folder).pending)
+
+  const now = new Date().toISOString()
+  let data = collectReview({ spec, git, mode, ref, base, now, notes })
+
+  // A CLEAN WORKING TREE IS NOT "NOTHING TO REVIEW". It is the state a phase
+  // ends in: the page is rendered before the commit, the commit happens
+  // immediately after, and from then on the working view is empty for the rest
+  // of the spec's life. Falling back to the branch range is what keeps the page
+  // answering after that commit.
+  //
+  // What could fool this: a *fresh* branch is clean too, and its branch range is
+  // empty as well. That costs nothing, because the fallback is kept only when it
+  // actually found something — so a spec with no work at all prints exactly what
+  // it printed before any of this existed.
+  //
+  // An explicit `--branch` is never re-interpreted, and a non-empty working tree
+  // is never swapped out from under the reader. The swap only ever replaces an
+  // empty view, so no information is lost by it.
+  let fellBack = false
+  if (!flags.branch && data.totals.files === 0) {
+    const fallbackBase = reviewBase()
+    const mergeBase = trimmed(['merge-base', fallbackBase, 'HEAD'])
+    // Cannot tell -> do nothing, exactly as the `--branch` path refuses. No
+    // merge-base means base and HEAD share no history, and diffing against the
+    // base tip would report every file in the project as changed.
+    if (mergeBase) {
+      const wider = collectReview({
+        spec,
+        git,
+        mode: 'branch',
+        ref: mergeBase,
+        base: fallbackBase,
+        now,
+        notes,
+        fellBack: true,
+      })
+      if (wider.totals.files > 0) {
+        data = wider
+        mode = 'branch'
+        base = fallbackBase
+        ref = mergeBase
+        fellBack = true
+      }
+    }
+  }
+
+  // The written review is the model's half, and it arrives as JSON so no prose
+  // ever has to round-trip through markup. Absent → the page renders without it.
+  if (flags.review) {
+    const raw = fs.readFileSync(path.resolve(flags.review), 'utf8')
+    data.review = JSON.parse(raw)
+  }
+
+  writeReviewPage(out, renderReviewPage(data, { reviewHtml: renderReviewBlock(data.review) }))
+
+  // The publish-ready copy, ONLY when asked. An ordinary render must not pay for
+  // a second copy of the whole diff on disk for a path most renders never take.
+  let publishCopy = null
+  if (flags.publishCopy) {
+    publishCopy = reviewPublishPath(out)
+    writeReviewPage(
+      publishCopy,
+      renderReviewFragment(data, { reviewHtml: renderReviewBlock(data.review) }),
+    )
+  }
+
+  // Read, never written, and never interpreted: the engine cannot publish, and
+  // names this file only so the skill that can never has to build a path.
+  const urlFile = reviewUrlPath(out)
+  const url = readReviewUrl(out)
+
+  // Resolved before the --json early return, so both outputs agree.
+  const reader = resolveReader(config, process.env)
+
+  // A remote reader cannot open a path on this machine — that is the whole of
+  // what detection established. Serving is how the engine answers it: a local
+  // process, ended by one flag, leaving nothing behind. PUBLISHING is still
+  // never automatic here; it leaves a page this tooling cannot remove, so it
+  // stays an explicit ask no detection can stand in for.
+  let served = null
+  // What to say about the server, if anything. `current` and `unknown` say
+  // nothing at all: the ordinary render must read exactly as it did before any
+  // of this existed.
+  let serverSaid = null
+  if (reader.reader === 'remote' && config.review.serveOnRemote) {
+    const up = await ensureReviewServer(dir, config, { host: '0.0.0.0' })
+    if (up.replaced === 'engine') {
+      serverSaid = up.error
+        ? // BOTH facts. A reader told only "could not start" cannot see why it
+          // was trying, and "it is running an old engine and I could not replace
+          // it" is the pair that explains the page they are about to open.
+          `the server was running engine ${up.engineWas} and could not be replaced (${up.error}) — ` +
+          `its pages are drawn by that engine`
+        : `the server was running engine ${up.engineWas}; restarted on ${up.engineIs}`
+    }
+    if (!up.error) {
+      // The URLs come from the bind the server HAS, not the one asked for just
+      // above — adoption can hand back a loopback server whatever was
+      // requested. See `reviewServedUrls`.
+      const urls = reviewServedUrls(up, lanAddresses(), spec.folder)
+      if (urls) {
+        served = { ...urls, port: up.port, token: up.token, started: up.started }
+      }
+    }
+  }
+
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          spec: spec.folder,
+          branch: spec.branch,
+          worktree: spec.worktreePath,
+          mode,
+          base,
+          fellBack,
+          out,
+          publishCopy,
+          reader: reader.reader,
+          readerWhy: reader.why,
+          served,
+          ...(serverSaid ? { server: serverSaid } : {}),
+          fileUrl: reviewFileUrl(out),
+          urlFile,
+          url,
+          notesFile: reviewNotesPath(out),
+          reviewed: Boolean(data.review),
+          totals: data.totals,
+          notes: data.notes,
+          merged,
+          resolved: resolvedNow,
+          ...(verdictReport ? { verdict: verdictReport } : {}),
+          ...(outcomeSaid ? { outcome: outcomeSaid } : {}),
+          ...(claimed ? { claimed } : {}),
+          ...(dropped ? { dropped } : {}),
+          ...(waiting.length ? { pending: waiting } : {}),
+          files: data.files.map((f) => ({
+            path: f.path,
+            status: f.status,
+            additions: f.additions,
+            deletions: f.deletions,
+            whole: f.whole,
+            noise: f.noise,
+            hash: f.hash,
+            accepted: f.accepted,
+            acceptedAt: f.acceptedAt,
+            comments: f.comments,
+          })),
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return
+  }
+
+  const t = data.totals
+  const n = data.notes.totals
+  const hasNotes = n.accepted + n.lapsed + n.unresolved + n.resolved > 0
+  process.stdout.write(
+    `spec-env review: ${spec.folder} (${
+      fellBack ? `working tree clean — since ${base}` : mode === 'branch' ? `since ${base}` : 'uncommitted'
+    })\n` +
+      `  ${t.files} file${t.files === 1 ? '' : 's'}, +${t.additions} -${t.deletions}\n` +
+      (merged
+        ? `  merged: ${merged.accepted} accept${merged.accepted === 1 ? '' : 's'}, ` +
+          `${merged.unaccepted} withdrawn, ${merged.comments} comment${merged.comments === 1 ? '' : 's'}\n`
+        : '') +
+      (resolvedNow
+        ? `  resolved: ${resolvedNow.applied} comment${resolvedNow.applied === 1 ? '' : 's'}` +
+          (resolvedNow.unknown.length
+            ? ` (skipped ${resolvedNow.unknown.length} unknown id: ${resolvedNow.unknown.join(', ')})`
+            : '') +
+          '\n'
+        : '') +
+      // The verdict is said ONCE, on the line that already carries the review
+      // state. An approve of a clean read has no counts to print, so the line
+      // appears for a verdict too — but never for a blob that carried none.
+      (hasNotes || verdictReport
+        ? `  notes: ${n.accepted} accepted · ${n.lapsed} lapsed · ` +
+          `${n.unresolved} open · ${n.resolved} resolved` +
+          (verdictReport ? ` · ${verdictSaid(verdictReport)}` : '') +
+          '\n'
+        : '') +
+      (claimed
+        ? `  claimed: ${claimed.code} — ${claimed.accepted} accept${claimed.accepted === 1 ? '' : 's'}, ` +
+          `${claimed.unaccepted} withdrawn, ${claimed.comments} comment${claimed.comments === 1 ? '' : 's'}\n`
+        : '') +
+      (dropped ? `  dropped: ${dropped.code} — merged nothing\n` : '') +
+      (waiting.length
+        ? `  pending: ${waiting.length} waiting\n` +
+          waiting
+            .map((p) => `    ${p.code} · ${p.verdict || 'no verdict'} · ${pendingAge(p.at, now)}\n`)
+            .join('')
+        : '') +
+      (outcomeSaid ? `  outcome: ${outcomeSaid}\n` : '') +
+      // Said only when it is true, so a review with no sidecar reads exactly as
+      // it did before any of this existed.
+      (stored.corrupt && !flags.notes
+        ? `  notes: ${reviewNotesPath(out)} is not readable JSON — ignored, not overwritten\n`
+        : '') +
+      // Said only when there is something to say. `unknown` is the ordinary
+      // state on a local machine, and announcing it would be noise about a
+      // healthy session.
+      (reader.reader === 'unknown'
+        ? ''
+        : `  reader: ${reader.reader}${reader.why ? ` (${reader.why})` : ''}\n`) +
+      `  page: ${out}\n` +
+      // Served: the `open:` line is a URL the reader can actually use, and
+      // `page:` above still says where the file is. Not served — including every
+      // way serving can fail — falls back to exactly the output this printed
+      // before, dead link and all: that is the floor, never made worse.
+      (served
+        ? `  open: ${served.url}\n` +
+          // Said only when there is a runner-up. One address is not a choice,
+          // and an `also:` line naming nothing reads as a warning.
+          (served.alternates.length
+            ? served.alternates.map((u) => `  also: ${u}\n`).join('')
+            : '') +
+          // A loopback server is reachable from this machine and nowhere else.
+          // Said here rather than left to be discovered by a phone that cannot
+          // open the URL — and it names the command instead of describing it.
+          (served.loopback
+            ? '  local only: this server is bound to 127.0.0.1 — not reachable from your phone.\n' +
+              `  widen: ${served.widen}\n`
+            : '') +
+          (served.started && !served.loopback
+            ? '  serving: every provisioned spec, to anyone with this URL on your network.\n' +
+              '  stop:  skitterspec spec-env review serve --stop\n'
+            : '') +
+          // One line, and only when something was actually done on the reader's
+          // behalf. An action nobody asked for is reported, not hidden — the
+          // same rule teardown follows.
+          (serverSaid ? `  ${serverSaid}\n` : '')
+        : `  open: ${reviewFileUrl(out)}${
+            reader.reader === 'remote' ? '   (will not open where you are reading)' : ''
+          }\n` +
+          (serverSaid ? `  ${serverSaid}\n` : '') +
+          (reader.reader === 'remote'
+            ? '  serve: skitterspec spec-env review serve --host 0.0.0.0\n'
+            : '')) +
+      // Named on its own line so the skill never has to build the path itself.
+      (publishCopy ? `  publish: ${publishCopy}\n` : '') +
+      (url ? `  published: ${url}\n` : '') +
+      (t.files === 0 ? '  nothing to review — no changes found.\n' : ''),
+  )
+}
+
 // Start/stop a spec's host dev servers on its reserved port block. Host dev
 // servers (e.g. `pnpm dev`) need a block even on a worktree-only spec, so `up`
 // allocates a slot if the spec has none (idempotent). The planner is pure
@@ -1170,6 +2225,441 @@ function proxyProcFor(config, routesFileAbs) {
   }
 }
 
+// Where a checkout keeps its copy of the daemon, relative to its root: this
+// monorepo developing itself, and a project that installed the package. Naming
+// the distribution here is a path, not provider machinery — `init.js` and
+// `PROVIDER_COMMANDS` above already know package names by name.
+const DAEMON_LOCATIONS = [
+  path.join('node_modules', '@skitterbyte', 'skitterspec', 'src', 'env', 'serve.js'),
+  path.join('packages', 'common', 'src', 'env', 'serve.js'),
+]
+
+/**
+ * The `serve.js` the daemon should actually execute.
+ *
+ * NOT `__dirname` — that is the module directory of whichever copy of the CLI
+ * is running, and running one from a worktree pinned the daemon to that
+ * worktree's tree (its `review.js` then resolves the page template into the
+ * worktree's `assets/`). Teardown removed the worktree, the daemon carried on
+ * answering on its port, and every render failed with ENOENT for every spec.
+ *
+ * `root` is the primary checkout, which every spec-env command has already
+ * resolved. A copy found there outlives every worktree, which is the whole
+ * point. Three states, and the third is the common one — a global install or
+ * `npx` has no copy under the checkout at all — so it falls back to the running
+ * module rather than refusing to serve. Being wrong there costs exactly what
+ * happens today; refusing would cost a feature.
+ */
+function daemonScript(root) {
+  if (root) {
+    for (const rel of DAEMON_LOCATIONS) {
+      const candidate = path.join(root, rel)
+      if (fs.existsSync(candidate)) return candidate
+    }
+  }
+  return path.join(__dirname, 'env', 'serve.js')
+}
+
+/**
+ * Is a running server's recorded script still on disk?
+ *
+ * A POSITIVE SIGNAL, and the one adoption was missing: a live pid and a
+ * readable settings file were treated as proof the server works, and neither
+ * can see that the code the process is executing has been deleted.
+ *
+ * WHAT WOULD FOOL THIS: a settings file written before `script` was recorded
+ * has no key to check. That absence is not evidence — it describes every
+ * healthy server started by an older build — so it adopts as before. The
+ * destructive reading would kill a working server over a key it never had
+ * (`.claude/rules/negative-checks.md` rule 4).
+ */
+function serverScriptOk(settings) {
+  const script = settings && settings.script
+  if (!script) return true
+  return fs.existsSync(script)
+}
+
+// The supervised review-server process descriptor. Same shape as the proxy's:
+// a tiny detached node process reading its settings from a file, so a restart is
+// a rewrite of that file rather than an argv change.
+function serveProcFor(config, settingsFileAbs, { root = null } = {}) {
+  const sdir = stateDirLabel(config)
+  return {
+    name: 'review-serve',
+    command: `node ${daemonScript(root)} ${settingsFileAbs}`,
+    script: daemonScript(root),
+    env: {},
+    logFile: `${sdir}/logs/review-serve.log`,
+    pidFile: `${sdir}/pids/review-serve.pid`,
+  }
+}
+
+// Interface names that mean "a network the reader's phone is not on". On the
+// machine this was written for, `bridge100`/`bridge101` are Parallels and `en0`
+// is the wifi the phone shares — so the real address is neither first nor last
+// in `networkInterfaces()` order, and order alone is a coin toss.
+//
+// WHAT WOULD FOOL THIS: it reads interface NAMES, so a VPN on a renamed adapter,
+// an unusual driver, or a platform that names things differently all rank wrong.
+// That is exactly why the runners-up are printed rather than discarded — a bad
+// guess costs a glance, not a dead end.
+const VIRTUAL_IFACE = /^(bridge|vmnet|vnic|vboxnet|docker|utun|tap|tun|veth|ppp|awdl|llw)/i
+const PHYSICAL_IFACE = /^(en|eth|wl)\d/i
+
+// Within a tier, the range a phone most plausibly shares. Only ever a
+// tie-break: a corporate LAN is legitimately 10/8, so this must never outrank
+// the interface name.
+function rangeRank(address) {
+  if (/^192\.168\./.test(address)) return 0
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(address)) return 1
+  if (/^10\./.test(address)) return 2
+  return 3
+}
+
+/**
+ * Order this machine's non-loopback IPv4 addresses, best candidate first.
+ *
+ * PURE — takes the interface map as an argument rather than reading
+ * `os.networkInterfaces()`, so a test states the machine it describes instead of
+ * depending on the one it runs on. Same discipline as `detectReader` and its
+ * environment, and for the same reason.
+ */
+function rankLanAddresses(nets) {
+  const out = []
+  for (const name of Object.keys(nets || {})) {
+    for (const net of nets[name] || []) {
+      if (net.family !== 'IPv4' || net.internal) continue
+      const tier = PHYSICAL_IFACE.test(name) ? 0 : VIRTUAL_IFACE.test(name) ? 2 : 1
+      out.push({ address: net.address, iface: name, tier })
+    }
+  }
+  // Stable sort, so an unrankable set keeps discovery order rather than
+  // shuffling between runs.
+  return out
+    .map((e, i) => ({ ...e, i }))
+    .sort((a, b) => a.tier - b.tier || rangeRank(a.address) - rangeRank(b.address) || a.i - b.i)
+    .map(({ address, iface }) => ({ address, iface }))
+}
+
+// Every non-loopback IPv4 address of this machine, best candidate first, for
+// printing a URL a phone on the same network can actually open.
+function lanAddresses(nets = require('node:os').networkInterfaces()) {
+  return rankLanAddresses(nets).map((e) => e.address)
+}
+
+/**
+ * Bring the review server up, or adopt the one already running.
+ *
+ * Shared by `serve` (which prints its own report) and by `review` on a remote
+ * reader (which needs a URL, not a report). Only the STARTING is shared — how
+ * each one talks about the result is its own business — so the two can never
+ * drift on how a server comes up.
+ *
+ * Reuse is deliberate and load-bearing: restarting mints a fresh token, which
+ * would silently kill a URL the operator already has open on their phone. Only
+ * an explicit `serve` invocation (`restart`) is allowed to do that.
+ *
+ * Returns `{ port, token, loopback, pid, started }`, or `{ error }` — never
+ * throws, because every caller's fallback is to carry on without a server.
+ */
+async function ensureReviewServer(dir, config, { host = '127.0.0.1', port, restart = false } = {}) {
+  const sdir = stateDirLabel(config)
+  const abs = (rel) => path.resolve(dir, rel)
+  const settingsFile = `${sdir}/review-serve.json`
+  const proc = serveProcFor(config, abs(settingsFile), { root: dir })
+
+  // A POSITIVE SIGNAL, not an absence: a pidfile on disk proves nothing (a
+  // crashed process leaves one behind), so `isAlive` is what decides.
+  const pid = readPid(abs(proc.pidFile))
+  const running = pid && isAlive(pid) ? pid : null
+
+  let replaced = false
+  // What the replaced server was running, and the URL it was answering on.
+  // Both survive into the result so the caller can say what happened, and the
+  // token survives into the NEW server so the operator's link keeps working.
+  let engineWas = null
+  let reuseToken = null
+  if (running && !restart) {
+    let settings = null
+    try {
+      settings = JSON.parse(fs.readFileSync(abs(settingsFile), 'utf-8'))
+    } catch {}
+    if (settings && settings.port) {
+      if (serverScriptOk(settings)) {
+        const now = engineVersionFor(proc.script)
+        const verdict = staleServer(settings.engine, now)
+        if (verdict !== 'stale') {
+          const lb = settings.host === '127.0.0.1' || settings.host === 'localhost'
+          return {
+            port: settings.port,
+            token: settings.token || null,
+            loopback: lb,
+            pid: running,
+            started: false,
+            // `current` needs no comment and `unknown` claims nothing — a server
+            // from before the version was recorded is healthy, not suspect.
+            engine: verdict,
+            engineWas: settings.engine || null,
+            engineIs: now,
+          }
+        }
+        // STALE: alive, addressable, its script still on disk — and drawing
+        // every page with an engine that has been replaced underneath it. This
+        // is invisible to every other check here, because each render IS
+        // current: the counts move, the timestamp moves, the diff is right.
+        // Only the renderer is old. Replace it rather than serve yesterday's
+        // output under today's timestamp.
+        replaced = 'engine'
+        engineWas = settings.engine || null
+        // KEEP THE URL. The operator is usually holding the old link on a phone,
+        // and a token minted here would kill it silently — the very thing the
+        // adoption path exists to avoid. Reused only when the bind is unchanged;
+        // a loopback restart has no token to carry and needs none.
+        reuseToken = settings.token || null
+      } else {
+        // Alive, addressable, and executing code that has been deleted — the
+        // worktree it was started from is gone. It answers on the port and fails
+        // on every page, so adopting it is worse than replacing it.
+        replaced = 'script'
+      }
+    } else {
+      // Running, but its settings are unreadable — we cannot address it, and
+      // killing a server we cannot describe is worse than declining to use it.
+      return { error: 'unreadable', pid: running }
+    }
+  }
+
+  const usePort = Number(port || config.review.servePort)
+  const loopback = host === '127.0.0.1' || host === 'localhost'
+  // The token is the ONLY guard on a non-loopback bind, so it is minted with the
+  // bind rather than offered as an option to forget — except when replacing a
+  // server on the same bind, where carrying the old one keeps a link that is
+  // already open on someone's phone alive.
+  const token = loopback ? null : reuseToken || mintToken()
+
+  if (running) await stopProcess(proc, { rootDir: dir })
+
+  // ASK ABOUT BOTH ADDRESSES, because a loopback bind and a wildcard bind
+  // COEXIST under BSD semantics and neither probe sees the other:
+  //
+  //   - probing 127.0.0.1 for a 0.0.0.0 bind succeeds while a wildcard squatter
+  //     holds the port — the substitution that let a leaked daemon sit on 7777
+  //     while every render claimed to have started a server
+  //   - probing 0.0.0.0 alone succeeds while something holds 127.0.0.1, which
+  //     would leave a server answering on the LAN and not on `localhost` — the
+  //     `local:` URL this CLI prints would be dead
+  //
+  // A port either half-taken is not usable, so both are asked and either
+  // refuses. Deduped, so a loopback bind asks once.
+  //
+  // ASKED ONE AT A TIME, and that is load-bearing rather than tidy. The probe
+  // binds, so two probes of one port contend with each other — and the BSD
+  // coexistence this comment relies on is exactly what Linux does NOT do, where
+  // a wildcard and a loopback bind of one port are mutually exclusive. Asked
+  // concurrently the pair therefore reported a free port as busy, and the review
+  // server refused to start on every Linux machine while macOS stayed green.
+  // `portsInUseOn` owns the ordering; see its comment for the verification.
+  const busy = await portsInUseOn(usePort, [host, '127.0.0.1'])
+  if (busy.length) return { error: 'busy', port: usePort, replaced, engineWas }
+
+  fs.mkdirSync(path.dirname(abs(settingsFile)), { recursive: true })
+  fs.writeFileSync(
+    abs(settingsFile),
+    // `script` is recorded so adoption has something to check. Without it the
+    // only evidence a server is healthy is that its process exists. `engine` is
+    // the second half of the same idea: the script can still be on disk and be a
+    // DIFFERENT VERSION of itself, which is invisible to every other check here
+    // — the process is alive, the file exists, and every page it renders is
+    // drawn by code that was replaced underneath it.
+    JSON.stringify(
+      { dir, port: usePort, host, token, script: proc.script, engine: engineVersionFor(proc.script) },
+      null,
+      2,
+    ) + '\n',
+  )
+  const res = startProcess(proc, { cwd: dir, rootDir: dir })
+  const up = await waitListening([usePort], { host: loopback ? host : '127.0.0.1' })
+  // A PORT ANSWERING IS NOT PROOF THAT OUR PROCESS IS ANSWERING IT. `waitListening`
+  // connects, and anything already bound satisfies a connect — so on its own it
+  // reports success for a daemon that died on EADDRINUSE seconds earlier. The
+  // process we spawned still being alive is the specific evidence; the port
+  // answering is merely consistent with it.
+  if (!up || !isAlive(res.pid)) {
+    // The stale context rides out on the failure too. A caller that only learns
+    // "could not start" cannot say WHY it was trying, and "your server is running
+    // an old engine and I could not replace it" is two facts the reader needs.
+    return { error: up ? 'died' : 'silent', port: usePort, pid: res.pid, replaced, engineWas }
+  }
+
+  return {
+    port: usePort,
+    token,
+    loopback,
+    pid: res.pid,
+    started: true,
+    replaced,
+    engineWas,
+    engineIs: engineVersionFor(proc.script),
+  }
+}
+
+/**
+ * `spec-env review serve` — stand up the local diff server.
+ *
+ * Three actions on one verb: start (the default), `--stop`, `--status`. The
+ * pidfile is the single source of truth for all three, so `--status` cannot
+ * claim a server that died and `--stop` cannot kill something it did not start.
+ */
+async function specEnvReviewServe(dir, config, flags) {
+  const sdir = stateDirLabel(config)
+  const abs = (rel) => path.resolve(dir, rel)
+  const settingsFile = `${sdir}/review-serve.json`
+  const proc = serveProcFor(config, abs(settingsFile), { root: dir })
+
+  // A POSITIVE SIGNAL, not an absence: a pidfile on disk proves nothing (a
+  // crashed process leaves one behind), so `isAlive` is what decides. Three
+  // states — running, not running, and a stale file, which reads as not running
+  // and is overwritten rather than reported as an error.
+  const pid = readPid(abs(proc.pidFile))
+  const running = pid && isAlive(pid) ? pid : null
+
+  if (flags.status) {
+    if (!running) {
+      process.stdout.write('spec-env review serve: not running.\n')
+      return
+    }
+    let settings = {}
+    try {
+      settings = JSON.parse(fs.readFileSync(abs(settingsFile), 'utf-8'))
+    } catch {}
+    // Three states, and only one of them is worth a line. `current` is the
+    // ordinary answer and needs no comment; `unknown` is a server from before
+    // this was recorded, which is healthy and must not be accused of anything.
+    const verdict = staleServer(settings.engine, engineVersionFor(proc.script))
+    process.stdout.write(
+      `spec-env review serve: running (pid ${running})\n` +
+        (settings.port ? `  local: ${serveUrl('127.0.0.1', settings)}\n` : '') +
+        (settings.engine ? `  engine: ${settings.engine}\n` : '') +
+        (verdict === 'stale'
+          ? `  the engine moved under it — this one is ${engineVersionFor(proc.script)}\n`
+          : ''),
+    )
+    return
+  }
+
+  if (flags.stop) {
+    if (!running) {
+      process.stdout.write('spec-env review serve: not running — nothing to stop.\n')
+      return
+    }
+    await stopProcess(proc, { rootDir: dir })
+    process.stdout.write(`spec-env review serve: stopped (pid ${running}).\n`)
+    return
+  }
+
+  // Read what the running server is bound to BEFORE replacing it, so a restart
+  // without `--host` keeps that bind instead of silently narrowing to loopback.
+  let currentSettings = null
+  try {
+    currentSettings = running ? JSON.parse(fs.readFileSync(abs(settingsFile), 'utf-8')) : null
+  } catch {}
+
+  const started = await ensureReviewServer(dir, config, {
+    host: restartHost(flags.host, currentSettings),
+    port: flags.port,
+    restart: true,
+  })
+
+  if (started.error === 'busy') {
+    process.stdout.write(
+      `spec-env review serve: port ${started.port} is already in use — ` +
+        'pass --port, or --stop if this is an older server.\n',
+    )
+    return
+  }
+  if (started.error === 'silent') {
+    process.stdout.write(
+      `spec-env review serve: started (pid ${started.pid}) but port ${started.port} never came up — ` +
+        `see ${proc.logFile}\n`,
+    )
+    return
+  }
+
+  const { port, token, loopback } = started
+  const res = { pid: started.pid }
+
+  const specs = servableSpecs(dir, config, gitReader(dir))
+  process.stdout.write(
+    `spec-env review serve: serving ${specs.length} spec${specs.length === 1 ? '' : 's'} ` +
+      `(pid ${res.pid})\n` +
+      `  local: ${serveUrl('127.0.0.1', { port, token })}\n` +
+      (loopback
+        ? ''
+        : lanAddresses()
+            .map((a) => `  lan:   ${serveUrl(a, { port, token })}\n`)
+            .join('') +
+          '  anyone with the lan URL can read every spec\'s diff while this runs.\n') +
+      '  stop:  skitterspec spec-env review serve --stop\n',
+  )
+}
+
+/**
+ * The URLs to print for a served page — derived from the bind the server
+ * ACTUALLY has, never from the one the caller asked for.
+ *
+ * `specEnvReview` requests `0.0.0.0` on a remote reader, but
+ * `ensureReviewServer` adopts a server that is already running rather than
+ * restarting it — deliberately, since a restart mints a fresh token and kills
+ * the URL already open on someone's phone. So the server in hand may be
+ * loopback-bound whatever was asked for, and printing `lanAddresses()` anyway
+ * produced a URL that could not be opened, with nothing saying why.
+ *
+ * Loopback does not go widened silently. Restarting to satisfy the printout
+ * would break the open URL to fix a description, so it prints the address that
+ * works and names the command that widens it.
+ */
+function reviewServedUrls(up, addrs, folder) {
+  const page = (host) => `${serveUrl(host, up)}${encodeURIComponent(folder)}`
+  if (up.loopback) {
+    return {
+      url: page('127.0.0.1'),
+      // No runners-up: every other address on this machine is one the server
+      // is not listening on.
+      alternates: [],
+      loopback: true,
+      widen: 'skitterspec spec-env review serve --host 0.0.0.0',
+    }
+  }
+  // Best candidate first, with the rest kept: the ranking reads interface names
+  // and can be wrong, so the alternates are offered rather than thrown away. No
+  // address at all means nothing to offer, and the `file://` fallback is the
+  // honest answer.
+  if (!addrs.length) return null
+  return { url: page(addrs[0]), alternates: addrs.slice(1).map(page), loopback: false, widen: null }
+}
+
+/**
+ * The host a `--restart` should bind to.
+ *
+ * An explicit `--host` wins. Otherwise KEEP WHAT THE RUNNING SERVER HAD: a
+ * restart defaulting back to `127.0.0.1` narrowed the bind silently, which is
+ * how a `--host 0.0.0.0` server became unreachable without anyone touching a
+ * flag.
+ *
+ * WHAT WOULD FOOL THIS: nothing running, or a settings file with no `host`.
+ * Both read as loopback — the narrow branch — because widening a bind by
+ * inference is the one direction that must never happen by accident
+ * (`.claude/rules/negative-checks.md` rule 4).
+ */
+function restartHost(flagHost, settings) {
+  if (flagHost) return flagHost
+  return (settings && settings.host) || '127.0.0.1'
+}
+
+function serveUrl(hostname, { port, token }) {
+  return `http://${hostname}:${port}/${token ? token + '/' : ''}`
+}
+
 // Connect the canonical origin to ONE spec (exclusive model): (re)start the
 // bundled proxy pointing at that spec's warm dev servers. `connect main` stops
 // the proxy so the primary checkout owns the canonical ports again.
@@ -1189,9 +2679,20 @@ async function specEnvConnect(dir, config, specArg) {
   const routesFile = `${sdir}/proxy.json`
   const connectedFile = `${sdir}/connected`
   const proxyProc = proxyProcFor(config, abs(routesFile))
-  const target = specArg || 'main'
 
-  if (target === 'main') {
+  // DISCONNECT IS NAMED, NOT ASSUMED. A missing spec used to mean `main` — so
+  // the bare form handed the ports BACK, the one verb in the family whose
+  // zero-arg behaviour was the opposite of acting on your spec. It now resolves
+  // like every other verb: the worktree you are standing in, else the sole
+  // provisioned spec, else a refusal that names the candidates.
+  //
+  // This reverses `feat-script-only-commands` Decision 8, deliberately and as
+  // the whole point of the change rather than as a side effect of one — see
+  // `feat-bare-argument-parity`. The literal `main` is honoured even where the
+  // base branch is called something else, matching `live main`, so the muscle
+  // memory works in either repo.
+  const base = resolveBaseBranch(config, gitReader(dir))
+  if (specArg === 'main' || specArg === base) {
     const res = await stopProcess(proxyProc, { rootDir: dir })
     for (const f of [connectedFile, routesFile]) {
       try {
@@ -1208,7 +2709,11 @@ async function specEnvConnect(dir, config, specArg) {
     return
   }
 
-  const spec = resolveSpecWithWorktree(dir, config, target)
+  // Ambiguity REFUSES here rather than degrading. `live` can fall back to its
+  // status report; `connect` has no read-only answer to fall back to, and a
+  // fallback to `main` would reinstate the very inversion above — disconnecting
+  // you at the moment you are least sure what is connected.
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
   const registry = readRegistry(dir, config)
   if (!Object.prototype.hasOwnProperty.call(registry.slots, spec.folder)) {
     process.stdout.write(
@@ -1296,9 +2801,13 @@ async function specEnvLive(dir, config, positional) {
     )
     return
   }
-  const { action, specArg } = liveGrammar(dir, config, positional)
+  const { action, specArg, note } = liveGrammar(dir, config, positional)
   switch (action) {
     case 'status':
+      // Only the bare form sets a note, and only for the one ambiguity the
+      // report cannot describe. It prints ABOVE the report, not instead of it:
+      // you asked a question and should still get the answer.
+      if (note) process.stdout.write(note)
       specEnvLiveStatus(dir, config, specArg)
       break
     case 'take':
@@ -1335,7 +2844,7 @@ const LIVE_VERBS = new Set(['status', 'take', 'release', 'abort'])
 // matching `connect main`, so the muscle memory works in either repo.
 function liveGrammar(dir, config, positional) {
   const [first, second] = positional
-  if (!first) return { action: 'status', specArg: undefined }
+  if (!first) return bareLive(dir, config)
   if (LIVE_VERBS.has(first)) return { action: first, specArg: second }
   if (first === 'main' || first === resolveBaseBranch(config, gitReader(dir))) {
     return { action: 'release', specArg: undefined }
@@ -1343,6 +2852,52 @@ function liveGrammar(dir, config, positional) {
   return { action: 'take', specArg: first }
 }
 
+/**
+ * `/spec-live` with nothing after it: take the spec you are on, when there is
+ * exactly one answer and the workbench is free — otherwise print the status
+ * report.
+ *
+ * TWO POSITIVE SIGNALS, both required, and neither is an absence: a spec must
+ * RESOLVE (not "no error"), and the primary checkout must be demonstrably on
+ * base with no receipt (not "no evidence it is busy"). Every other state —
+ * several worktrees, none, a spec already live, a hand-switched branch — is
+ * *cannot tell*, and cannot-tell prints the report. That is the whole safety
+ * argument for letting a bare command switch a branch at all: the one case it
+ * acts on is the case with a single possible meaning.
+ *
+ * It decides WHICH VERB, never whether the verb is allowed. `specEnvLiveTake`
+ * keeps every refusal it already had — dirty tree, hotfix, stateful spec,
+ * migrations, a held instance — through `planTake`. Re-checking any of them here
+ * would be a second copy free to drift from the first.
+ */
+function bareLive(dir, config) {
+  const choice = provisionedSpecChoice(dir, config)
+  if (!choice.folder) {
+    // Several worktrees is the only cannot-tell the status report does not
+    // explain — it reports on the repo, not on what you might have meant. With
+    // none provisioned the report's own `in-flight:` line already says it.
+    const note = choice.candidates.length
+      ? `spec-env live: ${choice.candidates.length} specs have worktrees — name the one you mean:\n` +
+        choice.candidates.map((f, i) => `  ${i + 1}. ${f}`).join('\n') +
+        '\n'
+      : undefined
+    return { action: 'status', specArg: undefined, note }
+  }
+
+  // The workbench must be FREE, not merely un-refused. When it is not, the
+  // report names the branch, the in-flight spec and the receipt — so it already
+  // says why nothing was taken, and a note here would only repeat it.
+  const primary = assertPrimaryOnMain(config, gitReader(dir))
+  const receipt = readReceipt(dir, config)
+  if (!primary.onBase || (receipt && receipt.spec)) {
+    return { action: 'status', specArg: undefined }
+  }
+
+  // Resolved here rather than passed as `undefined`, so the verb acts on the
+  // spec this function actually decided about.
+  return { action: 'take', specArg: choice.folder }
+}
+
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {
@@ -1608,16 +3163,50 @@ async function specEnv(rest) {
   const [sub, ...args] = rest
   let dir = process.cwd()
   const positional = []
-  const flags = { keepVolumes: false, force: false, also: [], olderThanDays: null }
+  const flags = {
+    keepVolumes: false,
+    force: false,
+    also: [],
+    olderThanDays: null,
+    branch: false,
+    out: null,
+    review: null,
+    notes: null,
+    resolve: null,
+    outcome: null,
+    claim: null,
+    drop: null,
+    json: false,
+  }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--keep-volumes') flags.keepVolumes = true
     else if (args[i] === '--force') flags.force = true
     else if (args[i] === '--also') flags.also.push(args[++i])
     else if (args[i] === '--older-than') flags.olderThanDays = Number(args[++i])
+    else if (args[i] === '--branch') flags.branch = true
+    else if (args[i] === '--stop') flags.stop = true
+    else if (args[i] === '--status') flags.status = true
+    else if (args[i] === '--port') flags.port = args[++i]
+    else if (args[i] === '--host') flags.host = args[++i]
+    else if (args[i] === '--publish-copy') flags.publishCopy = true
+    else if (args[i] === '--out') flags.out = args[++i]
+    else if (args[i] === '--review') flags.review = args[++i]
+    else if (args[i] === '--notes') flags.notes = args[++i]
+    else if (args[i] === '--resolve') flags.resolve = args[++i]
+    else if (args[i] === '--outcome') flags.outcome = args[++i]
+    else if (args[i] === '--claim') flags.claim = args[++i]
+    else if (args[i] === '--drop') flags.drop = args[++i]
+    else if (args[i] === '--json') flags.json = true
+    else if (args[i] === '--record-primary') flags.recordPrimary = true
+    else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])
   }
   dir = path.resolve(dir)
+  // Where the caller actually is, kept before the re-anchor below. Only `stage`
+  // wants it: every other subcommand asks about the repo, while that one asks
+  // about the tree in front of you, and the two differ inside a worktree.
+  const invokedFrom = dir
   // Anchor on the primary checkout so every subcommand resolves {repo}, worktree
   // paths, and the registry identically whether run from main or a worktree.
   dir = resolvePrimaryCheckout(dir, gitReader(dir))
@@ -1657,20 +3246,34 @@ async function specEnv(rest) {
       specEnvStatus(dir, config)
       break
     case 'resolve':
-      specEnvResolve(dir, config, positional[0])
+      specEnvResolve(dir, config, positional[0], flags)
+      break
+    case 'stage':
+      specEnvStage(dir, config, positional[0], flags, invokedFrom)
+      break
+    case 'review':
+      // `serve` is the one review sub-action rather than a verb of its own: it
+      // answers the same question ("show me this diff") from the same engine,
+      // and a sibling verb would have to re-derive every bit of that.
+      if (positional[0] === 'serve') {
+        await specEnvReviewServe(dir, config, flags)
+        break
+      }
+      await specEnvReview(dir, config, positional[0], flags)
       break
     case 'live':
       await specEnvLive(dir, config, positional)
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n' +
-          '  [spec] is optional for up/down/dev/integrate/hotfix/resolve and live take:\n' +
-          '  omit it and the sole provisioned spec is used (several -> it lists them).\n' +
-          '  NOTE connect and live status keep their own meaning for a missing spec:\n' +
-          '  connect disconnects (= main), live status reports on the whole repo.\n' +
-          '  connect and live also take a bare spec name: `live <spec>` takes the\n' +
-          '  instance, `live main` (or your base branch) hands it back.\n',
+        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--json] [--record-primary] [--assert-primary-clean]\n' +
+        '  review serve [--port <n>] [--host <addr>] [--stop] [--status]  serve every diff locally\n' +
+          '  [spec] is optional everywhere: omit it and the worktree you are standing\n' +
+          '  in is used, else the sole provisioned spec (several -> it lists them).\n' +
+          '  A bare `live` takes that spec when the workbench is free, and prints the\n' +
+          '  status report when it cannot tell. `live status` still reports on the\n' +
+          '  whole repo. `live main` / `connect main` (or your base branch) hand the\n' +
+          '  instance and the ports back.\n',
       )
   }
 }
@@ -1687,6 +3290,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
@@ -1735,11 +3346,13 @@ async function run(argv) {
       // 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')
-        const answers = await promptSetup({ isolationSeed: isolation })
+        const answers = await promptSetup({ isolationSeed: isolation, gatingSeed: gating })
         isolation = answers.isolation
         workspaceMode = answers.mode
+        gating = answers.gating
       }
       await init({
         dir,
@@ -1748,12 +3361,18 @@ async function run(argv) {
         mode: 'init',
         isolation,
         workspaceMode,
+        gating,
       })
       break
     }
     case 'update':
       // `update` is a resync — refresh managed files, keep customized ones
       // (--force to overwrite). Leaves specs/ and live .core config alone.
+      // `--check` reports what it WOULD change and writes nothing.
+      if (opts.check) {
+        checkSync(dir, { claudeMd: opts.claudeMd })
+        break
+      }
       resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
       await cleanupReleaseTooling(dir, opts)
       break
@@ -1762,4 +3381,15 @@ async function run(argv) {
   }
 }
 
-module.exports = { run, parse, HELP, unknownCommand }
+module.exports = {
+  run,
+  parse,
+  HELP,
+  unknownCommand,
+  rankLanAddresses,
+  serveProcFor,
+  serverScriptOk,
+  daemonScript,
+  reviewServedUrls,
+  restartHost,
+}