create-agent-rig 0.6.0 → 0.6.2

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

@@ -1,19 +1,22 @@
 #!/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).
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
 //
-//   node .claude/scripts/unattended-flag.mjs on --item AR-51 --run-dir <dir> --allow <prefix> [<prefix>…]
-//   node .claude/scripts/unattended-flag.mjs off
+//   node .claude/scripts/unattended-flag.mjs on --root <checkout> --item AR-51 --run-dir <dir> --allow <prefix> [<prefix>…]
+//   node .claude/scripts/unattended-flag.mjs off --root <checkout>
+//   node .claude/scripts/unattended-flag.mjs off --legacy --path <reported-path>
 //
 // 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` ›
+// session exported — the generator's `test/template/guard-rulebook.test.ts` (absent in a generated rig) ›
 // "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.
+// and this module copies its two-home lookup. Unlike the machine-wide brake,
+// each unattended record is scoped to the canonical checkout, so concurrent
+// worktrees cannot overwrite or clear one another's authorization.
 //
 // 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
@@ -35,15 +38,33 @@
 // 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".
+// the rulebook (`src/`) is harmless because it is never judged; a narrow entry
+// inside it (`.claude/skills/loop/`) authorizes only that subtree. Items name
+// both forms, so they are kept — › "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';
+// both limits are refusals, never silent truncation. A candidate is opened
+// nonblocking and must be a regular file — see the generator's
+// `test/template/unattended-flag.test.ts` (absent in a generated rig) ›
+// "returns promptly and fails closed when a candidate is a FIFO". An access
+// error is unreadable, not absent — › "is on-but-unreadable when access to an
+// existing flag fails at the stat boundary".
+// Cleanup preserves the same distinction: an owned legacy record that cannot
+// be inspected is an error, not evidence that nothing remains — › "exits
+// nonzero and leaves an unreadable owned legacy flag in place".
+import { createHash } from 'node:crypto';
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homesOf } from './stop-flag.mjs';
 
@@ -57,13 +78,21 @@ export const MAX_ALLOW_ENTRIES = 64;
  * writer above, to refuse an allow-list that reaches outside them.
  */
 export const RULEBOOK_PREFIXES = Object.freeze([
+  '.agents/',
+  '.claude/.rig-manifest.json',
+  '.claude/doctor-exemptions.json',
+  '.claude/agents/',
   '.claude/hooks/',
   '.claude/settings.json',
   '.claude/queue.json',
-  '.claude/scripts/queue/',
-  '.claude/scripts/decision-router.mjs',
-  '.claude/scripts/detect-missed-gate.mjs',
+  // the per-checkout board selector: picks among the boards queue.json declares,
+  // so an unattended run must not be able to re-aim itself through it either
+  '.claude/queue.board',
+  '.claude/scripts/',
   '.claude/rules/',
+  '.claude/skills/',
+  '.codex/',
+  'AGENTS.md',
   'CLAUDE.md',
 ]);
 
@@ -72,24 +101,82 @@ 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).
+ * Does this allow entry widen the rulebook? It is unsafe when it is an
+ * exact protected prefix deliberately unavailable as an allow root (`.agents/`,
+ * `.claude/scripts/`, `.codex/`), or when it is a proper prefix of any
+ * rulebook prefix and would therefore admit that prefix plus siblings. All
+ * protected script paths sit under `.claude/scripts/`; a narrower path such as
+ * `.claude/scripts/queue/` is an ordinary allow entry and does not widen it.
+ * `src/` also does not widen it because the guard judges nothing there.
  */
 export const isWidening = (entry) =>
   typeof entry !== 'string' ||
   entry === '' ||
+  entry === '.agents/' ||
+  entry === '.claude/scripts/' ||
+  entry === '.codex/' ||
   RULEBOOK_PREFIXES.some((prefix) => prefix !== entry && prefix.startsWith(entry));
 
