@skitterbyte/skitterspec 22.0.0 → 22.1.0

package/src/env/serve.js

@@ -36,8 +36,9 @@ const {
   resolveSpec,
   resolveBaseBranch,
 } = require('./resolve.js')
+const { readRegistry } = require('./registry.js')
 const { loadEnvConfig } = require('./config.js')
-const { specDocsIn } = require('./classify.js')
+const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
 const { liveStateFor } = require('./live.js')
 const {
   rawGitReader,
@@ -52,6 +53,8 @@ const {
   addPending,
   readNotes,
   readGate,
+  readRenderRecord,
+  DEFAULT_BUTTON_SET,
 } = require('./review.js')
 
 /**
@@ -195,6 +198,23 @@ ${body}
  * spec with no worktree BY DEFINITION, so gating the route on a worktree
  * excludes precisely the specs the docs view exists for.
  */
+/**
+ * Is this worktree a spec being WRITTEN rather than built?
+ *
+ * Returns the owned document paths when it is, and null for every other
+ * answer — including the ones we cannot work out. Never throws: a page is a
+ * convenience and a git that will not read is not evidence of anything.
+ */
+function docsWorktree(wt, spec, config) {
+  if (!spec || spec.bucket !== 'backlog') return null
+  const paths = dirtyPaths(trimmedGitReader(wt))
+  // Cannot tell — not "no documents".
+  if (paths === null) return null
+  const { owned, foreign } = classifyDirtyTree(spec, paths, config)
+  if (!owned.length || foreign.length) return null
+  return { owned }
+}
+
 function viewFor(dir, config, spec, git, { fallback = false } = {}) {
   if (!spec) return null
   // LIVE COMES FIRST, because while a spec is live its worktree still exists —
@@ -203,7 +223,34 @@ function viewFor(dir, config, spec, git, { fallback = false } = {}) {
   // here too, so this checkout is the tree that answers.
   if (spec.branch && headBranchOf(git) === spec.branch) return { kind: 'live', tree: dir }
   const wt = spec.worktreePath
-  if (wt && wt !== dir && fs.existsSync(wt)) return { kind: 'worktree', tree: wt }
+  if (wt && wt !== dir && fs.existsSync(wt)) {
+    // A DOCS WORKTREE IS NOT A CODE WORKTREE, and this used to be unreachable.
+    //
+    // `/spec` once wrote into the primary checkout, so a backlog spec had no
+    // worktree at all and fell through to the docs branch below. It now
+    // provisions the spec's own `--docs` worktree and writes there — so this
+    // check began winning for exactly the specs the docs branch exists to
+    // serve, and their pages were served the COMMITTING set. A reader pressed
+    // `Commit & Continue` on a backlog spec that has no phase to continue.
+    //
+    // Asked as a POSITIVE SIGNAL and never as "no code yet"
+    // (`.claude/rules/negative-checks.md` rule 1), and it takes BOTH halves:
+    //
+    //   - the spec is in the BACKLOG, which is what `authoring` means. Without
+    //     this, the window right after `/spec-start` — where the `git mv` and
+    //     the header edit are uncommitted and no phase code exists yet — reads
+    //     as documents-only and would offer `Commit & Start` for a spec
+    //     already in flight.
+    //   - the worktree holds NOTHING BUT this spec's own documents. Without
+    //     this, a backlog spec whose tree had been used for anything else
+    //     would have that work rendered under an authoring verdict.
+    //
+    // Anything else is the ordinary worktree view, including every cannot-tell:
+    // an unresolvable bucket, a git that will not read, an empty tree.
+    const docs = docsWorktree(wt, spec, config)
+    if (docs) return { kind: 'docs', tree: wt, owned: docs.owned }
+    return { kind: 'worktree', tree: wt }
+  }
   const found = specDocsIn(dir, spec, config, trimmedGitReader(dir))
   // `error` is cannot-tell — not a page, and not an error page either (rule 4:
   // the harmless branch).
@@ -303,9 +350,12 @@ function trimmedGitReader(treePath) {
  * IT INCLUDES WORKTREE-LESS SPECS NOW, and both halves are needed together: a
  * page that serves but is absent from the index is a page nobody finds.
  */
-function servableSpecs(dir, config, git) {
+function servableSpecs(dir, config, git, specless = {}) {
   const worktreePaths = liveWorktreePaths(git)
-  return allSpecs(dir, config, worktreePaths)
+  // `allSpecs` scans `specs/**`, where a specless branch is by definition not —
+  // so it takes the registry's map and adds them. Defaulted to empty, because
+  // every caller that has no concept of them should behave exactly as before.
+  return allSpecs(dir, config, worktreePaths, specless)
     .filter((s) => Boolean(viewFor(dir, config, s, git)))
     .sort((a, b) => a.folder.localeCompare(b.folder))
 }
@@ -368,13 +418,65 @@ function receivePass(dir, config, spec, blob) {
   return { code: added.code, accepted: parsed.accepted.length, comments: parsed.comments.length }
 }
 
+/**
+ * The button set a SERVED page shows.
+ *
+ * Two sources, and each answers only what it knows.
+ *
+ * THE TREE ANSWERS THE FAMILY, and it answers it better than any record can,
+ * because a record is as old as the last render while the tree is now. A spec's
+ * uncommitted documents are `authoring`; a branch with no spec at all is
+ * `nospec`; a phase in a worktree is `committing`. Those three are exactly the
+ * sets that describe what the work IS, so they are read off what the work is.
+ *
+ * THE RECORD ANSWERS WHETHER THE RUN HAD FINISHED, which no tree can show.
+ * `midrun` and `refresh` exist for that — one offers `Continue` in place of the
+ * committing pair, the other drops the start verdict — and only the caller that
+ * rendered knew. So they, and nothing else, are taken from the record.
+ *
+ * WHICH MAKES THE RECORD NARROWING-ONLY. A word it does not recognise, a word
+ * that would WIDEN the offer, an unreadable file, no file at all: every one of
+ * them falls through to the tree (`.claude/rules/negative-checks.md` rule 4).
+ * The cost of a stale record is therefore a reader shown `Continue` where they
+ * could have been shown `Commit` — one refresh away from the right page — and
+ * never a specless branch handed a `Commit & Start` for a spec that does not
+ * exist. That was the bug: `renderSpecPage` took `{ branch }` and no set at all,
+ * so every `/no-spec` page served over http offered to put nothing in flight,
+ * and the pass came back naming a verdict its own skill could not act on.
+ */
+const NARROWING_SETS = ['midrun', 'refresh']
+
+function buttonsForView(viewKind, spec, recorded) {
+  if (NARROWING_SETS.includes(recorded)) return recorded
+  if (viewKind === 'docs' || viewKind === 'docs-committed') return 'authoring'
+  if (spec && spec.specless) return 'nospec'
+  return DEFAULT_BUTTON_SET
+}
+
+// What the last CLI render of this spec declared, or null when it declared
+// nothing readable. Never throws: the page is a convenience, and a sidecar is
+// not what it is for.
+function recordedButtons(dir, spec) {
+  try {
+    return readRenderRecord(reviewOutPath(dir, spec.folder, null), spec.folder).buttons
+  } catch {
+    return null
+  }
+}
+
 function renderSpecPage(dir, config, spec, { branch = false } = {}) {
   const view = viewFor(dir, config, spec, rawGitReader(dir), { fallback: true })
   if (!view) return null
 
-  // THE DOCS VIEW IS A DIFFERENT TREE AND A DIFFERENT FILE SET, and it takes
-  // the authoring buttons: a spec with no worktree has no phase in flight, so
-  // "commit and build the next phase" is the wrong offer for it.
+  // Resolved once, for BOTH paths below. The docs path used to hard-code
+  // `authoring` here and everything else took the default by saying nothing —
+  // which is how a specless branch ended up offering `Commit & Start`.
+  const buttons = buttonsForView(view.kind, spec, recordedButtons(dir, spec))
+
+  // THE DOCS VIEW IS A DIFFERENT TREE AND A DIFFERENT FILE SET. Its buttons
+  // come from `buttonsForView` above like every other view's — it used to name
+  // `authoring` here itself, which was right for this one case and left every
+  // other case with no answer at all.
   if (view.kind === 'docs' || view.kind === 'docs-committed') {
     const docsGit = rawGitReader(view.tree)
     const out = reviewOutPath(dir, spec.folder, null)
@@ -391,7 +493,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
       now: new Date().toISOString(),
       notes,
       gate: gateRead.corrupt ? null : gateRead.gate,
-      buttons: 'authoring',
+      buttons,
       only: view.owned,
       treePath: view.tree,
     })
@@ -460,6 +562,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
     now,
     notes,
     gate,
+    buttons,
     live,
     tiers,
   })
@@ -468,6 +571,10 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
     const fallbackBase = base()
     const mergeBase = trimmed(['merge-base', fallbackBase, 'HEAD'])
     if (mergeBase) {
+      // THE SET SURVIVES THE FALLBACK, and forgetting it here is not a smaller
+      // version of the same mistake — it is the one that fires most. A clean
+      // worktree is the state a phase ENDS in: the page is rendered, the commit
+      // lands, and from then on every render of that spec comes through here.
       const wider = collectReview({
         spec,
         git,
@@ -477,6 +584,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
         now,
         notes,
         gate,
+        buttons,
         live,
         tiers,
         fellBack: true,
@@ -770,53 +878,55 @@ function staleServer(recorded, running, recordedMtime, runningMtime) {
   return 'current'
 }
 
-module.exports = {
-  mintToken,
-  readBody,
-  MAX_PASS_BYTES,
-  engineVersionFor,
-  staleServer,
-  specSummary,
-  viewFor,
-  headBranchOf,
-  pageTiers,
-  routeFor,
-  renderIndex,
-  servableSpecs,
-  renderSpecPage,
-  receivePass,
-  createReviewServer,
-  startReviewServer,
-}
-
-// Entry point: run detached by the CLI, reading its settings from a file so a
-// restart is a rewrite of that file — the same contract `proxy.js` uses. Only
-// `dir` is stored, never a snapshot of the specs: resolving per request is what
-// keeps a spec provisioned after the server started from being invisible to it.
-if (require.main === module) {
-  const settingsFile = process.argv[2]
-  if (!settingsFile) {
-    process.stderr.write('serve: usage: node serve.js <settingsFile>\n')
-    process.exit(1)
-  }
-  const { dir, port, host, token } = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'))
-  const { config } = loadEnvConfig(dir)
+/**
+ * The hooks `createReviewServer` needs, built once.
+ *
+ * WHY THIS IS A FUNCTION AND NOT INLINE IN THE ENTRY POINT. It used to be
+ * inline, and the test suite built its own copy the same way — so the two
+ * drifted independently, and a suite standing up its own wiring could be green
+ * about a server nobody was shipping. That is exactly what happened: both
+ * copies called `resolveSpec` with no `specless` map, every `/no-spec` page
+ * 404'd, and nothing failed.
+ *
+ * THE SPECLESS MAP IS THE POINT. A `/no-spec` branch has a worktree and a
+ * branch and no document anywhere under `specs/**`, so it can only ever be
+ * resolved on the registry's word — which is a POSITIVE SIGNAL, and the reason
+ * a typo still 404s (`.claude/rules/negative-checks.md` rule 1). Both resolvers
+ * already took it; the server simply never passed it.
+ */
+function serverHooks(dir, config) {
   const git = rawGitReader(dir)
   const trimmedGit = (argv) => {
     const out = git(argv)
     return out == null ? null : String(out).trim() || null
   }
 
+  // READ PER REQUEST, never cached. A branch provisioned after the daemon
+  // started must be servable without restarting it — the same reason `dir` is
+  // all the settings file stores. An unreadable registry is cannot-tell and
+  // yields an empty map: the specless branches lose their pages, and every
+  // ordinary spec carries on being served.
+  const specless = () => {
+    try {
+      return readRegistry(dir, config).specless || {}
+    } catch {
+      return {}
+    }
+  }
+
   const resolveOne = (folder) => {
     try {
-      return resolveSpec(folder, dir, config, { searchDirs: [...liveWorktreePaths(trimmedGit)] })
+      return resolveSpec(folder, dir, config, {
+        searchDirs: [...liveWorktreePaths(trimmedGit)],
+        specless: specless(),
+      })
     } catch {
       return null
     }
   }
 
   const resolveEntries = () =>
-    servableSpecs(dir, config, trimmedGit).map((s) => {
+    servableSpecs(dir, config, trimmedGit, specless()).map((s) => {
       const one = resolveOne(s.folder)
       return {
         folder: s.folder,
@@ -825,7 +935,7 @@ if (require.main === module) {
       }
     })
 
-  const server = createReviewServer({
+  return {
     resolveEntries,
     render: (folder, opts) => renderSpecPage(dir, config, resolveOne(folder), opts),
     receive: (folder, blob) => receivePass(dir, config, resolveOne(folder), blob),
@@ -837,8 +947,43 @@ if (require.main === module) {
       if (!one) return { state: 'unknown' }
       return readPassState(reviewOutPath(dir, one.folder, null), one.folder, code)
     },
-    token,
-  })
+  }
+}
+
+module.exports = {
+  mintToken,
+  readBody,
+  MAX_PASS_BYTES,
+  engineVersionFor,
+  staleServer,
+  specSummary,
+  viewFor,
+  headBranchOf,
+  pageTiers,
+  routeFor,
+  renderIndex,
+  servableSpecs,
+  serverHooks,
+  renderSpecPage,
+  buttonsForView,
+  receivePass,
+  createReviewServer,
+  startReviewServer,
+}
+
+// Entry point: run detached by the CLI, reading its settings from a file so a
+// restart is a rewrite of that file — the same contract `proxy.js` uses. Only
+// `dir` is stored, never a snapshot of the specs: resolving per request is what
+// keeps a spec provisioned after the server started from being invisible to it.
+if (require.main === module) {
+  const settingsFile = process.argv[2]
+  if (!settingsFile) {
+    process.stderr.write('serve: usage: node serve.js <settingsFile>\n')
+    process.exit(1)
+  }
+  const { dir, port, host, token } = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'))
+  const { config } = loadEnvConfig(dir)
+  const server = createReviewServer({ ...serverHooks(dir, config), token })
   startReviewServer(server, { port, host }).then(
     () => {},
     (err) => {

package/src/env/teardown.js

@@ -22,6 +22,7 @@
  */
 
 const { expandTokens } = require('./resolve.js')
+const { composeFileArg } = require('./provision.js')
 
 /**
  * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
@@ -64,6 +65,14 @@ function planDown(spec, config, flags, ctx) {
   // (Stack: worktree) has no stack/volumes even when the project master switch is
   // on — tearing it down is just removing the worktree. A spec resolved without an
   // explicit stack (legacy/tests) follows the master switch (pre-`Stack` behaviour).
+  //
+  // DELIBERATELY NOT GATED ON THE COMPOSE FILE, where `planUp` is. The two
+  // directions are not symmetric: bringing a stack up without evidence there is
+  // one to bring costs a failed provision, while skipping a `down` costs an
+  // orphaned stack and its volumes, still running, that nothing will come back
+  // for. So `up` needs a positive signal and `down` errs toward cleaning up —
+  // a `down` for a stack that was never started is a no-op (rule 4, pointing
+  // the other way because the harmless branch is the other branch).
   const stack = spec.stack || (config.docker.enabled ? 'docker' : 'worktree')
   const wantsDocker = stack === 'docker' && config.docker.enabled
 
@@ -86,7 +95,9 @@ function planDown(spec, config, flags, ctx) {
 
   // --- docker compose down (drop volumes unless kept) ---
   if (wantsDocker) {
-    const base = `docker compose --project-name ${spec.projectName} down`
+    const base =
+      `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
+      ` --project-name ${spec.projectName} down`
     commands.push(volumesDropped ? `${base} --volumes` : base)
   }
 

package/src/init.js

@@ -5,7 +5,7 @@ const path = require('path')
 const crypto = require('crypto')
 
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
-const { ensureReviewGateHook } = require('./env/hooks.js')
+const { ensureHooks } = require('./env/hooks.js')
 const { repoInfo, expandTokens } = require('./env/resolve.js')
 
 const ASSETS = path.join(__dirname, '..', 'assets')
@@ -93,14 +93,20 @@ const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled'
 // env.config isolation templates; a provider superset also ships its own).
 const CORE_FILES = listCoreTemplates()
 
-// The CLI is a local devDependency and never on PATH, so a command file that
-// pre-executes it must carry a literal, working invocation. Detect the runner
-// from the lockfile and bake it in at write time.
+// A command file pre-executes the CLI, so it must carry a literal invocation
+// that actually resolves in THIS project. Three installs are possible — local
+// dependency, global, or none — and the runner differs for each.
 //
-// The lockfile is a POSITIVE signal — a file that must be present for the answer
-// to be yes — rather than an absence. When none is found we do not guess a
-// package manager we have no evidence for; `npx` is the fallback because it is
-// the one runner that works across all three installs.
+// A LOCKFILE DOES NOT ANSWER THIS QUESTION. It says which runner would be used
+// *if* the CLI were installed here, which is a different thing, and reading it
+// as evidence of an install is inferring from an absence
+// (`.claude/rules/negative-checks.md` rule 1). It cost the non-Node case
+// outright: a project with no lockfile got `npx skitterspec` baked into every
+// command file, and the unscoped name `skitterspec` does not exist on npm, so
+// all four 404'd.
+//
+// So the lockfile keeps the job it is good at — picking the runner once a local
+// install is established — and a ladder decides whether there is one.
 const PACKAGE_MANAGERS = [
   ['pnpm-lock.yaml', 'pnpm exec'],
   ['yarn.lock', 'yarn'],
@@ -108,6 +114,8 @@ const PACKAGE_MANAGERS = [
   ['bun.lockb', 'bunx'],
 ]
 
+// Which runner would reach a LOCAL install here? Rung 1's answer only — it says
+// nothing about whether the CLI is present, which is `detectRunner`'s job.
 function detectPackageManager(dir) {
   for (const [lockfile, exec] of PACKAGE_MANAGERS) {
     if (fs.existsSync(path.join(dir, lockfile))) return exec
@@ -115,12 +123,97 @@ function detectPackageManager(dir) {
   return 'npx'
 }
 
+// The bin names a distribution may expose. A provider superset ships its own
+// name alongside `skitterspec`, and either proves the engine is reachable.
+const ENGINE_BINS = ['skitterspec', 'skitterspec-linear']
+
+function binNames() {
+  return process.platform === 'win32'
+    ? ENGINE_BINS.flatMap((n) => [n, `${n}.cmd`, `${n}.exe`])
+    : ENGINE_BINS
+}
+
+// Rung 1 — a local install, found by walking up. Bounded at 6 levels, matching
+// the hooks' own `findEngine`: a git worktree's checkout has its own
+// `node_modules`, and a monorepo package hoists to the root.
+function hasLocalInstall(dir) {
+  let at = path.resolve(dir)
+  for (let i = 0; i < 6; i++) {
+    for (const name of binNames()) {
+      if (fs.existsSync(path.join(at, 'node_modules', '.bin', name))) return true
+    }
+    const up = path.dirname(at)
+    if (up === at) break
+    at = up
+  }
+  return false
+}
+
+// An npx cache bin directory. Matched on the path SEGMENT, so a project that
+// happens to live under a directory called `_npxtools` is not mistaken for one.
+const NPX_CACHE_RE = /[\\/]_npx[\\/]/
+
+// Rung 2 — a global install, found on PATH.
+//
+// WHAT WOULD FOOL THIS, and why the filter is not optional: `npx` PREPENDS its
+// own cache bin directory to PATH for the processes it spawns. Verified, not
+// assumed. So running `npx @skitterbyte/skitterspec init` puts a `skitterspec`
+// on PATH that exists only for the duration of that one command — and probing
+// for it here would bake a bare `skitterspec …` into four COMMITTED files that
+// stop working the moment init exits. Excluding `_npx` entries is what makes
+// this rung evidence of an install rather than evidence of the install running.
+function hasPathInstall(env = process.env) {
+  const raw = env.PATH || env.Path || ''
+  if (!raw) return false
+  for (const entry of raw.split(path.delimiter)) {
+    if (!entry || NPX_CACHE_RE.test(entry)) continue
+    for (const name of binNames()) {
+      if (fs.existsSync(path.join(entry, name))) return true
+    }
+  }
+  return false
+}
+
+/**
+ * How should a command file invoke the CLI here?
+ *
+ * A positive-signal ladder: each rung asserts something that must be PRESENT,
+ * and only the last is a fallback.
+ *
+ *   local — a local install; the lockfile picks the runner
+ *   path  — a global install; no runner at all, the bin is invoked bare
+ *   none  — neither could be found. `npx` is written as before, and the caller
+ *           warns, because this is the cannot-tell case rather than a third
+ *           kind of install (rule 4: the unknown routes to the harmless branch,
+ *           which here is "write what we always wrote and say so").
+ *
+ * PROJECT-VISIBLE SIGNALS OUTRANK MACHINE-VISIBLE ONES, which is why `local` is
+ * checked first. `.claude/commands/*.md` is committed and `renderCommand` feeds
+ * `managedTargets`, so a render that varies by machine makes the file flip
+ * between pristine and updatable as different people run `update`. A lockfile
+ * is committed and answers the same everywhere; PATH is one machine's business.
+ */
+function detectRunner(dir, env = process.env) {
+  if (hasLocalInstall(dir)) return { runner: detectPackageManager(dir), rung: 'local' }
+  if (hasPathInstall(env)) return { runner: '', rung: 'path' }
+  return { runner: 'npx', rung: 'none' }
+}
+
 // Fill a command file's `{{exec}}` placeholders. Kept a pure function of
 // (content, dir) so `managedTargets` can compare against exactly what
 // `installCommands` would write — otherwise every install would hash as
 // customized on the next run.
+//
+// The token is consumed WITH its trailing space, so an empty runner leaves
+// `Bash(skitterspec …)` rather than `Bash( skitterspec …)`. The second pass
+// catches a bare `{{exec}}` in case a template ever lands without one.
 function renderCommand(content, dir) {
-  return content.split('{{exec}}').join(detectPackageManager(dir))
+  const { runner } = detectRunner(dir)
+  return content
+    .split('{{exec}} ')
+    .join(runner ? `${runner} ` : '')
+    .split('{{exec}}')
+    .join(runner)
 }
 
 // --- composed-assets guard -------------------------------------------------
@@ -425,6 +518,19 @@ function installCommands(dir, opts) {
     )
     writeFile(dir, path.join(dir, '.claude', 'commands', name), content, opts)
   }
+
+  // ONLY on the cannot-tell rung, and it warns rather than refusing: `init` has
+  // real work to do either way — skills, rules, folders — and none of it needs
+  // the CLI reachable later. Silence here is what let a project install cleanly
+  // and hand back four commands that 404 on first use.
+  if (COMMANDS.length && detectRunner(dir).rung === 'none') {
+    report.warnings.push(
+      `the skitterspec CLI could not be found here, so the ${COMMANDS.length} slash ` +
+        'command(s) were written to call `npx skitterspec`, which will fail — ' +
+        'install it (npm i -g @skitterbyte/skitterspec, or add it as a dev ' +
+        'dependency) and re-run `skitterspec update` to rewrite them',
+    )
+  }
 }
 
 function installRule(dir, opts) {
@@ -444,17 +550,20 @@ function installRule(dir, opts) {
 // reported and left alone, never rewritten, and never fatal — the hook is an
 // extra layer, and the engine and `/spec-next` hold the gate without it.
 function registerReviewGateHook(dir) {
-  const label = '.claude/settings.json (review-gate hook)'
+  // "hooks", plural, because two ship now — the review gate and the main guard.
+  // The label names the file and the subject rather than one script, so adding a
+  // third does not leave a report that undercounts what it wrote.
+  const label = '.claude/settings.json (skitterspec hooks)'
   let res
   try {
-    res = ensureReviewGateHook(dir)
+    res = ensureHooks(dir)
   } catch {
-    report.warnings.push('could not write .claude/settings.json — review-gate hook not registered')
+    report.warnings.push('could not write .claude/settings.json — skitterspec hooks not registered')
     return
   }
   if (res.reason === 'malformed') {
     report.warnings.push(
-      '.claude/settings.json is not valid JSON — did not register the review-gate hook',
+      '.claude/settings.json is not valid JSON — did not register the skitterspec hooks',
     )
   } else if (res.reason === 'created') {
     report.created.push(label)
@@ -465,9 +574,9 @@ function registerReviewGateHook(dir) {
     // that: rewriting the registered path and then reporting "already
     // registered" — a run that acts and says it did not, which is the shape of
     // the bug this whole change exists to fix.
-    report.updated.push('.claude/settings.json (review-gate hook repointed at the renamed script)')
+    report.updated.push('.claude/settings.json (skitterspec hooks repointed at the renamed script)')
   } else {
-    report.skipped.push('.claude/settings.json (review-gate hook already registered)')
+    report.skipped.push('.claude/settings.json (skitterspec hooks already registered)')
   }
 }
 
@@ -1004,5 +1113,6 @@ module.exports = {
   assertSafeToDelete,
   assertComposedAssets,
   detectPackageManager,
+  detectRunner,
   renderCommand,
 }