create-agent-rig 0.5.0 → 0.6.0

package/templates/agent-os/universal/.claude/hooks/gate-stop-dod.mjs

@@ -62,10 +62,30 @@
 //     exists and cannot be used announces —
 //     see hooks.test.ts › "stays silent when there is no config at all — nothing to gate is the design, not a swallowed error"
 import { execSync, spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 import { withoutGitLocation } from '../scripts/git-env.mjs';
 
+// 🔴 The tree this gate measures is the project the hook BELONGS to — the
+// directory above `.claude/hooks/` — never the directory the session happens
+// to be in. Observed twice in one session (AR-119): reviewing another branch
+// in a worktree under `.claude/worktrees/`, the gate ran the suite in the
+// worktree the shell had last cd-ed into and reported THAT branch's failing
+// test as this session's own Definition-of-Done failure. Reviewing a foreign
+// branch in a worktree is a first-class motion here, so an inherited cwd is
+// the wrong tree often enough to matter. `git status` and every check run
+// with this as their `cwd`, and both refusals name it, so a failure that is
+// still foreign is visible at a glance. It is the session's ROOT, not its
+// branch: a session started at the main checkout whose own task lives in a
+// `worktree-task` worktree is measured at the main checkout, and the refusal
+// says so. Resolved inside `main()`, so a throw here reaches the backstop
+// and announces itself like every other fault of the gate's own.
+//   see hooks.test.ts › "runs the checks in the project root, so a check reading the tree sees the session project"
+//   see hooks.test.ts › "asks "is the tree clean?" about the project, not about the cwd"
+//   see hooks.test.ts › "names the tree it measured in the refusal, so a foreign failure is visible at a glance"
+const projectRootOf = () => realpathSync(fileURLToPath(new URL('../..', import.meta.url)));
+
 // The default total budget, and the allowance for everything that happens
 // OUTSIDE it.
 //
@@ -155,6 +175,8 @@ function main() {
   if (input.hook_event_name !== 'Stop' && input.hook_event_name !== 'SubagentStop') return 0;
   if (input.stop_hook_active) return 0;
 
+  const PROJECT_ROOT = projectRootOf();
+
   try {
     // The environment loses the variables that locate a repository first. A
     // process started under a git hook inherits an absolute GIT_DIR, and this
@@ -183,6 +205,7 @@ function main() {
     // and the reason the bound can be generous. The options object stays terse
     // on purpose; a sibling test matches it by a bounded window.
     const status = execSync('git status --porcelain', {
+      cwd: PROJECT_ROOT,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
       env: withoutGitLocation(),
@@ -252,6 +275,7 @@ function main() {
     // that did not fit instead of blaming it for spending what an earlier one
     // spent. One path, and no branch that only a race can reach.
     const result = spawnSync(command, {
+      cwd: PROJECT_ROOT,
       shell: true,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -277,7 +301,8 @@ function main() {
       // unknown, and an unmeasured Definition of Done is not a passed one.
       const timedOut = result.error.code === 'ETIMEDOUT';
       process.stderr.write(
-        `STOP GATED — \`${command}\` produced no verdict: ${result.error.message}\n` +
+        `STOP GATED — \`${command}\` produced no verdict (measured in ${PROJECT_ROOT}): ` +
+          `${result.error.message}\n` +
           (timedOut
             ? `It did not finish inside the ${budget.ms} ms budget for the whole suite ` +
               `(RIG_DOD_BUDGET_MS lowers it; raising it means raising this hook's default ` +
@@ -297,7 +322,7 @@ function main() {
         .slice(-15)
         .join('\n');
       process.stderr.write(
-        `STOP GATED — a Definition of Done check fails: ${command}\n` +
+        `STOP GATED — a Definition of Done check fails (measured in ${PROJECT_ROOT}): ${command}\n` +
           (tail.trim() ? `${tail}\n` : '') +
           `Fix the failure before ending the session. If this failure has resisted ` +
           `repeated attempts, follow the stop rules instead: end with a written ` +

package/templates/agent-os/universal/.claude/hooks/guard-rulebook.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// PreToolUse hook: in an UNATTENDED run, the rulebook is never edited outside
+// the current item's allow-list (AR-51).
+//
+// The rulebook is the set of files that decide what this session may do — the
+// hooks, their wiring, the queue config and adapters, the router and the gate
+// sweep, the rules, `CLAUDE.md`. Every one of them was editable by the run it
+// governs: a Write to `.claude/hooks/dod-checks.json` with `[]` switched the
+// stop gate off, and nothing refused it until the merge sweep, long after.
+//
+// How it decides — and it is deliberately dumb:
+//   1. No unattended flag on disk (`.claude/scripts/unattended-flag.mjs`) → an
+//      attended session → exit 0 for everything. A human at the keyboard edits
+//      the rulebook on purpose.
+//   2. Flag present and readable → every edit fragment whose repo-relative path
+//      sits under a rulebook prefix is refused (exit 2) unless it also sits
+//      under one of the item's `allow` prefixes. Paths outside the rulebook are
+//      never judged.
+//   3. Flag present and UNREADABLE → a rulebook edit is refused and the reason
+//      names the flag; an edit outside the rulebook still passes. Refusing to
+//      inspect is not allowing (`.claude/rules/invariants.md`).
+//
+// Limits — each stated here and each measured in the generator's
+// `test/template/guard-rulebook.test.ts` (absent in a generated rig), by the
+// test named beside it:
+//   - it sees one edit at a time, as text, before it lands — a rulebook file
+//     rewritten through a Bash redirect (`echo … > .claude/settings.json`), a
+//     generated file, or `git checkout` of another branch is not an edit tool
+//     call and never reaches it, and `guard-bash` does not cover that either —
+//     › "a Bash redirect into the rulebook is not an edit tool call and passes
+//     — guard-bash does not cover it either";
+//   - the flag in either home arms it (the env-derived one and the password
+//     database one, like the kill switch), and ONLY a flag arms it: an
+//     exported variable changes nothing, and an attended session that never
+//     set a flag is exactly as free as before — › "only a flag arms it — an
+//     exported RIG_UNATTENDED=1 with no flag changes nothing";
+//   - it judges paths, not content: a README that merely mentions
+//     `.claude/hooks/guard-bash.mjs` is not a rulebook edit — › "guards the
+//     path, not prose that mentions a guarded path";
+//   - it compares paths as text: the repo-relative tail is what is left after
+//     stripping `CLAUDE_PROJECT_DIR` (falling back to the working directory
+//     when the harness does not set it) from the front of the tool's absolute
+//     path, so a root spelled differently from the file path — a symlinked
+//     `/tmp` versus `/private/tmp`, a case difference on a case-insensitive
+//     disk — is not stripped, and the edit is not judged. Documented and
+//     measured, not fixed: the harness spells both from one root — › "compares
+//     paths as text: a root spelled differently from the file path is not
+//     judged (documented, fails open)";
+//   - an `allow` prefix is a string prefix of the repo-relative path and may
+//     not widen the rulebook — an entry that is itself a prefix of a rulebook
+//     prefix (`.`, `.claude/`, `.claude/scripts/`) makes the flag unreadable
+//     and the guard refuses — › "a flag whose allow-list widens the rulebook is
+//     unreadable, so `--allow .` cannot disarm it";
+//   - fail-open on its own errors and on a payload it cannot parse — › "allows
+//     an empty payload object" and › "allows non-JSON stdin" — and fail-closed
+//     on a flag it cannot read — › "blocks a rulebook edit when the flag exists
+//     but cannot be read, and names the file": the guard targets drift, not an
+//     adversary.
+//
+// The rule it enforces is stated in `.claude/rules/autonomy.md`, "Never".
+import { readFileSync } from 'node:fs';
+import { editFragments } from './lib/edit-input.mjs';
+import { RULEBOOK_PREFIXES, isRulebookPath, readUnattended } from '../scripts/unattended-flag.mjs';
+
+export { RULEBOOK_PREFIXES, isRulebookPath };
+
+const EDIT_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'apply_patch']);
+
+const toPosix = (value) => String(value ?? '').replaceAll('\\', '/');
+
+/** The repo-relative tail of an absolute path, or the path itself when it is not under the root. */
+export const relativeTo = (root, filePath) => {
+  const dir = toPosix(root).replace(/\/+$/, '');
+  const file = toPosix(filePath);
+  if (dir !== '' && file.startsWith(`${dir}/`)) return file.slice(dir.length + 1);
+  return file.replace(/^\.\//, '');
+};
+
+export const isAllowed = (rel, allow) =>
+  (Array.isArray(allow) ? allow : []).some((prefix) => prefix !== '' && (rel === prefix || rel.startsWith(prefix)));
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return 0; // unparseable payload: not ours to judge
+  }
+  if (!EDIT_TOOLS.has(input?.tool_name)) return 0;
+
+  const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  const paths = [];
+  for (const { filePath } of editFragments(input)) {
+    if (typeof filePath !== 'string' || filePath === '') continue;
+    const rel = relativeTo(root, filePath);
+    if (isRulebookPath(rel) && !paths.includes(rel)) paths.push(rel);
+    if (paths.length >= 64) break;
+  }
+  if (paths.length === 0) return 0; // nothing under the rulebook: never judged
+
+  const mode = readUnattended();
+  if (!mode.on) return 0; // attended session
+
+  if (mode.unreadable) {
+    process.stderr.write(
+      `BLOCKED — "${paths[0]}" is part of the rulebook and the unattended flag at ${mode.path} is unreadable (${mode.why}). ` +
+        'Refusing to inspect is not allowing: fix or remove the flag (`node .claude/scripts/unattended-flag.mjs off`), then retry.\n',
+    );
+    return 2;
+  }
+
+  const refused = paths.filter((rel) => !isAllowed(rel, mode.allow));
+  if (refused.length === 0) return 0;
+  process.stderr.write(
+    `BLOCKED — "${refused[0]}" is part of the rulebook, and an unattended run never edits the rulebook outside its item's allow-list ` +
+      `(item ${mode.item ?? '(none)'}; allowed prefixes: ${mode.allow.length === 0 ? 'none' : mode.allow.join(', ')}). ` +
+      'If the item really needs this path, it belongs in the allow-list the loop wrote at claim time — a decision, not a default. ' +
+      'See .claude/rules/autonomy.md, "Never".\n',
+  );
+  return 2;
+}
+
+try {
+  process.exit(main());
+} catch {
+  process.exit(0); // a crashed guard must not block the session
+}

package/templates/agent-os/universal/.claude/hooks/lib/edit-input.mjs

@@ -45,6 +45,8 @@ const MAX_TOTAL_HUNK_LINES = 10_000;
 const MAX_OUTPUT_LINES = 20_000;
 const MAX_SPLICE_OPERATIONS = 1_000;
 const MAX_PATCH_SECTIONS = 128;
+/** A MultiEdit is capped before it is mapped — bounded work, never a spread of input. */
+const MAX_MULTI_EDITS = 256;
 const MAX_PATCH_PATH_COMPONENTS = 512;
 
 export function editFragments(input) {
@@ -60,6 +62,27 @@ export function editFragments(input) {
       },
     ];
   }
+  // Claude Code's other two edit surfaces (AR-51). `MultiEdit` carries one
+  // file and a list of edits — one fragment per edit, same path — and
+  // `NotebookEdit` carries a cell's new source. Before this, both reached every
+  // guard through the unanchored `Write|Edit` matcher and yielded no fragment,
+  // so a `Date.now()` in a MultiEdit to the core passed unchecked.
+  if (toolName === 'MultiEdit') {
+    if (!Array.isArray(toolInput.edits)) return [];
+    const filePath = normalisePath(toolInput.file_path);
+    return toolInput.edits.slice(0, MAX_MULTI_EDITS).map((edit) => ({
+      filePath,
+      fragment: String(edit?.new_string ?? ''),
+    }));
+  }
+  if (toolName === 'NotebookEdit') {
+    return [
+      {
+        filePath: normalisePath(toolInput.notebook_path),
+        fragment: String(toolInput.new_source ?? ''),
+      },
+    ];
+  }
   if (toolName !== 'apply_patch') return [];
   const rawCommand = toolInput.command;
   // ⚠ **Absent is not malformed, and the difference decides which way this fails.**

package/templates/agent-os/universal/.claude/rules/autonomy.md

@@ -108,6 +108,14 @@ own cost figures are read next to the lane they do not cover.
   at runtime instead of writing it out, or the check reports its own test data as
   a leak.
 - touch production data outside a reviewed migration
+- edit the rulebook from an **unattended** run outside the item's allow-list — `guard-rulebook` refuses it.
+  The rulebook: the hooks, their wiring, `.claude/queue.json`, the queue
+  adapters, the router, the gate sweep, the rules, `CLAUDE.md`. Mechanical:
+  the hook refuses the edit while the unattended flag the `loop` skill writes
+  at claim time is on disk (`.claude/scripts/unattended-flag.mjs`), and does
+  nothing in an attended session. ⚠ It sees edit tool calls only — a
+  shell redirect into `.claude/settings.json` is not one — and the flag, not
+  the run, is what arms it; its header states the rest of its limits.
 
 ## Stop rules — by work-state, not by feelings
 

package/templates/agent-os/universal/.claude/rules/invariants.md

@@ -168,9 +168,28 @@ Two rules that follow from it:
   deliberately coarse and stop trying to out-parse the input. Where a false block
   interrupts ordinary work, stay narrow and specific. Uniform precision
   everywhere is how a guard ends up simultaneously too loose and too annoying.
-- **One mechanism, one implementation.** If two files enforce the same
-  invariant, they will disagree — and the one nobody is looking at is the one
-  that is wrong. Export it from a single module and import it.
+- **One mechanism, one implementation.** And one spelling of a fact. If two
+  files enforce the same invariant, they will disagree — and the one nobody is
+  looking at is the one that is wrong. Export it from a single module and import
+  it. The same holds for any mechanically expressible fact two artifacts encode
+  — a list, a vocabulary, a set of paths, a lane's reviewer floor: prefer one
+  source that the others derive from or are generated from. Where a second copy
+  has to stay (prose a reader needs), put a correspondence check between the two
+  that goes red in both directions — a copy that gains an entry the source
+  lacks, and a source that gains one the copy lacks — and put that check in
+  before adding prose or a memory note about keeping them aligned. The shape is
+  in the generator's `test/template/correspondence.test.ts` (absent in a
+  generated rig): the check itself, ›
+  "every point the module knows is named by the loop or pr-ship skill, and vice versa"
+  and ›
+  "the pr-ship fan-out bullets name exactly the floor of each lane, and only known lanes";
+  and the proof that it names the offender, one mutation per side, ›
+  "reports a point named in prose that no script knows (mutation: BEFORE_MERGE)",
+  › "reports a point the module knows that no prose mentions (mutation: extended POINTS)",
+  › "reports a reviewer added to a bullet the floor does not include (mutation: prose)"
+  and › "reports a floor widened in the mapping that the prose does not carry (mutation: mapping)".
+  What such a check costs is written where the check is, in the header of the
+  file that carries it.
 
 ## The worked example — and it is one project's answer, not a law
 
@@ -217,6 +236,17 @@ If a hook matters enough to keep, it is worth ten minutes to copy the shape from
 `.claude/skills/new-invariant/guard-invariant.example.test.mjs` and pin the
 behaviour you actually rely on.
 
+**That boundary is audited, not remembered.** `node .claude/scripts/doctor.mjs`
+reads `.claude/.rig-manifest.json` and asks of every hook in `.claude/hooks/` (and
+`.husky/`, when it exists) whether the project owns it — the bytes differ from
+what the generator installed, or the manifest has no entry — and, if so, whether
+`<hook>.test.mjs` sits beside it. A shipped, unchanged hook is not a finding; an
+owned hook with no neighbour is; a rig with no manifest gets `unknown` for every
+hook that has no test neighbour, never a pass. Exemptions are an explicit list with reasons in
+`.claude/doctor-exemptions.json`, and the report ends with what the script did
+not check. Pinned in the generator's `test/template/doctor.test.ts` — absent in a
+generated rig — › "an owned hook without a test is a FAIL, and the run is STOP".
+
 ## Adding one
 
 Use the `new-invariant` skill. It asks what the invariant is (it will not invent

package/templates/agent-os/universal/.claude/scripts/decision-router.mjs

@@ -927,12 +927,30 @@ export const route = ({ files, elevatedPaths } = {}) => {
   };
 };
 
+/**
+ * The floor each lane sets, and nothing else — what `pr-ship` step 4 launches
+ * before any trigger adds to it. Exported as the ONE spelling of that fact:
+ * `pr-ship/SKILL.md` restates it in prose, and the generator's
+ * test/template/correspondence.test.ts › "the pr-ship fan-out bullets name
+ * exactly the floor of each lane, and only known lanes" keeps the two in step
+ * in both directions (AR-137). Only the `model` entry has a runtime consumer
+ * (`reviewersFor` below, which the router calls); the other two are checked
+ * against the prose alone — `route()` launches nothing on those lanes itself.
+ * Cost of the check: a floor change touches this function and one bullet, and
+ * the bullet must keep its `- \`lane\` → …` shape or the parse fails by name.
+ */
+export const reviewersForLane = (lane) => {
+  if (lane === 'model') return ['code-reviewer'];
+  if (lane === 'fast-path') return ['prose-reviewer'];
+  return [];
+};
+
 /**
  * Who the expensive lane fans out to — `code-reviewer` first, always, and the
  * conditional gates `pr-ship` already names, decided from the same paths.
  */
 const reviewersFor = (files, risks) => {
-  const reviewers = ['code-reviewer'];
+  const reviewers = [...reviewersForLane('model')];
 
   let wantsProse = false;
   for (const file of files) {