-/** Every path that arms unattended mode. The env-derived home is first. */
+/**
+ * One spelling for one directory — the single canonicaliser this file compares
+ * and hashes with (`invariants.md`, "One mechanism, one implementation").
+ *
+ * RP-54: it is `realpathSync.native`, not `realpathSync`, and on Windows those
+ * differ. Both normalise separators; only the native one expands an 8.3 short
+ * name, so `C:\Users\RUNNER~1\…` and `C:\Users\runneradmin\…` survive
+ * `realpathSync` as two strings for one directory. The flag is named by a hash
+ * of this value while the generated Codex Windows hook supplies
+ * `git rev-parse --show-toplevel` — a different spelling of the same checkout —
+ * so the guard looked for a file nobody wrote and, being fail-open, allowed the
+ * rulebook edit it exists to refuse. Proven by
+ * unattended-flag.test.ts › "scopes the flag by the checkout, so two spellings
+ * of one directory arm one file".
+ *
+ * A path that does not exist has no real path; `resolve` is the fallback, and
+ * it is the same one on both sides of every comparison below.
+ */
+const canonicalPath = (p) => {
+  try {
+    return realpathSync.native(p);
+  } catch {
+    return resolve(p);
+  }
+};
+
+const canonicalCheckout = (env) => {
+  const declared = typeof env.CLAUDE_PROJECT_DIR === 'string' ? env.CLAUDE_PROJECT_DIR.trim() : '';
+  if (declared === '') return null;
+  return canonicalPath(declared);
+};
+
+const checkoutId = (env) => {
+  const canonical = canonicalCheckout(env);
+  if (canonical === null) return null;
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+};
+
+const scopedBasename = (env) => {
+  const id = checkoutId(env);
+  return id === null ? FLAG_BASENAME : FLAG_BASENAME.replace('-loop-UNATTENDED', `-${id}-loop-UNATTENDED`);
+};
+
+/** Every checkout-scoped 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));
+  homesOf(env).map((home) => join(home, '.claude', scopedBasename(env)));
+
+/** Legacy machine-wide candidates are never accepted as scoped authorization. */
+const legacyFlags = (env) => homesOf(env).map((home) => join(home, '.claude', FLAG_BASENAME));
+
+const isMissing = (error) => error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
 
 const readCapped = (path) => {
-  const fd = openSync(path, 'r');
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
   try {
+    if (!fstatSync(fd).isFile()) {
+      const error = new Error('unattended flag is not a regular file');
+      error.code = 'EINVAL';
+      throw error;
+    }
     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)) };
