@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/deprecate.js

@@ -0,0 +1,138 @@
+'use strict'
+
+// Cleanup path for projects that installed release tooling from an older
+// skitterspec (before it moved to @skitterbyte/skittership). `skitterspec update`
+// detects the leftover files and — only on an explicit interactive "yes" or the
+// --remove-release-tooling flag — removes exactly what skitterspec used to
+// install. It never touches the user's generated CHANGELOG.md / RELEASES.md, nor
+// any script it didn't add.
+
+const fs = require('fs')
+const path = require('path')
+
+const SKITTERSHIP = '@skitterbyte/skittership'
+
+// Files/dirs skitterspec used to install for release tooling (repo-relative).
+const RELEASE_PATHS = [
+  'skitterspec.config.json',
+  path.join('scripts', 'generate-changelog.js'),
+  path.join('scripts', 'generate-releases.js'),
+  path.join('scripts', 'lib', 'git-commits.js'),
+  path.join('scripts', 'lib', 'config.js'),
+  path.join('.claude', 'skills', 'commit'),
+  path.join('.claude', 'rules', 'commit-messages.md'),
+]
+
+// npm scripts skitterspec used to wire; only removed when their value still
+// matches the generator command (so a user's custom override is preserved).
+const HELPER_SCRIPTS = {
+  changelog: 'node scripts/generate-changelog.js',
+  'changelog:retro': 'node scripts/generate-changelog.js --retro',
+  releases: 'node scripts/generate-releases.js',
+  'releases:retro': 'node scripts/generate-releases.js --retro',
+}
+
+function readPkg(dir) {
+  const pkgPath = path.join(dir, 'package.json')
+  if (!fs.existsSync(pkgPath)) return null
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+// Does package.json have a `version` script that runs the release generators?
+function versionHookReferencesGenerators(pkg) {
+  const v = pkg && pkg.scripts && pkg.scripts.version
+  return typeof v === 'string' && /generate-(changelog|releases)\.js/.test(v)
+}
+
+// Is skittership the source of the release tooling here (rather than a leftover
+// legacy skitterspec install)? True when the project has adopted skittership —
+// its config file is present, or it's a declared dependency. In that case the
+// release files are skittership's current install and must NOT be offered for
+// removal (they'd just come back on the next `skittership init`).
+function skittershipAdopted(dir) {
+  if (fs.existsSync(path.join(dir, 'skittership.config.json'))) return true
+  const pkg = readPkg(dir)
+  const deps = Object.assign({}, pkg && pkg.dependencies, pkg && pkg.devDependencies)
+  return Boolean(deps['@skitterbyte/skittership'])
+}
+
+// Report which release-tooling artifacts are present. `present` is true only when
+// there are legacy artifacts to clean up (a file/dir or a generator-driven version
+// hook) AND skittership hasn't been adopted — otherwise the files belong to a
+// live skittership install, not an old bundled-skitterspec one.
+function detectReleaseTooling(dir) {
+  const files = RELEASE_PATHS.filter((rel) => fs.existsSync(path.join(dir, rel)))
+  const pkg = readPkg(dir)
+  const versionHook = versionHookReferencesGenerators(pkg)
+  const adopted = skittershipAdopted(dir)
+  return { present: (files.length > 0 || versionHook) && !adopted, files, versionHook, adopted }
+}
+
+// Remove an emptied directory, walking up while parents are left empty. Never
+// climbs out of `dir`.
+function pruneEmptyDirs(dir, startAbs) {
+  let cur = startAbs
+  while (cur.startsWith(dir) && cur !== dir && fs.existsSync(cur)) {
+    if (fs.readdirSync(cur).length > 0) break
+    fs.rmdirSync(cur)
+    cur = path.dirname(cur)
+  }
+}
+
+// Remove exactly the detected artifacts + unwire the version hook. Returns a
+// report of what was removed. Scoped and non-destructive: only skitterspec's own
+// files, and only npm scripts whose value still matches the generator command.
+function removeReleaseTooling(dir, detection = detectReleaseTooling(dir)) {
+  const removed = []
+
+  for (const rel of detection.files) {
+    const abs = path.join(dir, rel)
+    if (!fs.existsSync(abs)) continue
+    fs.rmSync(abs, { recursive: true, force: true })
+    removed.push(rel)
+    pruneEmptyDirs(dir, path.dirname(abs))
+  }
+
+  const pkg = readPkg(dir)
+  if (pkg && pkg.scripts) {
+    let changed = false
+    if (versionHookReferencesGenerators(pkg)) {
+      delete pkg.scripts.version
+      removed.push('package.json (version hook)')
+      changed = true
+    }
+    for (const [name, cmd] of Object.entries(HELPER_SCRIPTS)) {
+      if (pkg.scripts[name] === cmd) {
+        delete pkg.scripts[name]
+        changed = true
+      }
+    }
+    if (changed) {
+      if (Object.keys(pkg.scripts).length === 0) delete pkg.scripts
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n')
+    }
+  }
+
+  return { removed }
+}
+
+// One-line pointer shown when we detect release tooling but don't remove it
+// (declined, or a non-interactive run).
+function releaseToolingNotice() {
+  return (
+    `Release tooling has moved to ${SKITTERSHIP} — run ` +
+    `npx ${SKITTERSHIP} init to keep it (your config is migrated automatically).`
+  )
+}
+
+module.exports = {
+  detectReleaseTooling,
+  removeReleaseTooling,
+  releaseToolingNotice,
+  RELEASE_PATHS,
+  SKITTERSHIP,
+}

package/src/env/bootstrap.js

@@ -0,0 +1,188 @@
+'use strict'
+
+/**
+ * Run a worktree's bootstrap steps — the engine half of `spec-env bootstrap`.
+ *
+ * `planUp` decides WHAT a fresh worktree needs (`worktreeSteps`); this module
+ * does it. Seeds and the env file are plain filesystem work, done here with
+ * `fs` and no shell at all. `setup` commands and the stack are spawned with the
+ * worktree as their cwd.
+ *
+ * WHY THE ENGINE RUNS THEM. These steps used to be printed as shell for the
+ * agent to run, and an agent does not copy shell faithfully. A consumer's
+ * secrets hook refuses any Bash call naming a `.env` file, with one exception
+ * for the exact printed shape — so every rewrite was refused, and the retry was
+ * refused again by auto mode as a workaround. The call that replaces them,
+ * `skitterspec spec-env bootstrap <name>`, names no file at all.
+ *
+ * Behaviour is the printed commands' behaviour, kept exactly: idempotent, one
+ * `seeded …` / `… — skipped` line per seed, a seed missing from the primary
+ * checkout is skipped rather than failed, a symlinked env file is refused before
+ * anything is written through it, and the run stops at the first failing step.
+ *
+ * Every side effect goes through `io`, so the tests drive it with a real temp
+ * directory and a fake spawn — no docker, no package manager.
+ */
+
+const realFs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+/** One line describing a step, for `--plan` and for the failure report. */
+function describeStep(step) {
+  switch (step.kind) {
+    case 'seed':
+      return `seed ${step.file} (${step.mode} from the primary checkout)`
+    case 'envFile':
+      return `env file ${step.file} (COMPOSE_PROJECT_NAME, PORT_OFFSET)`
+    case 'setup':
+      return `setup: ${step.command}`
+    case 'docker':
+      return `docker: ${step.argv.join(' ')}`
+    default:
+      return `unknown step ${step.kind}`
+  }
+}
+
+// `lstat` that answers null for a missing path rather than throwing.
+function lstatOrNull(fs, p) {
+  try {
+    return fs.lstatSync(p)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Seed one gitignored file from the primary checkout.
+ *
+ * The source is tested with `existsSync`, which follows links — a dangling
+ * link in the primary checkout is "not in main", exactly as `[ -e ]` read it.
+ * The target is tested with `lstat`, which does not: an existing link, even a
+ * dangling one, is somebody's deliberate state and is left alone.
+ */
+function runSeed(step, { cwd, mainRoot, fs }) {
+  const src = path.join(mainRoot, step.file)
+  const dst = path.join(cwd, step.file)
+  if (!fs.existsSync(src)) {
+    return { outcome: 'skipped', line: `seed ${step.file}: not in main — skipped` }
+  }
+  if (lstatOrNull(fs, dst)) {
+    return { outcome: 'skipped', line: `seed ${step.file}: exists — skipped` }
+  }
+  fs.mkdirSync(path.dirname(dst), { recursive: true })
+  if (step.mode === 'copy') fs.copyFileSync(src, dst)
+  else fs.symlinkSync(src, dst)
+  return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
+}
+
+/**
+ * Make sure the spec's env file sets its project name and port block.
+ *
+ * Additive: a key is appended only when no line already sets it, so a re-run
+ * writes nothing and a file `setup` already wrote to keeps every value it holds
+ * — a deliberate `PORT_OFFSET` of its own included.
+ *
+ * A SYMLINK IS REFUSED, before anything is written. Seeding links gitignored
+ * files from the primary checkout, so a seeded env file IS the primary
+ * checkout's own, and appending through it would write this spec's port block
+ * into the main stack's configuration. The fix is a `docker.envFile` naming a
+ * file of its own.
+ */
+function runEnvFile(step, { cwd, fs }) {
+  const p = path.join(cwd, step.file)
+  const st = lstatOrNull(fs, p)
+  if (st && st.isSymbolicLink()) {
+    return {
+      outcome: 'refused',
+      line:
+        `env file ${step.file} is a symlink — docker.envFile must name a file of its own, ` +
+        "not a seeded one; refusing to write this spec's port block through it",
+    }
+  }
+  const before = st ? fs.readFileSync(p, 'utf8') : ''
+  let add = ''
+  // A file without a trailing newline would glue the first appended key onto
+  // its last line.
+  const sep = before.length && !before.endsWith('\n') ? '\n' : ''
+  for (const [key, value] of [
+    ['COMPOSE_PROJECT_NAME', step.projectName],
+    ['PORT_OFFSET', step.offset],
+  ]) {
+    if (!new RegExp(`^${key}=`, 'm').test(before)) add += `${key}=${value}\n`
+  }
+  if (!st || add) {
+    fs.mkdirSync(path.dirname(p), { recursive: true })
+    fs.writeFileSync(p, before + (add ? sep + add : ''))
+  }
+  return { outcome: add ? 'written' : 'skipped', line: `env file ${step.file}: ready` }
+}
+
+/**
+ * Spawn a setup command (through the shell — it is the project's own command
+ * line) or the stack (an argv, no shell).
+ *
+ * `stdout` is where the child's own output goes: inherited normally, so an
+ * install streams as it runs, and moved to stderr under `--json` so the payload
+ * on stdout stays parseable.
+ */
+function runSpawned(step, { cwd, spawn, childStdout }) {
+  const stdio = ['ignore', childStdout, 'inherit']
+  const res =
+    step.kind === 'setup'
+      ? spawn(step.command, { cwd, shell: true, stdio })
+      : spawn(step.argv[0], step.argv.slice(1), { cwd, stdio })
+  if (res.error) {
+    return { outcome: 'failed', line: `${describeStep(step)} — ${res.error.message}` }
+  }
+  if (res.status !== 0) {
+    const why = res.status === null ? `killed by ${res.signal || 'a signal'}` : `exit ${res.status}`
+    return { outcome: 'failed', line: `${describeStep(step)} — ${why}` }
+  }
+  return { outcome: 'ran', line: null }
+}
+
+/**
+ * Run `steps` in order in `cwd`, stopping at the first that fails.
+ *
+ * io: { cwd, mainRoot, fs?, spawn?, write?, childStdout? }
+ *   - `write(line)` receives every report line as it happens
+ *   - `childStdout` is the stdio slot for spawned output ('inherit' default)
+ *
+ * Returns { ok, results: [{ step, outcome, line }], failedAt } — `failedAt` is
+ * the 1-based index of the step that stopped the run, or null.
+ */
+function runBootstrap(steps, io) {
+  const ctx = {
+    cwd: io.cwd,
+    mainRoot: io.mainRoot,
+    fs: io.fs || realFs,
+    spawn: io.spawn || spawnSync,
+    childStdout: io.childStdout || 'inherit',
+  }
+  const write = io.write || (() => {})
+  const results = []
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]
+    // A spawned step announces itself BEFORE it runs, so the streamed output
+    // that follows has a heading.
+    if (step.kind === 'setup' || step.kind === 'docker') write(describeStep(step))
+    let r
+    try {
+      if (step.kind === 'seed') r = runSeed(step, ctx)
+      else if (step.kind === 'envFile') r = runEnvFile(step, ctx)
+      else if (step.kind === 'setup' || step.kind === 'docker') r = runSpawned(step, ctx)
+      else r = { outcome: 'failed', line: describeStep(step) }
+    } catch (err) {
+      r = { outcome: 'failed', line: `${describeStep(step)} — ${err.message}` }
+    }
+    results.push({ step, ...r })
+    if (r.line && r.outcome !== 'failed' && r.outcome !== 'refused') write(r.line)
+    if (r.outcome === 'failed' || r.outcome === 'refused') {
+      return { ok: false, results, failedAt: i + 1 }
+    }
+  }
+  return { ok: true, results, failedAt: null }
+}
+
+module.exports = { runBootstrap, describeStep }

package/src/env/building.js

@@ -0,0 +1,143 @@
+'use strict'
+
+/**
+ * The primary-checkout leak guard.
+ *
+ * A phase can be built in a worktree from a session standing somewhere else —
+ * every write an absolute path, every command `cd`-prefixed. That works;
+ * `spec-env review` already reads a worktree exactly that way. What it cannot do
+ * is *prove* it worked: one relative path and the edit lands in the primary
+ * checkout, on the base branch, silently.
+ *
+ * So record what the primary checkout looked like before the build
+ * (`--record-primary`) and compare after it (`--assert-primary-clean`).
+ *
+ * The baseline is the whole point. `negative-checks.md` rule 1 asks for a
+ * positive signal rather than an absence, and "these were the dirty paths at a
+ * known moment" is one; a bare "the primary must be clean" check would accuse
+ * anyone who left an unrelated edit open in another window. Rule 4 supplies the
+ * third state: when the baseline is missing, or is for another spec, the check
+ * cannot tell — and cannot-tell reports and exits 0 rather than accusing.
+ */
+
+const path = require('node:path')
+
+// The state dir sits beside the registry file, e.g. `.spec-env` — the same
+// convention `dev.js` uses for logs and pids.
+function stateDir(config) {
+  return path.posix.dirname(config.registry) || '.spec-env'
+}
+
+/** Where the baseline lives. Gitignored with the rest of `.spec-env/`. */
+function baselinePath(dir, config) {
+  return path.join(dir, stateDir(config), 'building.json')
+}
+
+/**
+ * Merge one or more newline-separated git path listings into a sorted, deduped
+ * array. Blank lines are dropped; nothing is parsed out of the line.
+ *
+ * DELIBERATELY NOT `git status --porcelain`, for two reasons, both found by
+ * running this against a real worktree:
+ *
+ *   1. Porcelain puts the path behind two fixed status columns and a space, and
+ *      the repo's `gitReader` TRIMS its stdout — so the first line loses its
+ *      leading space and a fixed `slice(3)` eats the first character of the
+ *      first path. A guard that renames the file it is accusing you of is worse
+ *      than no guard.
+ *   2. Porcelain reports stat-dirty entries: a file whose mtime moved but whose
+ *      content is identical to HEAD. One was observed here, reported as ` M`
+ *      with an empty `git diff`. Accusing someone of leaking a file they never
+ *      changed is exactly the false accusation `negative-checks.md` exists to
+ *      prevent.
+ *
+ * `git diff --name-only HEAD` compares CONTENT, and
+ * `git ls-files --others --exclude-standard` lists genuinely new files. Between
+ * them they answer "what did this tree gain?" without a column to miscount.
+ */
+function mergePaths(...listings) {
+  const out = new Set()
+  for (const listing of listings) {
+    for (const line of String(listing || '').split('\n')) {
+      const p = line.replace(/\r$/, '').trim()
+      if (p !== '') out.add(p)
+    }
+  }
+  return [...out].sort()
+}
+
+/** Are these two paths the same tree? */
+function sameTree(a, b) {
+  return path.resolve(a) === path.resolve(b)
+}
+
+/** The record written by `--record-primary`. Pure. */
+function buildBaseline({ spec, worktreePath, primary, paths }) {
+  return { spec, worktreePath, primary, paths: [...paths].sort() }
+}
+
+/**
+ * Compare a recorded baseline against the primary checkout's current state.
+ *
+ * Three verdicts, never two (`negative-checks.md` rule 4):
+ *   - `clean`   — nothing new appeared; say nothing and exit 0.
+ *   - `leaked`  — these paths appeared since; name them and exit non-zero.
+ *   - `unknown` — the check cannot tell; say why and exit 0.
+ *
+ * Pure: every input is supplied, nothing is read from disk or git.
+ *
+ * WHAT WOULD FOOL THIS CHECK, deliberately unhandled:
+ *   - Work the build COMMITTED in the primary checkout. A commit empties the
+ *     porcelain, so a leak that was tidied away looks identical to no leak. The
+ *     guard is aimed at the actual failure mode — writes going astray mid-build,
+ *     while nothing has been committed yet — and runs before the phase commit
+ *     for that reason.
+ *   - A write to a GITIGNORED path in the primary (`.spec-env/` itself, build
+ *     output, `node_modules`). `git status` cannot see it, by design, and the
+ *     baseline file lives in exactly such a path so that recording it is not
+ *     itself a change the next comparison trips over.
+ *   - A path dirty at record time and then edited FURTHER by the build. It is in
+ *     the baseline, so it stays silent. That is the deliberate trade: silence
+ *     there costs a missed edit to a file someone was already working on, and
+ *     the opposite default accuses every healthy concurrent edit.
+ */
+function compare(baseline, currentPaths, { spec, worktreePath, primary }) {
+  if (sameTree(primary, worktreePath)) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: 'the worktree IS the primary checkout — there is no second tree to leak into',
+    }
+  }
+  if (!baseline) {
+    return { verdict: 'unknown', paths: [], reason: 'no baseline recorded' }
+  }
+  if (baseline.spec !== spec) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: `the baseline was recorded for ${baseline.spec}, not ${spec}`,
+    }
+  }
+  if (!sameTree(baseline.worktreePath, worktreePath)) {
+    return {
+      verdict: 'unknown',
+      paths: [],
+      reason: 'the baseline records a different worktree for this spec',
+    }
+  }
+  const before = new Set(baseline.paths || [])
+  const appeared = [...currentPaths].filter((p) => !before.has(p)).sort()
+  return appeared.length === 0
+    ? { verdict: 'clean', paths: [], reason: null }
+    : { verdict: 'leaked', paths: appeared, reason: null }
+}
+
+module.exports = {
+  stateDir,
+  baselinePath,
+  mergePaths,
+  sameTree,
+  buildBaseline,
+  compare,
+}

