create-agent-rig 0.4.0 → 0.6.0

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

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * 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
+ *
+ * `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.
+ * With `[gate]`, a block claiming another gate is refused. The argument is
+ * optional because a caller checking one report of a known gate does not need
+ * it; a caller that fanned reviewers out does.
+ *
+ * 🔴 **The exit code says whether the REPORT was usable, never what the verdict
+ * was.** A well-formed `HOLD` exits 0 and prints `"verdict": "HOLD"` — a gate
+ * that found something is not a gate that broke, and a caller keying on the exit
+ * code would read the two as one. Read the word on stdout.
+ *
+ * 🔴 **stdout stays empty on a refusal.** A caller redirecting it into a file
+ * would otherwise capture a verdict this command has just refused, which is the
+ * failure the whole schema exists to prevent, reintroduced by the reader.
+ */
+
+import { readFileSync } from 'node:fs';
+
+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' +
+  '       node .claude/scripts/verdict.mjs coverage <commit>   ' +
+  '(reads the run journal in $RIG_RUN_DIR)\n';
+
+const refuse = (message) => {
+  process.stderr.write(message);
+  process.exit(1);
+};
+
+const readReport = (source) => {
+  try {
+    return readFileSync(source === '-' ? 0 : source, 'utf8');
+  } catch (error) {
+    // The path, not a stack: the operator needs to know WHICH report could not
+    // be read, and a node trace answers a question nobody asked.
+    refuse(
+      `verdict: could not read the report at ${source} (${error?.code ?? 'unknown error'}). ` +
+        'Nothing was checked.\n',
+    );
+    return '';
+  }
+};
+
+const [subcommand, source, expectedGate] = process.argv.slice(2);
+
+// Two arms, one branch apart, and telling them apart is the whole value of
+// 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}`);
+}
+if (source === undefined) {
+  refuse(`verdict: \`check\` needs the report to read; no file was given.\n${USAGE}`);
+}
+
+const result = parseVerdict(readReport(source));
+
+if (!result.ok) {
+  refuse(
+    `verdict: the report at ${source} does not end in a verdict this gate can act on. ` +
+      'Treat it as `incomplete` — the gate did not answer, which is not the same as ' +
+      'answering that nothing is wrong.\n' +
+      result.problems.map((problem) => `  - ${problem}\n`).join(''),
+  );
+}
+
+if (expectedGate !== undefined && result.verdict.gate !== expectedGate) {
+  refuse(
+    `verdict: the report at ${source} was checked as ` +
+      `\`${safeForDiagnosis(expectedGate)}\`, and the block it ends with answers for ` +
+      `\`${safeForDiagnosis(result.verdict.gate)}\`. One capture holding two gates' ` +
+      "answers says only what the second one said, so the first one's verdict — a stop, " +
+      'as often as not — would go unread. Check each report on its own.\n',
+  );
+}
+
+try {
+  process.stdout.write(`${JSON.stringify(result.verdict, null, 2)}\n`);
+} catch {
+  // A verdict can parse and still be unprintable: nothing refuses an unknown
+  // key inside a blocker, and one nested deeply enough defeats the printer.
+  // Uncaught it is a raw stack, which this file promises never to emit — and a
+  // legitimate stop then reads as `incomplete` with no way to see why.
+  refuse(
+    `verdict: the verdict in ${source} parsed, and could not be printed — a blocker ` +
+      'nested far past anything a reader needs. Nothing was printed; flatten the ' +
+      'blocker and answer again.\n',
+  );
+}

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

@@ -2,7 +2,7 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -11,6 +11,14 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-web-boundary.mjs\""
+          },
+          {
+            "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\""
           }
         ]
       },
@@ -33,7 +41,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/gate-stop-dod.mjs\""
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/gate-stop-dod.mjs\"",
+            "timeout": 900
           }
         ]
       }

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

@@ -1,9 +1,9 @@
 ---
 name: check-premises
-description: Check a queue item's claims about the code before building on them. Use immediately after taking an item and before the failing test — whenever the item asserts that something exists, is missing, is broken, or works a particular way.
+description: Check claims about the code before building on them, or before shipping them. Use after taking a queue item and before the failing test — whenever the item asserts something exists, is missing, is broken, or works a particular way. Use again before the gate, on the run's own prose, where a behaviour claim nothing backs is UNMEASURED.
 context: fork
 allowed-tools: Read, Grep, Glob, Bash
