@skitterbyte/skitterspec 17.0.0 → 18.0.0

package/src/cli.js

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

package/src/env/classify.js

@@ -0,0 +1,91 @@
+'use strict'
+
+/**
+ * Which uncommitted paths belong to ONE spec?
+ *
+ * `/spec-start` refuses a dirty tree because moving another spec's unfinished
+ * work is not ours to do. But the commonest dirty tree there is — the spec you
+ * just authored and are now starting — is not another spec's work at all, and
+ * refusing it costs a round trip through `/commit` on every single start.
+ *
+ * The distinction this module draws is deliberately NOT "does the dirt look
+ * important?" (a judgement, and the gate rightly refuses to make one) but
+ * membership in an exactly-known set: the spec's own folder, plus whatever the
+ * project declares in `spec.companionPaths`. Everything else is foreign, and one
+ * foreign path disqualifies the whole tree.
+ */
+
+const path = require('node:path')
+const { BUCKETS, expandTokens, readFrontmatterField } = require('./resolve.js')
+
+// git reports repo-relative, forward-slashed paths; an untracked directory comes
+// back with a trailing slash. Normalise both away so comparisons are exact.
+function normalize(p) {
+  return String(p || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+}
+
+/**
+ * Expand a `companionPaths` pattern for this spec, or return null when it cannot
+ * be expanded.
+ *
+ * A PATTERN THAT REFERENCES `{identifier}` WHEN NO IDENTIFIER RESOLVES MATCHES
+ * NOTHING, deliberately. Two ordinary situations produce a spec with no id — a
+ * project that never set `branch.identifierField`, and a spec deliberately kept
+ * local, never pushed to a tracker — and in both the file the pattern describes
+ * either does not exist or belongs to some OTHER spec. Expanding `{identifier}`
+ * to a placeholder, or dropping the token, would widen the owned set to a path
+ * this spec has no claim on and sweep another spec's snapshot into its commit.
+ * Being wrong this way costs a refusal the operator can fix with `/commit`; the
+ * other way costs them a file they never staged.
+ */
+function expandCompanion(pattern, spec, config) {
+  const tokens = { slug: spec.slug }
+  if (/\{identifier\}/.test(pattern)) {
+    const field = config && config.branch && config.branch.identifierField
+    const identifier = readFrontmatterField(spec.path, field)
+    if (!identifier) return null
+    tokens.identifier = identifier
+  }
+  return normalize(expandTokens(pattern, tokens))
+}
+
+/**
+ * Split `dirtyPaths` into the ones that belong to `spec` and the ones that do
+ * not. Repo-relative paths in, repo-relative paths out; nothing is read from git
+ * and nothing is written.
+ *
+ * Owned:
+ *   - anything inside `specs/<bucket>/<folder>/` for ANY bucket. Every bucket is
+ *     checked rather than the spec's current one because starting a spec MOVES it
+ *     (backlog → in-progress), so a tree mid-move is dirty in two buckets at once
+ *     and both halves are the same spec's.
+ *   - each expandable `spec.companionPaths` entry.
+ *
+ * @returns {{owned: string[], foreign: string[]}}
+ */
+function classifyDirtyTree(spec, dirtyPaths, config) {
+  const owned = []
+  const foreign = []
+  if (!spec) return { owned, foreign: (dirtyPaths || []).map(normalize).filter(Boolean) }
+
+  const folders = BUCKETS.map((bucket) => `specs/${bucket}/${spec.folder}`)
+  const companions = new Set()
+  for (const pattern of (config && config.spec && config.spec.companionPaths) || []) {
+    const expanded = expandCompanion(pattern, spec, config)
+    if (expanded) companions.add(expanded)
+  }
+
+  for (const raw of dirtyPaths || []) {
+    const p = normalize(raw)
+    if (!p) continue
+    const inFolder = folders.some((f) => p === f || p.startsWith(`${f}/`))
+    if (inFolder || companions.has(p)) owned.push(p)
+    else foreign.push(p)
+  }
+  return { owned, foreign }
+}
+
+module.exports = { classifyDirtyTree, expandCompanion }

package/src/env/config.js

@@ -30,6 +30,9 @@
  *     open:     { command },   // optional, editor/terminal-agnostic opener
  *     registry: ".spec-env/registry.json",
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
+ *     spec:     { companionPaths: [ "path", ... ] },  // paths that belong to a
+ *               // spec alongside its own folder (provider-neutral; {slug} and
+ *               // {identifier} expand); empty = the spec folder only
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
  *     teardown: { deleteRemoteBranch },
@@ -90,6 +93,13 @@ const DEFAULT_CONFIG = Object.freeze({
   // 00-overview.md frontmatter field a provider writes the ticket id into (empty
   // = no identifier, so patterns referencing {identifier} fall back to type/slug).
   branch: Object.freeze({ pattern: '{type}/{slug}', identifierField: '' }),
+  // Paths that belong to a spec ALONGSIDE its own `specs/<bucket>/<name>/` folder
+  // — a tracker provider's per-spec snapshot, for instance. Provider-neutral by
+  // design: the base engine must not know that any particular tracker exists, so
+  // the project declares the shape and `{slug}` / `{identifier}` expand exactly as
+  // they do in `branch.pattern` ({identifier} via `branch.identifierField`).
+  // Default: none, so a spec owns only its own folder.
+  spec: Object.freeze({ companionPaths: Object.freeze([]) }),
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
@@ -128,6 +138,7 @@ function defaults() {
     open: { ...DEFAULT_CONFIG.open },
     registry: DEFAULT_CONFIG.registry,
     branch: { ...DEFAULT_CONFIG.branch },
+    spec: { companionPaths: [] },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
     teardown: { ...DEFAULT_CONFIG.teardown },
@@ -296,6 +307,10 @@ function mergeConfig(base, parsed) {
     }
   }
 
+  if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {
+    base.spec.companionPaths = normalizeFileList(parsed.spec.companionPaths)
+  }
+
   if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
     base.live.migrations = normalizeFileList(parsed.live.migrations)
   }

package/src/env/provision.js

@@ -11,6 +11,7 @@
  * no live git/docker.
  */
 
+const { classifyDirtyTree } = require('./classify.js')
 const { portOffset } = require('./registry.js')
 const { renderEnvFile, expandOpenCommand } = require('./render.js')
 const { expandTokens } = require('./resolve.js')
@@ -71,6 +72,126 @@ function seedCommandFor(file, mode) {
   )
 }
 
+
+// Cap a path list in a message: enough to recognise, not a wall of text.
+function listPaths(paths) {
+  const shown = paths.slice(0, 5).join(', ')
+  return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown
+}
+
+/**
+ * Decide what an uncommitted tree means for a provisioning run: commit it, refuse
+ * it, or ignore it.
+ *
+ * `/spec-start` refuses a dirty tree so another spec's unfinished work is never
+ * moved without its author asking. But the commonest dirty tree of all is the
+ * spec you just wrote and are now starting, and refusing THAT costs a round trip
+ * through `/commit` on every start. So the question asked here is not "does this
+ * dirt look important?" — a judgement the gate rightly declines to make — but
+ * membership in an exactly-known set (see `classify.js`). One foreign path
+ * disqualifies the whole tree.
+ *
+ * WHAT WOULD FOOL THIS: `ctx.dirtyPaths` being absent. That is not "the tree is
+ * clean" — it is "nobody looked", which happens on every legacy caller and
+ * whenever git itself could not be read. Either way it is never permission to
+ * commit: with no classification there is no owned set, so no commit is planned.
+ *
+ * Whether it also REFUSES depends on `carriesChanges`, and the asymmetry is the
+ * two modes' actual risk, not an inconsistency:
+ *
+ *   - checkout mode (`carriesChanges`) — `git switch -c` silently carries
+ *     uncommitted work onto the new branch. Unable to see the tree means unable
+ *     to rule that out, so it refuses, exactly as it did before this gate existed.
+ *   - worktree mode — `git worktree add` carries nothing, and forks from a commit
+ *     regardless. Refusing here would fire on a healthy repo whose git we merely
+ *     could not read, which is a cost paid by someone who did nothing wrong. So
+ *     it plans no commit and provisions as before.
+ *
+ * `specOnFork` is the other half, and a POSITIVE signal rather than an absence:
+ * the worktree forks from a specific commit, so a spec absent from it produces a
+ * branch missing the very spec it is for. A clean tree cannot detect that — the
+ * spec may be committed, just somewhere else. `null` means the caller could not
+ * tell (an unreadable git, or a hotfix, which forks from a tag predating its own
+ * spec), and routes to carrying on, never to refusing.
+ *
+ * ctx: { dirtyPaths?, clean?, specOnFork?, specFoundOn?, forkRef?, specUntracked? }
+ * @returns {{blocked: boolean, reason: string|null, commands: string[]}}
+ */
+function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
+  const ok = { blocked: false, reason: null, commands: [], owned: [], verb: null }
+  const c = ctx || {}
+
+  if (!Array.isArray(c.dirtyPaths)) {
+    // Nobody looked: never commit, and refuse only where switching could carry
+    // work we cannot see (see the asymmetry above).
+    if (carriesChanges && c.clean === false) {
+      return {
+        blocked: true,
+        reason:
+          'the primary checkout has uncommitted changes — commit or stash them first' +
+          (carriesChanges ? ' (switching would carry them onto the new branch)' : ''),
+        commands: [],
+        owned: [],
+        verb: null,
+      }
+    }
+    return ok
+  }
+
+  const { owned, foreign } = classifyDirtyTree(spec, c.dirtyPaths, config)
+
+  if (foreign.length) {
+    return {
+      blocked: true,
+      reason:
+        `the primary checkout has uncommitted changes that are not ${spec.folder}'s — ` +
+        'commit or stash them first' +
+        (carriesChanges ? ' (switching would carry them onto the new branch)' : '') +
+        `: ${listPaths(foreign)}`,
+      commands: [],
+    }
+  }
+
+  if (owned.length) {
+    // `add` or `update`? Asked of git (`ctx.specUntracked`, from `git ls-files`)
+    // rather than inferred from the shape of the status output. The inference —
+    // "a bare directory entry means the folder is wholly untracked" — was wrong in
+    // the ordinary case of the FIRST spec in a bucket, where git reports the
+    // bucket as the untracked directory instead. The old inference stays as a
+    // fallback for callers that pass no fact; unknown yields `update`, which is
+    // never a false claim.
+    const isNew =
+      typeof c.specUntracked === 'boolean'
+        ? c.specUntracked
+        : owned.includes(`specs/${spec.bucket}/${spec.folder}`)
+    const verb = isNew ? 'add' : 'update'
+    return {
+      blocked: false,
+      reason: null,
+      owned,
+      verb,
+      commands: [
+        `git add ${owned.map((p) => `"${p}"`).join(' ')}`,
+        `git commit -m "chore(spec): ${verb} ${spec.folder}"`,
+      ],
+    }
+  }
+
+  // Tree is clean. The spec must already be in the base branch's tree, or the
+  // worktree forks without it.
+  if (c.specOnFork === false) {
+    return {
+      blocked: true,
+      reason:
+        `${spec.folder} is not committed in ${c.forkRef || 'the fork point'}` +
+        (c.specFoundOn ? ` — it is on ${c.specFoundOn}` : '') +
+        ' — the worktree would fork without the spec it is for',
+      commands: [],
+    }
+  }
+  return ok
+}
+
 /**
  * Plan a provisioning run.
  *
@@ -83,7 +204,7 @@ function seedCommandFor(file, mode) {
  *                     envContents, openCommand, commands, seedCommands,
  *                     setupCommands, attached }
  */
