create-agent-rig 0.6.2 → 0.7.1

package/templates/agent-os/universal/.agents/skills/pr-ship/SKILL.md

@@ -35,7 +35,7 @@ blockers.
      flow, and this gate with it, begins when the project has a remote
      (`workflow.md`, "PR flow"). The refusal exists because two rounds were once counted ahead of a
      commit pre-commit then refused, so the counter and the fan-out's verdicts
-     named a head that never shipped (AR-141) — pinned in the generator's
+     named a head that never shipped — pinned in the generator's
      `test/template/gate-rounds.test.ts` — absent in a generated rig — ›
      "refuses to count a round on a dirty tree, and counts nothing".
 
@@ -57,26 +57,90 @@ blockers.
    confidently-wrong reviews. Everything below is scoped to this diff.
 
    Then, on the fetched ref, ask whether the branch is still the branch the run
-   took up (AR-134):
+   took up. **Two paths, and you state which one — the command infers neither.**
+   A branch that is a queue item's take-up:
 
    ```sh
    node .claude/scripts/revalidate.mjs --point BEFORE_PR --ticket <item-id> --base origin/<default>
    ```
 
-   It compares two sources and names each one that moved: the item's `updatedAt`
-   against the take-up snapshot `next` recorded (`task:updatedAt`), and what the
-   default branch changed since this branch forked, on the paths the branch
-   touches or a `check-premises` record in this run cited (`main:<path>`). It
+   Owner-directed work or a hotfix that has **no item** — the case step 4 below
+   already tells you to declare to the reviewers:
+
+   ```sh
+   node .claude/scripts/revalidate.mjs --point BEFORE_PR --owner-directed --base origin/<default>
+   ```
+
+   🔴 **The second path is not a lighter checkpoint, and it is never a skip.**
+   It runs the same `main:<path>` comparison and holds on the same exit 2; what
+   it drops is the claim comparison, because work with no item has no claim to
+   compare. It resolves no queue config, so it reaches no tracker and needs no
+   credentials. Passing both flags, or neither, is exit 1.
+
+   **Four refusals** — exit 1, nothing journalled — keep it from being the way
+   around a claim or revalidation failure. It is refused when this run carries
+   an **unresolved revalidation hold** (what the ticketed path writes when it
+   holds or answers `UNVERIFIABLE`), when this run **declares a take-up**, when
+   the branch **touches a tracked `.rig/claims/*.json`** in any direction —
+   added, modified, removed or renamed — and at `BEFORE_CLOSE`. So re-running a
+   held ticketed call in this mode does not get past it: resolve the hold with
+   `outcome` instead.
+
+   ⚠ **What those refusals do not cover**, because a governance mode is trusted
+   exactly as far as it is described:
+
+   - **With no `RIG_RUN_DIR` there is no run state to read**, so the hold and
+     take-up refusals cannot fire — and nothing is journalled. The command says
+     so on stdout and in `evidence.runState`; it is not evidence that neither
+     exists. An attended gate run is exactly this shape, so read that line.
+   - The claim refusal reads the **branch diff**, so a claim record already on
+     the default branch, or written and not committed, is not seen.
+   - **`--base` is the sole authority for the verdict here**, the claim
+     comparison that would otherwise survive a wrong base being absent. Pass
+     the fetched `origin/<default>`, not a local copy and not `HEAD`.
+   - Nothing can prove an item does not exist. The rest is your word, recorded
+     as such, with `ticket: null` and no invented id.
+
+   Pinned in the generator's `test/template/owner-directed-revalidation.test.ts`
+   (absent in a generated rig) › "refuses when this run carries an unresolved
+   revalidation hold", › "refuses when the declared run already carries a
+   take-up", › "refuses when the branch RENAMES a claim record — the case
+   --diff-filter=AM could not see" and › "says out loud that an undeclared run
+   checked neither the hold nor the take-up".
+
+   **Exit 2 here is a HOLD with the same shape as the ticketed one**, and the
+   same two-step remedy: re-read the default branch on each named path, then
+   record what the re-read concluded — `node .claude/scripts/revalidate.mjs
+   outcome --point BEFORE_PR --owner-directed --action-changed <true | false>
+   --note '…'` — and come back through step 0. The owner-directed detection
+   carries no ticket, so `--owner-directed` is how the outcome addresses it;
+   the ticketed `--ticket <item-id>` form below cannot match it and is refused.
+
+   The ticketed path runs the existing revalidation chain against the tracked, versioned
+   `.rig/claims/<item-id>.json`: the content-blind `scope` fingerprint set is
+   authoritative here, while `takeUps` / `updatedAt` remain evidence only. It
+   also names what the default branch changed since this branch forked on paths
+   the branch touches or a `check-premises` record cited (`main:<path>`). It
    journals one `revalidation` event at `point: BEFORE_PR`; **exit code 2 is a HOLD**, with one blocker per named source: re-read the item, or the default
    branch on that path, record what the re-read concluded —
    `node .claude/scripts/revalidate.mjs outcome --point BEFORE_PR --ticket <item-id> --action-changed <true | false> --note '…'`
