create-agent-rig 0.4.0 → 0.6.0

package/templates/agent-os/universal/.agents/skills/worktree-task/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: worktree-task
+description: Start and finish a task in its own git worktree — creation off the remote default branch, and the full cleanup after the merge. Use at the start of every implementation task and after every merge, and whenever two sessions might touch this repo at once.
+allowed-tools: Bash, Read
+---
+
+# Worktree task lifecycle
+
+`.claude/rules/workflow.md` says **one task, one branch**. A worktree is how
+that rule survives a second session: two branches checked out at once, in two
+directories, with one `.git`. Without it, an unattended run and a hand-driven
+session share a working tree and overwrite each other's edits.
+
+**Use one when** anything else may touch this repo while you work — an
+unattended `loop` run, a colleague, a second Claude session. A single attended
+session on a quiet repo can just use a branch; the discipline that is never
+optional is the branch, not the worktree.
+
+## Start
+
+```bash
+cd "$(git rev-parse --show-toplevel)"   # ALWAYS anchor cwd first — see gotcha 1
+git fetch origin
+git worktree add -b <type>/<slug> .claude/worktrees/<slug> origin/HEAD
+git worktree list                       # verify the path is DIRECTLY under .claude/worktrees/
+```
+
+- **Branch off the remote default branch**, never a local copy — a stale local
+  default is how a task gets built on code that was replaced last week
+  (`.claude/rules/autonomy.md`, "Session staleness"). If `origin/HEAD` is not
+  set locally, name the branch explicitly: `origin/<default-branch>`.
+- **Branch name: `<type>/<slug>`**, type one of `feat|fix|docs|chore|refactor`.
+  If the project's queue gives work an id, the branch carries it —
+  `feat/<id>-<slug>` — because the branch name is often the only thread between
+  a queue item and its code. Work with no queue item keeps the plain form: **do
+  not invent an id.**
+- If tests will run there, install inside the worktree first. A worktree gets a
+  fresh, empty `node_modules`; a missing install fails as a confusing
+  module-resolution error rather than as "you forgot to install".
+
+## Finish (after the PR is merged)
+
+```bash
+cd "$(git -C <repo root> rev-parse --show-toplevel)"   # cd OUT of the worktree first — gotcha 2
+git worktree remove .claude/worktrees/<slug> --force
+git worktree prune
+git branch -D <type>/<slug>
+git push origin --delete <type>/<slug>    # if the merge did not already delete it
+rm -rf .claude/worktrees/<slug>           # only if `remove` left the directory behind
+```
+
+Add `.claude/worktrees/` to `.gitignore` once, so a live worktree never shows
+up as untracked noise in every `git status`.
+
+## Gotchas
+
+1. **A stale cwd creates worktrees inside dead paths.** If your shell sits in a
+   directory that has been removed (typically the *previous* task's worktree), a
+   relative `git worktree add .claude/worktrees/x` recreates the dead path and
+   nests the new worktree inside it. Always `cd` to the repo root by an
+   **absolute** path first, and verify with `git worktree list` afterwards.
+2. **`git worktree remove` fails while your shell is inside it** — or while a
+   watcher or install still holds a handle on `node_modules`. `cd` out first. If
+   the directory survives `remove --force`, run `git worktree prune` (the
+   metadata is then clean) and delete the leftover directory; retry later if it
+   is still busy.
+3. **Never touch a worktree you did not create.** Concurrent sessions make
+   worktrees appear and vanish mid-task. Removing another session's worktree
+   destroys unmerged work — and it is indistinguishable, afterwards, from that
+   session never having done the work.
+4. **One worktree per task.** Do not reuse a finished task's worktree: its
+   branch state and its install are both stale, and the reuse is invisible in
+   the diff.

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

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: Reviews a completed change against the checklist before a PR is opened or merged. Use after any non-trivial implementation work, and always before opening a PR. Blocking findings must be resolved, not argued with.
+description: Reviews a completed change against the checklist before a PR is opened or merged. Use after any non-trivial implementation work, and always before opening a PR the decision-router puts on its `model` lane, which is everything its two cheap lanes did not claim — code, a rulebook document, an unclassifiable path, a derived artifact git does not report as drift, or anything a risk flag escalated. Blocking findings must be resolved, not argued with.
 tools: Read, Grep, Glob, Bash
 ---
 
@@ -49,3 +49,42 @@ do not block on them.
 - Quote the checklist item a blocking finding violates. If nothing blocks, say
   so explicitly — "no blocking findings" is a valid, useful verdict.
 - Do not request rewrites of working, tested code for style alone.
+
+## The verdict block
+
+Write your report for the human, then end it with **exactly one** fenced `json`
+block of this shape, and nothing after it. That block is what the calling gate
+reads; a report that never writes one is read as whatever the caller expected.
+
+```json
+{
+  "gate": "code-reviewer",
+  "verdict": "HOLD",
+  "blockers": [
+    {
+      "file": "packages/core/src/note.ts",
+      "line": 42,
+      "rule": "checklist item 2 — test integrity",
+      "note": "the failing case was deleted rather than fixed"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["diffed against origin/master", "queue item supplied"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.
+- Every blocker names the `rule` it violates. `file` and `line` travel together
+  and are both omitted when the finding has no single location.
+- A `HOLD` with an empty `blockers` list is **refused**, and so is a `SHIP`
+  carrying one: `node .claude/scripts/verdict.mjs check <report> <this gate>` is
+  what refuses them, and the shape it enforces is in
+  `.claude/scripts/lib/verdict.mjs`. The gate name is what stops your answer
+  being read as somebody else's.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.

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

@@ -50,7 +50,39 @@ about it here, so the two gates never file competing opinions on one paragraph.
    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
+5. **An unbacked behaviour claim.** A sentence asserts what a mechanism does, how
+   much something costs, or how often it happens, and **nothing backs it**: no
+   test you can name, no command output, no citation to the code. Per
+   `.claude/rules/invariants.md` ("State the limits") such a sentence must be
+   **generated** from what it describes or be a **pointer to a test** — the form is
+   `see <test file> › "<test name>"`, and the name has to be greppable in a file the
+   reader has. This is a blocker **by rule**, so you do not have to prove the claim
+   wrong; an unbacked claim about behaviour is the finding.
+
+   ⚠ A pointer into a test suite the reader's project does not carry is normally
+   item 2, not backing. There is one narrow inherited-snapshot exception from
+   `invariants.md`: a generator-authored hook may point to upstream generator
+   tests that are absent locally **only while the hook is unchanged downstream**
+   and its hook header identifies those tests as absent locally. If that hook is
+   edited downstream or appears as changed in the current diff, the exception
+   expires and the local test is yours; then an absent pointer is item 2 again.
+
+   🔴 Three things this is not. It is not item 1: that one is about enforcement the
+   mechanism does not provide, this one is about any claim with nothing behind it,
+   including a true one. It is not item 4 either, and the split is worth getting
+   right because both can reach one sentence: **item 4 is for a limit you checked
+   against the mechanism and found wrong or missing; item 5 is for a claim you did
+   not have to check, because nothing is offered as backing.** If you opened the
+   hook and it disagrees with the text, file item 4 and quote the line. If there was
+   nothing offered to open, file item 5. If you opened it and the claim was right,
+   there is no finding. One sentence, one item. And it is not an attack on rationale — "we chose X
+   because Y" needs no test. The target is a **factual assertion about behaviour**:
+   a number, a rate, a limit, a "measured" anything.
+
+   The remedy has two forms and rewording is neither: the sentence goes, or it
+   becomes a pointer. Say which you would expect, and where the test lives if one
+   exists.
+6. **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.
@@ -102,3 +134,41 @@ You read text and the mechanisms it names. You cannot tell whether a rule is
 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.
+
+## The verdict block
+
+End your report with **exactly one** fenced `json` block of this shape, and
+nothing after it. The prose above it is for the human; this block is what the
+calling gate reads.
+
+```json
+{
+  "gate": "prose-reviewer",
+  "verdict": "HOLD",
+  "blockers": [
+    {
+      "file": ".claude/rules/invariants.md",
+      "line": 118,
+      "rule": "item 5 — an unbacked behaviour claim",
+      "note": "no test named, and the hook it describes does not do this"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["opened .claude/hooks/guard-bash.mjs and quoted the line"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.
+- Every blocker names the `rule` it violates; give the `file` and `line` of the
+  text, and cite the contradicting mechanism in the `note`.
+- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:
+  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses
+  them, and the gate name is what stops your answer being read as somebody
+  else's.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.

package/templates/agent-os/universal/.claude/agents/security-scanner.md

@@ -38,3 +38,43 @@ blocking findings stop the PR until resolved.
   the smallest fix. No theoretical lectures without a code path.
 - If the change is outside your triggers, say so and return quickly — a clean
   "not security-relevant" is a valid verdict.
+
+## The verdict block
+
+End your report with **exactly one** fenced `json` block of this shape, and
+nothing after it. It is what the calling gate reads; the prose above it is for
+the human who has to fix the finding.
+
+```json
+{
+  "gate": "security-scanner",
+  "verdict": "HOLD",
+  "blockers": [
+    {
+      "file": "services/api/src/handlers/upload.ts",
+      "line": 31,
+      "rule": "unvalidated input",
+      "note": "the filename reaches the shell unescaped — attacker-controlled"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["grepped for the pattern across services/"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
+}
+```
+
+- `verdict` is `SHIP` (nothing blocking), `HOLD`, or `NOT_APPLICABLE` when the
+  change is outside your triggers — that last one is the structured form of the
+  clean "not security-relevant" answer above.
+- Every blocker names the `rule` it violates, with `file` and `line` when the
+  finding has a location and neither when it does not.
+- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:
+  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses
+  them, and the gate name is what stops your answer being read as somebody
+  else's.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.

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

@@ -9,21 +9,174 @@
 //   - stop_hook_active in the payload means we already blocked this stop once
 //     — never block again, or an agent that cannot go green spins forever;
 //   - a clean git tree stops instantly: nothing changed, nothing to gate;
-//   - fail open on any hook error — a crashed gate must not make the session
-//     unquittable.
-import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+//   - fail open on any fault of the hook's OWN — a crashed gate must not make
+//     the session unquittable. A check that ran and was killed is NOT one of
+//     those; the 🔴 block below is the rule that separates the two.
+//
+// 🔴 The budget, and the one place this gate fails CLOSED. The checks are a
+// real test suite, and it can outrun the wiring `timeout` in
+// `.claude/settings.json`. So the hook carries a budget of its own and spends
+// it BEFORE the wiring's runs out.
+//
+// The rule the whole file follows, stated once because two earlier readings of
+// it disagreed:
+//
+//   a check that did not produce a VERDICT blocks;
+//   a gate that could not START stays open.
+//
+// `spawnSync` reports a timeout and a buffer overrun the same way — an `error`
+// with `status: null` — and in both the check's result is unknown. Unmeasured
+// is not a pass. The hook's OWN faults (an unreadable payload, a config it
+// cannot use, a shell it cannot spawn) keep failing open and announcing
+// themselves, so a crashed gate still cannot make the session unquittable.
+//
+// The budget is ONE allowance for the whole suite, not a fresh one per check:
+// a per-step budget is how three checks quietly cost three times the wall
+// clock the wiring allows (`.claude/rules/invariants.md` — "an explicit total
+// budget rather than a per-step one").
+//   see hooks.test.ts › "gates the stop when a check outruns the budget — unmeasured is not a pass"
+//   see hooks.test.ts › "spends one budget across the whole suite, not a fresh one per check"
+//   see hooks.test.ts › "gives the stop gate a harness timeout its own budget finishes inside"
+//
+// ⚠ This rests on ONE assumption about the harness that nothing in this
+// repository can prove or falsify: that a hook outrunning its timeout is
+// killed, and that a killed Stop hook does not block the stop. If it is false
+// the budget is not merely inert — it becomes the only thing that would stop a
+// suite still running at the wiring timeout. It is stated rather than asserted
+// because the whole design follows from it.
+//
+// Limits, each with the test that pins it:
+//   - a check whose output outgrows the buffer is UNMEASURED, and blocks like
+//     any other unmeasured check —
+//     see hooks.test.ts › "gates the stop when a check drowns its own buffer — a pass nobody watched is not a pass"
+//   - below that buffer, output volume is not a verdict: a chatty check that
+//     passes, passes —
+//     see hooks.test.ts › "does not read a chatty passing check as a failure (the ENOBUFS false gate)"
+//   - the RIG_DOD_BUDGET_MS override may only LOWER the budget, and an
+//     override this hook did not honour is announced rather than ignored —
+//     see hooks.test.ts › "clamps a budget override that would outlive the harness, and names the budget it used"
+//   - a fail-open is announced on stderr, because a silent exit 0 and a clean
+//     pass are the same observation from outside —
+//     see hooks.test.ts › "announces a fail-open instead of returning a silent clean pass"
+//   - an ABSENT config is not a failure and says nothing; only a config that
+//     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, 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.
+//
+// The relation the gate actually needs is not "the budget is below the wiring
+// `timeout`" — it is `budget + preamble <= timeout`. The budget's clock starts
+// after node has booted, the payload has been read, `git status` has answered
+// and the config has been parsed, so a budget merely below the wiring timeout
+// still lets the whole hook outrun it. That was a real reader: 890_000 ms
+// against a 900 s wiring timeout obeys "strictly below" and restores the silent
+// kill this hook exists to remove.
+//
+// So the preamble gets a number and a leash: `git status` below is given this
+// as its own timeout, which turns the allowance from a guess into a bound.
+// Both numbers are read from this file and compared against the wiring —
+//   see hooks.test.ts › "gives the stop gate a harness timeout its own budget finishes inside"
+//   see hooks.test.ts › "bounds its own preamble: the git status call carries a timeout derived from the declared margin"
+const DEFAULT_BUDGET_MS = 600_000;
+const PREAMBLE_MARGIN_MS = 60_000;
+
+/** The gate stays open, and says so — a silent 0 is indistinguishable from clean. */
+function failOpen(reason) {
+  process.stderr.write(`[hook fail-open] ${reason}\n`);
+  return 0;
+}
+
+/**
+ * Error codes that mean the child never ran, so there is no verdict to lose.
+ * Everything else that surfaces as `result.error` — a timeout, a buffer
+ * overrun — killed a check that WAS running, and that is the unmeasured case.
+ */
+// 🔴 `E2BIG` looks like it belongs here by the letter of the rule — the exec
+// never started — and adding it would reopen the round-1 bypass: one
+// over-long entry would then fail the WHOLE suite open. It blocks instead, and
+// that is deliberate.
+const SPAWN_NEVER_STARTED = new Set(['ENOENT', 'EACCES', 'EPERM', 'EMFILE', 'ENFILE', 'ENOMEM']);
+
+/**
+ * The total budget for the whole suite, and a note when the override was not
+ * taken at face value.
+ *
+ * 🔴 The override may only LOWER the budget. Raising it past the wiring's
+ * `timeout` puts back the exact defect this hook exists to remove — the
+ * harness kills the gate before it can report, and that kill is silent.
+ * Raising the ceiling is a two-file decision (this constant and the wiring),
+ * deliberately not something one environment variable can do.
+ *
+ * An override this hook did not honour is announced, never silently dropped:
+ * an operator who set a budget and got a different one has to be able to see
+ * it. `Number.isSafeInteger` is the test rather than `isFinite`, because
+ * `spawnSync` throws on a fractional `timeout` — and a throw here would land in
+ * the backstop and open the gate completely.
+ *   see hooks.test.ts › "runs the gate on the default budget when the override is unusable, instead of not running it"
+ */
+function budgetMs(env) {
+  const raw = env.RIG_DOD_BUDGET_MS;
+  if (raw === undefined || raw === '') return { ms: DEFAULT_BUDGET_MS, notice: null };
+
+  const declared = Number(raw);
+  if (!Number.isSafeInteger(declared) || declared <= 0) {
+    return {
+      ms: DEFAULT_BUDGET_MS,
+      notice:
+        `RIG_DOD_BUDGET_MS=${raw} is not a whole number of milliseconds above zero — ` +
+        `using the default ${DEFAULT_BUDGET_MS} ms instead.`,
+    };
+  }
+  if (declared > DEFAULT_BUDGET_MS) {
+    return {
+      ms: DEFAULT_BUDGET_MS,
+      notice:
+        `RIG_DOD_BUDGET_MS=${raw} is above this gate's ceiling and was clamped to ` +
+        `${DEFAULT_BUDGET_MS} ms — the budget must expire before the Stop hook's ` +
+        `\`timeout\` in .claude/settings.json, or the gate is killed before it can report. ` +
+        `Raise both, in their own files, to raise it at all.`,
+    };
+  }
+  return { ms: declared, notice: null };
+}
 
 function main() {
   let input;
   try {
     input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0;
+  } catch (error) {
+    return failOpen(`the Stop payload could not be read: ${error.message}`);
   }
   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
@@ -31,23 +184,32 @@ function main() {
     // 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.
+    // The canonical list, imported. This file used to carry four of the eight
+    // inline, justified by "it ships into generated projects, so it cannot
+    // import the canonical list from the generator" — a reason that expired the
+    // day `.claude/scripts/git-env.mjs` started shipping into generated projects
+    // too. Both are in the same layer, one directory apart.
+    //
+    // The four it dropped were not a smaller opinion. `GIT_OBJECT_DIRECTORY`
+    // pointing anywhere but this repository's objects makes `git status` exit
+    // 128 (`fatal: bad object HEAD`) — which the catch below reads as "not a git
+    // repo" and waves through, running the whole Definition-of-Done suite
+    // against a tree it never managed to read.
     //
     // 🔴 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];
-    }
+    // `timeout` below is the preamble's own leash: this is the one call that
+    // runs before the budget's clock starts. A repository slow enough to exceed
+    // it throws into the catch and the checks run anyway — the safe direction,
+    // 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,
+      env: withoutGitLocation(),
+      timeout: PREAMBLE_MARGIN_MS,
     });
     if (status.trim() === '') return 0;
   } catch {
@@ -57,21 +219,110 @@ function main() {
   let checks;
   try {
     checks = JSON.parse(readFileSync(new URL('./dod-checks.json', import.meta.url), 'utf8'));
-  } catch {
-    return 0;
+  } catch (error) {
+    // An absent config is the documented "nothing to gate" case, not an error
+    // to announce; anything else is a config that exists and cannot be used.
+    if (error.code === 'ENOENT') return 0;
+    return failOpen(`dod-checks.json could not be read: ${error.message}`);
   }
-  if (!Array.isArray(checks) || checks.length === 0) return 0;
+  if (!Array.isArray(checks)) return failOpen('dod-checks.json is not an array of commands');
+  // Judged per ENTRY, and the two ways to get this wrong are mirror images.
+  //
+  // Refusing the whole config on one bad entry hides a FAILING check standing
+  // next to the bad one: the refusal returns 0 and the neighbour never runs.
+  // Skipping the bad entry and returning 0 when nothing usable is left hides
+  // the bad entry itself: a declared check produced no verdict and the session
+  // still ended green. Both were shipped here, one after the other, and both
+  // are closed the same way — every usable entry runs, and a skipped entry is
+  // a check with no verdict, which blocks.
+  //   see hooks.test.ts › "never lets an unusable config entry hide a failing check behind it (an empty string)"
+  //   see hooks.test.ts › "refuses the stop for an empty config entry it skipped, even though every check it could run passed"
+  //
+  // The predicate is exactly the three shapes `spawnSync` throws on, and no
+  // wider: the shell answers every other unrunnable string with 127, which is
+  // a verdict. Filtering past these three converts a real block into a skip.
+  //   see hooks.test.ts › "refuses the stop for a config it could read but cannot use, and names the file to fix"
+  const runnable = (command) =>
+    typeof command === 'string' && command !== '' && !command.includes('\0');
+  const usable = checks.filter(runnable);
+  const skipped = checks.map((command, index) => index).filter((index) => !runnable(checks[index]));
+
+  // Nothing DECLARED is the documented "nothing to gate" case. Everything
+  // declared being unusable is not the same state, and reading them as one is
+  // what let a skipped check pass for a passing suite.
+  if (checks.length === 0) return 0;
+
+  // Said UP FRONT, because the block for it comes last: a check that failed is
+  // the more useful first message, and without this line a run that stops on a
+  // failing check would never mention the entry it could not run at all.
+  //
+  // Deliberately NOT the `[hook fail-open]` marker: that marker means the gate
+  // stayed open, and this path ends in a block. One vocabulary, one meaning.
+  if (skipped.length > 0) {
+    process.stderr.write(
+      `gate-stop-dod: dod-checks.json entr${skipped.length > 1 ? 'ies' : 'y'} at index ` +
+        `${skipped.join(', ')} cannot be run as a command and will not be measured.\n`,
+    );
+  }
+
+  const budget = budgetMs(process.env);
+  if (budget.notice) process.stderr.write(`gate-stop-dod: ${budget.notice}\n`);
+  const deadline = Date.now() + budget.ms;
+
+  for (const command of usable) {
+    // A 1 ms floor rather than a branch for "the budget is already gone": the
+    // check then times out through the ordinary path, which names the command
+    // 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'],
+      timeout: Math.max(1, deadline - Date.now()),
+      // Output volume is not a verdict — below this bound. Past it the child is
+      // killed and its result is unknown, which the error branch treats as
+      // unmeasured rather than as a failure or a pass. The old 1 MB default
+      // made a chatty but PASSING suite look like a failing check.
+      maxBuffer: 64 * 1024 * 1024,
+    });
+
+    if (result.error) {
+      // 🔴 The rule this file follows, at the point where it is decided.
+      //
+      // A spawn that never started is the gate's own problem — no shell, no
+      // file descriptors — and there is no verdict to lose, so it stays open
+      // and says so.
+      if (SPAWN_NEVER_STARTED.has(result.error.code)) {
+        return failOpen(`the check \`${command}\` could not be started: ${result.error.message}`);
+      }
+      // Everything else killed a check that WAS running — a timeout, a buffer
+      // overrun, anything unrecognised. `status` is null, so the verdict is
+      // 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 (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 ` +
+              `and the Stop hook's \`timeout\` in .claude/settings.json together, in that ` +
+              `order — the budget must stay the smaller of the two).\n`
+            : `It was killed before it could report — output past the buffer is the usual ` +
+              `cause. Run it yourself to see the result.\n`) +
+          `The check's outcome is UNMEASURED, which is not a pass. ` +
+          `This gate never fires twice in a row.\n`,
+      );
+      return 2;
+    }
 
-  for (const command of checks) {
-    try {
-      execSync(command, { stdio: ['ignore', 'pipe', 'pipe'] });
-    } catch (error) {
-      const tail = String(error.stdout ?? '')
+    if (result.status !== 0) {
+      const tail = String(result.stdout ?? '')
         .split('\n')
         .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 ` +
@@ -80,7 +331,31 @@ function main() {
       return 2;
     }
   }
+
+  // Reached only when every check that COULD run passed. A skipped entry is a
+  // declared check that produced no verdict, and unmeasured is not a pass —
+  // the same rule the killed-check branch above answers to. It is reported
+  // last because a check that actually failed is the more useful message.
+  if (skipped.length > 0) {
+    const plural = skipped.length > 1;
+    process.stderr.write(
+      `STOP GATED — dod-checks.json entr${plural ? 'ies' : 'y'} at index ` +
+        `${skipped.join(', ')} cannot be run as a command, so ${plural ? 'those checks' : 'that check'} ` +
+        `produced no verdict. Every other check passed; these were never measured, ` +
+        `and unmeasured is not a pass. Fix the entr${plural ? 'ies' : 'y'} — an empty string, ` +
+        `a NUL byte or a non-string is not a command. This gate never fires twice in a row.\n`,
+    );
+    return 2;
+  }
   return 0;
 }
 
-process.exit(main());
+let code;
+try {
+  code = main();
+} catch (error) {
+  // The backstop. A gate that throws must not make the session unquittable —
+  // but it must not look clean either.
+  code = failOpen(`the gate itself threw: ${error.message}`);
+}
+process.exit(code);