create-agent-rig 0.3.2 → 0.5.0

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

@@ -3,9 +3,13 @@
 // an agent (or a human using the agent) cannot write an impure line into
 // packages/core/src/ even if it wants to.
 //
-// Contract (Claude Code): JSON on stdin; exit 0 = allow, exit 2 = block, and
+// Contract (Claude Code and Codex): JSON on stdin; exit 0 = allow, exit 2 = block, and
 // stderr is shown to the agent as the reason.
+// Generator-owned coverage for the neutral bounded-inspection refusal lives upstream in
+// codex.test.ts › "$guard blocks with a neutral, actionable size-limit refusal"; generated
+// projects do not carry that suite, and a downstream edit requires a local replacement test.
 import { readFileSync } from 'node:fs';
+import { editFragments } from './lib/edit-input.mjs';
 
 /** The only non-relative import the core may use: its schema/validation library. */
 const ALLOWED_PACKAGES = ['zod'];
@@ -31,17 +35,27 @@ function main() {
   } catch {
     return 0; // unparseable payload: not ours to judge
   }
-  const toolName = input.tool_name;
-  const toolInput = input.tool_input ?? {};
-  if (toolName !== 'Write' && toolName !== 'Edit') return 0;
-
-  const filePath = String(toolInput.file_path ?? '').replaceAll('\\', '/');
-  if (!CORE_PATH.test(filePath) || !CODE_FILE.test(filePath)) return 0;
-
-  const fragment = String(
-    (toolName === 'Write' ? toolInput.content : toolInput.new_string) ?? '',
+  const fragments = editFragments(input);
+  const blocked = fragments.find(
+    ({ inspectionRefusal, appliesToAll }) => appliesToAll && inspectionRefusal,
   );
-  const violations = findViolations(fragment);
+  const globalRefusal = blocked?.inspectionRefusal;
+  if (globalRefusal) {
+    process.stderr.write(
+      `BLOCKED — cannot safely inspect this edit: ${globalRefusal}\n` +
+        // The remedy has to match the refusal: splitting cannot change a
+        // container shape, and a fixed line sent the agent into a retry loop
+        // on the one path it could not retry out of.
+        `${blocked.remedy ?? 'Split it into a smaller patch and retry.'}\n`,
+    );
+    return 2;
+  }
+
+  const violations = fragments.flatMap(({ filePath, fragment, inspectionRefusal }) => {
+    if (!CORE_PATH.test(filePath) || !CODE_FILE.test(filePath)) return [];
+    if (inspectionRefusal) return [`cannot safely inspect this move — ${inspectionRefusal}`];
+    return findViolations(fragment);
+  });
   if (violations.length === 0) return 0;
 
   process.stderr.write(

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

@@ -0,0 +1,180 @@
+// PreToolUse hook: a credential never enters the repository through an edit.
+//
+// Two arms, because a credential arrives two ways and only one of them has a
+// telltale name:
+//
+//   - the PATH is a credential file   (`jira.env`, `id_rsa`, `secrets/prod.txt`)
+//   - the CONTENT carries a credential VALUE, in a file named nothing special
+//
+// The second is the likelier path and the one nothing in this rulebook refused
+// before: an ignore rule can only ever answer the first.
+//
+// The vocabulary and both matchers come from `../scripts/lib/secrets.mjs`. This
+// file holds no list of its own on purpose — `.claude/rules/invariants.md`, "one
+// mechanism, one implementation": the same invariant written in two places will
+// disagree, and the copy nobody is looking at is the one that is wrong.
+//
+// Contract (Claude Code): JSON on stdin; exit 0 = allow, exit 2 = block, and
+// stderr is shown to the agent as the reason.
+//
+// 🔴 LIMITS, stated because a guard's own claim about its reach is the first
+// thing to go stale. Each names the test that pins it where one exists, and says
+// so plainly where none does — a limits comment nothing checks drifts into
+// overstatement, which is the direction that gets a reader hurt. ⚠ Those tests live in the GENERATOR this rig came from, not here;
+// `.claude/rules/invariants.md` ("About the hooks you were given") says the same
+// of this hook's own tests, and the moment you edit it they are yours.
+//
+// There are FOUR:
+//
+//   - It sees ONE edit fragment, not the resulting file. A credential assembled
+//     across two edits is not seen — see guard-secret-file.test.ts › "does not
+//     see a credential split across two edits, because it is shown one fragment
+//     at a time". This is the same limit every guard in this directory has,
+//     stated in full in `.claude/rules/invariants.md`, "What the enforcement
+//     actually is — stated exactly".
+//   - It sees only what the AGENT writes. The `toolName` branch in `main` below
+//     names the complete surface: `Write`, `Edit`, and `apply_patch`; every other
+//     tool returns before inspection. A human editing the file, or a
+//     `git commit` of something already on disk, never reaches a PreToolUse hook
+//     at all, and no test here can show that: it is a property of the harness,
+//     not of this file.
+//
+//     🔴 WHETHER ANYTHING ELSE CATCHES THAT IS NOT A QUESTION THIS FILE CAN
+//     ANSWER, and it is the one worth asking before relying on the rule. The
+//     layer that covers a human's edit is a COMMIT-TIME check — a git hook, a CI
+//     sweep — and this hook cannot see whether one is installed. Look at
+//     `.husky/` and the CI workflow rather than assuming: the generator this
+//     rulebook came from has both, running the same vocabulary; a freshly
+//     generated rig ships neither, and adding one is a decision for the project.
+//
+//   - It reads at most the first 2 MB of the text being written, the cap
+//     `findSecretValues` applies by default so a fail-open guard cannot be made
+//     to hang. A credential past that point is not seen. ⚠ No test here pins
+//     this one: the case is pinned one layer down, on the module, by
+//     secrets-lib.test.ts › "has a limit even when the caller names none". The CI sweep lifts the
+//     cap; this hook cannot, and that asymmetry is the point.
+//   - It FAILS OPEN on what it cannot understand — see guard-secret-file.test.ts
+//     › "allows a payload that is not JSON at all" and its neighbours. An
+//     unparseable payload, a missing field, or an internal throw all allow the
+//     edit; a crashed guard that blocks everything gets deleted within the hour.
+//
+//     ⚠ **An `apply_patch` command that is PRESENT and is not a shape this guard
+//     reads is the other case, and it now REFUSES** — see codex.test.ts ›
+//     "refuses, rather than failing open, when apply_patch command is supplied
+//     as %s". The line between them is whether the guard can tell: an absent
+//     field is a payload it does not understand, a container it detects and
+//     cannot read is a decision it can report. That reversed a contract this
+//     file previously pinned the other way, so it is stated rather than
+//     assumed. What catches the rest is whatever this project has put
+//     behind it: review always, a commit-time check once one exists.
+//
+// Failing open is also why every line here does provably bounded work: the scan
+// is capped inside `findSecretValues`, there is no recursion, and the one arm
+// that revisits offsets — the one that judges a candidate's value — is bounded
+// by an explicit per-line candidate cap rather than running to exhaustion. Any
+// unbounded work in a fail-open guard is a total bypass of every rule at once,
+// not just of this one.
+import { readFileSync } from 'node:fs';
+
+import { findSecretValues, isCredentialPath } from '../scripts/lib/secrets.mjs';
+import { editFragments } from './lib/edit-input.mjs';
+
+/** Where a refusal points the agent, so the block is actionable rather than a wall. */
+const WHERE_CREDENTIALS_BELONG =
+  'Credentials live outside the repo (an env file in your home config, a secret manager) ' +
+  'and reach the process through the environment — see .claude/rules/autonomy.md, "Never".';
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return 0; // unparseable payload: not ours to judge
+  }
+
+  const toolName = input?.tool_name;
+  if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'apply_patch') return 0;
+
+  if (toolName === 'apply_patch') {
+    let refused = false;
+    for (const { filePath, fragment, inspectionRefusal, remedy, appliesToAll } of editFragments(input)) {
+      if (inspectionRefusal) {
+        refused = true;
+        process.stderr.write(
+          `BLOCKED — cannot safely inspect this edit: ${inspectionRefusal}\n` +
+            // The remedy has to match the refusal: splitting cannot change a
+            // container shape, and a fixed line sent the agent into a retry loop
+            // on the one path it could not retry out of.
+            `${remedy ?? 'Split it into a smaller patch and retry.'}\n`,
+        );
+        continue;
+      }
+      if (isCredentialPath(filePath)) {
+        refused = true;
+        process.stderr.write(`BLOCKED — "${filePath}" is a credential file, and this repository never carries one.\n${WHERE_CREDENTIALS_BELONG}\n`);
+        continue;
+      }
+      const findings = findSecretValues(fragment);
+      if (findings.length > 0 || appliesToAll) {
+        refused = true;
+        if (findings.length > 0) process.stderr.write(`BLOCKED — this edit writes a credential value into "${filePath}".\n${WHERE_CREDENTIALS_BELONG}\n`);
+      }
+    }
+    return refused ? 2 : 0;
+  }
+
+  const toolInput = input?.tool_input ?? {};
+  const filePath = String(toolInput.file_path ?? '').replaceAll('\\', '/');
+  if (filePath === '') return 0; // nothing to judge; fail open
+
+  // The tool sends an absolute path. Judge the repo-relative tail so a checkout
+  // living under a directory literally called `secrets` does not make every edit
+  // in the project a credential.
+  // Trailing slashes stripped: with `CLAUDE_PROJECT_DIR=/repo/` the prefix test
+  // below never matches, every path stays absolute, and a checkout that happens
+  // to live under a directory called `secrets` has EVERY edit refused. That is
+  // the "deleted within the hour" outcome `.claude/rules/invariants.md` warns
+  // about — see guard-secret-file.test.ts › "judges the repo-relative path even
+  // when the project directory is given with a trailing slash".
+  const projectDir = String(process.env.CLAUDE_PROJECT_DIR ?? '')
+    .replaceAll('\\', '/')
+    .replace(/\/+$/, '');
+  const relativePath =
+    projectDir !== '' && filePath.startsWith(`${projectDir}/`)
+      ? filePath.slice(projectDir.length + 1)
+      : filePath;
+
+  if (isCredentialPath(relativePath)) {
+    process.stderr.write(
+      `BLOCKED — "${relativePath}" is a credential file, and this repository never carries one.\n` +
+        `${WHERE_CREDENTIALS_BELONG}\n` +
+        `If this file is a documented placeholder, name it .env.example — that form stays committable.\n`,
+    );
+    return 2;
+  }
+
+  const fragment = String((toolName === 'Write' ? toolInput.content : toolInput.new_string) ?? '');
+  const findings = findSecretValues(fragment);
+  if (findings.length === 0) return 0;
+
+  process.stderr.write(
+    `BLOCKED — this edit writes a credential value into "${relativePath}":\n` +
+      findings
+        .map((finding) => `  - ${finding.id} on line ${finding.line} of the text being written`)
+        .join('\n') +
+      `\n${WHERE_CREDENTIALS_BELONG}\n` +
+      // Deliberately NOT the matched text. A guard that prints what it found has
+      // copied the credential into a hook transcript and a terminal scrollback —
+      // it has leaked the secret in the act of refusing it.
+      `The matched value is deliberately not shown; open the line above to see it.\n`,
+  );
+  return 2;
+}
+
+let status;
+try {
+  status = main();
+} catch {
+  status = 0; // fail open — see the LIMITS block above
+}
+process.exit(status);

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

