@skitterbyte/skitterspec 19.0.0 → 20.0.0

package/src/env/review.js

@@ -231,7 +231,7 @@ function resolveReader(config, env = {}) {
  * clean, not because the caller asked for it — see the fallback in
  * `specEnvReview` (`cli.js`).
  */
-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 }) {
   const files = []
   for (const f of trackedFiles(git, ref)) {
     const { patch, whole } = patchFor(git, ref, f, false)
@@ -298,6 +298,9 @@ 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) } : {}),
     // 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
@@ -705,6 +708,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.
  *
@@ -1289,9 +1485,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,20 @@ function listCommands() {
   }
 }
 
+// Hook scripts shipped as `assets/hooks/*.js`, 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.
+function listHooks() {
+  try {
+    return fs
+      .readdirSync(path.join(ASSETS, 'hooks'))
+      .filter((f) => f.endsWith('.js'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no hooks
+  }
+}
+
 function listRules() {
   return fs
     .readdirSync(path.join(ASSETS, 'rules'))
@@ -61,6 +76,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 +226,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 +390,40 @@ 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 {
+    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)
@@ -737,6 +789,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 +889,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 })