create-agent-rig 0.3.1 → 0.4.0

package/packages/cli/dist/lib/manifest.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isSafeSegment } from './safe-path.js';
+/**
+ * The install manifest: what this rig installed, at which version, and the
+ * hash each file had when it was written.
+ *
+ * It exists to answer the one hard question an upgrade has — *did the user
+ * edit this file?* — with evidence instead of a guess. It is **evidence, not a
+ * command**: a file the manifest names but the disk no longer has is reported,
+ * never silently restored.
+ *
+ * It is meant to be committed. Without it in the repository, an upgrade run on
+ * CI or on a colleague's machine is blind and falls back to the hash history.
+ */
+export const MANIFEST_REL = '.claude/.rig-manifest.json';
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function isStringRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((v) => typeof v === 'string'));
+}
+/**
+ * A manifest, or `null` when there is nothing trustworthy to read.
+ *
+ * The distinction matters: `null` means "no evidence", which sends the upgrade
+ * to the hash history. A half-parsed manifest treated as an empty one would
+ * claim every file on disk belongs to the user, and upgrade nothing at all.
+ */
+export function parseManifest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const m = parsed;
+    if (typeof m.version !== 'string')
+        return null;
+    if (m.kind !== 'create' && m.kind !== 'init')
+        return null;
+    const project = m.project;
+    if (typeof project !== 'object' ||
+        project === null ||
+        typeof project.name !== 'string' ||
+        typeof project.scope !== 'string' ||
+        typeof project.region !== 'string') {
+        return null;
+    }
+    // Values, not just types. These are substituted into file names and joined
+    // into paths, and this file is committed — it reaches a maintainer's disk
+    // through a pull request. A name of `../..` would send every write out of
+    // the repository, so an unsafe value invalidates the whole manifest rather
+    // than being quietly corrected into something plausible.
+    if (!isSafeSegment(project.name) || !isSafeSegment(project.scope))
+        return null;
+    if (project.region !== '' && !isSafeSegment(project.region))
+        return null;
+    if (!Array.isArray(m.stacks) || m.stacks.some((s) => typeof s !== 'string'))
+        return null;
+    if (m.stacks.some((s) => !isSafeSegment(s)))
+        return null;
+    if (!isStringRecord(m.files))
+        return null;
+    return {
+        version: m.version,
+        kind: m.kind,
+        project: { name: project.name, scope: project.scope, region: project.region },
+        stacks: [...m.stacks],
+        files: { ...m.files },
+    };
+}
+/** Stable bytes: sorted paths, so a re-run produces no diff of its own. */
+export function serializeManifest(manifest) {
+    const files = {};
+    for (const rel of Object.keys(manifest.files).sort())
+        files[rel] = manifest.files[rel];
+    return `${JSON.stringify({ ...manifest, files }, null, 2)}\n`;
+}
+export async function readManifest(repoDir) {
+    try {
+        return parseManifest(await readFile(path.join(repoDir, ...MANIFEST_REL.split('/')), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeManifest(repoDir, manifest) {
+    const dest = path.join(repoDir, ...MANIFEST_REL.split('/'));
+    await mkdir(path.dirname(dest), { recursive: true });
+    await writeFile(dest, serializeManifest(manifest));
+}

package/packages/cli/dist/lib/prompts.js

@@ -1,4 +1,24 @@
 import { createInterface } from 'node:readline';
+/**
+ * A yes/no gate before something irreversible. **The default is no**, and a
+ * non-interactive caller gets `false` without being asked — the same rule the
+ * rest of this CLI follows: never guess for a run that cannot answer.
+ *
+ * Unlike the target prompt, an unrecognised answer is *not* forgiving: the
+ * question is asked before rewriting files in somebody's repository, and "I
+ * did not understand you" must not resolve to "go ahead".
+ */
+export function promptConfirm(question, streams) {
+    if (!streams.isInteractive)
+        return Promise.resolve(false);
+    const rl = createInterface({ input: streams.input, output: streams.output });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
 /**
  * Pick a target interactively: by number, by name, or Enter for the default.
  * Anything unrecognised falls back to the default — generation should never

package/packages/cli/dist/lib/safe-path.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+/**
+ * Path safety for values that came from **outside the CLI** — the install
+ * manifest is committed to a repository, so it arrives in pull requests like
+ * any other file, and its values are substituted into paths.
+ *
+ * One module owns both halves so they cannot disagree: what may become a path
+ * segment, and where a resolved path is allowed to land.
+ */
+/** A value that can be substituted into a path without steering it. */
+export function isSafeSegment(value) {
+    return (value !== '' &&
+        value !== '.' &&
+        value !== '..' &&
+        !value.includes('/') &&
+        !value.includes('\\') &&
+        !value.includes('\0'));
+}
+/**
+ * `rel` resolved under `root`, or `null` when it would land anywhere else —
+ * including an absolute path, an empty path, and the classic sibling
+ * (`/tmp/rig` must not contain `/tmp/rig-evil`).
+ *
+ * This is the containment behind every write an upgrade makes. It is deliberate
+ * belt-and-braces: the values that build `rel` are validated where they are
+ * parsed, and this refuses the write anyway.
+ */
+export function resolveInside(root, rel) {
+    if (rel === '' || path.isAbsolute(rel))
+        return null;
+    const segments = rel.split('/');
+    // Refused, not repaired: joining an absolute or `..`-bearing path onto the
+    // root would silently turn hostile input into a plausible-looking write.
+    if (segments.some((segment) => !isSafeSegment(segment)))
+        return null;
+    const base = path.resolve(root);
+    const dest = path.resolve(base, ...segments);
+    if (dest === base)
+        return null;
+    return dest.startsWith(base + path.sep) ? dest : null;
+}

package/packages/cli/dist/lib/substitute.js

@@ -5,6 +5,38 @@ export function substituteContent(content, ctx) {
         .replaceAll('__REGION__', ctx.region)
         .replaceAll('@app/', `@${ctx.projectScope}/`);
 }
+/**
+ * The inverse of {@link substituteContent}, used **only to recognise** an
+ * installed file as a released version of its template: the released bytes
+ * carry tokens, the installed bytes carry the project's own name, and without
+ * this every token-carrying file (the kill switch, the loop skill, `CLAUDE.md`)
+ * would be a permanent conflict on every rig.
+ *
+ * 🔴 Limits, and both of them fail in the safe direction — an unrecognised file
+ * is reported and left alone, never overwritten:
+ *
+ * - `__PROJECT_SCOPE__` is not reversed. It substitutes to the same string as
+ *   `__PROJECT_NAME__`, so the two are indistinguishable after the fact; the
+ *   agent-os layer (the only layer an upgrade touches) uses neither the scope
+ *   token nor `@app/` in prose, which a template test pins.
+ * - A template that contains the project's name as a *literal* reverses into a
+ *   token that was never there. That costs nothing on its own — recognition
+ *   offers the untouched bytes as a candidate too, and those still match. It
+ *   bites only on a file carrying **both** a token and the literal, which then
+ *   reads as a conflict for that one project.
+ */
+export function detokenizeContent(content, ctx) {
+    let out = content;
+    // scope first: reversing the name first would rewrite `@name/` into
+    // `@__PROJECT_NAME__/` and the scope form could never match afterwards
+    if (ctx.projectScope !== '')
+        out = out.replaceAll(`@${ctx.projectScope}/`, '@app/');
+    if (ctx.region !== '')
+        out = out.replaceAll(ctx.region, '__REGION__');
+    if (ctx.projectName !== '')
+        out = out.replaceAll(ctx.projectName, '__PROJECT_NAME__');
+    return out;
+}
 /**
  * Files that must exist in the generated project under a dotted name, but are
  * stored un-dotted in the template because `npm publish` strips the dotted

package/packages/cli/dist/lib/targets.js

@@ -10,5 +10,19 @@ export const TARGETS = {
     },
 };
 export const TARGET_NAMES = Object.keys(TARGETS);
-/** Zero options at the personal stage: one implicit target (PLAN.md §6). */
+/**
+ * The pre-selected entry in the interactive menu, and the API-level default.
+ *
+ * 🔴 **Not the fallback for a non-interactive run.** A run with no TTY and no
+ * `--target` is *refused* (`index.ts`) — never prompt into a pipe, and never
+ * guess a whole project shape for a script that did not say. This constant is
+ * what `Enter`, an out-of-range number or an unrecognised name resolve to at the
+ * prompt (`prompts.ts`), plus what `createProject` uses when called as a library
+ * with no target.
+ *
+ * The comment this replaces said "one implicit target", which was stale from
+ * when there was one. Its first correction claimed the CLI defaults silently in
+ * CI — the opposite of what it does, in the file a maintainer would open to
+ * check exactly that.
+ */
 export const DEFAULT_TARGET = 'aws-serverless';

package/packages/cli/dist/lib/version.js

@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { templatesRoot } from '../templates.js';
+/**
+ * The version of the rig doing the installing — stamped into every manifest
+ * and printed by `--version`.
+ *
+ * Resolved through {@link templatesRoot} so there is one walk from this file
+ * to the package root, valid in the repo, the tarball and a git install alike.
+ */
+export async function packageVersion() {
+    const pkgPath = path.join(templatesRoot(), '..', 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    return pkg.version;
+}

package/scripts/prepare.mjs

@@ -5,25 +5,62 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const root = path.dirname(fileURLToPath(import.meta.url)) + '/..';
 
-// 1. Wire up the pre-commit hook when working inside the git checkout.
-if (existsSync(path.join(root, '.git'))) {
-  spawnSync('git', ['config', 'core.hooksPath', '.husky'], { cwd: root, stdio: 'inherit' });
+/**
+ * The environment `git config` runs under, minus anything that could point it
+ * at another repository's config file.
+ *
+ * This script runs from `pnpm install`, and a pre-commit hook can reach an
+ * install — a hook-started process inherits an absolute `GIT_DIR`, and
+ * `core.hooksPath` would then be written into somebody ELSE's repository.
+ *
+ * ⚠ The canonical list lives in `packages/cli/src/lib/git-env.ts` and this is a
+ * deliberate second copy, because `prepare` step 1 runs *before* step 2 builds
+ * the TypeScript that would make it importable. The subset is not a smaller
+ * opinion about that list: `git config --local` resolves its target file only
+ * through `GIT_DIR`/`GIT_COMMON_DIR`, and `GIT_CONFIG` names a config file
+ * outright. `GIT_WORK_TREE` and `GIT_INDEX_FILE` cannot move it, so stripping
+ * them here would be noise.
+ *
+ * Exported so the behaviour is testable — importing this module must not build
+ * anything, hence the entry-point guard at the bottom.
+ */
+export const gitConfigEnv = (env = process.env) => {
+  const sanitised = { ...env };
+  for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_CONFIG']) delete sanitised[key];
+  return sanitised;
+};
+
+function main() {
+  // 1. Wire up the pre-commit hook when working inside the git checkout.
+  if (existsSync(path.join(root, '.git'))) {
+    spawnSync('git', ['config', 'core.hooksPath', '.husky'], {
+      cwd: root,
+      env: gitConfigEnv(),
+      stdio: 'inherit',
+    });
+  }
+
+  // 2. Build the CLI so the `bin` entry exists (required for git/tarball installs).
+  const require = createRequire(import.meta.url);
+  const tscPath = path.join(
+    path.dirname(require.resolve('typescript/package.json')),
+    'lib',
+    'tsc.js',
+  );
+  const result = spawnSync(
+    process.execPath,
+    [tscPath, '-p', path.join(root, 'packages/cli/tsconfig.build.json')],
+    { cwd: root, stdio: 'inherit' },
+  );
+  process.exit(result.status ?? 1);
 }
 
-// 2. Build the CLI so the `bin` entry exists (required for git/tarball installs).
-const require = createRequire(import.meta.url);
-const tscPath = path.join(
-  path.dirname(require.resolve('typescript/package.json')),
-  'lib',
-  'tsc.js',
-);
-const result = spawnSync(
-  process.execPath,
-  [tscPath, '-p', path.join(root, 'packages/cli/tsconfig.build.json')],
-  { cwd: root, stdio: 'inherit' },
-);
-process.exit(result.status ?? 1);
+// Run only when executed, never when imported: a test that imports this module
+// to check one exported function must not trigger a build or touch git config.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/templates/agent-os/init/CLAUDE.md

@@ -20,8 +20,10 @@ wrong.
 .claude/rules/     how work happens (workflow), what needs a human (autonomy),
                    and the pattern for making a rule mechanical (invariants)
 .claude/hooks/     the checks that refuse a violation at the tool layer
-.claude/agents/    the review gates: test-writer, code-reviewer, security-scanner
-.claude/skills/    the drivers: loop, pr-ship, worktree-task, new-invariant
+.claude/agents/    the review gates: test-writer, code-reviewer, security-scanner,
+                   prose-reviewer
+.claude/skills/    the drivers: loop, pr-ship, worktree-task, new-invariant,
+                   check-premises
 .claude/scripts/   the queue adapter, the preflight, the out-of-band sweeps
 ```
 
@@ -51,9 +53,13 @@ it a hook via the `new-invariant` skill.
   `.claude/rules/workflow.md` ("Branches and commits", "PR flow"). When another
   session may touch this repo at the same time, the branch lives in its own
   worktree — the `worktree-task` skill has the lifecycle and the cleanup.
-- **Gates.** `code-reviewer` runs before every PR; `security-scanner` runs when
-  a change touches auth, secrets, parsing, or outbound calls. Blocking findings
-  are resolved, not argued with. The `pr-ship` skill drives the gate.
+- **Gates.** `code-reviewer` before every PR; `security-scanner` when a change
+  touches auth, secrets, parsing, or outbound calls; `prose-reviewer` when it
+  touches the documents that instruct agents — rules, skills, agent specs, this
+  file, the README. Blocking findings are resolved, not argued with, and the
+  `pr-ship` skill drives the fan-out. **No hook launches them** — a gate here is
+  a session following a written rule, so "the gate ran" is a claim, not a
+  guarantee. That is the honest reading of every gate in this file.
 - **Enforcement is mechanical.** `block-no-verify` refuses pre-commit bypasses;
   `guard-bash` refuses the "Never" tier — force-pushing a shared branch, a
   production deploy, a filesystem wipe — and carries the kill switch;

package/templates/agent-os/universal/.claude/agents/code-reviewer.md

@@ -21,6 +21,21 @@ references, and you classify every finding as **blocking** or **advisory**.
 5. **Autonomy breaches** — Tier-2 territory (schema, auth, new dependency,
    public API) entered without a recorded decision. See
    `.claude/rules/autonomy.md`.
+6. **Contradicts the item it claims to implement** — the change does something
+   the queue item did not ask for, drops a stated requirement, or quietly
+   re-aims the task into an adjacent one. Read the item first, then the diff.
+   **Report the contradiction; never reconcile the two yourself** by deciding
+   which one "must have been meant" — that is the author's call, and a reviewer
+   who makes it silently turns a visible mismatch into an invisible one. A
+   change that is well-built and not the change that was asked for is the one
+   failure the rest of this checklist cannot see.
+
+   **If the item was not handed to you, say so and stop there.** Do not
+   reconstruct it from the branch name or the PR description: those are written
+   by whoever opened the PR — including the run being reviewed — and this
+   rulebook already refuses that evidence elsewhere (`.claude/rules/autonomy.md`).
+   "Item not supplied, item 6 not checked" is a useful line in a report; a
+   guess dressed as a verdict is worse than the silence it replaces.
 
 ## Advisory findings
 

package/templates/agent-os/universal/.claude/agents/prose-reviewer.md

@@ -0,0 +1,104 @@
+---
+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.
+tools: Read, Grep, Glob, Bash
+---
+
+In this project the prose **is** the implementation. A rule file is what an agent
+reads before it acts; a skill is a procedure; `CLAUDE.md` is the map. When one of
+them says something untrue, nothing fails — the next session simply acts on it,
+confidently, and the failure surfaces somewhere unrelated hours later.
+
+You review that layer the way `code-reviewer` reviews code: findings with
+`file:line`, each classified **BLOCKER** or **advisory**, and no fixes. You do
+not edit anything.
+
+## 🔴 The boundary — read this before the checklist
+
+**You are not a literary editor.** Wording, voice, rhythm, repetition, a
+paragraph that runs long, a heading you would have phrased differently: none of
+these is a finding. Prose that is merely clumsy is **not a finding** and must not
+appear in your report, not even as advisory. Every one of them you report costs
+the next reader the attention that should have gone to the ones that matter, and
+a gate that fires on taste gets ignored, then removed.
+
+You have exactly one question: **would a competent agent, acting on this text,
+do the wrong thing?** If no, it is not yours.
+
+Style in this layer is not forbidden ground, it is simply not yours: it lands in
+`code-reviewer`'s advisory bucket like any other readability note. Say nothing
+about it here, so the two gates never file competing opinions on one paragraph.
+
+## Checklist (blocking findings)
+
+1. **An overstated claim of enforcement.** The text says something is refused,
+   blocked, guaranteed or verified, and the mechanism behind it does not do that
+   — or does not exist. Read the hook, the script, the CI job, and quote what it
+   actually does. This is the most expensive failure in the layer: a rule trusted
+   past its reach is worse than no rule, because it stops anyone from looking.
+2. **A dead reference.** A file, hook, script, agent, skill, section or command
+   that is named but no longer exists, or has been renamed. Check it resolves —
+   a path is cheap to verify and a reader who hits a missing file learns to
+   distrust every other pointer in the document.
+3. **Two rules that contradict each other.** Same subject, incompatible
+   instructions, in different files or in different sections of one. Report both
+   locations and say which reading a session would most likely take. Do **not**
+   pick the winner: the resolution belongs in the rules, not in your report.
+4. **A stated limit that has gone stale — in either direction.** A guard that
+   lists limits it no longer has understates itself and invites work nobody
+   needs; one whose limits were never written, or were written before its last
+   two bypasses, sells cover it does not have. Both are blocking, and both are
+   found the same way: read the mechanism, then read what the text claims about
+   it.
+5. **Domain that must not travel.** In a layer meant to be neutral: a provider or
+   vendor name, a host-specific absolute path, a tracker key, a company or
+   product name, credentials or personal data in an example. State which layer
+   the file belongs to and why the mention breaks it.
+
+   🔴 **A seam built to name a vendor is not a leak.** An adapter, a driver, a
+   provider-specific module — its whole job is to name the thing it adapts, and
+   so is the documentation of it. The finding is a vendor name in text that
+   claims to be neutral, not a vendor name anywhere in a neutral directory.
+   Check what the file is for before reporting it; this is the item most likely
+   to fire on deliberate, tested code.
+
+## Advisory findings
+
+An instruction that is genuinely ambiguous — two readings that lead to different
+actions, where you cannot tell which was meant. A rule with no stated reason,
+where the reason is not obvious and the rule is the kind that gets deleted by
+whoever inherits it. A document that has grown to where the load-bearing part is
+no longer findable.
+
+That is the whole advisory list, on purpose. If a note does not fit one of those
+three, it belongs in your head, not in the report.
+
+## How you work
+
+- **Diff first** (`git diff`, `git log`), then read the surrounding document —
+  a claim is only judgeable in the context that qualifies it. Review what
+  changed, not the whole rulebook.
+- **Verify against the mechanism, never against your memory of it.** Every
+  blocking finding of type 1, 2 or 4 requires you to have opened the hook, the
+  script or the workflow file and quoted the line. A finding you could not check
+  is reported as unverified, or not at all.
+- **Quote the checklist item** each blocking finding violates, and give the
+  `file:line` of both the text and the mechanism that contradicts it.
+- **"No blocking findings" is a valid and useful verdict.** Say it plainly when
+  it is true; a gate that always finds something teaches everyone to discount it.
+
+## What you cannot see, stated so nobody relies on it
+
+🔴 **Nothing launches you.** No hook fires this review; a session reads a rule
+and decides to. So a change that skipped this gate and a change that passed it
+look identical afterwards, and any text — including this file — that says this
+review "runs" is describing a convention, not a mechanism. Report a claim of
+enforcement that rests on you the same way you would report any other: as an
+overstatement, item 1, including when the file making it is a rulebook you are
+named in.
+
+You read text and the mechanisms it names. You cannot tell whether a rule is
+*worth having*, whether the process it describes is the right one, or whether a
+claim about the world outside this repository is true. Those are the owner's
+questions, and answering them from this seat would be exactly the overreach
+item 1 exists to catch.

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

@@ -25,9 +25,29 @@ function main() {
   if (input.stop_hook_active) return 0;
 
   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
+    // question — "is the tree clean?" — would then be answered about a
+    // different repository entirely: gated on somebody else's uncommitted
+    // work, or waved through despite its own.
+    //
+    // Four of the eight variables that can relocate a repository, because
+    // these are the four git itself hands its hooks — and this file ships into
+    // generated projects, so it cannot import the canonical list from the
+    // generator. A shorter list that says why it is shorter beats a copy that
+    // silently drifts.
+    //
+    // 🔴 Limit: only THIS command is sanitised. The Definition-of-Done checks
+    // below run with the environment as given, because they are the project's
+    // own commands and their environment is the project's business.
+    const env = { ...process.env };
+    for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR']) {
+      delete env[key];
+    }
     const status = execSync('git status --porcelain', {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
+      env,
     });
     if (status.trim() === '') return 0;
   } catch {

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

@@ -51,6 +51,10 @@ travels one path to merge, in this order:
    - the `code-reviewer` agent **always**;
    - `security-scanner` when it touches auth, secrets/configuration, input
      parsing, file handling, or outbound calls;
+   - `prose-reviewer` when it touches the documents that instruct agents — a
+     rule file, a skill, an agent spec, `CLAUDE.md`, the README. In this layer
+     the prose *is* the implementation, and it fails the same way code does:
+     silently, in the direction of false confidence;
    - an infrastructure review when it touches infrastructure (the stack layer
      names the reviewing agent for the target).
 

package/templates/agent-os/universal/.claude/scripts/detect-missed-gate.mjs

@@ -109,8 +109,21 @@ export const parseElevatedPaths = (markdown) => {
  * in — EXCEPT the rulebook itself. Declaring `.claude/` as elevated was a no-op
  * for every `.md` under it, so a merged PR rewriting the autonomy tiers or the
  * Never list passed the gate meant to catch exactly that.
+ *
+ * 🔴 A rulebook is recognised **wherever it sits**, not only at the repository
+ * root. The root-anchored version of this test was true of a project this tool
+ * generates and false of the tool itself: a generator keeps rulebooks under
+ * `templates/`, every one of them is a `.md`, and all of them were dropped as
+ * inert — so two merges that changed agent specs, skills and an init map were
+ * reported clean, while a third that also touched a `.mjs` was caught for that
+ * reason alone. Any repository that vendors, templates or nests a rig has the
+ * same shape.
  */
-const isRulebook = (path) => path === 'CLAUDE.md' || path.startsWith('.claude/');
+const isRulebook = (path) =>
+  path === 'CLAUDE.md' ||
+  path.endsWith('/CLAUDE.md') ||
+  path.startsWith('.claude/') ||
+  path.includes('/.claude/');
 
 const isInert = (path) =>
   !isRulebook(path) &&
@@ -149,7 +162,16 @@ export const elevatedPathsIn = (files = [], elevatedPaths = []) => {
 // reads 100 PR bodies, so a crafted set costs minutes of CPU on a scheduled job
 // that reports nothing when it is killed.
 const REVIEWERS = /\b(code-reviewer|security-scanner|[a-z][a-z0-9-]{0,48}-reviewer)\b/i;
-const VERDICT = /\b(clean|passed|pass|approved|no blocking|green)\b/i;
+// SHIP and HOLD are what `pr-ship` actually emits, and their absence here meant
+// a PR body recording a real verdict registered as no evidence at all — so the
+// weaker "someone says a gate ran, go check" observation never fired on this
+// rulebook's own PRs, only on bodies phrased in somebody else's vocabulary.
+//
+// 🔴 Widening this list widens what is *observed*, never what is *permitted*.
+// `body-claim` is still a finding; only the `human-review` label suppresses one.
+// Adding a word must never move a PR from "reported" to "clean" — if a change
+// here could do that, it is the wrong change.
+const VERDICT = /\b(clean|passed|pass|approved|no blocking|green|ship|hold)\b/i;
 
 /**
  * 🔴 The body is NOT authority, and this is the security core of the file.
@@ -284,8 +306,14 @@ export const classifyPr = (pr, { elevatedPaths = [], epoch = null } = {}) => {
           'claims a reviewer verdict, but the body is written by the author — it is ' +
           'not verifiable after the fact. Only the human-review label, which needs ' +
           'repository permission, records the gate. Confirm the gate ran and label it.'
-        : `merged touching ${elevatedFiles.length} elevated-tier path(s) with ` +
-          'no human-review label and no reviewer verdict recorded anywhere',
+        : // "anywhere" claimed more than this sweep can see: it reads the label
+          // and scans the body for a reviewer name next to a passing word. A
+          // verdict phrased any other way — or recorded in a review thread, a
+          // journal, a chat — is invisible here, and saying otherwise taught the
+          // reader to treat absence of evidence as evidence of absence.
+          `merged touching ${elevatedFiles.length} elevated-tier path(s) with ` +
+          'no human-review label, and no reviewer verdict this sweep could ' +
+          'recognise in the body',
   };
 };
 

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

@@ -32,8 +32,41 @@ export const UNCHECKED = [
   'a budget is declared for this run, and it is written down somewhere the run can re-read',
 ];
 
+/**
+ * The environment loses the variables that locate a git repository.
+ *
+ * A process started under a git hook inherits an absolute `GIT_DIR`, and every
+ * probe below would then answer about a DIFFERENT repository — `fetch` writing
+ * into it, `rev-parse` comparing its refs. This file's whole point is that an
+ * `unknown` never becomes a `pass`; a confident answer about the wrong repo is
+ * worse than either.
+ *
+ * 🔴 Limit: only repository *location* is stripped. `gh` inherits the rest of
+ * the environment on purpose — its credentials live there.
+ */
+export const withoutGitLocation = (env = process.env) => {
+  const sanitised = { ...env };
+  for (const key of [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_NAMESPACE',
+    'GIT_PREFIX',
+  ]) {
+    delete sanitised[key];
+  }
+  return sanitised;
+};
+
 const run = (command, args) =>
-  execFileSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: withoutGitLocation(),
+  }).trim();
 
 /** The kill switch must be absent before a run starts. */
 export const checkKillSwitch = () => {