package/src/env/classify.js

@@ -0,0 +1,176 @@
+'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
+    // NO PATH IS CANNOT-TELL, not an error. Callers hand in spec objects of two
+    // shapes: `resolveSpec` returns a full one, and `allSpecs` returns
+    // `{folder, slug, worktreePath}` with no `path` at all. Reading the
+    // frontmatter of `undefined` threw, and the throw surfaced as
+    // `render failed: The "path" argument must be of type string` on the review
+    // server's index — every spec, not just one.
+    //
+    // It routes to the same answer a missing identifier already routes to:
+    // expand nothing, so the pattern matches nothing and the path is not
+    // claimed as this spec's. Being wrong here costs a companion file left
+    // unstaged; throwing cost the whole page.
+    const identifier = spec.path ? readFrontmatterField(spec.path, field) : null
+    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 }
+}
+
+// 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
+}
+
+/**
+ * A spec's own uncommitted documents in one tree: `{tree, owned}`, or a reason.
+ *
+ * SHARED ON PURPOSE. Two surfaces render a spec's documents — the CLI's
+ * `review --docs` and the review server's route for a spec with no worktree —
+ * and if they classified separately they could disagree about what the page
+ * shows. A reader's verdict is about the page they read, so the served page and
+ * the written page have to be the same page.
+ *
+ * Three states, never two (`.claude/rules/negative-checks.md` rule 4). An
+ * unreadable git is `cannot tell`, and must not collapse into an empty file
+ * set: an empty set renders a page saying nothing changed, which is the one
+ * reading that is certainly wrong.
+ *
+ * WHAT WOULD FOOL THIS: a document of this spec's that is already committed.
+ * `dirtyPaths` answers about the uncommitted tree only, so a spec whose files
+ * are all committed reports `empty` rather than showing its own text. That is
+ * the intended reading — there is no change to review — and it is why `empty`
+ * is a distinct answer rather than an error.
+ *
+ * @returns {{tree: string, owned: string[]}|{error: string}|{empty: true}}
+ */
+function specDocsIn(tree, spec, config, git) {
+  const paths = dirtyPaths(git)
+  if (paths === null) return { error: 'git could not be read' }
+  const { owned } = classifyDirtyTree(spec, paths, config)
+  if (!owned.length) return { empty: true }
+  return { tree, owned }
+}
+
+module.exports = { classifyDirtyTree, expandCompanion, unquotePath, dirtyPaths, specDocsIn }