-   — and come back through step 0. A hold with no outcome is counted by the
-   report as a re-read the run skipped. Exit 0 with
-   `unverifiable` means the task side could not be compared — no take-up
-   snapshot in this run, or no marker — and is stated in the evidence, not read
-   as a pass. Exit 1 is the command refusing (unknown point, no ticket, a base
-   that is not a revision): fix the call. Its limits are its own header's; the
-   cited-path set is a labelled assumption, not a recorded fact.
+   — and come back through step 0. **That `--ticket` form is this path's, not
+   both paths'** — the owner-directed detection carries no ticket for it to
+   name, and its own `--owner-directed` outcome is written out above. A hold
+   with no outcome, in either mode, is counted by the report as a re-read the
+   run skipped. A missing, untracked, unreadable or
+   unsupported claim is `UNVERIFIABLE`, exits 2, and stops automatic progress;
+   so is a tracker whose adapter the command cannot READ, which means the
+   question was never put rather than that the claim record is unreadable.
+   Neither is ever read as a pass. Exit 1 is the command refusing (unknown
+   point, neither mode or both, a base that is not a revision, or a queue config
+   that does not resolve — plus, on the owner-directed path, the four refusals
+   above): fix the call or the config — the message says which. Its limits are its own header's; the
+   cited-path set is a labelled assumption, not a recorded fact. Pinned in the
+   generator's `test/template/revalidate.test.ts` (absent in a generated rig) ›
+   "continues when only updatedAt moved and still reports the marker evidence"
+   and `test/template/content-blind-revalidation.test.ts` › "refuses a deleted
+   tracked claim in a fresh run without take-up markers".
 2. **Route the diff before you spend on it.** This gate always ran its most
    expensive path, so a typo fix in a README bought the same fan-out as a
    rewrite of the storage layer. The dispatcher decides which lane the change
@@ -175,9 +239,13 @@ blockers.
    **Whatever you launch, pass it the text of the queue item this branch
    implements.** A reviewer given only a diff cannot check the change against
    what was asked: a cold context has no way to know, and reconstructing it from
-   the PR description would mean trusting the run under review. If there is no
-   item — owner-directed work, a hotfix — say so when launching, and the
-   reviewer skips that check openly instead of guessing at it.
+   the PR description would mean trusting the run under review. When there is
+   no item — owner-directed work, a hotfix — launch every reviewer with the
+   words **`no item — owner-directed`** instead. That skips the item-contract
+   check, openly, and **nothing else**: the checks, the routing, the security,
+   code and prose/governance reviews, the coverage check and the DoD all still
+   run. It is one check narrower than a ticketed fan-out, not a cheaper gate,
+   and the same words are what step 1's `--owner-directed` call records.
 
    🔴 **The triggers below are lane-independent and may only ADD.** They read
    *what the code does*; the router reads *paths*, and a path cannot say that a

package/templates/agent-os/universal/.claude/hooks/block-no-verify.mjs

@@ -12,13 +12,33 @@
 // to tokenise: it owns exactly one invariant and stays readable because of it
 // (see .claude/rules/invariants.md, "One invariant per hook"). Use a file rather
 // than a heredoc, or quote the example.
