create-agent-rig 0.5.0 → 0.6.0

package/templates/agent-os/universal/.claude/scripts/run-state.mjs

@@ -1,6 +1,8 @@
 /**
  * The run's own state — three of the four values `stopConditionOf` asks for and
- * nothing used to answer. The fourth, `killSwitch`, is deliberately not here:
+ * nothing used to answer, plus one value it does not ask for: the take-up
+ * snapshot `takeUps` ({@link recordTakeUp}), which is the run's fact as much as
+ * the other three. The fourth stop input, `killSwitch`, is deliberately not here:
  * it is already mechanical in `guard-bash` and scripted in preflight, and a
  * second answer to "is the brake on" is the disagreement `invariants.md`
  * forbids.
@@ -47,8 +49,8 @@
  * per run is the caller's part of the contract, and the `loop` skill states it.
  */
 
-import { readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { opendirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const STATE = 'state.json';
@@ -199,6 +201,102 @@ export const recordEscalation = (runDir) => {
   }
 };
 
+/**
+ * The take-up snapshot: the selected item's `updatedAt` marker, keyed by id, as
+ * seen at SELECT. `queue/core.mjs` › revalidationOf compares the next selection
+ * against it, so a stale take-up is reported rather than silently continued.
+ *
+ * Per run, like everything else here — a snapshot from yesterday's run is not
+ * a take-up this run made. Merged by id, so a second item does not erase the
+ * first; re-recording an id moves its baseline forward. A marker that is not a
+ * string is not recorded at all: `plan-md` has none, and writing `null` would
+ * later compare equal to `null` and read as "unchanged".
+ *
+ * No run directory → nothing written, `null` back, no throw: an attended
+ * selection has no run to snapshot into. (Like {@link recordEscalation} it
+ * refuses to throw there; unlike it, there is no count to hand back, so `null`.)
+ */
+export const recordTakeUp = (runDir, { id, updatedAt } = {}) => {
+  if (!runDir || typeof updatedAt !== 'string' || id === undefined || id === null) return null;
+  const state = readState(runDir);
+  const takeUps = typeof state.takeUps === 'object' && state.takeUps !== null ? state.takeUps : {};
+  return updateState(runDir, { takeUps: { ...takeUps, [String(id)]: updatedAt } });
+};
+
+/**
+ * The take-up an EARLIER run recorded for this item, or null (AR-138).
+ *
+ * {@link recordTakeUp} is per run on purpose, and that left a hole RX1
+ * measured: an item taken up yesterday and re-offered today compared against
+ * nothing and reported a first sight, however far its marker had moved. So
+ * when this run has no take-up for the item, SELECT asks the sibling run
+ * directories — newest first by name, which is the `YYYYMMDD-HHMMSS` the
+ * `loop` skill declares — and takes the first that recorded one. The answer
+ * names the run it came from, so the revalidation event can say whose
+ * baseline it compared against.
+ *
+ * 🔴 A sibling is a run only by NAME — `YYYYMMDD-HHMMSS`, the shape the `loop`
+ * skill declares — and so is the run asking. The first version took every
+ * sibling directory, and two measurements showed why that is wrong. On CI,
+ * with `RIG_RUN_DIR` under a shared temp root, a neighbouring test's scratch
+ * directory carrying a `state.json` was read as yesterday's run, and a first
+ * sight came back as a hold against a marker nobody had taken up. Locally,
+ * the same temp root held 454 000 entries, and every SELECT paid a 540 ms
+ * directory read for a question it could not answer. So a run declared under
+ * another naming looks at no siblings at all, and the limit is the mirror
+ * image: an earlier run declared under another naming is not seen here.
+ *
+ * Bounded and fail-soft: the runs root is walked through one directory handle
+ * and at most 10 000 entries are looked at, whatever is in there; at most 200
+ * candidate runs are read, an unreadable state is skipped rather than trusted,
+ * and the answer is `null` for no run directory, an unnamed one, or no runs
+ * root. Never this run's own state — that is {@link readState}'s answer, and
+ * the caller asks it first.
+ */
+const RUN_DIR_NAME = /^\d{8}-\d{6}$/;
+const RUNS_ROOT_ENTRY_BUDGET = 10_000;
+const RUNS_READ_CAP = 200;
+
+export const previousTakeUp = (runDir, id) => {
+  if (!runDir || id === undefined || id === null) return null;
+  const root = dirname(runDir);
+  const self = basename(runDir);
+  if (!RUN_DIR_NAME.test(self)) return null;
+  const names = [];
+  let dir;
+  try {
+    dir = opendirSync(root);
+  } catch {
+    return null;
+  }
+  try {
+    for (let seen = 0; seen < RUNS_ROOT_ENTRY_BUDGET; seen += 1) {
+      const entry = dir.readSync();
+      if (entry === null) break;
+      if (entry.isDirectory() && entry.name !== self && RUN_DIR_NAME.test(entry.name)) {
+        names.push(entry.name);
+      }
+    }
+  } catch {
+    return null;
+  } finally {
+    dir.closeSync();
+  }
+  names.sort().reverse();
+  for (const name of names.slice(0, RUNS_READ_CAP)) {
+    const candidate = join(root, name);
+    let state;
+    try {
+      state = JSON.parse(readFileSync(statePathIn(candidate), 'utf8'));
+    } catch {
+      continue;
+    }
+    const updatedAt = state?.takeUps?.[String(id)];
+    if (typeof updatedAt === 'string') return { updatedAt, runDir: candidate };
+  }
+  return null;
+};
+
 /**
  * The stop inputs, read out of a state object that anything may have written.
  *

package/templates/agent-os/universal/.claude/scripts/stop-flag.mjs

@@ -21,19 +21,26 @@ import { existsSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { delimiter, join } from 'node:path';
 
-/** Every path that arms the brake. The machine-level default is always first. */
-export const stopFlags = (env = process.env) => {
-  // BOTH homes: `homedir()` honours $HOME, which `.claude/settings.json` can set —
-  // pointing it at an empty directory disarmed the brake. `userInfo()` reads the
-  // password database and ignores the environment, so the operator's real flag is
-  // always among the paths checked.
-  const homes = new Set([homedir()]);
+/**
+ * BOTH homes, env-derived first: `$HOME` (what `.claude/settings.json` can set —
+ * pointing it at an empty directory once disarmed the brake) and the password
+ * database's, which ignores the environment, so the operator's real flag is
+ * always among the paths checked. Shared with the unattended flag (AR-51): one
+ * lookup, one place to be wrong.
+ */
+export const homesOf = (env = process.env) => {
+  const homes = new Set([env.HOME || homedir()]);
   try {
     homes.add(userInfo().homedir);
   } catch {
     // no password entry — the env-derived home is all there is
   }
-  const paths = [...homes].map((home) => join(home, '.claude', '__PROJECT_NAME__-loop-STOP'));
+  return [...homes];
+};
+
+/** Every path that arms the brake. The machine-level default is always first. */
+export const stopFlags = (env = process.env) => {
+  const paths = homesOf(env).map((home) => join(home, '.claude', '__PROJECT_NAME__-loop-STOP'));
   const extra = env.AGENT_LOOP_STOP;
   if (extra) {
     // Filtered and CAPPED before the spread, never after. Spreading an

package/templates/agent-os/universal/.claude/scripts/unattended-flag.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// The unattended flag — how a hook learns that a loop is running, and what the
+// current item is allowed to touch (AR-51).
+//
+//   node .claude/scripts/unattended-flag.mjs on --item AR-51 --run-dir <dir> --allow <prefix> [<prefix>…]
+//   node .claude/scripts/unattended-flag.mjs off
+//
+// It is a FILE, not an environment variable: a `PreToolUse` hook is spawned by
+// the harness with the harness's own environment, never with a variable the
+// session exported — the generator's `test/template/guard-rulebook.test.ts` ›
+// "only a flag arms it — an exported RIG_UNATTENDED=1 with no flag changes
+// nothing" pins that side of it — and in some harnesses an `export` does not
+// even survive to the next Bash call. The kill switch (`stop-flag.mjs`) is a
+// file for the same reason,
+// and this module copies its shape: machine-level, under BOTH homes, so a
+// worktree sees it and a `$HOME` set from `.claude/settings.json` cannot hide it.
+//
+// The flag is JSON, `{ item, runDir, allow }`. `allow` is the list of
+// repo-relative prefixes the current item may write under even though they are
+// part of the rulebook — the loop writes it at claim time from the paths the
+// item names, and clears the flag when the run ends. A blanket "no rulebook
+// edits while unattended" would stall on the first queue item that touches
+// `queue/*.mjs`, which is most of this queue; the allow-list is what makes the
+// guard livable, and the guard is what makes the allow-list a decision rather
+// than a default.
+//
+// 🔴 Three answers, and the third is not the first: `{ on: false }` when no flag
+// exists — an attended session, the guard does nothing; `{ on: true, item,
+// runDir, allow }` when it reads; `{ on: true, unreadable: true, why }` when a
+// file is THERE and this module cannot read it as the shape above. A guard that
+// treated the third as the first would be disarmed by a corrupt flag, which is
+// the fail-open bypass `.claude/rules/invariants.md` names.
+//
+// 🔴 An `allow` entry may not WIDEN the rulebook: one that is a prefix of a
+// rulebook prefix — `.`, `.claude/`, `.claude/scripts/`, `CLAUDE` — would let
+// the flag disarm the guard for a whole tree while it reports itself as on, so
+// the writer refuses it and a flag carrying one is unreadable. An entry outside
+// the rulebook (`src/`, `.claude/skills/loop/`) is harmless — such a path is
+// never judged — and items name those all the time, so it is kept, not
+// refused — › "an allow entry that widens the rulebook — a prefix of a rulebook prefix such as `.` — makes the flag unreadable".
+//
+// Bounded: the file is read up to 64 KiB, `allow` is capped at 64 entries, and
+// both limits are refusals, never silent truncation.
+import { closeSync, existsSync, mkdirSync, openSync, readSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { homesOf } from './stop-flag.mjs';
+
+export const FLAG_BASENAME = '__PROJECT_NAME__-loop-UNATTENDED';
+export const MAX_FLAG_BYTES = 64 * 1024;
+export const MAX_ALLOW_ENTRIES = 64;
+
+/**
+ * The files that decide what a session may do — repo-relative prefixes. Owned
+ * here because two things read them: the guard, to judge an edit, and the
+ * writer above, to refuse an allow-list that reaches outside them.
+ */
+export const RULEBOOK_PREFIXES = Object.freeze([
+  '.claude/hooks/',
+  '.claude/settings.json',
+  '.claude/queue.json',
+  '.claude/scripts/queue/',
+  '.claude/scripts/decision-router.mjs',
+  '.claude/scripts/detect-missed-gate.mjs',
+  '.claude/rules/',
+  'CLAUDE.md',
+]);
+
+/** Is this repo-relative path part of the rulebook? */
+export const isRulebookPath = (rel) =>
+  RULEBOOK_PREFIXES.some((prefix) => rel === prefix || rel.startsWith(prefix));
+
+/**
+ * Does this allow entry widen the rulebook — is it a proper prefix of a rulebook
+ * prefix, so that it would admit the whole prefix and more? `.claude/scripts/`
+ * widens (it covers `.claude/scripts/queue/` and its siblings); `src/` does not
+ * (it covers nothing the guard judges); `.claude/scripts/queue/` does not (it is
+ * exactly a rulebook prefix, the ordinary allow entry).
+ */
+export const isWidening = (entry) =>
+  typeof entry !== 'string' ||
+  entry === '' ||
+  RULEBOOK_PREFIXES.some((prefix) => prefix !== entry && prefix.startsWith(entry));
+
+/** Every path that arms unattended mode. The env-derived home is first. */
+export const unattendedFlags = (env = process.env) =>
+  homesOf(env).map((home) => join(home, '.claude', FLAG_BASENAME));
+
+const readCapped = (path) => {
+  const fd = openSync(path, 'r');
+  try {
+    const buffer = Buffer.alloc(MAX_FLAG_BYTES + 1);
+    const bytes = readSync(fd, buffer, 0, buffer.length, 0);
+    return { bytes, text: buffer.toString('utf8', 0, Math.min(bytes, MAX_FLAG_BYTES)) };
+  } finally {
+    closeSync(fd);
+  }
+};
+
+const unreadable = (path, why) => ({ on: true, unreadable: true, path, why });
+
+/** The mode the flag declares — see the header for the three answers. */
+export const readUnattended = (env = process.env) => {
+  const path = unattendedFlags(env).find((candidate) => {
+    try {
+      return existsSync(candidate);
+    } catch {
+      return false;
+    }
+  });
+  if (!path) return { on: false };
+  let raw;
+  try {
+    raw = readCapped(path);
+  } catch (error) {
+    return unreadable(path, `cannot be read: ${error?.code ?? 'read failed'}`);
+  }
+  if (raw.bytes > MAX_FLAG_BYTES) return unreadable(path, `larger than ${MAX_FLAG_BYTES} bytes`);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw.text);
+  } catch {
+    return unreadable(path, 'not valid JSON');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return unreadable(path, 'not a JSON object');
+  }
+  if (!Array.isArray(parsed.allow) || parsed.allow.some((entry) => typeof entry !== 'string')) {
+    return unreadable(path, '`allow` is not an array of strings');
+  }
+  if (parsed.allow.length > MAX_ALLOW_ENTRIES) {
+    return unreadable(path, `\`allow\` carries more than ${MAX_ALLOW_ENTRIES} entries`);
+  }
+  const allow = parsed.allow.map((entry) => entry.trim()).filter(Boolean);
+  const wide = allow.find(isWidening);
+  if (wide !== undefined) {
+    return unreadable(
+      path,
+      `\`allow\` entry ${JSON.stringify(wide)} widens the rulebook (it is a prefix of a rulebook prefix) — an allow-list narrows the rulebook, never widens it`,
+    );
+  }
+  return {
+    on: true,
+    item: typeof parsed.item === 'string' ? parsed.item : null,
+    runDir: typeof parsed.runDir === 'string' ? parsed.runDir : null,
+    allow,
+  };
+};
+
+/** Write the flag under the env-derived home. Returns the paths written. */
+export const writeUnattended = ({ item, runDir = null, allow = [] } = {}, env = process.env) => {
+  if (typeof item !== 'string' || item.trim() === '') {
+    throw new Error('the unattended flag needs an item id — a run without an item has nothing to allow');
+  }
+  const list = (Array.isArray(allow) ? allow : []).map((entry) => String(entry).trim()).filter(Boolean);
+  if (list.length > MAX_ALLOW_ENTRIES) {
+    throw new Error(`the allow-list is capped at ${MAX_ALLOW_ENTRIES} entries`);
+  }
+  const wide = list.find(isWidening);
+  if (wide !== undefined) {
+    throw new Error(
+      `allow entry ${JSON.stringify(wide)} widens the rulebook — it is a prefix of one of ${RULEBOOK_PREFIXES.join(', ')}; ` +
+        'an allow-list narrows the rulebook, never widens it. A directory entry needs its trailing slash ' +
+        '(`.claude/hooks/`, not `.claude/hooks`).',
+    );
+  }
+  const [path] = unattendedFlags(env);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ item: item.trim(), runDir, allow: list }, null, 2)}\n`);
+  return [path];
+};
+
+/** Remove every flag that exists. Returns the paths removed. */
+export const clearUnattended = (env = process.env) => {
+  const removed = [];
+  for (const path of unattendedFlags(env)) {
+    try {
+      if (existsSync(path)) {
+        rmSync(path);
+        removed.push(path);
+      }
+    } catch {
+      // a home this process cannot write is not this run's flag to remove
+    }
+  }
+  return removed;
+};
+
+const invokedDirectly = () => {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+};
+
+if (invokedDirectly()) {
+  const [word, ...rest] = process.argv.slice(2);
+  const valueOf = (flag) => {
+    const index = rest.indexOf(flag);
+    return index === -1 ? null : (rest[index + 1] ?? null);
+  };
+  if (word === 'on') {
+    const item = valueOf('--item');
+    if (!item || item.startsWith('--')) {
+      process.stderr.write('unattended-flag on: --item <id> is required — the flag names the item whose paths are allowed\n');
+      process.exit(1);
+    }
+    const allowIndex = rest.indexOf('--allow');
+    const allow =
+      allowIndex === -1
+        ? []
+        : rest.slice(allowIndex + 1).filter((entry, i, all) => {
+            const stop = all.findIndex((e) => e.startsWith('--'));
+            return stop === -1 || i < stop;
+          });
+    let path;
+    try {
+      [path] = writeUnattended({ item, runDir: valueOf('--run-dir'), allow });
+    } catch (error) {
+      process.stderr.write(`unattended-flag on: ${error?.message ?? error}\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`${path}\n`);
+    process.exit(0);
+  }
+  if (word === 'off') {
+    const removed = clearUnattended();
+    process.stdout.write(removed.length === 0 ? 'no unattended flag was set\n' : `${removed.join('\n')}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(`unknown word: ${word ?? '(none)'}. This CLI has two: on, off.\n`);
+  process.exit(1);
+}

package/templates/agent-os/universal/.claude/scripts/verdict.mjs

@@ -3,11 +3,18 @@
  * The verdict CLI — what a gate runs before it believes a reviewer.
  *
  *   node .claude/scripts/verdict.mjs check <file> [gate]   # `-` reads stdin
+ *   node .claude/scripts/verdict.mjs coverage <commit>    # reads the run journal
  *
- * It reads a gate's report, hands it to `lib/verdict.mjs`, and either prints the
- * parsed verdict on stdout (exit 0) or refuses with a diagnosis on stderr
+ * `check` reads a gate's report, hands it to `lib/verdict.mjs`, and either prints
+ * the parsed verdict on stdout (exit 0) or refuses with a diagnosis on stderr
  * (exit 1). All the deciding lives in the module; this file is the call site.
  *
+ * `coverage` answers the question one report cannot: did every reviewer this
+ * round asked for actually answer, for the commit being merged? It compares the
+ * three sets the run journal already holds — routed, launched, answered — through
+ * `lib/gate-coverage.mjs`, and it is a READ. It never launches a reviewer and it
+ * never writes.
+ *
  * 🔴 **Name the gate you launched.** The module reads the report's LAST block
  * (its limit 3), so a capture holding two reviewers' answers end to end says
  * only what the second one said — a stop that vanishes behind a later pass.
@@ -27,11 +34,15 @@
 
 import { readFileSync } from 'node:fs';
 
-import { parseVerdict, safeForDiagnosis } from './lib/verdict.mjs';
+import { coverageOf } from './lib/gate-coverage.mjs';
+import { isCommitId, parseVerdict, safeForDiagnosis } from './lib/verdict.mjs';
+import { readRun } from './run-journal.mjs';
 
 const USAGE =
   'usage: node .claude/scripts/verdict.mjs check <file> [gate]   ' +
-  '(`-` reads the report from stdin)\n';
+  '(`-` reads the report from stdin)\n' +
+  '       node .claude/scripts/verdict.mjs coverage <commit>   ' +
+  '(reads the run journal in $RIG_RUN_DIR)\n';
 
 const refuse = (message) => {
   process.stderr.write(message);
@@ -58,6 +69,92 @@ const [subcommand, source, expectedGate] = process.argv.slice(2);
 // either: an operator told the subcommand is unknown goes looking for a typo
 // that is not there.
 if (subcommand === undefined) refuse(USAGE);
+
+if (subcommand === 'coverage') {
+  // The four cases and the fix each one needs, said in the line that names the
+  // reviewer — a single "missing" list makes the reader guess between
+  // relaunching a reviewer and going to read why one stayed silent.
+  const CASES = [
+    ['neverLaunched', 'the route asked for it and the fan-out never launched it — launch it'],
+    ['unanswered', 'launched, and it did not answer — no verdict of its own parsed'],
+    ['unattributed', 'it answered, and its verdict named no commit — so it cannot say it answered for this one'],
+    ['stale', 'it answered for another commit — the head moved after the verdict'],
+  ];
+
+  const commit = source;
+  // The same two arms `check` keeps apart: the subcommand was right and the
+  // argument was not supplied. Reporting the opposite sends the operator
+  // looking for a typo that is not there.
+  if (commit === undefined) {
+    refuse(
+      'verdict: `coverage` needs the commit the round is about; no commit was given. ' +
+        'It is the head the reviewers were launched against — `git rev-parse HEAD` in the ' +
+        `reviewed checkout.\n${USAGE}`,
+    );
+  }
+
+  // The one commit field this command owns, and the only one shaped before it is
+  // compared: the journal is the other way in and `recordDecision` takes any
+  // non-blank string, which is why `sameCommit` enforces its own floor and
+  // ceiling rather than trusting an upstream check. Without this arm
+  // `coverage <a-full-sha>garbage` prefix-matched its way to "covered" — the
+  // answer that ends in a merge.
+  if (!isCommitId(commit)) {
+    refuse(
+      `verdict: \`${safeForDiagnosis(commit)}\` is not a commit to ask about. ` +
+        'It is 7 to 64 hex characters (0-9a-f), the same shape a verdict may name — ' +
+        '`git rev-parse HEAD` in the reviewed checkout.\n',
+    );
+  }
+
+  const runDir = process.env.RIG_RUN_DIR;
+  if (!runDir) {
+    // 🔴 Exit 0 with nothing printed is indistinguishable from a clean round,
+    // and an unattended session reads it as one. The skip is the honest answer —
+    // this run kept no trace — and it has to be said out loud.
+    process.stdout.write(
+      'verdict: coverage skipped — no run directory is declared (RIG_RUN_DIR is unset), so ' +
+        'this run journalled no fan-out and no verdicts. Nothing was checked, which is not ' +
+        'the same as nothing being outstanding.\n',
+    );
+    process.exit(0);
+  }
+
+  let decisions;
+  try {
+    ({ decisions } = readRun({ runDir }));
+  } catch (error) {
+    refuse(
+      `verdict: the run journal in ${runDir} could not be read, so coverage was not ` +
+        `checked (${error?.message ?? 'unknown error'}).\n`,
+    );
+  }
+
+  const coverage = coverageOf({ records: decisions, headSha: commit });
+  if (coverage.ok) {
+    process.stdout.write(
+      `verdict: coverage complete for ${safeForDiagnosis(commit)} — ` +
+        `${coverage.launched.length} reviewer(s) launched, every one of them answered for ` +
+        'that commit.\n',
+    );
+    process.exit(0);
+  }
+
+  const lines = [];
+  if (coverage.reason !== undefined) lines.push(`  ${coverage.reason}`);
+  for (const [key, why] of CASES) {
+    // Through the sanitiser like every other quoted value here: the names come
+    // from the fan-out record, which `recordDecision` checks as strings and
+    // nothing more, and a name carrying a cursor sequence repaints this refusal
+    // as a pass for whoever is watching the scrollback.
+    for (const reviewer of coverage[key]) lines.push(`  ${safeForDiagnosis(reviewer)} — ${why}`);
+  }
+  refuse(
+    `verdict: the fan-out for ${safeForDiagnosis(commit)} is not covered.\n` +
+      `${lines.join('\n')}\n`,
+  );
+}
+
 if (subcommand !== 'check') {
   refuse(`verdict: \`${subcommand}\` is not a subcommand of this tool.\n${USAGE}`);
 }

package/templates/agent-os/universal/.claude/settings.json

@@ -2,7 +2,7 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|apply_patch",
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -15,6 +15,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-secret-file.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-rulebook.mjs\""
           }
         ]
       },

package/templates/agent-os/universal/.claude/skills/check-premises/SKILL.md

@@ -173,7 +173,8 @@ inside the block; both forms are the contract.
     }
   ],
   "advisories": [],
-  "evidence": ["read the validator and both call sites"]
+  "evidence": ["read the validator and both call sites"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -187,6 +188,8 @@ inside the block; both forms are the contract.
   and the caller is what checks: the `loop` skill runs
   `node .claude/scripts/verdict.mjs check <report> check-premises` on what you
   return. Nothing in this skill runs it — this skill writes nothing at all.
+- **`headSha` is the commit you read** — `git rev-parse HEAD` in the checkout
+  you examined. A premise check answers about a tree, and the tree moves.
 
 ## Examples — the three shapes this actually catches