-argument-hint: <the queue item's text>
+argument-hint: <the queue item's text, or the diff and prose to check>
 ---
 
 A queue item is a **claim about the code**, written by someone who was not
@@ -11,8 +11,33 @@ reading the code at the time. "The retry path swallows the error", "there is no
 validation on that field", "the worker never gets the second message" — each of
 those is a premise, and the work that follows is only worth doing if it is true.
 
-This skill checks the premises. It runs **after selection, before the Red step**,
-and it produces one of three verdicts. It writes nothing.
+This skill checks the premises. It writes nothing, and it has **two entry points**.
+
+| entry point | the claims are | the code is | verdicts |
+| --- | --- | --- | --- |
+| after selection, **before the Red step** | the queue item's, about code it did not read | the repository | `PREMISES HOLD` / `PREMISE FALSE` / `UNVERIFIABLE` |
+| after the work, **before the gate** | your own, in the rulebook prose the diff touches — and in the PR description if one exists yet | your diff | `PREMISES HOLD` / `UNVERIFIABLE` / `UNMEASURED` |
+
+🔴 **Why the second one exists.** A claim you wrote about a mechanism you did not run
+is cheap to write and expensive to find: `prose-reviewer` reaches it only after loading
+the whole diff, and the fix is an edit to one sentence. Same machinery, same question — *is this claim true?* — pointed
+at the text the run wrote instead of the text it was handed.
+
+The rest of this skill is written for the first entry point. The second one runs the
+same four steps with the diff as the code, and §4 carries what is different.
+
+**What "rulebook prose" means here is not a new list** — it is the set
+`.claude/rules/workflow.md` already uses for the `prose-reviewer` trigger: a rule
+file, a skill, an agent spec, a decision record, `CLAUDE.md`, the README. Where a
+rulebook file exists twice (a template source and a generated copy), check the
+**source**; the copy is composed from it. A comment in a test or a hook is in scope
+too when it asserts behaviour — the file it lives in does not change what a claim is.
+
+🔴 **`PREMISE FALSE` belongs to the first entry point only.** At the second one the
+claims are your own and the remedy is an edit, so a false one is not an escalation:
+it is `UNMEASURED`'s neighbour — delete or correct the sentence and carry on. Reading
+it as the escalation `loop` §6 defines would send a finished branch back to the queue
+over one sentence.
 
 ## Why it sits here and not in review
 
@@ -62,6 +87,10 @@ Read the code. Not the tests, not the docs, not another queue item — those are
 claims too. Each verified premise gets a `file:line` citation; a premise you
 believe but cannot cite is not verified, it is remembered.
 
+At the **second** entry point this inverts for one case: a test is exactly what backs
+a behaviour claim, so reading it is the point. The rule above is about not letting a
+test's *name* stand in for what the code does; §4 says which artifacts count.
+
 ## 4. The verdict
 
 | Verdict | When | What happens next |
@@ -69,6 +98,50 @@ believe but cannot cite is not verified, it is remembered.
 | `PREMISES HOLD` | every load-bearing claim checked out, or there were none | proceed to the Red step |
 | `PREMISE FALSE` | a load-bearing claim is contradicted by the code | **stop and report** |
 | `UNVERIFIABLE` | a load-bearing claim could not be decided from the code | report it as unverifiable, name what would decide it, and proceed only under a **labelled assumption** |
