@skitterbyte/skitterspec-linear 13.0.0 → 14.0.0

package/src/cli.js

@@ -68,15 +68,24 @@ const {
   readPending,
   writePending,
   claimPending,
+  passesSince,
   describePending,
   pendingAge,
   reviewPendingPath,
   validateResolutions,
   mergeNotes,
   applyResolutions,
+  COMMITTING,
+  reviewGatePath,
+  readGate,
+  writeGate,
+  armGate,
+  disarmGate,
+  gateState,
 } = require('./env/review.js')
 const { planUp, planCheckoutUp } = require('./env/provision.js')
 const { classifyDirtyTree } = require('./env/classify.js')
+const { isGitCommit } = require('./env/commitcmd.js')
 const { planDown, planDownCheckout } = require('./env/teardown.js')
 const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
 const { planIntegrate, planIntegrateCheckout } = require('./env/integrate.js')
@@ -1628,6 +1637,195 @@ function verdictSaid(v) {
   return 'discuss first'
 }
 
+/**
+ * Resolve the spec and its page path for a gate verb, or say why not.
+ *
+ * Shared by `arm`, `gate` and `skip` so all three answer about the same
+ * sidecar the render writes beside the page — `--out` moves them together, and
+ * a gate keyed to a different path than its page is a gate nobody can clear.
+ *
+ * It never throws. Resolution failure is a cannot-tell for these verbs, not an
+ * error: `gate --check` is called by a commit hook, and a hook that fails on a
+ * repo it could not resolve would block every commit in it.
+ */
+function gateTarget(dir, config, specArg) {
+  try {
+    const spec = resolveSpecWithWorktree(dir, config, specArg)
+    return { spec, out: reviewOutPath(dir, spec.folder), reason: null }
+  } catch (err) {
+    return { spec: null, out: null, reason: err.message }
+  }
+}
+
+// `review arm` — a phase ended, and its diff is now owed a verdict.
+function specEnvReviewArm(dir, config, specArg, flags) {
+  const target = gateTarget(dir, config, specArg)
+  if (!target.spec) {
+    // Arming is a best-effort half of a phase ending; the phase is still built.
+    process.stdout.write(`spec-env review arm: cannot tell which spec — ${target.reason}\n`)
+    return
+  }
+  const read = readGate(target.out, target.spec.folder)
+  if (read.corrupt) {
+    // Same rule as every other sidecar: never write over a file we could not
+    // read. Here that also means never claiming to have armed something.
+    process.stdout.write(
+      `spec-env review arm: ${reviewGatePath(target.out)} is not readable JSON — ` +
+        'move it aside rather than losing the history it holds.\n',
+    )
+    return
+  }
+  const phase = flags.phase === undefined ? null : flags.phase
+  const before = read.gate
+  const gate = armGate(before, { at: new Date().toISOString(), phase })
+  writeGate(target.out, gate)
+  const again = before.armed && gate.armedAt === before.armedAt
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ spec: target.spec.folder, armed: true, armedAt: gate.armedAt, phase: gate.phase, alreadyArmed: again }, null, 2) + '\n')
+    return
+  }
+  process.stdout.write(
+    `spec-env review arm: ${target.spec.folder} is awaiting a verdict` +
+      `${gate.phase ? ` (phase ${gate.phase})` : ''}` +
+      `${again ? ' — already was, since ' + String(gate.armedAt).slice(0, 19) : ''}\n`,
+  )
+}
+
+/**
+ * `review gate` — is anything owed?
+ *
+ * `--check` is the one call a commit hook makes, and it exits non-zero ONLY on
+ * `armed`: a positive signal, read from a present and parseable sidecar. Every
+ * other state — cleared, unreadable, versioned past this engine, switched off
+ * — exits 0 and says which, because a check that accuses on an absence accuses
+ * healthy repos (`.claude/rules/negative-checks.md`).
+ */
+function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
+  // `--for-command` is the hook's half: it asks about a command line rather
+  // than about the repo, and a command that is not a commit is simply not this
+  // check's business. Answered FIRST and in silence, because the overwhelming
+  // majority of tool calls land here and every one of them must cost nothing
+  // and say nothing.
+  if (flags.forCommand !== undefined && !isGitCommit(flags.forCommand)) return
+
+  const target = gateTarget(dir, config, specArg)
+  let judged = target.spec
+    ? gateState({ ...readGate(target.out, target.spec.folder), required: config.review.required })
+    : { state: 'unknown', reason: target.reason, gate: null }
+
+  // ASKED ABOUT A COMMAND, the question is narrower than "is anything owed in
+  // this repo": it is "does the commit happening HERE owe a verdict". The bare
+  // resolution answers with the sole provisioned spec wherever you stand, which
+  // is right for a person typing the verb and wrong for this — it denied a
+  // commit on the base branch because some other spec was mid-review, which is
+  // exactly how a backlog spec authored from the primary checkout (the thing
+  // `commit-trailers.md` asks for) would be blocked by unrelated work.
+  //
+  // So it wants a POSITIVE signal (`.claude/rules/negative-checks.md` rule 1):
+  // this commit is running inside that spec's own worktree. Anything else —
+  // the primary checkout, another spec's tree, a path that cannot be resolved —
+  // is a cannot-tell, and cannot-tell allows.
+  if (flags.forCommand !== undefined && judged.state === 'armed') {
+    const inside = (child, parent) => {
+      try {
+        const rel = path.relative(fs.realpathSync(parent), fs.realpathSync(child))
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+      } catch {
+        return false
+      }
+    }
+    if (!inside(invokedFrom, target.spec.worktreePath)) {
+      judged = {
+        state: 'unknown',
+        reason: `this command is not running inside ${target.spec.folder}'s worktree`,
+        gate: judged.gate,
+      }
+    }
+  }
+
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          spec: target.spec ? target.spec.folder : null,
+          state: judged.state,
+          reason: judged.reason,
+          armedAt: judged.gate ? judged.gate.armedAt : null,
+          phase: judged.gate ? judged.gate.phase : null,
+          required: config.review.required,
+          log: judged.gate && Array.isArray(judged.gate.log) ? judged.gate.log : [],
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+  } else if (judged.state === 'armed') {
+    const g = judged.gate
+    process.stdout.write(
+      `spec-env review gate: ${target.spec.folder} is awaiting a verdict` +
+        `${g.phase ? ` (phase ${g.phase})` : ''}` +
+        `${g.armedAt ? ` since ${String(g.armedAt).slice(0, 19)}` : ''}\n` +
+        '  read the page and send a verdict, or record why you are moving on:\n' +
+        '    skitterspec spec-env review skip "<reason>"\n',
+    )
+  } else if (judged.state === 'clear') {
+    process.stdout.write(`spec-env review gate: ${target.spec.folder} owes nothing — ${judged.reason}\n`)
+  } else {
+    process.stdout.write(
+      `spec-env review gate: cannot tell — ${judged.reason}.\n` +
+        '  nothing is being claimed, and nothing is blocked.\n',
+    )
+  }
+
+  // The exit status is the whole interface for a hook, so it is set from the
+  // one state that is evidence and never from the two that are not.
+  if (flags.check && judged.state === 'armed') process.exitCode = 1
+}
+
+// `review skip` — move on without a verdict, on the record.
+function specEnvReviewSkip(dir, config, reason, flags) {
+  const said = String(reason || '').trim()
+  if (!said) {
+    // The reason IS the feature. A skip with no reason is the silence this
+    // whole gate exists to replace, so it is refused rather than defaulted.
+    process.stdout.write(
+      'spec-env review skip: needs a reason — skitterspec spec-env review skip "<why>"\n',
+    )
+    process.exitCode = 1
+    return
+  }
+  const target = gateTarget(dir, config, null)
+  if (!target.spec) {
+    process.stdout.write(`spec-env review skip: cannot tell which spec — ${target.reason}\n`)
+    process.exitCode = 1
+    return
+  }
+  const read = readGate(target.out, target.spec.folder)
+  if (read.corrupt) {
+    process.stdout.write(
+      `spec-env review skip: ${reviewGatePath(target.out)} is not readable JSON — ` +
+        'move it aside rather than losing the history it holds.\n',
+    )
+    process.exitCode = 1
+    return
+  }
+  const result = disarmGate(read.gate, { at: new Date().toISOString(), by: 'skip', reason: said })
+  if (!result.logged) {
+    // Nothing was owed, so nothing is recorded: a log entry here would claim a
+    // decision was taken about an obligation that did not exist.
+    process.stdout.write(`spec-env review skip: ${target.spec.folder} owes nothing — nothing to skip\n`)
+    return
+  }
+  writeGate(target.out, result.gate)
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ spec: target.spec.folder, skipped: true, reason: said }, null, 2) + '\n')
+    return
+  }
+  process.stdout.write(
+    `spec-env review skip: ${target.spec.folder} moved on without a verdict\n  reason: ${said}\n`,
+  )
+}
+
 async function specEnvReview(dir, config, specArg, flags) {
   // An unknown name throws here rather than falling back to the branch: a review
   // of the wrong spec looks exactly like a review of the right one.
@@ -1690,11 +1888,51 @@ async function specEnvReview(dir, config, specArg, flags) {
   let sentVerdict = null
   let claimed = null
 
+  // `--claim-since <iso>` resolves to a code and then joins the ordinary claim
+  // path below. THE ENGINE PICKS SO THE AGENT DOES NOT: an agent left to find
+  // "the pass that just arrived" reads the store and chooses, and the rule that
+  // it must not choose becomes a request. Here the window is the only input, and
+  // an answer of anything but exactly one pass acts on nothing.
+  let claimCode = flags.claim
+  if (!claimCode && flags.claimSince) {
+    const heldRead = readPending(out, spec.folder)
+    if (heldRead.corrupt) {
+      process.stdout.write(
+        `spec-env review: ${reviewPendingPath(out)} is not readable JSON — ` +
+          'move it aside rather than losing the passes it holds.\n',
+      )
+      return
+    }
+    const window = passesSince(heldRead.pending, flags.claimSince)
+    if (!window.usable) {
+      process.stdout.write(
+        `spec-env review: --claim-since ${flags.claimSince} is not a timestamp — nothing claimed\n`,
+      )
+      return
+    }
+    if (window.codes.length === 0) {
+      process.stdout.write(
+        `spec-env review: no pass has arrived since ${flags.claimSince} — nothing claimed\n`,
+      )
+      return
+    }
+    if (window.codes.length > 1) {
+      // Names the count, never the codes — the same silence a wrong `--claim`
+      // keeps, for the same reason. The operator has them; the page prints them.
+      process.stdout.write(
+        `spec-env review: ${window.codes.length} passes arrived in that window — ` +
+          'claim one by its code rather than guessing between them.\n',
+      )
+      return
+    }
+    claimCode = window.codes[0]
+  }
+
   // A CLAIM IS A DELIVERY MECHANISM, not a second kind of review. It lifts a
   // pass out of the holding area and hands it to exactly the same merge a
   // pasted blob goes through, so nothing downstream can tell — or behave
   // differently — by how the pass arrived.
-  if (flags.claim) {
+  if (claimCode) {
     const heldRead = readPending(out, spec.folder)
     if (heldRead.corrupt) {
       // Same rule as the notes sidecar: a file we cannot parse is not "nothing
@@ -1705,7 +1943,7 @@ async function specEnvReview(dir, config, specArg, flags) {
       )
       return
     }
-    const result = claimPending(heldRead.pending, String(flags.claim).trim())
+    const result = claimPending(heldRead.pending, String(claimCode).trim())
     if (!result.pass) {
       // NO FALLBACK, EVER. Not "the only one", not "the most recent" — either
       // would let a pass nobody read out reach the review, which is the whole
@@ -1869,6 +2107,29 @@ async function specEnvReview(dir, config, specArg, flags) {
       // read the config itself — one answer, from the engine that owns it.
       commitWith: config.review.commitWith,
     }
+
+    // A COMMITTING verdict is what the gate was waiting for, so it clears it —
+    // and only it. `changes` leaves the gate armed deliberately: the work
+    // happens, the page re-renders, and the next verdict is the exit. `discuss`
+    // likewise, including a REFUSED commit, which did not happen and must not
+    // clear an obligation on the strength of having been asked for.
+    if (judged.honoured && COMMITTING.includes(judged.effective)) {
+      const gateRead = readGate(out, spec.folder)
+      if (!gateRead.corrupt) {
+        const result = disarmGate(gateRead.gate, {
+          at: new Date().toISOString(),
+          by: 'verdict',
+          reason: judged.effective,
+        })
+        if (result.logged) {
+          writeGate(out, result.gate)
+          verdictReport.gateCleared = true
+        }
+      }
+      // A corrupt gate is left exactly as it is. It already reads as
+      // cannot-tell everywhere, so it refuses nothing — there is no obligation
+      // to clear, and writing over it would lose the log it holds.
+    }
   }
 
   // What the last decision PRODUCED — written after the thing it asked for has
@@ -1898,8 +2159,14 @@ async function specEnvReview(dir, config, specArg, flags) {
   // request rather than a discipline.
   const waiting = describePending(readPending(out, spec.folder).pending)
 
+  // Read AFTER the verdict half above, so a claim that just cleared the gate
+  // renders as cleared rather than as still owing. Corrupt contributes nothing:
+  // the page is a convenience and the gate is not what it is for.
+  const gateNow = readGate(out, spec.folder)
+  const gate = gateNow.corrupt ? null : gateNow.gate
+
   const now = new Date().toISOString()
-  let data = collectReview({ spec, git, mode, ref, base, now, notes })
+  let data = collectReview({ spec, git, mode, ref, base, now, notes, gate })
 
   // A CLEAN WORKING TREE IS NOT "NOTHING TO REVIEW". It is the state a phase
   // ends in: the page is rendered before the commit, the commit happens
@@ -1931,6 +2198,7 @@ async function specEnvReview(dir, config, specArg, flags) {
         base: fallbackBase,
         now,
         notes,
+        gate,
         fellBack: true,
       })
       if (wider.totals.files > 0) {
@@ -3196,8 +3464,12 @@ async function specEnv(rest) {
     else if (args[i] === '--resolve') flags.resolve = args[++i]
     else if (args[i] === '--outcome') flags.outcome = args[++i]
     else if (args[i] === '--claim') flags.claim = args[++i]
+    else if (args[i] === '--claim-since') flags.claimSince = args[++i]
     else if (args[i] === '--drop') flags.drop = args[++i]
     else if (args[i] === '--json') flags.json = true
+    else if (args[i] === '--check') flags.check = true
+    else if (args[i] === '--for-command') flags.forCommand = args[++i]
+    else if (args[i] === '--phase') flags.phase = args[++i]
     else if (args[i] === '--record-primary') flags.recordPrimary = true
     else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
     else positional.push(args[i])
@@ -3259,6 +3531,24 @@ async function specEnv(rest) {
         await specEnvReviewServe(dir, config, flags)
         break
       }
+      // The gate verbs sit here for the same reason `serve` does: they answer
+      // about the page this command renders, keyed to the same path, and a
+      // sibling verb would have to re-derive every bit of that.
+      if (positional[0] === 'arm') {
+        specEnvReviewArm(dir, config, positional[1], flags)
+        break
+      }
+      if (positional[0] === 'gate') {
+        specEnvReviewGate(dir, config, positional[1], flags, invokedFrom)
+        break
+      }
+      if (positional[0] === 'skip') {
+        // The one positional is the REASON, not a spec: the two are
+        // indistinguishable as free text, and the spec is the one thing this
+        // engine can already resolve from where you are standing.
+        specEnvReviewSkip(dir, config, positional[1], flags)
+        break
+      }
       await specEnvReview(dir, config, positional[0], flags)
       break
     case 'live':
@@ -3268,6 +3558,11 @@ async function specEnv(rest) {
       process.stdout.write(
         'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--json] [--record-primary] [--assert-primary-clean]\n' +
         '  review serve [--port <n>] [--host <addr>] [--stop] [--status]  serve every diff locally\n' +
+          '  review arm [spec] [--phase <n>]        a phase ended — its diff now owes a verdict\n' +
+          '  review gate [spec] [--check] [--json]  is one owed? --check exits non-zero if so\n' +
+          '       [--for-command <cmdline>]         ...but only when that command is a git commit\n' +
+          '  review skip "<reason>"                 move on without one, on the record\n' +
+          '  review [spec] --claim-since <iso>      claim the one pass that arrived since <iso>\n' +
           '  [spec] is optional everywhere: omit it and the worktree you are standing\n' +
           '  in is used, else the sole provisioned spec (several -> it lists them).\n' +
           '  A bare `live` takes that spec when the workbench is free, and prints the\n' +

package/src/env/commitcmd.js

@@ -0,0 +1,108 @@
+'use strict'
+
+/**
+ * Is this shell command a `git commit`?
+ *
+ * Asked by the review-gate hook, which is handed the command line a tool is
+ * about to run and has to decide whether the gate is even relevant. It lives
+ * here rather than inside the hook script for one reason: **a check that blocks
+ * a commit is an accusation** (`.claude/rules/negative-checks.md`), and an
+ * accusation that cannot be unit-tested will be wrong in ways nobody finds. The
+ * hook is a stdin shim over `spec-env review gate --check --for-command`; this
+ * is the part with the judgement in it.
+ *
+ * It answers TRUE only on a positive reading — a `git` invocation whose first
+ * non-option argument is `commit`. Everything it cannot parse confidently reads
+ * FALSE, because the cost of the two mistakes is not symmetric: a false
+ * negative lets one commit through a gate the skills also enforce, while a
+ * false positive blocks a command that has nothing to do with reviewing and
+ * leaves the operator with no idea why.
+ */
+
+// Shell metacharacters that end one command and begin another. `|` covers `||`
+// too, and `&` covers `&&`; over-splitting is harmless here because each
+// fragment is judged on its own.
+const SEPARATORS = /[;&|\n]+/
+
+/**
+ * Remove every quoted span. Pure.
+ *
+ * THE POINT IS WHAT THIS PREVENTS, twice over. `echo "deploy && git commit"`
+ * must not read as a commit — splitting a raw string on `&&` would manufacture
+ * a fragment out of someone's prose. And `git commit -m "fix the git log"`
+ * must still read as one: emptying the quotes leaves the real argv intact,
+ * because a verb is never inside quotes.
+ *
+ * An UNTERMINATED quote empties the rest of the line, so a half-written command
+ * reads as nothing rather than as something — the cannot-tell case going to the
+ * harmless branch, again.
+ */
+function stripQuoted(command) {
+  let out = ''
+  let quote = null
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]
+    if (quote) {
+      if (c === '\\' && quote === '"') {
+        i++
+        continue
+      }
+      if (c === quote) quote = null
+      continue
+    }
+    if (c === '"' || c === "'") {
+      quote = c
+      continue
+    }
+    out += c
+  }
+  return out
+}
+
+// git's own options, before the subcommand. Those taking a separate value have
+// to be skipped WITH their value, or `git -C /tmp commit` reads its verb as the
+// path. The `=` forms carry their value already.
+const GIT_OPTS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path'])
+
+/**
+ * Does this one fragment invoke `git commit`? Pure.
+ *
+ * `env`, `sudo`, `time` and the like are NOT unwrapped: a wrapper is not the
+ * common case and guessing at one is how a false positive gets built. The
+ * binary may be a path (`/usr/bin/git`), because that is ordinary.
+ */
+function fragmentCommits(fragment) {
+  const tokens = fragment.trim().split(/\s+/).filter(Boolean)
+  const at = tokens.findIndex((t) => t === 'git' || /(^|\/)git$/.test(t))
+  if (at === -1) return false
+
+  for (let i = at + 1; i < tokens.length; i++) {
+    const t = tokens[i]
+    if (GIT_OPTS_WITH_VALUE.has(t)) {
+      i++
+      continue
+    }
+    if (t.startsWith('-')) continue
+    // The first non-option token is the subcommand, whatever it is. Only one
+    // word is a commit.
+    return t === 'commit'
+  }
+  return false
+}
+
+/**
+ * Does this command line run `git commit` anywhere in it? Pure.
+ *
+ * WHAT WOULD FOOL THIS, named here so the next reader does not have to
+ * rediscover it: a commit hidden inside a quoted script (`sh -c 'git commit'`),
+ * behind an alias, or built by string interpolation reads as FALSE. All three
+ * are deliberate — they are the unknown case, and the unknown case does not
+ * accuse. The gate is still enforced by `/spec-next`, which does not depend on
+ * reading anybody's shell.
+ */
+function isGitCommit(command) {
+  if (typeof command !== 'string' || !command.trim()) return false
+  return stripQuoted(command).split(SEPARATORS).some(fragmentCommits)
+}
+
+module.exports = { isGitCommit, stripQuoted, fragmentCommits }

package/src/env/config.js

@@ -126,7 +126,19 @@ const DEFAULT_CONFIG = Object.freeze({
   // a verdict that records itself and does nothing. A review is the guard in
   // front of an action; recording an approval for SOMEONE ELSE to act on is a
   // different mechanism, not a value of this key.
-  review: Object.freeze({ reader: 'detect', servePort: 7777, serveOnRemote: true, commitWith: '/commit' }),
+  //
+  // `required` decides whether a phase that ended owes a verdict before its
+  // work can be committed or the next phase built. It defaults TRUE: the push
+  // toward reading the diff is the point, and a project that would rather not
+  // be pushed says so once. It is the only key anything reads to decide
+  // whether the gate refuses, so turning it off turns off the hook with it.
+  review: Object.freeze({
+    reader: 'detect',
+    servePort: 7777,
+    serveOnRemote: true,
+    commitWith: '/commit',
+    required: true,
+  }),
   // 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
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
@@ -338,6 +350,10 @@ function mergeConfig(base, parsed) {
     // here. There is nothing it could mean instead: the hand-off has no off
     // switch, so a blank value is a typo rather than an instruction.
     assign(base.review, parsed.review, 'commitWith', 'string')
+    // Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
+    // leaves the gate ON. Turning off a check that refuses must be something
+    // someone WROTE, never something a typo achieved on their behalf.
+    assign(base.review, parsed.review, 'required', 'boolean')
   }
 
   if (isObject(parsed.spec) && Array.isArray(parsed.spec.companionPaths)) {

package/src/env/hooks.js

@@ -0,0 +1,117 @@
+'use strict'
+
+/**
+ * Register the review-gate hook in the project's Claude Code settings.
+ *
+ * `.claude/settings.json` rather than `settings.local.json`, and the difference
+ * is the point: the trusted-worktree entry is an absolute path and therefore
+ * one machine's business, while this is the project's policy — a phase that
+ * ended owes a verdict — and it should reach everyone who clones the repo. The
+ * command is written with `${CLAUDE_PROJECT_DIR}` so it stays true wherever the
+ * checkout lives, worktrees included.
+ *
+ * Conservative in the same way `trust.js` is: every existing key is preserved,
+ * a file it cannot parse is left exactly as it is, and re-running changes
+ * nothing once the entry is there. Callers own the reporting.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const HOOK_SCRIPT = '.claude/hooks/review-gate.js'
+const HOOK_COMMAND = `node "\${CLAUDE_PROJECT_DIR}/${HOOK_SCRIPT}"`
+// Seconds. The engine call behind this is one git-free read of a small JSON
+// file, so anything approaching this is a wedge rather than slow work — and a
+// hook that times out fails OPEN, which is the answer we want for a wedge.
+const HOOK_TIMEOUT = 10
+const MATCHER = 'Bash'
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function settingsPath(dir) {
+  return path.join(dir, '.claude', 'settings.json')
+}
+
+function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
+}
+
+function hookEntry() {
+  return {
+    matcher: MATCHER,
+    hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: HOOK_TIMEOUT }],
+  }
+}
+
+/**
+ * Is our hook already registered under `PreToolUse`? Pure.
+ *
+ * Matched on the SCRIPT PATH, not on the whole command string. An operator who
+ * added a timeout, wrapped the invocation, or changed the interpreter has
+ * 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) {
+  if (!Array.isArray(preToolUse)) return false
+  return preToolUse.some(
+    (group) =>
+      isObject(group) &&
+      Array.isArray(group.hooks) &&
+      group.hooks.some((h) => isObject(h) && typeof h.command === 'string' && h.command.includes(HOOK_SCRIPT)),
+  )
+}
+
+/**
+ * Ensure the review-gate hook 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
+ *   - `present`   — already registered (no write)
+ *   - `malformed` — the file exists but is not parseable JSON (left untouched)
+ */
+function ensureReviewGateHook(dir) {
+  const file = settingsPath(dir)
+
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      writeSettings(file, { hooks: { PreToolUse: [hookEntry()] } })
+      return { changed: true, reason: 'created' }
+    }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    // Never rewrite a settings file we could not read. It is the operator's
+    // config and everything else in it would be lost.
+    return { changed: false, reason: 'malformed' }
+  }
+  if (!isObject(parsed)) return { changed: false, reason: 'malformed' }
+
+  const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
+  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+  if (alreadyRegistered(preToolUse)) return { changed: false, reason: 'present' }
+
+  writeSettings(file, {
+    ...parsed,
+    hooks: { ...hooks, PreToolUse: [...preToolUse, hookEntry()] },
+  })
+  return { changed: true, reason: 'added' }
+}
+
+module.exports = {
+  ensureReviewGateHook,
+  alreadyRegistered,
+  hookEntry,
+  settingsPath,
+  HOOK_SCRIPT,
+  HOOK_COMMAND,
+}