@skitterbyte/skitterspec 22.0.0 → 22.1.0

package/src/env/config.js

@@ -187,7 +187,16 @@ const DEFAULT_CONFIG = Object.freeze({
   spec: Object.freeze({ companionPaths: Object.freeze([]) }),
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
-  guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
+  // `mainIsLandingZone` defaults ON wherever isolation is configured, matching
+  // the review gate's precedent: the push toward not working on the base branch
+  // is the normal path, and stepping off it is the deliberate act. That does
+  // change behaviour for a project on upgrade, which is the honest cost — the
+  // refusal names both exits (`/no-spec` and `/allow-main`) and this key.
+  guards: Object.freeze({
+    refuseTeardownIfDirty: true,
+    refuseTeardownIfUnpushed: true,
+    mainIsLandingZone: true,
+  }),
   // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
   // `spec-env down` does about a branch the USER published by hand — nothing
   // publishes one at provisioning, so there is often no remote ref at all and
@@ -251,6 +260,12 @@ const DEFAULT_CONFIG = Object.freeze({
     allowRemote: false,
     commitWith: '/commit',
     required: true,
+    // External code reviewers whose findings render as CHECKS on the page.
+    // Empty by default and never written by `init`: configuring one sends the
+    // worktree's diff to whatever the command talks to, which is a decision
+    // only the project can make. Two entry shapes — `{use}` names a bundled
+    // adapter, `{name, command, format}` is bring-your-own.
+    reviewers: Object.freeze([]),
   }),
   // Live overlay (`spec-env live`). `migrations` is a list of globs marking
   // migration files; a branch that changes any of them is treated as stateful and
@@ -325,7 +340,7 @@ function defaults() {
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
     teardown: { ...DEFAULT_CONFIG.teardown },
-    review: { ...DEFAULT_CONFIG.review },
+    review: { ...DEFAULT_CONFIG.review, reviewers: [] },
     live: { migrations: [] },
     hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
@@ -382,6 +397,89 @@ function normalizeFileList(parsed) {
   return out
 }
 
+// How long a reviewer gets before it is killed, in seconds. A generous default:
+// these tools take 30s-3min, and the render they precede is about to wait on a
+// human for far longer.
+const DEFAULT_REVIEWER_TIMEOUT = 180
+
+// Output formats the runner can parse. `rdjsonl` is the native contract
+// (reviewdog's interchange shape); a bundled adapter brings its own parser and
+// declares no format at all.
+const REVIEWER_FORMATS = ['rdjsonl']
+
+/**
+ * Read one `review.reviewers` entry. Returns the normalised entry, or `null`
+ * with a reason — the caller decides whether to keep it or report it.
+ *
+ * Two shapes, and they are told apart by which key is present rather than by
+ * guessing: `{use}` names a bundled adapter (the engine owns its command line
+ * and its parser), `{name, command}` is bring-your-own. An entry carrying both
+ * is refused BY NAME rather than resolved in some order — it is two
+ * instructions, and picking one would run a reviewer the author did not ask for.
+ *
+ * WHETHER A NAMED ADAPTER EXISTS IS NOT CHECKED HERE, deliberately: the adapter
+ * registry lives in the runner, and this module must not depend on it to answer
+ * a question about shape. The runner reports an unknown `use` as its own
+ * outcome.
+ */
+function readReviewer(raw) {
+  if (!isObject(raw)) return { entry: null, reason: 'not an object' }
+  const use = typeof raw.use === 'string' ? raw.use.trim() : ''
+  const command = typeof raw.command === 'string' ? raw.command.trim() : ''
+  if (use && command) return { entry: null, reason: 'carries both use and command — write one' }
+  // A number that is not finite and positive is not a timeout. Falling through
+  // to the default is safe in a way `0` would not be: a zero timeout kills every
+  // reviewer instantly and would read, on the page, as one that never ran.
+  const t = raw.timeout
+  const timeout = typeof t === 'number' && Number.isFinite(t) && t > 0 ? t : DEFAULT_REVIEWER_TIMEOUT
+  if (use) {
+    const name = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : use
+    return { entry: { name, use, command: null, format: null, timeout }, reason: null }
+  }
+  if (!command) return { entry: null, reason: 'has neither use nor command' }
+  const name = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : ''
+  if (!name) return { entry: null, reason: 'has a command but no name' }
+  // An unrecognised format is refused rather than defaulted to `rdjsonl`. The
+  // scalars above can fall through because their default is what the author
+  // most likely meant; here it is not — parsing one tool's output as another's
+  // shape yields zero findings and reports the reviewer as clean, which is the
+  // false clean this whole feature is built to avoid.
+  const fmt = raw.format === undefined || raw.format === null ? 'rdjsonl' : raw.format
+  if (!REVIEWER_FORMATS.includes(fmt)) {
+    return { entry: null, reason: `format ${JSON.stringify(raw.format)} is not one of ${REVIEWER_FORMATS.join(', ')}` }
+  }
+  return { entry: { name, use: null, command, format: fmt, timeout }, reason: null }
+}
+
+function normalizeReviewers(parsed) {
+  const out = []
+  for (const raw of parsed) {
+    const { entry } = readReviewer(raw)
+    if (entry) out.push(entry)
+  }
+  return out
+}
+
+/**
+ * List the `review.reviewers` entries the merge dropped, as
+ * `{ index, reason }`. Advisory, like `collectUnknownKeys` — nothing refuses.
+ *
+ * It exists because `collectUnknownKeys` structurally cannot cover this: it
+ * descends only where the DEFAULT is a plain object, and this default is an
+ * array. Without this, a reviewer entry with a typo in it is dropped in exactly
+ * the silence that check was added to end — and worse than an ignored key,
+ * because the page would then show no line for it at all.
+ */
+function collectBadReviewers(parsed) {
+  if (!isObject(parsed) || !isObject(parsed.review) || !Array.isArray(parsed.review.reviewers)) return []
+  const out = []
+  parsed.review.reviewers.forEach((raw, index) => {
+    const { entry, reason } = readReviewer(raw)
+    if (!entry) out.push({ index, reason })
+  })
+  return out
+}
+
 /**
  * Normalise a parsed `seedFiles` value into `{ mode, files }`. Accepts two forms:
  *   - the array shorthand `[".env", ...]` → { mode: 'symlink', files: [...] }
@@ -473,6 +571,7 @@ function mergeConfig(base, parsed) {
   if (isObject(parsed.guards)) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')
     assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
+    assign(base.guards, parsed.guards, 'mainIsLandingZone', 'boolean')
   }
 
   // An unrecognised policy falls through to the default rather than erroring or
@@ -539,6 +638,15 @@ function mergeConfig(base, parsed) {
     // a typo cannot quietly widen a bind or permit a publish.
     assign(base.review, parsed.review, 'allowNetwork', 'boolean')
     assign(base.review, parsed.review, 'allowRemote', 'boolean')
+    // An entry that is neither shape is DROPPED rather than refused, like every
+    // other value here — but unlike the scalars above there is no default for it
+    // to fall through to, so a dropped entry is a reviewer that silently never
+    // runs. `collectUnknownKeys` cannot see it either: the default is an array,
+    // and it deliberately does not walk into one. So the dropping is reported
+    // separately, by `collectBadReviewers` below.
+    if (Array.isArray(parsed.review.reviewers)) {
+      base.review.reviewers = normalizeReviewers(parsed.review.reviewers)
+    }
   }
 
   if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {
@@ -580,7 +688,7 @@ function loadEnvConfig(dir = process.cwd()) {
   try {
     raw = readFileSync(file, 'utf-8')
   } catch (error) {
-    if (error.code === 'ENOENT') return { config: base, present: false, unknown: [] }
+    if (error.code === 'ENOENT') return { config: base, present: false, unknown: [], badReviewers: [] }
     throw error
   }
 
@@ -591,7 +699,12 @@ function loadEnvConfig(dir = process.cwd()) {
     throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
   }
 
-  return { config: mergeConfig(base, parsed), present: true, unknown: collectUnknownKeys(parsed) }
+  return {
+    config: mergeConfig(base, parsed),
+    present: true,
+    unknown: collectUnknownKeys(parsed),
+    badReviewers: collectBadReviewers(parsed),
+  }
 }
 
 module.exports = {
@@ -603,7 +716,11 @@ module.exports = {
   PORT_BASE,
   PORT_SPAN,
   collectUnknownKeys,
+  collectBadReviewers,
+  readReviewer,
   mergeConfig,
   DEFAULT_CONFIG,
+  DEFAULT_REVIEWER_TIMEOUT,
+  REVIEWER_FORMATS,
   CONFIG_FILE,
 }

package/src/env/hooks.js

@@ -39,6 +39,41 @@ const HOOK_SCRIPT_RE = /[.]claude[/\\]hooks[/\\]review-gate(?:[.][A-Za-z0-9]+)?(
 const HOOK_TIMEOUT = 10
 const MATCHER = 'Bash'
 
+/**
+ * Every hook this package registers, as data.
+ *
+ * ONE LIST, so a second hook cannot arrive as a second copy of the merge logic
+ * below — which is where every property this file has earned would have to be
+ * re-derived and one of them forgotten. Each entry supplies only what differs:
+ * the script's stem, the tools it matches, and its timeout.
+ *
+ * The `re` for each is built from its stem with the same boundary lookahead the
+ * review gate's has, so `main-guard-extra.js` — somebody else's hook — is not
+ * silently rewritten as ours.
+ */
+function hookStemRe(stem) {
+  const name = stem.split('/').pop()
+  return new RegExp(`[.]claude[/\\\\]hooks[/\\\\]${name}(?:[.][A-Za-z0-9]+)?(?![\\w.-])`)
+}
+
+const HOOKS = [
+  {
+    key: 'review-gate',
+    stem: HOOK_STEM,
+    matcher: MATCHER,
+    timeout: HOOK_TIMEOUT,
+  },
+  {
+    // Refuses an Edit/Write in the primary checkout while it is on the base
+    // branch. A different matcher from the review gate's, because it guards a
+    // different moment: the first write, before any work exists.
+    key: 'main-guard',
+    stem: '.claude/hooks/main-guard',
+    matcher: 'Edit|Write|NotebookEdit|MultiEdit',
+    timeout: HOOK_TIMEOUT,
+  },
+].map((h) => ({ ...h, script: `${h.stem}.cjs`, re: hookStemRe(h.stem) }))
+
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -52,10 +87,14 @@ function writeSettings(file, settings) {
   fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
 }
 
-function hookEntry() {
+function commandFor(script) {
+  return `node "\${CLAUDE_PROJECT_DIR}/${script}"`
+}
+
+function hookEntry(hook = HOOKS[0]) {
   return {
-    matcher: MATCHER,
-    hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: HOOK_TIMEOUT }],
+    matcher: hook.matcher,
+    hooks: [{ type: 'command', command: commandFor(hook.script), timeout: hook.timeout }],
   }
 }
 
@@ -67,34 +106,72 @@ function hookEntry() {
  * registered our hook their way — re-adding a second copy beside theirs would
  * run it twice and look like a bug in the gate.
  */
-function alreadyRegistered(preToolUse) {
-  return registeredHooks(preToolUse).length > 0
+function alreadyRegistered(preToolUse, hook = HOOKS[0]) {
+  return registeredHooks(preToolUse, hook).length > 0
 }
 
 // Every hook object under `PreToolUse` whose command names our script, whatever
 // extension it names it under. Pure.
-function registeredHooks(preToolUse) {
+function registeredHooks(preToolUse, hook = HOOKS[0]) {
   if (!Array.isArray(preToolUse)) return []
   const out = []
   for (const group of preToolUse) {
     if (!isObject(group) || !Array.isArray(group.hooks)) continue
     for (const h of group.hooks) {
-      if (isObject(h) && typeof h.command === 'string' && HOOK_SCRIPT_RE.test(h.command)) out.push(h)
+      if (isObject(h) && typeof h.command === 'string' && hook.re.test(h.command)) out.push(h)
     }
   }
   return out
 }
 
 /**
- * Ensure the review-gate hook is registered in `dir`'s project settings.
- * Idempotent and non-destructive. Returns `{ changed, reason }`:
+ * Ensure ONE hook is registered in an already-parsed settings object.
+ * Mutates `parsed` in place when it migrates a stale path; returns
+ * `{ changed, reason }` with the same vocabulary as the wrapper below.
+ *
+ * Split out so a second hook could be added without a second copy of this
+ * logic — which is where every property this file has earned (preserve unknown
+ * keys, match on the script PATH, migrate in place, stay idempotent) would have
+ * had to be re-derived, and one of them forgotten.
+ */
+function ensureOneHook(parsed, hook) {
+  const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
+  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+
+  // Registered already — but possibly under a path that no longer exists, since
+  // the script's extension changed. Rewrite the path IN PLACE rather than
+  // replacing the command: an operator who wrapped our hook, added a flag or
+  // changed the interpreter has registered it their way, and the thing that
+  // moved is the file, not their command. Adding a fresh entry beside theirs
+  // would run the gate twice and read as a bug in the gate; leaving the old one
+  // alone would aim the harness at a file this same upgrade retires.
+  const registered = registeredHooks(preToolUse, hook)
+  if (registered.length) {
+    const stale = registered.filter((h) => !h.command.includes(hook.script))
+    if (!stale.length) return { changed: false, reason: 'present' }
+    for (const h of stale) h.command = h.command.replace(hook.re, hook.script)
+    return { changed: true, reason: 'migrated' }
+  }
+
+  parsed.hooks = { ...hooks, PreToolUse: [...preToolUse, hookEntry(hook)] }
+  return { changed: true, reason: 'added' }
+}
+
+/**
+ * Ensure every hook this package ships is registered in `dir`'s project
+ * settings. Idempotent and non-destructive. Returns `{ changed, reason }`:
  *   - `created`   — no settings file; one was written
  *   - `added`     — merged into an existing file
  *   - `migrated`  — registered under a retired path; the path was rewritten
  *   - `present`   — already registered (no write)
  *   - `malformed` — the file exists but is not parseable JSON (left untouched)
+ *
+ * WITH SEVERAL HOOKS THE REASON IS THE STRONGEST ONE that applied, in the order
+ * added > migrated > present. A run that added one hook and found the other
+ * already there did change the file, and reporting `present` for it would tell
+ * an operator nothing happened when something did.
  */
-function ensureReviewGateHook(dir) {
+function ensureHooks(dir) {
   const file = settingsPath(dir)
 
   let raw
@@ -102,7 +179,7 @@ function ensureReviewGateHook(dir) {
     raw = fs.readFileSync(file, 'utf-8')
   } catch (error) {
     if (error.code === 'ENOENT') {
-      writeSettings(file, { hooks: { PreToolUse: [hookEntry()] } })
+      writeSettings(file, { hooks: { PreToolUse: HOOKS.map((h) => hookEntry(h)) } })
       return { changed: true, reason: 'created' }
     }
     throw error
@@ -118,38 +195,30 @@ function ensureReviewGateHook(dir) {
   }
   if (!isObject(parsed)) return { changed: false, reason: 'malformed' }
 
-  const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
-  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+  const reasons = HOOKS.map((h) => ensureOneHook(parsed, h))
+  const changed = reasons.some((r) => r.changed)
+  if (changed) writeSettings(file, parsed)
 
-  // Registered already — but possibly under a path that no longer exists, since
-  // the script's extension changed. Rewrite the path IN PLACE rather than
-  // replacing the command: an operator who wrapped our hook, added a flag or
-  // changed the interpreter has registered it their way, and the thing that
-  // moved is the file, not their command. Adding a fresh entry beside theirs
-  // would run the gate twice and read as a bug in the gate; leaving the old one
-  // alone would aim the harness at a file this same upgrade retires.
-  const registered = registeredHooks(preToolUse)
-  if (registered.length) {
-    const stale = registered.filter((h) => !h.command.includes(HOOK_SCRIPT))
-    if (!stale.length) return { changed: false, reason: 'present' }
-    for (const h of stale) h.command = h.command.replace(HOOK_SCRIPT_RE, HOOK_SCRIPT)
-    writeSettings(file, parsed)
-    return { changed: true, reason: 'migrated' }
+  for (const rank of ['added', 'migrated', 'present']) {
+    if (reasons.some((r) => r.reason === rank)) return { changed, reason: rank }
   }
-
-  writeSettings(file, {
-    ...parsed,
-    hooks: { ...hooks, PreToolUse: [...preToolUse, hookEntry()] },
-  })
-  return { changed: true, reason: 'added' }
+  return { changed, reason: 'present' }
 }
 
+// The name this shipped under when there was one hook. Kept as an alias rather
+// than renamed away, because it is what an installed `init.js` from an older
+// version calls — and a rename that breaks an upgrade path is not a rename, it
+// is a removal.
+const ensureReviewGateHook = ensureHooks
+
 module.exports = {
+  ensureHooks,
   ensureReviewGateHook,
   alreadyRegistered,
   registeredHooks,
   hookEntry,
   settingsPath,
+  HOOKS,
   HOOK_STEM,
   HOOK_SCRIPT,
   HOOK_SCRIPT_RE,

package/src/env/live.js

@@ -256,7 +256,27 @@ function planTake(spec, config, ctx) {
     branch,
     worktreePath: spec.worktreePath,
   }
-  const block = (reason) => ({ ...result, blocked: true, reason })
+  /**
+   * A refusal, and — only where one exists — the way out of it.
+   *
+   * AN OFFER IS DECLARED HERE OR NOWHERE. A caller that raises a picker from a
+   * refusal is reading this field, never re-deciding from the reason text: the
+   * one boundary that matters is that work which is not the operator's must
+   * never be offered up (a workbench another spec holds is theirs to free), and
+   * a rule in prose is not what should be holding that line.
+   *
+   * ABSENT STAYS ABSENT. A refusal with no way out carries no `offer` key at
+   * all, so every existing consumer sees exactly the shape it saw before.
+   *
+   * @param {string} reason   what is wrong, unchanged
+   * @param {object} [offer]  { kind: 'satisfy'|'bypass', label, command }
+   */
+  const block = (reason, offer) => ({
+    ...result,
+    blocked: true,
+    reason,
+    ...(offer ? { offer } : {}),
+  })
 
   // 1. The lock: the primary checkout must be on base (free). Off-base → a spec
   //    (or you) already holds the live instance.
@@ -293,6 +313,15 @@ function planTake(spec, config, ctx) {
     return block(
       `${spec.folder}'s worktree has uncommitted changes — commit or stash them in ` +
         `${spec.worktreePath} first (the rebase cannot run over them)`,
+      // SATISFYING THE GUARD, not stepping past it. Committing the phase is the
+      // precondition `live take` is asking for, so doing it weakens nothing and
+      // needs no record — which is what separates this from a `bypass`.
+      //
+      // Offered for the WORKTREE's tree and never for the primary checkout's
+      // (check 2 above): that one holds whatever the operator happens to have
+      // open, not this spec's phase work, and committing it under this spec's
+      // ticket is the mis-stamping `commit-trailers.md` exists to prevent.
+      { kind: 'satisfy', label: 'Commit first, then go live', command: '/commit' },
     )
   }
   // 4. A hotfix is built on an old release tag; checking its branch out under the

package/src/env/mainguard.js

@@ -0,0 +1,240 @@
+'use strict'
+
+/**
+ * The main guard — is this write about to land on the base branch?
+ *
+ * `main` is where work **lands**, not where it happens. Two routes reach it
+ * otherwise, and both cost someone else something: a dirty base branch that
+ * every in-flight spec has to replay over and no release can be cut through,
+ * and — worse — work that renders no review page at all, because nothing in
+ * this workflow renders one for the primary checkout.
+ *
+ * Both routes now have somewhere to go: `/spec` authors in its own `--docs`
+ * worktree, and `/no-spec` gives mechanical work a branch of its own. So the
+ * guard is a push toward a path that exists rather than a refusal with no exit.
+ *
+ * THE ACCUSATION IS POSITIVE, AND ALL FOUR PARTS MUST HOLD. It is
+ * `.claude/rules/negative-checks.md` rule 1 applied to a check that stops
+ * someone working: isolation is configured, the guard is not switched off, this
+ * directory IS the primary checkout, and HEAD IS the base branch. Anything the
+ * engine cannot establish — no repo, no config, an unresolvable base, a
+ * worktree, an unreadable allow file — allows the write and says nothing.
+ * Being wrong the permissive way costs one unguarded edit on a rule the skills
+ * also carry; being wrong the other way costs someone their work with no idea
+ * why.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { assertPrimaryOnMain, resolvePrimaryCheckout } = require('./resolve.js')
+
+// Where the allow lives. Gitignored, machine-local and beside the registry —
+// this is one person's decision about one session, never the project's policy.
+const ALLOW_FILE = 'main-allow.json'
+
+function allowPath(rootDir, config) {
+  return path.resolve(rootDir, path.dirname(config.registry), ALLOW_FILE)
+}
+
+/**
+ * Read the recorded allow. Pure but for the read.
+ *
+ * MISSING AND MALFORMED BOTH READ AS "NO ALLOW", which is the *strict* answer
+ * here rather than the lenient one — and that is the right way round only
+ * because the strict answer is also the safe one. An unreadable allow file
+ * makes the guard fire, and firing costs a refusal naming two exits; silently
+ * treating it as permission would let a stale file switch the guard off
+ * forever.
+ */
+function readAllow(rootDir, config) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(allowPath(rootDir, config), 'utf-8'))
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+function writeAllow(rootDir, config, value) {
+  const file = allowPath(rootDir, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n')
+}
+
+function clearAllow(rootDir, config) {
+  try {
+    fs.unlinkSync(allowPath(rootDir, config))
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Does `allow` permit a write from `sessionId`? Pure.
+ *
+ * TWO KINDS, AND THEY MUST NOT LOOK ALIKE. A **session** allow names the
+ * session that asked for it, so it lapses the moment that conversation ends —
+ * which is what "temporary" has to mean for something nobody will remember to
+ * switch back. A **repo** allow is the degraded form for a harness that exposes
+ * no session id; it outlives the session and is cleared only by hand, so
+ * `mainGuardStatus` says which kind is in force rather than reporting a bare
+ * "allowed".
+ *
+ * A session allow with no session id to compare against does NOT apply. The
+ * alternative — treating "cannot tell whose session this is" as a match — would
+ * turn every session allow into a repo one the moment a caller forgot to pass
+ * the id.
+ */
+function allowApplies(allow, sessionId) {
+  if (!allow) return false
+  if (allow.scope === 'repo') return true
+  if (allow.scope === 'session') return Boolean(sessionId) && allow.session === sessionId
+  return false
+}
+
+/**
+ * Should a write in `dir` be refused? Pure — every fact arrives in `ctx`.
+ *
+ * ctx: { configured, enabled, isPrimary, onBase, allow, sessionId }
+ *
+ * Returns `{ refuse, reason }`. `reason` is for the operator and names both
+ * exits; `refuse: false` always carries a null reason, because a guard that
+ * explains why it is NOT firing is the narration this codebase bans.
+ *
+ * WHAT WOULD FOOL THIS: nothing here inspects the *file* being written. A write
+ * to `specs/`, to `.claude/`, to a scratch file — all refused alike, and that is
+ * the decision rather than an oversight. An allowlist was considered and is
+ * empty by construction: with `/spec` authoring into its own worktree and
+ * `/no-spec` catching ad-hoc work, no legitimate writer to the base branch is
+ * left. `/spec-init` is the apparent exception and is not one — it bootstraps a
+ * repo that has no `env.config.json` yet, so `configured` is false and the
+ * guard never reaches this function.
+ */
+function judgeMainWrite(ctx) {
+  const { configured, enabled, isPrimary, onBase, allow, sessionId } = ctx || {}
+
+  // Every one of these is a CANNOT-TELL or a NOT-APPLICABLE, and each routes to
+  // the harmless branch on its own rather than through a combined condition —
+  // so a later reader can delete one without silently widening the others.
+  if (!configured) return { refuse: false, reason: null }
+  if (enabled === false) return { refuse: false, reason: null }
+  if (!isPrimary) return { refuse: false, reason: null }
+  if (!onBase) return { refuse: false, reason: null }
+  if (allowApplies(allow, sessionId)) return { refuse: false, reason: null }
+
+  return {
+    refuse: true,
+    reason:
+      'the primary checkout is on the base branch, and the base branch is a landing zone — ' +
+      'work lands there, it does not happen there.\n\n' +
+      'Move the work instead of writing here:\n' +
+      '  /no-spec <name>      a one-off with no spec — its own branch, worktree and review page\n' +
+      '  /spec-start <name>   a spec that is ready to be built\n' +
+      '  /spec                a change that wants grilling first\n\n' +
+      'If this really does belong on the base branch, the USER types /allow-main — ' +
+      'it is theirs to run, not yours.',
+  }
+}
+
+/**
+ * Gather the facts and judge. The only IO in the module's hot path.
+ *
+ * `git` is an injected reader, as everywhere in this package: the caller owns
+ * the child-process boundary, which is what keeps `judgeMainWrite` testable
+ * without one.
+ */
+function checkMainWrite(dir, config, git, opts = {}) {
+  // `present` from `loadEnvConfig` — the caller has it and this module must not
+  // re-read the file to find out. A defaults-only config is indistinguishable
+  // from a configured one that happens to match the defaults, so asking the
+  // config object would answer the wrong question.
+  const configured = opts.present === true
+  const enabled = !(config && config.guards && config.guards.mainIsLandingZone === false)
+
+  // IS THIS THE PRIMARY CHECKOUT? A worktree is somebody's spec branch and none
+  // of this guard's business, so the question is asked positively rather than by
+  // looking for the absence of a worktree marker.
+  let isPrimary = false
+  let primary = null
+  try {
+    primary = resolvePrimaryCheckout(dir, git)
+    isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
+  } catch {
+    // Not a git repo, or git unreadable. Cannot tell → allow.
+    return { refuse: false, reason: null, branch: null, baseBranch: null }
+  }
+
+  let onBase = false
+  let branch = null
+  let baseBranch = null
+  try {
+    const state = assertPrimaryOnMain(config, git)
+    onBase = state.onBase
+    branch = state.branch
+    baseBranch = state.baseBranch
+  } catch {
+    return { refuse: false, reason: null, branch: null, baseBranch: null }
+  }
+
+  const root = isPrimary ? dir : primary || dir
+  const verdict = judgeMainWrite({
+    configured,
+    enabled,
+    isPrimary,
+    onBase,
+    allow: readAllow(root, config),
+    sessionId: opts.sessionId || null,
+  })
+  return { ...verdict, branch, baseBranch }
+}
+
+/**
+ * Record an allow. `sessionId` present → a session allow; absent → a repo one.
+ * Returns what was written, so the caller can report which kind it is.
+ */
+function recordAllow(rootDir, config, { sessionId = null, reason = null, at = null } = {}) {
+  const value = sessionId
+    ? { scope: 'session', session: sessionId, reason, at }
+    : { scope: 'repo', reason, at }
+  writeAllow(rootDir, config, value)
+  return value
+}
+
+/**
+ * What is in force, as data. Four states, and the caller reports all four —
+ * `off` (the project switched the guard off), `unconfigured`, `allowed` (with
+ * its scope and reason), or `guarded`.
+ */
+function mainGuardStatus(rootDir, config, opts = {}) {
+  if (opts.present !== true) return { state: 'unconfigured' }
+  if (config && config.guards && config.guards.mainIsLandingZone === false) {
+    return { state: 'off' }
+  }
+  const allow = readAllow(rootDir, config)
+  if (allowApplies(allow, opts.sessionId || null)) {
+    return { state: 'allowed', scope: allow.scope, reason: allow.reason || null, at: allow.at || null }
+  }
+  // A session allow belonging to ANOTHER session is reported rather than hidden:
+  // the operator asked for one somewhere, and a bare "guarded" would send them
+  // hunting for why their /allow-main did nothing.
+  if (allow && allow.scope === 'session') {
+    return { state: 'guarded', otherSession: true }
+  }
+  return { state: 'guarded' }
+}
+
+module.exports = {
+  ALLOW_FILE,
+  allowPath,
+  readAllow,
+  writeAllow,
+  clearAllow,
+  allowApplies,
+  judgeMainWrite,
+  checkMainWrite,
+  recordAllow,
+  mainGuardStatus,
+}