@@ -100,22 +187,54 @@ const readCapped = (path) => {
 
 const unreadable = (path, why) => ({ on: true, unreadable: true, path, why });
 
+const inspectCandidates = (candidates) => {
+  const present = [];
+  for (const path of candidates) {
+    try {
+      present.push({ path, raw: readCapped(path) });
+    } catch (error) {
+      if (isMissing(error)) continue;
+      return {
+        present,
+        failure: unreadable(path, `cannot be read: ${error?.code ?? 'read failed'}`),
+      };
+    }
+  }
+  return { present, failure: null };
+};
+
 /** 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;
+  const scoped = checkoutId(env) !== null;
+  const inspected = inspectCandidates(unattendedFlags(env));
+  if (inspected.failure) return inspected.failure;
+  const { present } = inspected;
+  let path = present[0]?.path;
+  let raw = present[0]?.raw ?? null;
+  if (scoped && present.length > 1) {
+    const first = present[0];
+    if (
+      present.some(
+        ({ raw: candidate }) =>
+          candidate.bytes !== first.raw.bytes || candidate.text !== first.raw.text,
+      )
+    ) {
+      return unreadable(first.path, 'mirrored checkout-scoped unattended flags disagree');
+    }
+    raw = first.raw;
+  }
+  if (!path && scoped) {
+    const legacy = inspectCandidates(legacyFlags(env));
+    if (legacy.failure) return legacy.failure;
+    path = legacy.present[0]?.path;
+    if (path) {
+      return unreadable(
+        path,
+        'legacy machine-wide unattended flag cannot authorize a scoped checkout; migrate or remove it explicitly',
+      );
     }
-  });
-  if (!path) return { on: false };
-  let raw;
-  try {
-    raw = readCapped(path);
-  } catch (error) {
-    return unreadable(path, `cannot be read: ${error?.code ?? 'read failed'}`);
   }
+  if (!path) return { on: false };
   if (raw.bytes > MAX_FLAG_BYTES) return unreadable(path, `larger than ${MAX_FLAG_BYTES} bytes`);
   let parsed;
   try {
@@ -148,7 +267,12 @@ export const readUnattended = (env = process.env) => {
   };
 };
 
-/** Write the flag under the env-derived home. Returns the paths written. */
+/**
+ * Write the flag. Scoped records are mirrored into both trusted homes, with the
+ * password-database home first, so a caller whose HOME differs still observes
+ * the target checkout's state. An unscoped legacy-compatible write keeps the
+ * historical first-home behaviour.
+ */
 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');
@@ -165,38 +289,103 @@ export const writeUnattended = ({ item, runDir = null, allow = [] } = {}, env =
         '(`.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];
+  const candidates = unattendedFlags(env);
+  const targets = checkoutId(env) === null ? candidates.slice(0, 1) : [...candidates].reverse();
+  const written = [];
+  const content = `${JSON.stringify({ item: item.trim(), runDir, allow: list }, null, 2)}\n`;
+  try {
+    for (const path of targets) {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+      written.push(path);
+    }
+  } catch (error) {
+    for (const path of written) {
+      try {
+        rmSync(path);
+      } catch {
+        // best-effort rollback; a surviving record keeps readers fail-closed
+      }
+    }
+    throw error;
+  }
+  return written;
 };
 
-/** Remove every flag that exists. Returns the paths removed. */
+const pathBelongsToCheckout = (candidate, checkout) => {
+  // `checkout` is `canonicalCheckout`'s output, so the candidate takes the same
+  // canonicaliser: two spellings compared here would put an in-checkout runDir
+  // outside its own checkout.
+  const resolved = canonicalPath(candidate);
+  const rel = relative(checkout, resolved);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+const legacyBelongsToCheckout = (flagPath, env) => {
+  const checkout = canonicalCheckout(env);
+  if (checkout === null) return false;
+  try {
+    const raw = readCapped(flagPath);
+    if (raw.bytes > MAX_FLAG_BYTES) return false;
+    const parsed = JSON.parse(raw.text);
+    return typeof parsed?.runDir === 'string' && pathBelongsToCheckout(parsed.runDir, checkout);
+  } catch (error) {
+    if (!isMissing(error)) {
+      throw new Error(
+        `legacy unattended flag at ${flagPath} cannot be read: ${error?.code ?? error?.message ?? 'read failed'}`,
+        { cause: error },
+      );
+    }
+    return false;
+  }
+};
+
+/** Remove this checkout's flags and a provably-owned legacy record. */
 export const clearUnattended = (env = process.env) => {
   const removed = [];
-  for (const path of unattendedFlags(env)) {
+  const failures = [];
+  const candidates = checkoutId(env) === null
+    ? unattendedFlags(env)
+    : [
+        ...unattendedFlags(env),
+        ...legacyFlags(env).filter((path) => legacyBelongsToCheckout(path, env)),
+      ];
+  for (const path of [...new Set(candidates)]) {
     try {
-      if (existsSync(path)) {
-        rmSync(path);
-        removed.push(path);
-      }
-    } catch {
-      // a home this process cannot write is not this run's flag to remove
+      rmSync(path);
+      removed.push(path);
+    } catch (error) {
+      if (isMissing(error)) continue;
+      failures.push(`${path}: ${error?.code ?? error?.message ?? 'remove failed'}`);
     }
   }
+  if (failures.length > 0) {
+    throw new Error(`failed to remove unattended flag(s): ${failures.join('; ')}`);
+  }
   return removed;
 };
 
+/** Explicit operator migration: remove exactly the inspected legacy record. */
+export const clearLegacyUnattended = (selectedPath) => {
+  if (typeof selectedPath !== 'string' || selectedPath.trim() === '') {
+    throw new Error('off --legacy requires --path <reported-path>');
+  }
+  const path = resolve(selectedPath);
+  if (basename(path) !== FLAG_BASENAME || basename(dirname(path)) !== '.claude') {
+    throw new Error(`refusing legacy cleanup outside .claude/${FLAG_BASENAME}`);
+  }
+  try {
+    rmSync(path);
+    return [path];
+  } catch (error) {
+    if (isMissing(error)) return [];
+    throw error;
+  }
+};
+
 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]);
+  return canonicalPath(fileURLToPath(import.meta.url)) === canonicalPath(process.argv[1]);
 };
 
 if (invokedDirectly()) {
@@ -205,6 +394,10 @@ if (invokedDirectly()) {
     const index = rest.indexOf(flag);
     return index === -1 ? null : (rest[index + 1] ?? null);
   };
+  const root = valueOf('--root');
+  const cliEnv = root && !root.startsWith('--')
+    ? { ...process.env, CLAUDE_PROJECT_DIR: root }
+    : process.env;
   if (word === 'on') {
     const item = valueOf('--item');
     if (!item || item.startsWith('--')) {
@@ -221,7 +414,7 @@ if (invokedDirectly()) {
           });
     let path;
     try {
-      [path] = writeUnattended({ item, runDir: valueOf('--run-dir'), allow });
+      [path] = writeUnattended({ item, runDir: valueOf('--run-dir'), allow }, cliEnv);
     } catch (error) {
       process.stderr.write(`unattended-flag on: ${error?.message ?? error}\n`);
       process.exit(1);
@@ -230,7 +423,25 @@ if (invokedDirectly()) {
     process.exit(0);
   }
   if (word === 'off') {
-    const removed = clearUnattended();
+    const legacy = rest.includes('--legacy');
+    let removed;
+    try {
+      removed = legacy ? clearLegacyUnattended(valueOf('--path')) : clearUnattended(cliEnv);
+    } catch (error) {
+      process.stderr.write(`unattended-flag off: ${error?.message ?? error}\n`);
+      process.exit(1);
+    }
+    if (!legacy && root) {
+      const remaining = readUnattended(cliEnv);
+      if (remaining.on) {
+        const reason = remaining.why ?? 'an unattended flag is still armed';
+        process.stderr.write(
+          `unattended-flag off: ${reason} at ${remaining.path}. ` +
+            'Inspect that exact record; if no pre-upgrade run still uses it, remove it with `off --legacy --path <reported-path>`.\n',
+        );
+        process.exit(1);
+      }
+    }
     process.stdout.write(removed.length === 0 ? 'no unattended flag was set\n' : `${removed.join('\n')}\n`);
     process.exit(0);
   }

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

@@ -39,6 +39,32 @@ node .claude/scripts/queue/index.mjs hygiene   # stale labels, link anomalies, o
   (`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`) and never from a file in the
   repo; the project or the JQL goes in `.claude/queue.json`.
 
+A config may declare several boards (`boards: { <name>: options }` plus a
+default `board`); the active one is chosen per checkout, not by editing the
+composed file:
+
+```bash
+node .claude/scripts/queue/index.mjs board        # the active board and the declared ones
+node .claude/scripts/queue/index.mjs board RP     # switch this checkout: writes .claude/queue.board
+```
+
+The selector is per-checkout runtime state, the same class as
+`.claude/queue.state.json`: it needs its own `.gitignore` line, which a generated
+project ships and an `init`-installed rig adds by hand. An undeclared name is
+refused, never read as "no board" (see `test/template/queue-board.test.ts` ›
+"refuses a board nobody declared instead of falling back" — in the generator,
+absent in a generated rig). It is a rulebook path for `guard-rulebook`:
+`.claude/queue.board` is refused even when an item allow-list names it,
+and the `board` command itself refuses a switch while the checkout is unattended. This
+does not prevent an arbitrary direct shell write to the selector — edit-tool
+hooks cannot see one. `.claude/queue.state.json` stays per config, not per board:
+the tier the last close recorded rations the next selection whichever board it
+lands on. This is repository-risk state, not tracker metadata: switching from
+one independent queue to another must not turn a previous mechanism close into
+permission for a second one in the same checkout. Pinned in the generator's
+`test/template/queue-board.test.ts` (absent in a generated rig) › "keeps
+completed-tier spacing repository-global when the active board switches".
+
 Adding a fourth is an adapter, not a rewrite: `core.mjs` holds every selection
 decision and each adapter only maps its tracker's records onto the neutral shape.
 
@@ -99,14 +125,15 @@ invocation. What a hook CAN see is a file, so the unattended signal is one:
 ```bash
 # at claim time, from the paths the item names (repo-relative prefixes, with
 # their trailing slash); the guard refuses every other rulebook edit while it is on
-node .claude/scripts/unattended-flag.mjs on --item <item-id> --run-dir "$RIG_RUN_DIR" --allow <prefix> [<prefix>…]
+node .claude/scripts/unattended-flag.mjs on --root "$PWD" --item <item-id> --run-dir "$RIG_RUN_DIR" --allow <prefix> [<prefix>…]
 ```
 
 `guard-rulebook` reads it (`.claude/rules/autonomy.md`, "Never"): with the flag
-on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under `.claude/hooks/`,
-`.claude/settings.json`, `.claude/queue.json`, `.claude/scripts/queue/`, the
-router, the gate sweep, `.claude/rules/` or `CLAUDE.md` is refused unless its
-path starts with an allowed prefix; with no flag the guard does nothing. An
+on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under the generated
+rulebook — both harnesses' rules, skills, agents and hook wiring, plus their
+scripts, queue config and integrity manifest — is refused unless its
+path starts with an allowed prefix; the board selector is the one always-refused
+exception and cannot be admitted by an allow-list. With no flag the guard does nothing. An
 item that needs a rulebook path names it here — a decision made at claim
 time, never a default — and the stop step below turns the flag off. Pinned in
 the generator's `test/template/guard-rulebook.test.ts` — absent in a generated
@@ -718,9 +745,18 @@ next attended session would find its rulebook edits refused in the name of an
 item nobody is working:
 
 ```bash
-node .claude/scripts/unattended-flag.mjs off
+node .claude/scripts/unattended-flag.mjs off --root "$PWD"
 ```
 
+If that command reports a legacy machine-wide flag, it deliberately leaves a
+foreign pre-upgrade authorization in place and the checkout stays fail-closed.
+Inspect the exact reported record and confirm that no pre-upgrade run still uses
+it, then remove only that record with
+`node .claude/scripts/unattended-flag.mjs off --legacy --path <reported-path>`.
+Run scoped `off --root "$PWD"` again to surface the next record, and repeat the
+inspection one at a time; do not record the flag as off until the scoped command
+succeeds.
+
 At every **stop** — not at a checkpoint — turn the run's findings into **at most
 three** improvement proposals. **The cap is the mechanism, not a budget:** an
 unbounded improvement list is another diary, and three forces a choice. Each names
@@ -750,7 +786,7 @@ node --input-type=module -e '
     // mechanism accepts a proposal without them; this procedure does not.
     measured: "<the paths the probe actually exercised>",
     inferred: "<the conclusion, citing only surfaces named in measured>",
-  }, { project: "<KEY>" }));   // jira only — the project key from .claude/queue.json;
+  }, { project: "<KEY>" }));   // jira only — the ACTIVE board's key: `queue/index.mjs board --json` → options.project;
                                // plan-md and github-issues take no second argument
 '
 ```
@@ -853,7 +889,7 @@ three poisons the only channel by which this project learns.
   validation and its take-up — an adapter re-records the take-up after each
   write of its own (§2, AR-140), so a comment posted after BEFORE_PR does not
   hold the close; pinned in the generator's
-  `test/template/self-inflicted-marker.test.ts` › "continues when the run’s own
+  `test/template/self-inflicted-marker.test.ts` (absent in a generated rig) › "continues when the run’s own
   write moved the marker after the last validation" — and its
   state against the `in-progress` a close expects, journals one `revalidation`
   event at `point: BEFORE_CLOSE`, and lists the item's dependants with each
@@ -864,7 +900,7 @@ three poisons the only channel by which this project learns.
   and reads a hold as a stop" and › "re-reads each dependant's state, and names
   one the tracker no longer offers". On a `github-issues` queue that list is
   empty: a single `gh issue view` carries no cross-index, so `find` answers no
-  `blocks` there (`test/template/close-transitioned.test.ts` › "github asks `gh
+  `blocks` there (`test/template/close-transitioned.test.ts` (absent in a generated rig) › "github asks `gh
   issue view` with the full field list and maps CLOSED to closed"). A
   hold (exit 2) stops the close: re-read the item, record the outcome with
   `node .claude/scripts/revalidate.mjs outcome --point BEFORE_CLOSE --ticket
@@ -876,7 +912,7 @@ three poisons the only channel by which this project learns.
   `true` says the close landed, because every adapter reads the item back after
   the transition — `jira` the status category after the POST, `github-issues`
   `gh issue view --json state`, `plan-md` the line being there and then gone
-  (the generator's `test/template/close-transitioned.test.ts` › "GETs the issue
+  (the generator's `test/template/close-transitioned.test.ts` (absent in a generated rig) › "GETs the issue
   status after the transition POST and reports transitioned: true when the
   category is done", › "runs `issue view <id> --json state` after `issue close`
   and reports transitioned: true on CLOSED", › "reports transitioned: true once

package/templates/agent-os/universal/.codex/agents/prose-reviewer.toml

@@ -1,4 +1,4 @@
 name = "prose-reviewer"
 description = "Reviews the documents that instruct agents — rule files, skills, agent specs, CLAUDE.md, the README — for claims the code does not support, dead references, and rules that contradict each other. Use when a change touches any of them, before the PR."
 sandbox_mode = "read-only"
-developer_instructions = "In this project the prose **is** the implementation. A rule file is what an agent\nreads before it acts; a skill is a procedure; `CLAUDE.md` is the map. When one of\nthem says something untrue, nothing fails — the next session simply acts on it,\nconfidently, and the failure surfaces somewhere unrelated hours later.\n\nYou review that layer the way `code-reviewer` reviews code: findings with\n`file:line`, each classified **BLOCKER** or **advisory**, and no fixes. You do\nnot edit anything.\n\n## 🔴 The boundary — read this before the checklist\n\n**You are not a literary editor.** Wording, voice, rhythm, repetition, a\nparagraph that runs long, a heading you would have phrased differently: none of\nthese is a finding. Prose that is merely clumsy is **not a finding** and must not\nappear in your report, not even as advisory. Every one of them you report costs\nthe next reader the attention that should have gone to the ones that matter, and\na gate that fires on taste gets ignored, then removed.\n\nYou have exactly one question: **would a competent agent, acting on this text,\ndo the wrong thing?** If no, it is not yours.\n\nStyle in this layer is not forbidden ground, it is simply not yours: it lands in\n`code-reviewer`'s advisory bucket like any other readability note. Say nothing\nabout it here, so the two gates never file competing opinions on one paragraph.\n\n## Checklist (blocking findings)\n\n1. **An overstated claim of enforcement.** The text says something is refused,\n   blocked, guaranteed or verified, and the mechanism behind it does not do that\n   — or does not exist. Read the hook, the script, the CI job, and quote what it\n   actually does. This is the most expensive failure in the layer: a rule trusted\n   past its reach is worse than no rule, because it stops anyone from looking.\n2. **A dead reference.** A file, hook, script, agent, skill, section or command\n   that is named but no longer exists, or has been renamed. Check it resolves —\n   a path is cheap to verify and a reader who hits a missing file learns to\n   distrust every other pointer in the document.\n3. **Two rules that contradict each other.** Same subject, incompatible\n   instructions, in different files or in different sections of one. Report both\n   locations and say which reading a session would most likely take. Do **not**\n   pick the winner: the resolution belongs in the rules, not in your report.\n4. **A stated limit that has gone stale — in either direction.** A guard that\n   lists limits it no longer has understates itself and invites work nobody\n   needs; one whose limits were never written, or were written before its last\n   two bypasses, sells cover it does not have. Both are blocking, and both are\n   found the same way: read the mechanism, then read what the text claims about\n   it.\n5. **An unbacked behaviour claim.** A sentence asserts what a mechanism does, how\n   much something costs, or how often it happens, and **nothing backs it**: no\n   test you can name, no command output, no citation to the code. Per\n   `.claude/rules/invariants.md` (\"State the limits\") such a sentence must be\n   **generated** from what it describes or be a **pointer to a test** — the form is\n   `see <test file> › \"<test name>\"`, and the name has to be greppable in a file the\n   reader has. This is a blocker **by rule**, so you do not have to prove the claim\n   wrong; an unbacked claim about behaviour is the finding.\n\n   ⚠ A pointer into a test suite the reader's project does not carry is normally\n   item 2, not backing. There is one narrow inherited-snapshot exception from\n   `invariants.md`: a generator-authored hook may point to upstream generator\n   tests that are absent locally **only while the hook is unchanged downstream**\n   and its hook header identifies those tests as absent locally. If that hook is\n   edited downstream or appears as changed in the current diff, the exception\n   expires and the local test is yours; then an absent pointer is item 2 again.\n\n   🔴 Three things this is not. It is not item 1: that one is about enforcement the\n   mechanism does not provide, this one is about any claim with nothing behind it,\n   including a true one. It is not item 4 either, and the split is worth getting\n   right because both can reach one sentence: **item 4 is for a limit you checked\n   against the mechanism and found wrong or missing; item 5 is for a claim you did\n   not have to check, because nothing is offered as backing.** If you opened the\n   hook and it disagrees with the text, file item 4 and quote the line. If there was\n   nothing offered to open, file item 5. If you opened it and the claim was right,\n   there is no finding. One sentence, one item. And it is not an attack on rationale — \"we chose X\n   because Y\" needs no test. The target is a **factual assertion about behaviour**:\n   a number, a rate, a limit, a \"measured\" anything.\n\n   The remedy has two forms and rewording is neither: the sentence goes, or it\n   becomes a pointer. Say which you would expect, and where the test lives if one\n   exists.\n6. **Domain that must not travel.** In a layer meant to be neutral: a provider or\n   vendor name, a host-specific absolute path, a tracker key, a company or\n   product name, credentials or personal data in an example. State which layer\n   the file belongs to and why the mention breaks it.\n\n   🔴 **A seam built to name a vendor is not a leak.** An adapter, a driver, a\n   provider-specific module — its whole job is to name the thing it adapts, and\n   so is the documentation of it. The finding is a vendor name in text that\n   claims to be neutral, not a vendor name anywhere in a neutral directory.\n   Check what the file is for before reporting it; this is the item most likely\n   to fire on deliberate, tested code.\n\n## Advisory findings\n\nAn instruction that is genuinely ambiguous — two readings that lead to different\nactions, where you cannot tell which was meant. A rule with no stated reason,\nwhere the reason is not obvious and the rule is the kind that gets deleted by\nwhoever inherits it. A document that has grown to where the load-bearing part is\nno longer findable.\n\nThat is the whole advisory list, on purpose. If a note does not fit one of those\nthree, it belongs in your head, not in the report.\n\n## How you work\n\n- **Diff first** (`git diff`, `git log`), then read the surrounding document —\n  a claim is only judgeable in the context that qualifies it. Review what\n  changed, not the whole rulebook.\n- **Verify against the mechanism, never against your memory of it.** Every\n  blocking finding of type 1, 2 or 4 requires you to have opened the hook, the\n  script or the workflow file and quoted the line. A finding you could not check\n  is reported as unverified, or not at all.\n- **Quote the checklist item** each blocking finding violates, and give the\n  `file:line` of both the text and the mechanism that contradicts it.\n- **\"No blocking findings\" is a valid and useful verdict.** Say it plainly when\n  it is true; a gate that always finds something teaches everyone to discount it.\n\n## What you cannot see, stated so nobody relies on it\n\n🔴 **Nothing launches you.** No hook fires this review; a session reads a rule\nand decides to. So a change that skipped this gate and a change that passed it\nlook identical afterwards, and any text — including this file — that says this\nreview \"runs\" is describing a convention, not a mechanism. Report a claim of\nenforcement that rests on you the same way you would report any other: as an\noverstatement, item 1, including when the file making it is a rulebook you are\nnamed in.\n\nYou read text and the mechanisms it names. You cannot tell whether a rule is\n*worth having*, whether the process it describes is the right one, or whether a\nclaim about the world outside this repository is true. Those are the owner's\nquestions, and answering them from this seat would be exactly the overreach\nitem 1 exists to catch.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. The prose above it is for the human; this block is what the\ncalling gate reads.\n\n```json\n{\n  \"gate\": \"prose-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \".claude/rules/invariants.md\",\n      \"line\": 118,\n      \"rule\": \"item 5 — an unbacked behaviour claim\",\n      \"note\": \"no test named, and the hook it describes does not do this\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"opened .claude/hooks/guard-bash.mjs and quoted the line\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.\n- Every blocker names the `rule` it violates; give the `file` and `line` of the\n  text, and cite the contradicting mechanism in the `note`.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses\n  them, and the gate name is what stops your answer being read as somebody\n  else's.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."
+developer_instructions = "In this project the prose **is** the implementation. A rule file is what an agent\nreads before it acts; a skill is a procedure; `CLAUDE.md` is the map. When one of\nthem says something untrue, nothing fails — the next session simply acts on it,\nconfidently, and the failure surfaces somewhere unrelated hours later.\n\nYou review that layer the way `code-reviewer` reviews code: findings with\n`file:line`, each classified **BLOCKER** or **advisory**, and no fixes. You do\nnot edit anything.\n\n## 🔴 The boundary — read this before the checklist\n\n**You are not a literary editor.** Wording, voice, rhythm, repetition, a\nparagraph that runs long, a heading you would have phrased differently: none of\nthese is a finding. Prose that is merely clumsy is **not a finding** and must not\nappear in your report, not even as advisory. Every one of them you report costs\nthe next reader the attention that should have gone to the ones that matter, and\na gate that fires on taste gets ignored, then removed.\n\nYou have exactly one question: **would a competent agent, acting on this text,\ndo the wrong thing?** If no, it is not yours.\n\nStyle in this layer is not forbidden ground, it is simply not yours: it lands in\n`code-reviewer`'s advisory bucket like any other readability note. Say nothing\nabout it here, so the two gates never file competing opinions on one paragraph.\n\n## Checklist (blocking findings)\n\n1. **An overstated claim of enforcement.** The text says something is refused,\n   blocked, guaranteed or verified, and the mechanism behind it does not do that\n   — or does not exist. Read the hook, the script, the CI job, and quote what it\n   actually does. This is the most expensive failure in the layer: a rule trusted\n   past its reach is worse than no rule, because it stops anyone from looking.\n2. **A dead reference.** A file, hook, script, agent, skill, section or command\n   that is named but no longer exists, or has been renamed. Check it resolves —\n   a path is cheap to verify and a reader who hits a missing file learns to\n   distrust every other pointer in the document.\n3. **Two rules that contradict each other.** Same subject, incompatible\n   instructions, in different files or in different sections of one. Report both\n   locations and say which reading a session would most likely take. Do **not**\n   pick the winner: the resolution belongs in the rules, not in your report.\n4. **A stated limit that has gone stale — in either direction.** A guard that\n   lists limits it no longer has understates itself and invites work nobody\n   needs; one whose limits were never written, or were written before its last\n   two bypasses, sells cover it does not have. Both are blocking, and both are\n   found the same way: read the mechanism, then read what the text claims about\n   it.\n5. **An unbacked behaviour claim.** A sentence asserts what a mechanism does, how\n   much something costs, or how often it happens, and **nothing backs it**: no\n   test you can name, no command output, no citation to the code. Per\n   `.claude/rules/invariants.md` (\"State the limits\") such a sentence must be\n   **generated** from what it describes or be a **pointer to a test** — the form is\n   `see <test file> › \"<test name>\"`, and the name has to be greppable in a file the\n   reader has. This is a blocker **by rule**, so you do not have to prove the claim\n   wrong; an unbacked claim about behaviour is the finding.\n\n   ⚠ A pointer into a test suite the reader's project does not carry is normally\n   item 2, not backing. There is one narrow inherited-snapshot exception from\n   `invariants.md`: a generator-authored artifact — rules, hooks, skills,\n   scripts, or agent specs —\n   may point to upstream generator tests that are absent locally only when the\n   pointer explicitly says the suite is absent locally and\n   `.claude/.rig-manifest.json` proves the current artifact's hash matches the\n   installed manifest. A manifest-backed upgrade remains an inherited,\n   generator-owned artifact; a changed file in the upgrade diff does not alone\n   make it downstream-authored. The exception applies **only while the manifest\n   hash matches**. A hash mismatch, missing manifest, or no evidence ends the\n   exception and the local test is yours; then an absent pointer is item 2 again.\n\n   🔴 Three things this is not. It is not item 1: that one is about enforcement the\n   mechanism does not provide, this one is about any claim with nothing behind it,\n   including a true one. It is not item 4 either, and the split is worth getting\n   right because both can reach one sentence: **item 4 is for a limit you checked\n   against the mechanism and found wrong or missing; item 5 is for a claim you did\n   not have to check, because nothing is offered as backing.** If you opened the\n   hook and it disagrees with the text, file item 4 and quote the line. If there was\n   nothing offered to open, file item 5. If you opened it and the claim was right,\n   there is no finding. One sentence, one item. And it is not an attack on rationale — \"we chose X\n   because Y\" needs no test. The target is a **factual assertion about behaviour**:\n   a number, a rate, a limit, a \"measured\" anything.\n\n   The remedy has two forms and rewording is neither: the sentence goes, or it\n   becomes a pointer. Say which you would expect, and where the test lives if one\n   exists.\n6. **Domain that must not travel.** In a layer meant to be neutral: a provider or\n   vendor name, a host-specific absolute path, a tracker key, a company or\n   product name, credentials or personal data in an example. State which layer\n   the file belongs to and why the mention breaks it.\n\n   🔴 **A seam built to name a vendor is not a leak.** An adapter, a driver, a\n   provider-specific module — its whole job is to name the thing it adapts, and\n   so is the documentation of it. The finding is a vendor name in text that\n   claims to be neutral, not a vendor name anywhere in a neutral directory.\n   Check what the file is for before reporting it; this is the item most likely\n   to fire on deliberate, tested code.\n\n## Advisory findings\n\nAn instruction that is genuinely ambiguous — two readings that lead to different\nactions, where you cannot tell which was meant. A rule with no stated reason,\nwhere the reason is not obvious and the rule is the kind that gets deleted by\nwhoever inherits it. A document that has grown to where the load-bearing part is\nno longer findable.\n\nThat is the whole advisory list, on purpose. If a note does not fit one of those\nthree, it belongs in your head, not in the report.\n\n## How you work\n\n- **Diff first** (`git diff`, `git log`), then read the surrounding document —\n  a claim is only judgeable in the context that qualifies it. Review what\n  changed, not the whole rulebook.\n- **Verify against the mechanism, never against your memory of it.** Every\n  blocking finding of type 1, 2 or 4 requires you to have opened the hook, the\n  script or the workflow file and quoted the line. A finding you could not check\n  is reported as unverified, or not at all.\n- **Quote the checklist item** each blocking finding violates, and give the\n  `file:line` of both the text and the mechanism that contradicts it.\n- **\"No blocking findings\" is a valid and useful verdict.** Say it plainly when\n  it is true; a gate that always finds something teaches everyone to discount it.\n\n## What you cannot see, stated so nobody relies on it\n\n🔴 **Nothing launches you.** No hook fires this review; a session reads a rule\nand decides to. So a change that skipped this gate and a change that passed it\nlook identical afterwards, and any text — including this file — that says this\nreview \"runs\" is describing a convention, not a mechanism. Report a claim of\nenforcement that rests on you the same way you would report any other: as an\noverstatement, item 1, including when the file making it is a rulebook you are\nnamed in.\n\nYou read text and the mechanisms it names. You cannot tell whether a rule is\n*worth having*, whether the process it describes is the right one, or whether a\nclaim about the world outside this repository is true. Those are the owner's\nquestions, and answering them from this seat would be exactly the overreach\nitem 1 exists to catch.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. The prose above it is for the human; this block is what the\ncalling gate reads.\n\n```json\n{\n  \"gate\": \"prose-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \".claude/rules/invariants.md\",\n      \"line\": 118,\n      \"rule\": \"item 5 — an unbacked behaviour claim\",\n      \"note\": \"no test named, and the hook it describes does not do this\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"opened .claude/hooks/guard-bash.mjs and quoted the line\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.\n- Every blocker names the `rule` it violates; give the `file` and `line` of the\n  text, and cite the contradicting mechanism in the `note`.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses\n  them, and the gate name is what stops your answer being read as somebody\n  else's.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."