@skitterbyte/skitterspec 19.0.0 → 21.0.0

package/src/env/hooks.js

@@ -0,0 +1,157 @@
+'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')
+
+// `.cjs`, and the extension is load-bearing. This file is copied INTO the target
+// project, where that project's `package.json` decides how node parses a `.js` —
+// so the CommonJS script shipped as `review-gate.js` died on its own first
+// `require` in every `"type": "module"` project, printing a stack trace over
+// every Bash tool call. `.cjs` settles the parse mode at the file, independently
+// of the one file skitterspec does not control.
+const HOOK_STEM = '.claude/hooks/review-gate'
+const HOOK_SCRIPT = `${HOOK_STEM}.cjs`
+const HOOK_COMMAND = `node "\${CLAUDE_PROJECT_DIR}/${HOOK_SCRIPT}"`
+
+// Our script under ANY extension, so a registration naming the retired `.js` is
+// recognised as ours and migrated rather than duplicated. The trailing lookahead
+// is the boundary: without it `review-gate-extra.js` — somebody else's hook —
+// matches on the stem and gets silently rewritten.
+const HOOK_SCRIPT_RE = /[.]claude[/\\]hooks[/\\]review-gate(?:[.][A-Za-z0-9]+)?(?![\w.-])/
+// 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) {
+  return registeredHooks(preToolUse).length > 0
+}
+
+// Every hook object under `PreToolUse` whose command names our script, whatever
+// extension it names it under. Pure.
+function registeredHooks(preToolUse) {
+  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)
+    }
+  }
+  return out
+}
+
+/**
+ * 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
+ *   - `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)
+ */
+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 : []
+
+  // 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' }
+  }
+
+  writeSettings(file, {
+    ...parsed,
+    hooks: { ...hooks, PreToolUse: [...preToolUse, hookEntry()] },
+  })
+  return { changed: true, reason: 'added' }
+}
+
+module.exports = {
+  ensureReviewGateHook,
+  alreadyRegistered,
+  registeredHooks,
+  hookEntry,
+  settingsPath,
+  HOOK_STEM,
+  HOOK_SCRIPT,
+  HOOK_SCRIPT_RE,
+  HOOK_COMMAND,
+}

package/src/env/review.js