@@ -3,9 +3,13 @@
 // layer (`…/db`) and never the services. Enforced at the tool layer, same as
 // core purity: best-effort text scan, failing safe toward a false block.
 //
-// Contract (Claude Code): JSON on stdin; exit 0 = allow, exit 2 = block, and
+// Contract (Claude Code and Codex): JSON on stdin; exit 0 = allow, exit 2 = block, and
 // stderr is shown to the agent as the reason.
+// Generator-owned coverage for the neutral bounded-inspection refusal lives upstream in
+// codex.test.ts › "$guard blocks with a neutral, actionable size-limit refusal"; generated
+// projects do not carry that suite, and a downstream edit requires a local replacement test.
 import { readFileSync } from 'node:fs';
+import { editFragments } from './lib/edit-input.mjs';
 
 const WEB_PATH = /(^|\/)apps\/web\//;
 const CODE_FILE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
@@ -22,21 +26,36 @@ function main() {
   } catch {
     return 0; // unparseable payload: not ours to judge
   }
-  const toolName = input.tool_name;
-  const toolInput = input.tool_input ?? {};
-  if (toolName !== 'Write' && toolName !== 'Edit') return 0;
-
-  const filePath = String(toolInput.file_path ?? '').replaceAll('\\', '/');
-  if (!WEB_PATH.test(filePath) || !CODE_FILE.test(filePath)) return 0;
-
-  const fragment = String((toolName === 'Write' ? toolInput.content : toolInput.new_string) ?? '');
   const violations = [];
   const importRe =
     /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|^\s*import\s+)['"]([^'"]+)['"]/gm;