-function planUp(spec, alloc, config) {
+function planUp(spec, alloc, config, ctx) {
   const { slot, attached } = alloc
 
   // Per-spec escalation: bring Docker up only when this spec's Stack is `docker`,
@@ -143,7 +264,18 @@ function planUp(spec, alloc, config) {
     commands.push(`docker compose --project-name ${spec.projectName} up -d`)
   }
 
+  // The tree gate. A worktree forks from the base branch's tree, so an
+  // uncommitted spec would produce a branch missing the spec it is for — this is
+  // where that gets committed, or refused. Worktree mode had NO clean gate before
+  // this: `git worktree add` does not carry uncommitted changes anywhere, so the
+  // failure surfaced three steps later as a live-overlay refusal naming the wrong
+  // stage. An absent `ctx` means no caller looked, and changes nothing.
+  const gate = planSpecCommit(spec, ctx, config)
+
   return {
+    blocked: gate.blocked,
+    reason: gate.reason,
+    specCommit: gate.owned && gate.owned.length ? { paths: gate.owned, verb: gate.verb } : null,
     worktreePath: spec.worktreePath,
     branch: spec.branch,
     projectName: spec.projectName,
@@ -151,9 +283,9 @@ function planUp(spec, alloc, config) {
     portOffset: offset,
     envContents,
     openCommand,
-    commands,
-    seedCommands,
-    setupCommands,
+    commands: gate.blocked ? [] : [...gate.commands, ...commands],
+    seedCommands: gate.blocked ? [] : seedCommands,
+    setupCommands: gate.blocked ? [] : setupCommands,
     attached,
   }
 }
@@ -196,12 +328,10 @@ function planCheckoutUp(spec, ctx, config) {
   if (ctx.current && ctx.current === spec.branch) {
     return { ...result, attached: true }
   }
-  if (!ctx.clean) {
-    return block(
-      'the primary checkout has uncommitted changes — commit or stash them first ' +
-        '(switching would carry them onto the new branch)',
-    )
-  }
+  // Same gate as worktree mode, but `git switch -c` genuinely CARRIES uncommitted
+  // work onto the new branch, so the refusal keeps saying so.
+  const gate = planSpecCommit(spec, ctx, config, { carriesChanges: true })
+  if (gate.blocked) return block(gate.reason)
   if (!ctx.onBase) {
     return block(
       `the primary checkout is on ${ctx.current || '(detached)'}, not ${base} — ` +
@@ -209,10 +339,14 @@ function planCheckoutUp(spec, ctx, config) {
     )
   }
 
+  if (gate.owned && gate.owned.length) {
+    result.specCommit = { paths: gate.owned, verb: gate.verb }
+  }
+  result.commands.push(...gate.commands)
   result.commands.push(
     ctx.branchExists ? `git switch ${spec.branch}` : `git switch -c ${spec.branch}`,
   )
   return result
 }
 
-module.exports = { planUp, planCheckoutUp, seedCommandFor, worktreeCd }
+module.exports = { planUp, planCheckoutUp, planSpecCommit, seedCommandFor, worktreeCd }

package/src/env/resolve.js

@@ -267,6 +267,7 @@ module.exports = {
   repoInfo,
   expandTokens,
   findSpecFolder,
+  readFrontmatterField,
   readStackField,
   readBaseVersionField,
 }