@@ -230,8 +230,11 @@ function resolveReader(config, env = {}) {
  * `fellBack` records that `branch` was reached because the working tree was
  * clean, not because the caller asked for it — see the fallback in
  * `specEnvReview` (`cli.js`).
+ *
+ * `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
+ * caller's declaration about the work, not a reading of the gate.
  */
-function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, fellBack = false }) {
+function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null }) {
   const files = []
   for (const f of trackedFiles(git, ref)) {
     const { patch, whole } = patchFor(git, ref, f, false)
@@ -298,6 +301,13 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
     // Absent stays absent, exactly as `phases` does: a spec this cannot read
     // adds no key and the page renders its header-less self.
     ...(context ? { context } : {}),
+    // Same rule again: a gate that was never armed and never skipped adds no
+    // key at all.
+    ...(gateForPage(gate) ? { gate: gateForPage(gate) } : {}),
+    // THE DEFAULT ADDS NO KEY, so a caller that did not ask for a button set —
+    // and a caller that asked for the default by name — renders the payload it
+    // rendered before this existed. Opting in is the only thing that shows.
+    ...(buttons && buttons !== DEFAULT_BUTTON_SET ? { buttons } : {}),
     // WHICH ENGINE DREW THIS PAGE. The render is always current — the git reads
     // happen per request — so a page rendered by a stale process looks entirely
     // right: the counts move, `generatedAt` moves, the diff is correct. Only the
@@ -396,16 +406,46 @@ const NOTES_VERSION = 1
  * `discuss` is the default because it is the behaviour that existed before any
  * verdict did. So a blob from an older page, or one a reader sent without
  * choosing, keeps doing exactly what it always did.
+ *
+ * `continue` is the mid-run verdict: *I have read it, carry on*. It names an
+ * action, which is what separates it from the `none` verdict that was removed —
+ * `none` recorded itself and did nothing, while this one resumes the run. What
+ * it does NOT do is commit, so it is deliberately absent from `COMMITTING`
+ * below and is therefore structurally incapable of clearing an armed gate: a
+ * phase that ended still owes a committing verdict or a recorded skip.
  */
-const VERDICTS = ['commit', 'commit-continue', 'changes', 'discuss']
+const VERDICTS = ['commit', 'commit-continue', 'continue', 'changes', 'discuss']
 const DEFAULT_VERDICT = 'discuss'
 
 // The verdicts that COMMIT, and are therefore blocked by an open comment. One
-// list, so a fourth verdict cannot become a way around the single refusal this
+// list, so a fifth verdict cannot become a way around the single refusal this
 // engine makes — adding a committing verdict means adding it here, and the
 // block follows for free.
+//
+// `continue` IS DELIBERATELY NOT HERE, and that omission is the whole of
+// decision 2: waiting is what any offer does, while arming asserts an
+// obligation that outlives the turn. A mid-run reader saying "carry on" has
+// answered the offer in front of them and nothing else, so the gate a finished
+// phase armed must survive it untouched.
 const COMMITTING = ['commit', 'commit-continue']
 
+/**
+ * Which set of buttons a rendered page shows.
+ *
+ * DECLARED BY THE CALLER, NEVER DERIVED FROM THE GATE. Deriving it — mid-run
+ * iff the gate is unarmed — is tidier and wrong: a project running
+ * `review.required: false` never arms at all, so every one of its pages would
+ * lose the committing buttons and the reader could never commit from the page.
+ * The caller knows whether the work it just rendered is finished; the gate only
+ * knows whether this project opted into gating.
+ *
+ * `committing` is the default, so a caller that says nothing keeps today's page
+ * exactly — the key is left off the payload entirely rather than written out as
+ * the default, so an unchanged caller renders an unchanged page.
+ */
+const BUTTON_SETS = ['committing', 'midrun']
+const DEFAULT_BUTTON_SET = 'committing'
+
 /**
  * What an older sidecar's `approve` means now. Pure.
  *
@@ -705,6 +745,199 @@ function claimPending(pending, code) {
   return { pass, pending: { ...pending, passes: rest }, count: rest.length }
 }
 
+/**
+ * Which pass arrived inside a WAIT WINDOW. Pure — it selects, never claims.
+ *
+ * THE WINDOW IS THE SCOPE, and it is what replaces "a person typed the
+ * command" when a watch wakes the session instead. A skill that asked to be
+ * woken when the store changed knows one thing nothing else does: the moment
+ * it started waiting. A pass sent after that, while it was waiting, is the
+ * pass it was waiting for — and a pass that was already there is a stranger's,
+ * or an older sitting's, and must not be swept up by a wait that was not about
+ * it.
+ *
+ * Three answers, and only one of them acts:
+ *
+ * - exactly one in the window → that is the pass, named by its code.
+ * - none → nothing to claim. Ordinary: the watch can fire on a write that was
+ *   not a pass at all.
+ * - more than one → REFUSE and name the count, never pick. Two people, or two
+ *   sittings, landed in one window; choosing between them is exactly the guess
+ *   `claimPending` refuses to make, and the operator has the codes.
+ *
+ * A pass whose `at` cannot be parsed is never in the window. That is the
+ * cannot-tell case routed to inaction (`.claude/rules/negative-checks.md` rule
+ * 4): including it would auto-claim a pass whose age — the one tell a stranger
+ * has — could not be established.
+ */
+function passesSince(pending, since) {
+  const from = Date.parse(since)
+  if (!Number.isFinite(from)) return { codes: [], usable: false }
+  const codes = (pending.passes || [])
+    .filter((p) => {
+      const at = Date.parse(p.at)
+      return Number.isFinite(at) && at >= from
+    })
+    .map((p) => p.code)
+  return { codes, usable: true }
+}
+
+/* ==========================================================================
+ * The gate — a standing obligation to review, not a message in flight
+ *
+ * A pending pass is something someone SENT. The gate is something the repo
+ * OWES: a phase ended, its page was rendered, and nobody has said what they
+ * concluded yet. Kept in its own sidecar for exactly that reason — claiming a
+ * pass consumes the pass, while only a COMMITTING verdict or a recorded skip
+ * consumes the gate, and one file holding both states would have to encode
+ * that difference anyway.
+ *
+ * It is the one thing in this engine that refuses. The marks still gate
+ * nothing and nothing counts them — what this asserts is narrower: a phase
+ * that ended is not finished until a person said something about it.
+ * ========================================================================== */
+
+const GATE_VERSION = 1
+
+// How a disarm happened. `verdict` is a review that reached a committing
+// conclusion; `skip` is the operator saying, on the record, that they are
+// moving on without one.
+const DISARMED_BY = ['verdict', 'skip']
+
+function reviewGatePath(outPath) {
+  return outPath.replace(/\.html$/, '') + '.gate.json'
+}
+
+function emptyGate(specFolder) {
+  return { version: GATE_VERSION, spec: specFolder, armed: false, armedAt: null, phase: null, log: [] }
+}
+
+/**
+ * Read the gate sidecar. Never throws, and reports `corrupt` rather than
+ * hiding it — the same three states `readNotes` answers in, for the same
+ * reason. Here the third state is load-bearing in the other direction: a gate
+ * we cannot parse must never READ AS ARMED, because that would refuse a commit
+ * on the strength of a file nobody can interpret.
+ */
+function readGate(outPath, specFolder) {
+  let raw
+  try {
+    raw = fs.readFileSync(reviewGatePath(outPath), 'utf8')
+  } catch {
+    // Absent is the ordinary state — a project that never ends a phase through
+    // the review path has no gate file at all.
+    return { gate: emptyGate(specFolder), corrupt: false, present: false }
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    return {
+      gate: {
+        version: parsed.version,
+        spec: parsed.spec || specFolder,
+        armed: parsed.armed === true,
+        armedAt: parsed.armedAt || null,
+        phase: parsed.phase === undefined ? null : parsed.phase,
+        log: Array.isArray(parsed.log) ? parsed.log : [],
+      },
+      corrupt: false,
+      present: true,
+    }
+  } catch {
+    return { gate: emptyGate(specFolder), corrupt: true, present: true }
+  }
+}
+
+function writeGate(outPath, gate) {
+  const p = reviewGatePath(outPath)
+  fs.mkdirSync(path.dirname(p), { recursive: true })
+  fs.writeFileSync(p, JSON.stringify(gate, null, 2) + '\n')
+  return p
+}
+
+/**
+ * Arm the gate. Pure.
+ *
+ * IDEMPOTENT ON PURPOSE. Re-rendering a page for a phase already awaiting a
+ * verdict must not move `armedAt` — the timestamp answers "how long has this
+ * been waiting", and a render is not an event that resets that. A gate armed
+ * for a DIFFERENT phase is re-armed, because that is a new obligation.
+ */
+function armGate(gate, { at, phase = null }) {
+  if (gate.armed && gate.phase === phase) return gate
+  return { ...gate, armed: true, armedAt: at, phase }
+}
+
+/**
+ * Disarm it, and say how. Pure.
+ *
+ * The log is append-only and nothing reads it back to decide anything — it is
+ * the record that a decision was taken, which is the whole value of a skip
+ * over a silence. Disarming an already-clear gate logs nothing: there was no
+ * obligation, so there is no outcome to record.
+ */
+function disarmGate(gate, { at, by, reason = null }) {
+  if (!gate.armed) return { gate, logged: false }
+  const log = Array.isArray(gate.log) ? gate.log.slice() : []
+  log.push({ by, at, phase: gate.phase === undefined ? null : gate.phase, reason })
+  return { gate: { ...gate, armed: false, armedAt: null, phase: null, log }, logged: true }
+}
+
+/**
+ * What the gate says, in three states. Pure.
+ *
+ * `armed` is the only one that refuses, and it is reached only by a POSITIVE
+ * signal: a sidecar that is present, parseable, and says so
+ * (`.claude/rules/negative-checks.md` rule 1). Everything else routes to the
+ * harmless branch (rule 4) under its own name:
+ *
+ * - `clear` — read it, nothing is owed.
+ * - `unknown` — could not read it, or the project turned the gate off. Nothing
+ *   is claimed and nothing refuses.
+ *
+ * WHAT WOULD FOOL THIS: a gate armed for a phase whose work has since been
+ * committed by hand still reads armed, so the refusal outlives the thing it
+ * was guarding. That is deliberate — the exit is one `skip` with a reason,
+ * which is precisely the decision this exists to put on the record — and it
+ * fails toward asking rather than toward letting a phase through unread.
+ */
+/**
+ * What the page is told about the gate. Pure. `null` when there is nothing to
+ * say, so a project that never armed one renders byte-identically to how it
+ * did before any of this existed — the same rule `phases` and `context` follow.
+ *
+ * The last SKIP travels with it, because that is the page's answer to the one
+ * question an untouched-looking review raises: was this read and moved past, or
+ * never read at all? A verdict already had an answer there; a skip did not.
+ */
+function gateForPage(gate) {
+  if (!gate) return null
+  const log = Array.isArray(gate.log) ? gate.log : []
+  const skips = log.filter((e) => e && e.by === 'skip')
+  const lastSkip = skips.length ? skips[skips.length - 1] : null
+  if (!gate.armed && !lastSkip) return null
+  return {
+    armed: gate.armed === true,
+    armedAt: gate.armedAt || null,
+    phase: gate.phase === undefined ? null : gate.phase,
+    ...(lastSkip ? { lastSkip: { at: lastSkip.at || null, reason: lastSkip.reason || null } } : {}),
+  }
+}
+
+function gateState({ gate, corrupt, present, required }) {
+  if (required === false) return { state: 'unknown', reason: 'review.required is false', gate }
+  if (corrupt) return { state: 'unknown', reason: 'the gate sidecar is not readable JSON', gate }
+  if (!present) return { state: 'clear', reason: 'no gate recorded', gate }
+  if (gate.version !== GATE_VERSION) {
+    return {
+      state: 'unknown',
+      reason: `gate version ${JSON.stringify(gate.version)} — this engine reads version ${GATE_VERSION}`,
+      gate,
+    }
+  }
+  if (!gate.armed) return { state: 'clear', reason: 'nothing is awaiting a verdict', gate }
+  return { state: 'armed', reason: 'a phase is awaiting a verdict', gate }
+}
+
 /**
  * Validate a blob from the page, wholesale.
  *
@@ -1269,6 +1502,8 @@ module.exports = {
   NOTES_VERSION,
   VERDICTS,
   COMMITTING,
+  BUTTON_SETS,
+  DEFAULT_BUTTON_SET,
   readVerdict,
   DEFAULT_VERDICT,
   DELETED_HASH,
@@ -1289,9 +1524,20 @@ module.exports = {
   mintPendingCode,
   addPending,
   claimPending,
+  passesSince,
   describePending,
   pendingAge,
   PENDING_CODE_LENGTH,
+  GATE_VERSION,
+  DISARMED_BY,
+  reviewGatePath,
+  emptyGate,
+  readGate,
+  writeGate,
+  armGate,
+  disarmGate,
+  gateState,
+  gateForPage,
   mergeNotes,
   applyResolutions,
   applyNotes,

package/src/env/serve.js

@@ -8,9 +8,16 @@
  * moment: true when it was taken, and overwritten by the next render. A served
  * page cannot be out of date, because there is no artefact between the git
  * objects and the response. That is the whole reason this exists, and it is why
- * nothing here reads or writes `.spec-env/reviews/` — the file path and the
- * served path are two answers to the same question, and keeping them
- * independent is what stops one quietly becoming the other's cache.
+ * no HTML is read from or written to `.spec-env/reviews/` — the file path and
+ * the served path are two answers to the same question, and keeping the
+ * artefacts independent is what stops one quietly becoming the other's cache.
+ *
+ * THE SIDECARS ARE A DIFFERENT MATTER, and this once over-applied the rule
+ * above to them. Notes, the gate and the pending store are the REVIEW'S state,
+ * not the page's: they belong to whoever is reading, and a reader on a phone is
+ * reading this page. So they are read here (and, for a pass arriving, written)
+ * — which is what makes a refresh keep your accepts and the history line say
+ * what happened. What is never read here is a rendered page.
  *
  * Dependency-free, in the shape of `proxy.js`: pure functions for routing and
  * the index, an injectable render callback, and a `require.main` entry point so
@@ -40,6 +47,8 @@ const {
   readPending,
   writePending,
   addPending,
+  readNotes,
+  readGate,
 } = require('./review.js')
 
 /**
@@ -248,7 +257,20 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
     mode = 'branch'
   }
 
-  let data = collectReview({ spec, git, mode, ref, base: baseName, now })
+  // THE REVIEW STATE IS THE READER'S, not the artefact's. It was once left out
+  // here on the reasoning that this path writes no file — but a reader on a
+  // phone is reading THIS page, and without the sidecar their own accepts
+  // vanish on every refresh and the history line never appears at all. The two
+  // surfaces answered differently about the same review, which is worse than
+  // either answer. Read-only: nothing on this path writes the sidecar.
+  const out = reviewOutPath(dir, spec.folder, null)
+  const notes = readNotes(out, spec.folder).notes
+  const gateRead = readGate(out, spec.folder)
+  // A corrupt gate contributes nothing rather than failing the render. The page
+  // is a convenience and the gate is not what it is for.
+  const gate = gateRead.corrupt ? null : gateRead.gate
+
+  let data = collectReview({ spec, git, mode, ref, base: baseName, now, notes, gate })
 
   if (!branch && data.totals.files === 0) {
     const fallbackBase = base()
@@ -261,6 +283,8 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
         ref: mergeBase,
         base: fallbackBase,
         now,
+        notes,
+        gate,
         fellBack: true,
       })
       if (wider.totals.files > 0) {

package/src/init.js

@@ -5,6 +5,7 @@ const path = require('path')
 const crypto = require('crypto')
 
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
+const { ensureReviewGateHook } = require('./env/hooks.js')
 const { repoInfo, expandTokens } = require('./env/resolve.js')
 
 const ASSETS = path.join(__dirname, '..', 'assets')
@@ -38,6 +39,29 @@ function listCommands() {
   }
 }
 
+// Hook scripts shipped as `assets/hooks/*.cjs` (or `*.mjs`), installed to
+// `.claude/hooks/`. Discovered from the bundled tree like everything else, so a
+// distribution installs precisely what it ships and a hook can be retired by
+// deleting it.
+//
+// A BARE `.js` IS DELIBERATELY NOT DISCOVERED. These files are copied into the
+// TARGET project, where that project's `package.json` — the one file skitterspec
+// does not control — decides how node parses a `.js`. Shipping CommonJS as `.js`
+// crashed the review-gate hook in every `"type": "module"` project, on every
+// Bash tool call. The extension is the only thing that settles it at the file,
+// so both accepted forms pin it; `env-review-hook.test.js` asserts the rule over
+// the whole directory rather than over this filter.
+function listHooks() {
+  try {
+    return fs
+      .readdirSync(path.join(ASSETS, 'hooks'))
+      .filter((f) => f.endsWith('.cjs') || f.endsWith('.mjs'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no hooks
+  }
+}
+
 function listRules() {
   return fs
     .readdirSync(path.join(ASSETS, 'rules'))
@@ -61,6 +85,8 @@ const COMMANDS = listCommands()
 
 const RULES = listRules()
 
+const HOOKS = listHooks()
+
 const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
 
 // Opt-in config templates, scaffolded into specs/.core/ (the base ships the
@@ -209,6 +235,7 @@ function managedTargets(dir) {
   for (const name of COMMANDS)
     add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
   for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
+  for (const name of HOOKS) add(path.join('hooks', name), path.join(dir, '.claude', 'hooks', name))
   for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
   return out
 }
@@ -372,6 +399,46 @@ function installRule(dir, opts) {
   }
 }
 
+// Register the review-gate hook in the project's committed settings, so a
+// phase that owes a verdict is enforced one level below the skills. Best-effort
+// in exactly the way `trustWorktreeRoot` is: a settings file we cannot parse is
+// 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)'
+  let res
+  try {
+    res = ensureReviewGateHook(dir)
+  } catch {
+    report.warnings.push('could not write .claude/settings.json — review-gate hook not registered')
+    return
+  }
+  if (res.reason === 'malformed') {
+    report.warnings.push(
+      '.claude/settings.json is not valid JSON — did not register the review-gate hook',
+    )
+  } else if (res.reason === 'created') {
+    report.created.push(label)
+  } else if (res.reason === 'added') {
+    report.updated.push(label)
+  } else if (res.reason === 'migrated') {
+    // A WRITE, so it may not fall through to `skipped`. It was doing exactly
+    // 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)')
+  } else {
+    report.skipped.push('.claude/settings.json (review-gate hook already registered)')
+  }
+}
+
+function installHooks(dir, opts) {
+  for (const name of HOOKS) {
+    copyAsset(dir, path.join('hooks', name), path.join(dir, '.claude', 'hooks', name), opts)
+  }
+  registerReviewGateHook(dir)
+}
+
 function installFolders(dir) {
   for (const folder of SPEC_FOLDERS) {
     const abs = path.join(dir, 'specs', folder)
@@ -676,6 +743,15 @@ function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
   installFolders(dir)
   removeRetiredFiles(dir)
   pruneRetiredManaged(dir, manifest)
+  // The hook SCRIPT arrives above, as one more managed target; registering it is
+  // a separate write to a file we do not manage, so it has to be asked for here.
+  // It is easy to read this as duplication of `installHooks()` and delete it —
+  // it is not. `installHooks()` is unreachable from this path, and the two
+  // halves being in different functions is exactly how they drifted apart once:
+  // `update` copied `.claude/hooks/` and registered nothing, for every upgrading
+  // project, while reporting a file created. `init-review-gate-hook.test.js`
+  // asserts over the entry points rather than over this call.
+  registerReviewGateHook(dir)
   if (claudeMd) installClaudeMd(dir, { mode: 'update' })
   flushManifest(dir)
   printReport(dir, 'resync', { diff })
@@ -737,6 +813,7 @@ function reset(dir, { claudeMd = true } = {}) {
   installSkills(dir, { force: true })
   installCommands(dir, { force: true })
   installRule(dir, { force: true })
+  installHooks(dir, { force: true })
   installFolders(dir)
   removeRetiredFiles(dir)
   installCore(dir, { force: true })
@@ -836,6 +913,7 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gati
   installSkills(dir, { force })
   installCommands(dir, { force })
   installRule(dir, { force })
+  installHooks(dir, { force })
   installFolders(dir)
   removeRetiredFiles(dir)
   installCore(dir, { force })