@skitterbyte/skitterspec-jira 0.0.0-stage → 1.0.0

package/src/env/supervise.js

@@ -0,0 +1,157 @@
+'use strict'
+
+/**
+ * Process-supervision IO for host dev servers — the side-effecting seam the CLI
+ * drives (the planning lives in the pure `dev.js`). Keeps `cli.js` thin and lets
+ * start/stop/health be exercised against a fixture server in tests.
+ *
+ * A "proc" here is one entry from `planDev(...).procs` (it carries `command`,
+ * `env`, `logFile`, `pidFile`, `health`). Log/pid paths are relative to the
+ * primary checkout root, resolved against `rootDir`.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawn } = require('node:child_process')
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+function resolveState(rootDir, rel) {
+  return path.resolve(rootDir, rel)
+}
+
+// Is `pid` a live process? `kill(pid, 0)` probes without signalling.
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    // EPERM → exists but not ours; still "alive" for our purposes.
+    return err.code === 'EPERM'
+  }
+}
+
+// Signal a detached process's whole group (its leader pid is `pid`, so the group
+// id is `-pid`) — reaches children like vite/tsc that a bare `pnpm dev` spawns.
+// Falls back to signalling just the leader if the group send fails.
+function signalGroup(pid, sig) {
+  try {
+    process.kill(-pid, sig)
+  } catch {
+    try {
+      process.kill(pid, sig)
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+// Read a pid from its file (absolute path). null when missing/malformed.
+function readPid(pidFileAbs) {
+  try {
+    const n = Number(fs.readFileSync(pidFileAbs, 'utf-8').trim())
+    return Number.isInteger(n) && n > 0 ? n : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Start one planned process detached, appending stdout+stderr to its log and
+ * writing its pid file. Idempotent: if the pid file already names a live
+ * process, nothing is spawned — returns `{ started: false, pid }`.
+ *
+ * `spawnImpl` is injectable for tests; defaults to child_process.spawn.
+ */
+function startProcess(proc, { cwd, rootDir, spawnImpl = spawn }) {
+  const logAbs = resolveState(rootDir, proc.logFile)
+  const pidAbs = resolveState(rootDir, proc.pidFile)
+
+  const existing = readPid(pidAbs)
+  if (existing && isAlive(existing)) {
+    return { started: false, pid: existing, logFile: logAbs, pidFile: pidAbs }
+  }
+
+  fs.mkdirSync(path.dirname(logAbs), { recursive: true })
+  fs.mkdirSync(path.dirname(pidAbs), { recursive: true })
+
+  const out = fs.openSync(logAbs, 'a')
+  try {
+    const child = spawnImpl('sh', ['-c', proc.command], {
+      cwd,
+      env: { ...process.env, ...proc.env },
+      detached: true,
+      stdio: ['ignore', out, out],
+    })
+    child.unref()
+    fs.writeFileSync(pidAbs, `${child.pid}\n`)
+    return { started: true, pid: child.pid, logFile: logAbs, pidFile: pidAbs }
+  } finally {
+    fs.closeSync(out)
+  }
+}
+
+/**
+ * Stop one planned process: SIGTERM its pid, wait up to `graceMs` for it to
+ * exit, then SIGKILL if still alive. Removes the pid file either way. Idempotent
+ * — a missing/dead pid is a clean no-op. Returns `{ stopped, pid }`.
+ */
+async function stopProcess(proc, { rootDir, graceMs = 3000, now = () => Date.now(), wait = sleep } = {}) {
+  const pidAbs = resolveState(rootDir, proc.pidFile)
+  const pid = readPid(pidAbs)
+  let stopped = false
+
+  if (pid && isAlive(pid)) {
+    signalGroup(pid, 'SIGTERM')
+    const deadline = now() + graceMs
+    while (now() < deadline && isAlive(pid)) await wait(100)
+    if (isAlive(pid)) signalGroup(pid, 'SIGKILL')
+    stopped = true
+  }
+
+  try {
+    fs.unlinkSync(pidAbs)
+  } catch {
+    /* no pid file → nothing to clean */
+  }
+  return { stopped, pid }
+}
+
+/**
+ * Poll `url` until it answers (any HTTP status counts as "up") or `timeoutMs`
+ * elapses. Returns true when reachable, false on timeout. A null/empty url means
+ * "no health gate" → true immediately. `fetchImpl`/`now`/`wait` are injectable
+ * for deterministic tests.
+ */
+async function waitHealthy(
+  url,
+  { timeoutMs = 30000, intervalMs = 500, fetchImpl = fetch, now = () => Date.now(), wait = sleep } = {},
+) {
+  if (!url) return true
+  const deadline = now() + timeoutMs
+  while (now() < deadline) {
+    try {
+      const ctrl = new AbortController()
+      const t = setTimeout(() => ctrl.abort(), intervalMs)
+      try {
+        await fetchImpl(url, { signal: ctrl.signal })
+        return true
+      } finally {
+        clearTimeout(t)
+      }
+    } catch {
+      /* not up yet */
+    }
+    await wait(intervalMs)
+  }
+  return false
+}
+
+// `signalGroup` is exported for TESTS that need to simulate a process dying.
+// Killing the recorded pid alone is not that simulation: the pid is the detached
+// `sh -c` leader, and where the shell forks rather than execs, the real server
+// is its child and survives. A test that reaches for `process.kill(pid, …)`
+// therefore kills the wrapper, leaves the server holding its port, and then
+// blames whatever it asserts next. Killing the group is what `stopProcess` does
+// and what a test must do to mean "it died".
+module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid, signalGroup }