+| `UNMEASURED` | **second entry point only:** a sentence you wrote asserts behaviour, and nothing you can point at backs it | **delete the sentence, or turn it into a pointer to the test that proves it** — before the gate |
+
+🔴 **The edit belongs to the calling session, not to this skill.** It reports; the
+caller performs the exit before the gate. (The rule is the one at the top of this
+file — it writes nothing — not a property of its tool grant.)
+
+🔴 **`UNMEASURED` has exactly two exits, and "reword it" is not one of them.** A
+behaviour claim is either backed or it is not; softening the wording keeps an
+unbacked claim in a document agents follow literally. So either the sentence goes,
+or it becomes `see guard-invariant.example.test.mjs › "blocks the violation, and the
+reason names what to do instead"` — the test's whole name, in a file this project
+carries, so one grep lands on it. `invariants.md` ("State the limits") states the norm this verdict
+enforces.
+
+**Two questions, and they have different answers — conflating them is how an unbacked
+sentence survives this check.**
+
+*Is the claim founded?* A test you can name, a command whose output is in front of
+you, or a citation to code that does the thing. What does not count: the queue item
+said so (the item is a claim too — that is what the first entry point is for), it was
+true of the previous design, or it is obviously right.
+
+*May it stay in the file as written?* Only the two forms `invariants.md` requires —
+**generated** from what it describes, or a **pointer** to the test. A command's output
+is not one of them: you saw it, the reader cannot, so a sentence resting on it is still
+`UNMEASURED` however sure you are. Point at the test that runs that command, or say
+something the reader can check.
+
+⚠ **A measurement of this project's own history fits none of the three**, and that is
+a real gap rather than an oversight: the run that produced it is not in the repository,
+and a journal entry does not travel with a rulebook that ships. So a figure about past
+runs belongs in the journal and **not** in a file other projects receive — where it
+would arrive with no backing at all.
+
+A sentence is qualitative when it names **no quantity a reader could check** — not a
+count, not a share, not a duration. "This has happened here before" qualifies; "this
+happened twice last month" does not, and moves to the journal.
+
+That is not a third exit from `UNMEASURED`. The two exits apply to **the sentence in
+front of you**: it goes, or it becomes a pointer. Writing a different sentence — one
+that claims no measurement, and so needs none — is the first exit followed by an
+unrelated edit, not a softened version of the same claim. `invariants.md` has a
+worked instance: "Both have happened here, in the same file, within one review
+cycle." No figure, no measurement claimed, and it ships.
 
 🔴 **On `PREMISE FALSE` the answer is stop and report — never quietly work around
 the false premise by building something adjacent that seems useful.** Write what
@@ -81,6 +154,43 @@ branch named after a task that does not exist.
 so the assumption travels in the open, in the item and in the PR description,
 where the next reader can see which part of the work rests on it.
 
+### The verdict block
+
+Report in prose for the caller, then end with **exactly one** fenced `json` block
+of this shape, and nothing after it. The word is spaced in prose and one token
+inside the block; both forms are the contract.
+
+```json
+{
+  "gate": "check-premises",
+  "verdict": "PREMISE_FALSE",
+  "blockers": [
+    {
+      "file": "packages/core/src/note.ts",
+      "line": 17,
+      "rule": "the item claims the schema does not reject an empty title",
+      "note": "it does, here — the reported bug is a caller that skips the validator"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["read the validator and both call sites"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `verdict` is `PREMISES_HOLD`, `PREMISE_FALSE`, `UNVERIFIABLE` or `UNMEASURED`
+  — this skill returns no other word, and none of the reviewers' words.
+- One blocker per premise that did not hold, per claim that could not be decided,
+  or per unbacked sentence — `rule` is the claim itself, `note` is what the code
+  actually says, and `file`/`line` is the citation §3 requires.
+- `PREMISES_HOLD` carries an empty `blockers` list; the other three name at
+  least one. A stop verdict without one is not an answer the caller can act on,
+  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
 
 **The thing already exists.** Item: "the payload schema does not reject an empty
@@ -110,9 +220,10 @@ is invisible to every gate downstream.
   about runtime behaviour ("this times out in production"), about intent, or
   about a system this repository does not contain is `UNVERIFIABLE` here, not
   false — say so rather than guessing.
-- **It is one pass, before the work.** A premise that becomes false while the
-  task runs (a merge lands, a dependency moves) is a staleness stop rule
-  (`.claude/rules/autonomy.md`), not this skill.
+- **Each entry point is one pass, at its own end of the task.** A premise that goes
+  false *between* them — a merge lands, a dependency moves — is a staleness stop rule
+  (`.claude/rules/autonomy.md`), not this skill. Neither pass watches the other's
+  claims.
 - **It has no opinion on whether the task is worth doing.** True premises and a
   pointless task is a perfectly consistent state, and it belongs to whoever fills
   the queue.