-  for (const match of fragment.matchAll(importRe)) {
-    const spec = match[1];
-    if (FORBIDDEN_WORKSPACE.test(spec) || FORBIDDEN_RELATIVE.test(spec)) {
-      violations.push(spec);
+  const fragments = editFragments(input);
+  const blocked = fragments.find(
+    ({ inspectionRefusal, appliesToAll }) => appliesToAll && inspectionRefusal,
+  );
+  const globalRefusal = blocked?.inspectionRefusal;
+  if (globalRefusal) {
+    process.stderr.write(
+      `BLOCKED — cannot safely inspect this edit: ${globalRefusal}\n` +
+        // The remedy has to match the refusal: splitting cannot change a
+        // container shape, and a fixed line sent the agent into a retry loop
+        // on the one path it could not retry out of.
+        `${blocked.remedy ?? 'Split it into a smaller patch and retry.'}\n`,
+    );
+    return 2;
+  }
+
+  for (const { filePath, fragment, inspectionRefusal } of fragments) {
+    if (!WEB_PATH.test(filePath) || !CODE_FILE.test(filePath)) continue;
+    if (inspectionRefusal) {
+      violations.push(`cannot safely inspect this move — ${inspectionRefusal}`);
+      continue;
+    }
+    for (const match of fragment.matchAll(importRe)) {
+      const spec = match[1];
+      if (FORBIDDEN_WORKSPACE.test(spec) || FORBIDDEN_RELATIVE.test(spec)) {
+        violations.push(spec);
+      }
     }
   }
   if (violations.length === 0) return 0;

package/templates/agent-os/universal/.claude/hooks/inject-rules.mjs

@@ -10,8 +10,144 @@
 // The injected content is deliberately STATELESS — rules, never facts about
 // the moment (mid-session injections are replayed on resume, so timestamps
 // or SHAs here would lie). And it is only the load-bearing part, not the
-// whole rulebook: CLAUDE.md is already loaded by the tool itself.
-import { readFileSync } from 'node:fs';
+// whole rulebook.
+//
+// Which part is load-bearing is not this hook's judgment to make: the rule
+// file marks what it does not need injected, and everything else goes. That
+// division of labour is the whole design, and it was arrived at the expensive
+// way. An earlier version of this file selected `## ` sections from a kept
+// list — and four review rounds each found a different way for that selection
+// to return a silently truncated excerpt: a heading inside a code fence, a
+// heading inside a skipped region, a section whose heading and body fell on
+// opposite sides of a marker, a heading inside an HTML block. Each fix closed
+// one spelling and the next round found another, because a parser that infers
+// structure has no bottom. This one does not parse structure at all.
+//
+// ⚠ The saving rests on an assumption this repository cannot enforce: that the
+// tool already loads `.claude/rules/*.md` as project instructions, so injecting
+// the whole file pays for it twice. That is harness behaviour, observable but
+// not pinned here. Where it does not hold, this is a plain subtraction — which
+// is why every ambiguity resolves toward injecting more.
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// Regions the rule file marks as not worth injecting. The marker is explicit
+// and lives in the rule file itself, where the person editing it can see it —
+// an earlier version keyed on heading level instead, which made "what every
+// session is governed by" a silent consequence of a formatting choice.
+const SKIP_OPEN = '<!-- inject:skip -->';
+const SKIP_CLOSE = '<!-- /inject:skip -->';
+
+/**
+ * A fence opener, as CommonMark defines one: three or more backticks or
+ * tildes. The closer has to be the same character and no shorter, which is why
+ * this returns the run rather than a boolean — a three-backtick line inside a
+ * four-backtick block is content, not the end of the block.
+ */
+function fenceRun(line) {
+  const trimmed = line.trimStart();
+  const char = trimmed[0];
+  if (char !== '`' && char !== '~') return null;
+  let length = 0;
+  while (trimmed[length] === char) length += 1;
+  if (length < 3) return null;
+  // `bare` is what separates a closer from an opener: an opener may carry an
+  // info string (```sh), a closer may not.
+  return { char, length, bare: trimmed.slice(length).trim() === '' };
+}
+
+/**
+ * The whole file, minus every region the file itself marks with
+ * `<!-- inject:skip -->` … `<!-- /inject:skip -->`. That is the entire
+ * operation: nothing here reads a heading, so no arrangement of headings —
+ * indented, inside an HTML block, split across a marker — can change what
+ * survives. What is omitted is a decision made in the rule file, by whoever
+ * writes the rule, and visible on the line above it.
+ *
+ * Fenced code is data, not structure, so a marker inside a fence is content.
+ * Both fence characters, with the CommonMark closing rule (same character, at
+ * least as long, nothing but whitespace after it) — a rules file quotes shell
+ * and markdown at each other, and an opener may carry an info string where a
+ * closer may not.
+ *
+ * It returns the input UNCHANGED whenever the markup is malformed: a skip
+ * region left open, one closed without being opened, one nested inside
+ * another, or a fence left open. Partial output is the dangerous answer,
+ * because a governance section can go missing with nothing to notice it; a run
+ * that gets the whole file has only paid twice.
+ *
+ * The limits, so nobody relies on cover that is not here. A marker is
+ * recognised only as the first non-whitespace text on its own line — so one
+ * inside a blockquote is not a marker, and its text reaches the context. And
+ * fence-awareness is the only structure it knows: a BALANCED marker pair
+ * written inside an indented code block or an HTML comment is obeyed, so a
+ * document that demonstrates the markers loses the lines between them. Show
+ * them inside a fence.
+ */
+export function excerptAutonomy(markdown) {
+  const lines = markdown.split('\n');
+  const kept = [];
+  let skipping = false;
+  let fence = null;
+  let malformed = false;
+
+  for (const line of lines) {
+    const run = fenceRun(line);
+    if (fence) {
+      if (run && run.char === fence.char && run.length >= fence.length && run.bare) fence = null;
+    } else if (run) {
+      fence = run;
+    } else {
+      const trimmed = line.trim();
+      // Matched by prefix: a marker with something after it is still a marker,
+      // and the whole line goes. Requiring the line to be exactly the marker
+      // would let `<!-- inject:skip --> note` open nothing and then print
+      // itself into the context.
+      if (trimmed.startsWith(SKIP_OPEN)) {
+        // A second open inside a region is as much a mistake as a stray close,
+        // and the two are the same signal: the markers do not pair up.
+        malformed ||= skipping;
+        skipping = true;
+        continue;
+      }
+      if (trimmed.startsWith(SKIP_CLOSE)) {
+        malformed ||= !skipping;
+        skipping = false;
+        continue;
+      }
+    }
+    if (!skipping) kept.push(line);
+  }
+
+  if (fence || skipping || malformed) return markdown;
+  const excerpt = kept.join('\n').trim();
+  // Nothing left is the largest possible version of "partial output", and the
+  // marker pairing cannot see it: a balanced pair around the whole file is
+  // well-formed. A zero, not a threshold — this is deliberately not the byte
+  // ratio an earlier round used and deleted.
+  return excerpt === '' ? markdown : excerpt;
+}
+
+/**
+ * Whether this file is being run as a script rather than imported.
+ *
+ * The realpath on both sides is the point: ESM resolves `import.meta.url`
+ * through symlinks while `process.argv[1]` keeps the path as typed, so a
+ * project under a symlinked directory — a macOS temp dir, a symlinked home, a
+ * checkout behind a link — fails a naive equality check. The hook would then
+ * print nothing and exit 0, which reads exactly like a healthy session.
+ */
+function 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]);
+}
 
 function main() {
   let input;
@@ -22,15 +158,47 @@ function main() {
   }
   if (input.hook_event_name !== 'SessionStart') return 0;
 
+  let rules;
   try {
-    const rules = readFileSync(new URL('../rules/autonomy.md', import.meta.url), 'utf8');
-    process.stdout.write(
-      `[agent-os] Autonomy rules refresh — in force regardless of compaction:\n\n${rules}\n`,
-    );
+    rules = readFileSync(new URL('../rules/autonomy.md', import.meta.url), 'utf8');
   } catch {
     // no rules file — nothing to inject, never an error
+    return 0;
+  }
+
+  // The cut is the only thing allowed to fail here, and its failure resolves
+  // the way every other ambiguity in this file does: inject more. Leaving it
+  // inside the read's catch meant a throw in the excerpter printed NOTHING and
+  // exited 0 — the rules gone, and the session looking healthy.
+  let body;
+  try {
+    body = excerptAutonomy(rules);
+  } catch {
+    body = rules;
   }
+
+  // The banner reports what happened, so it cannot be written once and assumed:
+  // on the fallback path nothing was removed, and telling a session to go read
+  // four sections it is already holding is the same kind of false report the
+  // cut itself is built to avoid.
+  // Compared trimmed, because the two paths differ by a trailing newline that
+  // is not a removal: the excerpt is trimmed and the fallback is not. A rules
+  // file that marks nothing would otherwise be announced as an excerpt — which
+  // is the case a project re-scoping its own rulebook lands in, every session.
+  const notice =
+    body.trim() === rules.trim()
+      ? 'This is `.claude/rules/autonomy.md` in full.\n\n'
+      : 'This is `.claude/rules/autonomy.md` with the sections it marks as ' +
+        'reference removed — read the file itself for those: how the Tier-2 ' +
+        'gate is swept from outside, how external work is reconciled, ' +
+        'post-deploy verification, and the escalation format.\n\n';
+
+  process.stdout.write(
+    `[agent-os] Autonomy rules refresh — in force regardless of compaction.\n${notice}${body}\n`,
+  );
   return 0;
 }
 
-process.exit(main());
+if (invokedDirectly()) {
+  process.exit(main());
+}