package/src/env/teardown.js

@@ -0,0 +1,248 @@
+'use strict'
+
+/**
+ * Pure teardown planner for `spec-env down`.
+ *
+ * `planDown` evaluates the dirty/unpushed guards, plans an optional config-driven
+ * pre-drop backup, and returns the exact commands the `/spec-env-down` skill runs
+ * (`docker compose down` [+`--volumes`], `git worktree remove`). It performs no
+ * side effects: the caller (the CLI) queries git for `worktreeState` and supplies
+ * a `timestamp`, keeping this deterministic and unit-testable with no live
+ * git/docker.
+ *
+ * Volumes are the only destructive action — dropped by default (reclaims disk)
+ * unless `--keep-volumes`, and always backed up first when a `backupCommand` is
+ * configured.
+ *
+ * `commands` is safe for a caller to run BLIND — that is the property the remote
+ * delete must not break. A remote branch delete reaches outside this machine, so
+ * it is returned in a separate `remoteCommands` array that the skills confirm
+ * with the user before running, and it never enters `commands` unless the
+ * project has opted in with `teardown.deleteRemoteBranch: "always"`.
+ */
+
+const { expandTokens } = require('./resolve.js')
+const { composeFileArg } = require('./provision.js')
+
+/**
+ * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
+ * @param {object} config normalised env config.
+ * @param {object} flags { keepVolumes, force }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag,
+ *                     remoteBranch }, timestamp }
+ * @returns {object} { blocked, reason, commands, remoteCommands, backupCommand,
+ *                     backupPath, volumesDropped }
+ */
+function planDown(spec, config, flags, ctx) {
+  const { worktreeState = {}, timestamp } = ctx || {}
+  const force = Boolean(flags && flags.force)
+  const keepVolumes = Boolean(flags && flags.keepVolumes)
+
+  // A hotfix lands by tag + cherry-pick, so its branch is never an ancestor of
+  // base — but once its head is captured by a tag (the deploy tag from
+  // `hotfix land`), the commits are recoverable and the branch is safe to drop.
+  // Treat "reachable from a tag" as landed, alongside merged. Read twice below:
+  // it decides whether the unpushed guard blocks, and whether the branch delete
+  // can use `-D` — the same question ("are these commits recoverable?"), so the
+  // two must never answer it differently.
+  const landed = Boolean(worktreeState.merged || worktreeState.reachableFromTag)
+
+  // --- guards (overridable with --force) ---
+  if (!force) {
+    if (config.guards.refuseTeardownIfDirty && worktreeState.dirty) {
+      return blocked('worktree has uncommitted changes')
+    }
+    // Unpushed commits are only unsafe when they aren't already integrated into
+    // the base branch (or captured by a tag). A landed branch carries nothing to
+    // lose even with no remote — so /spec-complete's local land-then-teardown
+    // needs no --force. Block only when unpushed AND not landed.
+    if (config.guards.refuseTeardownIfUnpushed && worktreeState.unpushed && !landed) {
+      return blocked('worktree has unpushed commits not yet merged into the base branch')
+    }
+  }
+
+  // Docker teardown only applies to a Docker-escalated spec. A worktree-only spec
+  // (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
+
+  const commands = []
+  const volumesDropped = !keepVolumes && wantsDocker
+
+  // --- optional pre-drop backup (only when volumes are actually dropped) ---
+  let backupCommand = null
+  let backupPath = null
+  if (volumesDropped && config.docker.backupCommand) {
+    backupPath = `.spec-env/backups/${spec.slug}-${timestamp}.dump`
+    backupCommand = expandTokens(config.docker.backupCommand, {
+      backupPath,
+      slug: spec.slug,
+      projectName: spec.projectName,
+      timestamp: String(timestamp),
+    })
+    commands.push(backupCommand)
+  }
+
+  // --- docker compose down (drop volumes unless kept) ---
+  // Run from the primary checkout with no `--env-file`, unlike `up`, and on
+  // purpose: compose finds the stack's containers, networks and volumes by the
+  // project label `--project-name` gives it, so it needs nothing from the env
+  // file — which may already be gone with a half-removed worktree.
+  if (wantsDocker) {
+    const base =
+      `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
+      ` --project-name ${spec.projectName} down`
+    commands.push(volumesDropped ? `${base} --volumes` : base)
+  }
+
+  // --- remove the worktree (force needed if we bypassed a dirty guard) ---
+  commands.push(
+    force
+      ? `git worktree remove --force ${spec.worktreePath}`
+      : `git worktree remove ${spec.worktreePath}`,
+  )
+
+  // --- delete the branch ---
+  // Runs after the worktree remove frees the branch. `-D` exactly when we have
+  // PROVEN the commits survive the delete, `-d` otherwise.
+  //
+  // `-d` looks like the safe default and mostly is, but its refusal answers a
+  // different question from ours: it also declines a branch that is ahead of its
+  // upstream ref, reporting `not yet merged to refs/remotes/origin/<branch>,
+  // even though it is merged to HEAD`. That fires on the ordinary spec flow —
+  // it fires on any branch with an upstream ref whose later commits were landed
+  // locally rather than pushed — the shape you get the moment someone publishes a
+  // spec branch by hand, which is the only way one reaches a remote now. Teardown
+  // then meets a branch whose every commit is on `main` and `-d` refuses it.
+  //
+  // DO NOT "simplify" this back to `-d` on the grounds that nothing pushes at
+  // provisioning any more. That removed the COMMON case, not the case: one
+  // hand-published branch is enough, and `merged` already establishes what we
+  // care about more strongly than `-d` checks. `merged` (HEAD is an ancestor
+  // of base) already establishes what we actually care about, and establishes it
+  // more strongly than `-d` checks.
+  //
+  // `reachableFromTag` is the same argument for a hotfix: never an ancestor of
+  // base, but its head is captured by the deploy tag.
+  //
+  // Everything else keeps `-d`, so a forced teardown of a genuinely unlanded
+  // branch fails loudly and the skill relays it rather than -D-ing.
+  if (spec.branch) {
+    commands.push(`git branch ${landed ? '-D' : '-d'} ${spec.branch}`)
+  }
+
+  // --- delete the branch on the remote (planned, never run here) ---
+  //
+  // A hand-published spec branch otherwise leaves a merged branch on the remote
+  // forever. Cleaning that up is the goal; doing it safely is the constraint.
+  // Nothing publishes at provision time any more, so this plans a delete only for
+  // a branch the user pushed themselves — which is exactly when they want it.
+  //
+  // Gated on `landed` because until the branch is merged (or captured by a tag)
+  // the remote copy is the ONLY backup of the work — that is the whole reason
+  // `refuseTeardownIfUnpushed` exists, and deleting the remote branch of an
+  // unlanded spec would defeat it. `--force` deliberately does NOT enable this:
+  // force is for "I accept losing this worktree", not "also reach out and delete
+  // the backup". The same `landed` that decides `-D` vs `-d` decides this, so the
+  // two can never disagree about whether the commits are recoverable.
+  //
+  // A null `remoteBranch` plans nothing. An absence is not evidence — the branch
+  // may well be on a remote this clone cannot see (pushed from another machine),
+  // and the honest answer to "is there a remote branch?" is then "cannot tell",
+  // which routes to doing nothing.
+  const remoteCommands = []
+  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
+  if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
+    // `remoteBranch` is a short ref like "origin/feat/thing" and the branch name
+    // itself contains slashes, so the remote is what remains once the exact
+    // "/<branch>" suffix is stripped — not the text before the first slash.
+    //
+    // If it does not end that way the ref maps to a differently-named branch on
+    // the remote (a push refspec, or push.default set to something exotic). We
+    // cannot tell what to delete, so we plan nothing rather than guess at a
+    // branch name on someone's shared remote.
+    const suffix = `/${spec.branch}`
+    if (worktreeState.remoteBranch.endsWith(suffix)) {
+      const remote = worktreeState.remoteBranch.slice(0, -suffix.length)
+      if (remote) {
+        const cmd = `git push ${remote} --delete ${spec.branch}`
+        // "always" is the project saying it never wants to be asked, so the push
+        // joins the run-blind list. Everything else keeps it quarantined.
+        if (policy === 'always') commands.push(cmd)
+        else remoteCommands.push(cmd)
+      }
+    }
+  }
+
+  return {
+    blocked: false,
+    reason: null,
+    commands,
+    remoteCommands,
+    backupCommand,
+    backupPath,
+    volumesDropped,
+  }
+}
+
+function blocked(reason) {
+  return {
+    blocked: true,
+    reason,
+    commands: [],
+    remoteCommands: [],
+    backupCommand: null,
+    backupPath: null,
+    volumesDropped: false,
+  }
+}
+
+/**
+ * Pure teardown planner for CHECKOUT mode.
+ *
+ * There is no worktree to remove, no slot and no volumes — the only thing a
+ * finished spec leaves behind is its branch, and the checkout standing on it.
+ *
+ * Order is load-bearing: git refuses to delete the branch you are on, so the
+ * switch to base must come first. It is also what returns the checkout to a
+ * state the next `spec-env up` will accept.
+ *
+ * The same "are these commits recoverable?" question decides `-d` vs `-D`, and
+ * it is asked exactly as worktree-mode teardown asks it — a landed branch is
+ * safe to force-delete because its commits are on base (or under a tag); an
+ * unlanded one is not, and is refused rather than quietly dropped.
+ *
+ * ctx: { dirty, landed, onBranch, base, checkoutPath }
+ */
+function planDownCheckout(spec, config, flags, ctx) {
+  const { dirty, landed, onBranch, base, checkoutPath } = ctx || {}
+  const force = Boolean(flags && flags.force)
+  const result = { mode: 'checkout', blocked: false, reason: null, commands: [], branch: spec.branch }
+  const block = (reason) => ({ ...result, blocked: true, reason })
+
+  if (!force) {
+    if (config.guards.refuseTeardownIfDirty && dirty) {
+      return block('the checkout has uncommitted changes')
+    }
+    if (!landed) {
+      return block(`${spec.branch} is not merged into ${base} — landing it first is what makes the delete safe`)
+    }
+  }
+
+  const commands = []
+  if (onBranch !== false) commands.push(`git -C ${checkoutPath} switch ${base}`)
+  commands.push(`git -C ${checkoutPath} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
+  return { ...result, commands }
+}
+
+module.exports = { planDown, planDownCheckout }

package/src/env/trust.js

@@ -0,0 +1,87 @@
+'use strict'
+
+/**
+ * Trust a per-spec worktree directory with Claude Code.
+ *
+ * Worktrees live outside the primary checkout (`../{repo}-wt/{slug}`), so Claude
+ * Code treats them as untrusted and prompts on every edit until the operator
+ * grants access. Registering the shared worktree root in
+ * `permissions.additionalDirectories` lifts those prompts for every spec at once.
+ *
+ * The root is an **absolute** path (relative entries aren't reliable in
+ * `additionalDirectories`) and therefore machine-specific, so it belongs in the
+ * gitignored `.claude/settings.local.json` — never committed config. This merge
+ * is deliberately conservative: it preserves every existing key (notably
+ * `permissions.allow`), dedups by exact path, and refuses to clobber a file it
+ * can't parse. `fs` is the only side effect; callers own the reporting.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// Absolute path to the machine-local Claude Code settings for `dir`.
+function settingsPath(dir) {
+  return path.join(dir, '.claude', 'settings.local.json')
+}
+
+function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
+}
+
+/**
+ * Ensure `rootAbs` is listed in `permissions.additionalDirectories` of `dir`'s
+ * `.claude/settings.local.json`. Idempotent and non-destructive. Returns
+ * `{ changed, reason }` where reason is one of:
+ *   - `created`   — the settings file was absent and was created
+ *   - `added`     — the root was merged into an existing file
+ *   - `present`   — the root was already listed (no write)
+ *   - `malformed` — the file exists but isn't parseable JSON (left untouched)
+ */
+function ensureWorktreeDirTrusted(dir, rootAbs) {
+  const file = settingsPath(dir)
+
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      writeSettings(file, { permissions: { additionalDirectories: [rootAbs] } })
+      return { changed: true, reason: 'created' }
+    }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return { changed: false, reason: 'malformed' }
+  }
+  if (!isObject(parsed)) return { changed: false, reason: 'malformed' }
+
+  const permissions = isObject(parsed.permissions) ? parsed.permissions : {}
+  const dirs = Array.isArray(permissions.additionalDirectories)
+    ? permissions.additionalDirectories
+    : []
+
+  if (dirs.includes(rootAbs)) return { changed: false, reason: 'present' }
+
+  writeSettings(file, {
+    ...parsed,
+    permissions: {
+      ...permissions,
+      additionalDirectories: [...dirs, rootAbs],
+    },
+  })
+  return { changed: true, reason: 'added' }
+}
+
+module.exports = {
+  ensureWorktreeDirTrusted,
+  settingsPath,
+}

package/src/gating.js

@@ -0,0 +1,155 @@
+'use strict'
+
+/**
+ * Release gating — the loader, the header reader, and the check.
+ *
+ * The feature records ONE decision per spec: does this ship behind a feature
+ * flag, or land live? Skitterspec never learns how a project does flags; it asks
+ * the question, cites the project's own documentation, and reads back what was
+ * written. Strictly opt-in: with `specs/.core/gating.config.json` absent, every
+ * function here reports "not configured" and nothing else changes.
+ *
+ * Mirrors `src/env/config.js` (frozen defaults, merge known keys only, never
+ * throws on absence) so the two opt-in configs behave alike.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const CONFIG_FILE = path.join('specs', '.core', 'gating.config.json')
+
+// Only these two buckets are ever read.
+//
+// A SPEC WRITTEN BEFORE GATING WAS ADOPTED HAS NO HEADER AND IS NOT BROKEN. That
+// is the blind spot this check would otherwise walk into: "no Gating: line" is
+// evidence of an unanswered question only for a spec that could have been asked,
+// and every finished or abandoned spec predates the question by definition. They
+// are excluded STRUCTURALLY rather than by a filter someone must remember — a
+// completed spec is not in range, so no future edit can make it fire. Pre-existing
+// specs still in flight ARE reported, deliberately: they are live work, the
+// question genuinely still applies, and the report never blocks anything.
+const ACTIVE_BUCKETS = ['backlog', 'in-progress']
+
+const DEFAULT_CONFIG = Object.freeze({
+  guidance: '',
+  default: 'none: <reason>',
+})
+
+/**
+ * Load `specs/.core/gating.config.json`. Returns `{ config, present }`;
+ * `present:false` means the project has not adopted gating, which is read as
+ * "this project does not use feature flags" — never as an error.
+ */
+function loadGatingConfig(dir = process.cwd()) {
+  const base = { ...DEFAULT_CONFIG }
+  let raw
+  try {
+    raw = fs.readFileSync(path.join(dir, CONFIG_FILE), 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return { config: base, present: false }
+    throw error
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
+  }
+  if (parsed && typeof parsed === 'object') {
+    if (typeof parsed.guidance === 'string') base.guidance = parsed.guidance.trim()
+    if (typeof parsed.default === 'string' && parsed.default.trim()) {
+      base.default = parsed.default.trim()
+    }
+  }
+  return { config: base, present: true }
+}
+
+/**
+ * Read a spec's `> **Gating:** …` blockquote field from `00-overview.md`.
+ *
+ * Returns `{ raw, kind }` with four kinds, because there are four states and
+ * collapsing them is what made the omission invisible in the first place:
+ *
+ *   flag     a flag name — ships behind it
+ *   none     `none: <reason>` — deliberately not flagged, and why
+ *   invalid  present but says nothing: empty, or a bare `none` with no reason
+ *   missing  no field at all
+ *
+ * `invalid` and `missing` are kept apart on purpose. A bare `none` is someone
+ * answering without deciding; a missing line is nobody having been asked. They
+ * want different words.
+ */
+function readGatingField(specPath) {
+  const overview = path.join(specPath, '00-overview.md')
+  let raw
+  try {
+    raw = fs.readFileSync(overview, 'utf-8')
+  } catch {
+    return { raw: null, kind: 'missing' }
+  }
+  const m = /^>\s*\*\*Gating:\*\*\s*(.*)$/m.exec(raw)
+  if (!m) return { raw: null, kind: 'missing' }
+  const value = m[1].trim().replace(/^["'`]|["'`]$/g, '')
+  if (!value) return { raw: value, kind: 'invalid' }
+  const bare = /^none\b/i.test(value)
+  if (bare) {
+    // `none` alone, or `none:` with nothing after it, is a shrug rather than a
+    // decision — the reason half is the whole point of recording it.
+    const reason = value.replace(/^none\b:?/i, '').trim()
+    return { raw: value, kind: reason ? 'none' : 'invalid' }
+  }
+  return { raw: value, kind: 'flag' }
+}
+
+// Active specs on disk, as `{ folder, bucket, path }`. A bucket that does not
+// exist is simply empty — git does not store empty directories, so a missing
+// `specs/backlog/` is the ordinary state of a project with nothing queued.
+function activeSpecs(dir) {
+  const out = []
+  for (const bucket of ACTIVE_BUCKETS) {
+    const root = path.join(dir, 'specs', bucket)
+    let entries
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) out.push({ folder: e.name, bucket, path: path.join(root, e.name) })
+    }
+  }
+  return out
+}
+
+/**
+ * Check specs for a recorded gating decision.
+ *
+ * Advisory by construction: it returns findings and says nothing about what the
+ * caller should do. Nothing here exits, throws on a finding, or blocks.
+ *
+ * @returns {{configured: boolean, findings: Array<{folder, bucket, kind, raw}>,
+ *            checked: number, guidance: string}}
+ */
+function checkGating(dir, specs) {
+  const { config, present } = loadGatingConfig(dir)
+  if (!present) return { configured: false, findings: [], checked: 0, guidance: '' }
+  const targets = specs && specs.length ? specs : activeSpecs(dir)
+  const findings = []
+  for (const spec of targets) {
+    const { kind, raw } = readGatingField(spec.path)
+    if (kind === 'missing' || kind === 'invalid') {
+      findings.push({ folder: spec.folder, bucket: spec.bucket, kind, raw })
+    }
+  }
+  return { configured: true, findings, checked: targets.length, guidance: config.guidance }
+}
+
+module.exports = {
+  CONFIG_FILE,
+  DEFAULT_CONFIG,
+  ACTIVE_BUCKETS,
+  loadGatingConfig,
+  readGatingField,
+  activeSpecs,
+  checkGating,
+}