-import { readHookInput } from './lib/hook-input.mjs';
+import { readHookInput, refusalText, shellCommandOf } from './lib/hook-input.mjs';
+import { SHELL_TOOLS } from '../scripts/lib/shell-tools.mjs';
 
 function main() {
   const input = readHookInput();
   if (input === null) return 0;
-  if (input.tool_name !== 'Bash') return 0;
-  const raw = String(input.tool_input?.command ?? '');
+  // One list, not a literal: this hook was launched for every shell surface
+  // and then excused itself from all but Bash, so the pre-commit gate stayed
+  // bypassable on the other one.
+  if (!SHELL_TOOLS.includes(input.tool_name)) return 0;
+  // Three outcomes, from the one shared contract (RP-80). `String(argv)` used
+  // to stand here, and it did not merely fail to read an array — it produced a
+  // plausible-looking string: `["git","commit","--no-verify"]` became
+  // `git,commit,--no-verify`, where the tokeniser below never splits on a comma,
+  // so the one flag this hook exists to refuse was silently absent. A guard that
+  // converts what it cannot read into something it can is worse than one that
+  // refuses, because it reports a check it did not perform.
+  const parsed = shellCommandOf(input);
+  if (parsed.kind === 'unreadable') {
+    process.stderr.write(`${refusalText(parsed)}\n`);
+    return 2;
+  }
+  // Positive test, not a list of the others: a member added later must not
+  // reach `raw.replace(…)` below with `undefined`, which throws, exits 1, and
+  // is read as allow.
+  if (parsed.kind !== 'string') return 0;
+  const raw = parsed.command;
 
   // Strip quoted segments first: a commit message that merely MENTIONS a
   // forbidden flag is prose, not a bypass. Only unquoted flags count.

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

@@ -74,13 +74,48 @@
 // written without thinking — not an adversary, and circumventing it is itself a
 // Never-tier violation. The layers behind it are review and CI.
 //
+// ── Which SURFACES it sees, and what that does not promise (RP-65) ───────────
+//
+// This runs for every tool named in `.claude/scripts/lib/shell-tools.mjs`, not
+// for `Bash` alone. It used to be wired under `Bash` only, and the measurement
+// that changed it is in that file: the same `--no-verify` command was blocked
+// through one tool and ran through the other, in one session.
+//
+// ⚠ Widening the matcher makes the same RULES run on both surfaces. It does not
+// make the PARSING identical: the tokeniser above is POSIX, and PowerShell's
+// quoting, escaping and separators are its own, so a command whose danger is
+// visible only after PowerShell-specific parsing can read differently here.
+//
+// ⚠ And the coarse checks are narrower than "coarse" suggests. The rules
+// match a command NAME — `git`, `gh`, `rm` — so they refuse the operation
+// only when the operation is spelled that way.
+// Measured with the brake armed: `gh pr merge …` is refused on both surfaces,
+// while `gh.exe pr merge …`, `Start-Process gh -ArgumentList …` and
+// `Remove-Item -Recurse -Force C:\` are all allowed. The first of those is
+// allowed under `Bash` too, so this is a rule-set bound rather than anything
+// the widened matcher introduced — but it is a bound, and an earlier draft of
+// this block claimed the opposite. This gap is why the file keeps a name that
+// says `bash`: a rename would promise a parity the parser does not have.
+//
 // Contract (Claude Code): JSON on stdin; exit 0 = allow, exit 2 = block, and
-// stderr is shown to the agent as the reason. Fails open on anything it cannot
-// parse — a crashed guard must never make the session unusable.
+// stderr is shown to the agent as the reason.
+//
+// Two different things happen to input this guard cannot act on, and collapsing
+// them into one sentence is the mistake `.claude/rules/invariants.md`
+// ("Refusing to inspect is a third outcome") says costs a credential either way:
+//   - NOTHING TO JUDGE -> allow. An unparseable payload, no `tool_input`, no
+//     `command`, an empty one, a tool this guard does not answer for, or a crash
+//     inside `inspect` — a guard that has nothing to look at, or that broke, must
+//     never make the session unusable.
+//   - HANDED SOMETHING IT CANNOT READ -> block. A `command` that is present in a
+//     shape this guard does not accept is refused, naming the shape expected,
+//     because allowing it would report a check that never ran.
+// The split is decided in one place for both shell guards, `lib/hook-input.mjs`.
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { brakeIsOn } from '../scripts/stop-flag.mjs';
-import { readHookInput } from './lib/hook-input.mjs';
+import { SHELL_TOOLS } from '../scripts/lib/shell-tools.mjs';
+import { readHookInput, refusalText, shellCommandOf } from './lib/hook-input.mjs';
 
 /** Branches that are shared by definition. */
 const PROTECTED_BRANCH = /^(main|master|develop|development|trunk)$/;
@@ -807,10 +842,33 @@ export const inspect = (raw, brake, depth = 0) => {
 function main() {
   const input = readHookInput();
   if (input === null) return 0;
-  if (input.tool_name !== 'Bash') return 0;
-  const commandValue = input.tool_input?.command;
-  if (typeof commandValue !== 'string') return 0;
-  const raw = commandValue;
+  // The ONE list decides which surfaces this guard answers for. Comparing a
+  // literal here is what made the widened matcher in `settings.json` cosmetic:
+  // the hook was launched for every shell tool and then excused itself from all
+  // but one, so the Never tier and the kill switch stayed bypassable on the
+  // other. Two spellings of one fact, and the one that ran was the wrong one.
+  if (!SHELL_TOOLS.includes(input.tool_name)) return 0;
+  // Three outcomes, decided in one shared place (RP-80): absent → allow, a
+  // string → inspect, present-in-a-shape-this-cannot-read → REFUSE. The last
+  // one used to be an allow, and what that cost is measured rather than
+  // asserted: on `master` at `254b25c8`, with the kill switch armed, a
+  // `command` spelled as an array of argv words returned 0 here before
+  // `brakeIsOn()` was ever consulted. Pinned in hook-command-shape.test.ts
+  // (absent in a generated rig) › "refuses an unreadable command through %s
+  // while the kill switch is armed". A rule that can be stepped over by
+  // restating the same command in another container is not a rule.
+  const command = shellCommandOf(input);
+  if (command.kind === 'unreadable') {
+    process.stderr.write(`${refusalText(command)}\n`);
+    return 2;
+  }
+  // Every member except `string` leaves nothing to inspect. Stated as one
+  // POSITIVE test rather than a list of the others, so a member added later
+  // cannot fall through to `raw.trim()` — which sits outside the try below,
+  // where a throw exits 1 and the harness reads that as allow. That is the
+  // fail-open this change removes, re-entering by another door.
+  if (command.kind !== 'string') return 0;
+  const raw = command.command;
   if (!raw.trim()) return 0;
 
   try {

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

@@ -6,8 +6,8 @@
 // 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.
+// codex.test.ts (absent in a generated rig) › "$guard blocks with a neutral,
+// actionable size-limit refusal" — a downstream edit requires a local replacement test.
 import { editFragments } from './lib/edit-input.mjs';
 import { readHookInput } from './lib/hook-input.mjs';
 

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

@@ -6,8 +6,8 @@
 // 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.
+// codex.test.ts (absent in a generated rig) › "$guard blocks with a neutral,
+// actionable size-limit refusal" — a downstream edit requires a local replacement test.
 import { editFragments } from './lib/edit-input.mjs';
 import { readHookInput } from './lib/hook-input.mjs';
 

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

@@ -53,3 +53,112 @@ export const readHookInput = () => {
     return null;
   }
 };
+
+/**
+ * ── The shape of a shell command, for the Never-tier SHELL guards (RP-80) ───
+ *
+ * One place, for the two guards that read `tool_input.command` on a shell tool —
+ * `guard-bash` and `block-no-verify`. It is deliberately NOT a repository-wide
+ * ruling on the word `command`: `guard-secret-file` reads an `apply_patch`
+ * `command` that is a **list of strings**, which is exactly the shape this
+ * module classifies as unreadable, and it is right to — the reasoning is in
+ * `docs/decisions/codex-adapter.md`. Routing a third guard through here without
+ * checking which shape its tool actually sends would start refusing input
+ * another guard exists to read.
+ *
+ * `.claude/rules/invariants.md` ("Refusing to inspect is a third outcome, not a
+ * match and not an error") draws the line these guards need:
+ *
+ * - **absent** — nothing to judge, so the guard fails OPEN. A `Write` with no
+ *   content and a shell tool with no `command` are the same case.
+ * - **`string`** — the guard inspects it as it always did.
+ * - **present and unreadable** — the guard was handed something and can tell
+ *   that it cannot read it. That is a REFUSAL: block, name the shape expected,
+ *   and say to resend in that shape.
+ *
+ * 🔴 Getting that last line backwards costs the whole rule set. Measured on
+ * `master` at `254b25c8`: a payload whose `command` was `["gh","pr","merge","1"]`
+ * exited 0 from `guard-bash` **with the kill switch armed** — the brake was
+ * never consulted, because the guard had already excused itself. `block-no-verify`
+ * had the same hole by another road: `String(argv)` comma-joins, and its
+ * tokeniser never splits on a comma, so `--no-verify` became invisible rather
+ * than unreadable.
+ *
+ * 🔴 The remedy is carried as a FIELD beside the reason, not inferred from the
+ * reason's wording by whoever prints it — `invariants.md` again. A remedy
+ * chosen by pattern-matching a sentence is wrong the day somebody rewords the
+ * sentence, in every copy at once. And it is deliberately NOT "split the change
+ * and retry": that advice belongs to a crossed BOUND, where a smaller input
+ * really does fit. Nothing about splitting changes a container's shape, so
+ * offering it here would turn a refusal into a loop.
+ *
+ * Bounded work, because a fail-open guard is a total bypass if any input can
+ * make it spin or throw: a fixed number of `typeof` tests and one lookup. The
+ * offending value is NEVER serialised into the message — only its shape word —
+ * so an enormous or cyclic `command` costs nothing and leaks nothing.
+ *
+ * Limits, stated rather than implied:
+ * - It reads `tool_input.command`. A surface that names its command field
+ *   differently is not seen at all, and that is the same blind spot the whole
+ *   list in `.claude/scripts/lib/shell-tools.mjs` has: harness → guard is
+ *   guarded by nobody.
+ * - `absent` covers `null` as well as `undefined`, on both `tool_input` and
+ *   `command`. A key explicitly set to null carries no command to read, and
+ *   refusing it would fire on payloads that mean "no command".
+ * - An empty or whitespace-only string is READABLE and allowed. It is a
+ *   command that does nothing, not a shape the guard failed to parse.
+ * Pinned in hook-command-shape.test.ts (absent in a generated rig) ›
+ * "refuses an unreadable command through %s while the kill switch is armed"
+ * and › "allows an ABSENT command through %s".
+ */
+
+/** The shape word for a value, bounded: never the value itself. */
+const shapeOf = (value) => {
+  if (Array.isArray(value)) return 'an array';
+  const type = typeof value;
+  return type === 'object' ? 'an object' : `a ${type}`;
+};
+
+/**
+ * What a shell guard was handed, as one of three outcomes.
+ *
+ * @returns {{kind:'absent'}
+ *          |{kind:'string', command:string}
+ *          |{kind:'unreadable', reason:string, remedy:string}}
+ */
+export const shellCommandOf = (input) => {
+  const toolInput = input?.tool_input;
+  if (toolInput === undefined || toolInput === null) return { kind: 'absent' };
+  if (typeof toolInput !== 'object' || Array.isArray(toolInput)) {
+    return unreadable('tool_input', shapeOf(toolInput), 'an object');
+  }
+  const command = toolInput.command;
+  if (command === undefined || command === null) return { kind: 'absent' };
+  if (typeof command !== 'string') {
+    return unreadable('tool_input.command', shapeOf(command), 'a string');
+  }
+  return { kind: 'string', command };
+};
+
+const unreadable = (field, got, expected) => ({
+  kind: 'unreadable',
+  reason:
+    `BLOCKED — ${field} is present as ${got}, and this guard reads ${expected}. ` +
+    'An input it cannot read is refused, never allowed: the Never-tier rules and ' +
+    'the kill switch are decided by reading the command, so allowing what was ' +
+    'not read would report a check that did not happen ' +
+    '(.claude/rules/invariants.md, "Refusing to inspect is a third outcome").',
+  remedy: `Resend the call with ${field} as ${expected}.`,
+});
+
+/**
+ * One refusal, one wording — so two guards cannot drift apart in what they say.
+ *
+ * It answers for the `unreadable` member only. Handed anything else it returns
+ * the empty string rather than `"undefined undefined"`: a guard that printed
+ * that would be reporting a refusal it cannot explain, and the caller could not
+ * act on it. The call sites below never do this today; the guard is here so a
+ * later one cannot introduce it silently.
+ */
+export const refusalText = (refusal) =>
+  refusal?.kind === 'unreadable' ? `${refusal.reason} ${refusal.remedy}` : '';

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

@@ -223,6 +223,25 @@ an artifact may cite the generator's upstream tests, which are absent locally,
 only when the pointer says they are absent and `.claude/.rig-manifest.json`
 proves the current artifact's hash matches the installed manifest.
 
+**In the generator, part of that is mechanical.** A citation there is a
+test-file name followed by `›` and a quoted test name, and the generator's
+`test/template/evidence-pointers.test.ts` (absent in a generated rig) resolves
+the citations it reads: › "names a test file this repository still has" and ›
+"quotes a test name that file still declares" go red when a target is renamed
+or a test retitled, and › "says so when the test it names is one a generated
+project never receives" goes red when a pointer into the generator's suite
+carries no word that the reader does not have it. The wording that satisfies
+the last one is `(absent in a generated rig)` beside the pointer, or the
+one-line disclosure nine scripts here open with — a phrase naming the generator
+is not enough, because it tells the reader where the test lives and nothing
+about whether they have it.
+
+⚠ **"the citations it reads" is not all of them**, and the test's own header
+states where the edges are: it looks only at the tree that ships into a rig,
+and it reads a citation's names from the line the file is named on and the two
+after it. A green run means no citation it read has gone dead — not that every
+pointer in the generator was verified.
+
 A manifest-backed upgrade remains an inherited, generator-owned artifact even
 though the upgrade diff changes its bytes. The exception applies **only while the
 manifest hash matches**. A hash mismatch, missing manifest, or no evidence ends