create-agent-rig 0.7.1 → 0.9.0

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

@@ -26,10 +26,10 @@ import { fileURLToPath } from 'node:url';
 // cycle, because preflight is the only scripted brake check and had no test.
 import { brakeIsOn } from './stop-flag.mjs';
 import { readRevalidationContract } from './lib/claim-records.mjs';
+import { loadConfig, optionsWithPlanPath, resolveAdapter } from './queue/index.mjs';
 
 /** The items this script cannot check: judgement, or a call worth more than it saves. */
 export const UNCHECKED = [
-  'the queue is reachable through its adapter (`node .claude/scripts/queue/index.mjs next`)',
   'no stray worktree from a dead session that this run might mistake for its own',
   'a budget is declared for this run, and it is written down somewhere the run can re-read',
 ];
@@ -136,6 +136,30 @@ export const checkDetectionContract = (projectRoot) => {
   }
 };
 
+// See test/template/preflight-queue.test.ts (absent in a generated rig) ›
+// "reads exactly one adapter listing without selecting, claiming, or writing queue and run files".
+export const checkQueue = async (projectRoot) => {
+  try {
+    const configPath = join(projectRoot, '.claude', 'queue.json');
+    const config = loadConfig(configPath, { strictRead: true });
+    const adapterName = config.adapter ?? 'plan-md';
+    const adapter = await resolveAdapter(adapterName);
+    await adapter.listEligible(optionsWithPlanPath(config.options, configPath));
+    return { ok: true, detail: `queue readable through ${adapterName}` };
+  } catch (error) {
+    const diagnostic = Array.from(String(error?.message ?? error), (character) => {
+      const code = character.codePointAt(0);
+      return code < 0x20 || (code >= 0x7f && code <= 0x9f)
+        ? `\\u${code.toString(16).padStart(4, '0')}`
+        : character;
+    }).join('');
+    return {
+      ok: false,
+      detail: `could not read queue: ${diagnostic}`,
+    };
+  }
+};
+
 /** The last deploy must have concluded successfully — never start on a broken runtime. */
 export const checkLastDeploy = ({ workflow = 'deploy' } = {}) => {
   try {
@@ -157,8 +181,7 @@ export const checkLastDeploy = ({ workflow = 'deploy' } = {}) => {
 
 /**
  * STOP on any hard failure; CAUTION on anything that is not a clean pass; GO only
- * when every scripted item genuinely passed. The three unscripted items are still
- * the reader's.
+ * when every scripted item genuinely passed. Unscripted checks remain the reader's.
  *
  * `stale` and `unknown` both give CAUTION but are never merged into one word:
  * "I looked and it is stale" is actionable, "I could not look" is not, and neither
@@ -216,6 +239,7 @@ if (invokedDirectly()) {
     killSwitch: checkKillSwitch(),
     runDirNotExported: checkRunDirNotExported(),
     detectionContract: checkDetectionContract(projectRoot),
+    queue: await checkQueue(projectRoot),
     defaultBranchFresh: checkDefaultBranchFresh(),
     lastDeploy: checkLastDeploy(),
   };

package/templates/agent-os/universal/.claude/scripts/queue/gate-rounds.mjs

@@ -25,9 +25,26 @@
  * and the failure is bounded and in the generous direction. What was worth fixing is
  * the crash it came with — a fixed temp filename made the losers of that race fail
  * with `ENOENT` on rename, reporting "could not run" for a condition nothing named.
+ * Pinned by the generator's `test/template/concurrent-sessions.test.ts`
+ * (absent in a generated rig) › "eight concurrent recordGateRound calls all exit 0
+ * and leave one parseable counter between one and eight".
+ *
+ * ⚠ **And a second crash, Windows-only, measured on the same race (RP-120):** a
+ * rename over a file another process holds open is refused there with `EPERM`, for
+ * exactly as long as the handle is open — a reader's `readFileSync` is enough. Eight
+ * racing callers lost one to it in four rounds of thirty, and each loser left its
+ * temp file behind. So the rename is retried within a fixed budget
+ * (`RENAME_BUDGET_MS`: the pauses between attempts never exceed it; the rename
+ * calls themselves add their own wall time), and a loser that still cannot rename
+ * removes its temp file and reports the code and the file rather than a bare
+ * `EPERM`. That is a bounded retry, not a lock: the count can still lose an
+ * increment, and nothing waits on a holder past the budget. Pinned by the
+ * generator's `test/template/gate-rounds.test.ts` (absent in a generated rig) ›
+ * "retries the rename while another process holds the counter open, and still counts the round"
+ * and › "gives up past its budget, removes its temp file, keeps the old count, and names the code and the file".
  */
 
-import { renameSync, readFileSync, writeFileSync } from 'node:fs';
+import { renameSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { mainCheckoutRoot } from './checkout.mjs';
@@ -154,7 +171,58 @@ export const recordGateRound = ({ branch, projectRoot, roundsPath } = {}) => {
   const updated = Object.assign(Object.create(null), rounds, { [key]: next });
   const temp = `${file}.${process.pid}.tmp`;
   writeFileSync(temp, `${JSON.stringify(updated, null, 2)}\n`);
-  renameSync(temp, file);
+  replaceWithRetry(temp, file);
 
   return { rounds: next };
 };
+
+// How many times the rename is tried, and how long each retry waits.
+const RENAME_ATTEMPTS = 20;
+const RENAME_BACKOFF_MS = 10;
+/** The whole budget a caller can spend pausing on a held-open counter. */
+export const RENAME_BUDGET_MS = RENAME_ATTEMPTS * RENAME_BACKOFF_MS;
+
+const RETRIED_CODES = new Set(['EPERM', 'EBUSY']);
+
+// A synchronous pause: this module is synchronous end to end (the CLI counts a round
+// and exits), and `Atomics.wait` on a throwaway buffer is the one sleep that shape
+// allows without a spin.
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+/**
+ * Rename `temp` over `file`, retrying a Windows-style refusal within the budget.
+ *
+ * Every attempt past the last, and every failure of another kind, ends the same way:
+ * the temp file is removed so the counter's directory holds nothing but the counter,
+ * and the error names the file and the code — the CLI prints that as "could not run",
+ * which pr-ship reads as a command failure to retry, not as an exhausted cap.
+ */
+const replaceWithRetry = (temp, file) => {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      renameSync(temp, file);
+      return;
+    } catch (error) {
+      const code = error?.code ?? 'unknown error';
+      if (RETRIED_CODES.has(code) && attempt < RENAME_ATTEMPTS) {
+        pause(RENAME_BACKOFF_MS);
+        continue;
+      }
+      // The cleanup must not displace the diagnosis: a temp file that cannot be
+      // removed (held open too, on Windows) is reported beside the rename
+      // failure, and the rename failure stays the error the caller sees.
+      let cleanup = 'and the temp file was removed';
+      try {
+        rmSync(temp, { force: true });
+      } catch (removal) {
+        cleanup = `but the temp file ${temp} could not be removed (${removal?.code ?? 'unknown error'})`;
+      }
+      throw new Error(
+        `${file} could not be replaced after ${attempt} attempt${attempt === 1 ? '' : 's'} ` +
+          `(${code}): another process may be holding it open. The round was NOT counted ` +
+          `${cleanup}; run the command again.`,
+        { cause: error },
+      );
+    }
+  }
+};

package/templates/agent-os/universal/.claude/scripts/queue/index.mjs

@@ -12,7 +12,7 @@
 // defaults to `plan-md`, which is the only adapter that works in a freshly
 // generated project. An unknown adapter is a hard error, never a fallback: a loop
 // that silently reads the wrong queue is worse than one that refuses to start.
-import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { basename, dirname, join } from 'node:path';
 import {
@@ -57,11 +57,19 @@ export const COMMANDS = ['next', 'list', 'hygiene', 'gate-round', 'board'];
  * trailing comma in `queue.json` made the loop read a different queue than the one
  * configured, which is the exact failure this file's header refuses for adapters.
  */
-export const loadConfig = (configPath) => {
+export const loadConfig = (configPath, { strictRead = false } = {}) => {
   let raw;
   try {
     raw = readFileSync(configPath, 'utf8');
-  } catch {
+  } catch (error) {
+    if (
+      strictRead &&
+      (error?.code !== 'ENOENT' || lstatSync(configPath, { throwIfNoEntry: false }) !== undefined)
+    ) {
+      throw new Error(`${configPath} could not be read (${error?.code ?? 'unknown error'})`, {
+        cause: error,
+      });
+    }
     return {};
   }
   let parsed;
@@ -70,7 +78,7 @@ export const loadConfig = (configPath) => {
   } catch (error) {
     throw new Error(
       `${configPath} exists but is not valid JSON, so the configured queue cannot be ` +
-        `read: ${String(error?.message ?? error).split('\n')[0]}. Fix the file — ` +
+        'read. Fix the file — ' +
         'silently reading a different queue is worse than refusing to start.',
       { cause: error },
     );

package/templates/agent-os/universal/.claude/scripts/unattended-flag.mjs

@@ -445,6 +445,69 @@ if (invokedDirectly()) {
     process.stdout.write(removed.length === 0 ? 'no unattended flag was set\n' : `${removed.join('\n')}\n`);
     process.exit(0);
   }
-  process.stderr.write(`unknown word: ${word ?? '(none)'}. This CLI has two: on, off.\n`);
+  // 🔴 **The read-back `on` did not have, and the reason it is a subcommand
+  // rather than a line in the skill (RP-103).**
+  //
+  // `on` refuses a widening allow entry — correctly — by throwing before it
+  // writes anything, so the refusal leaves NO flag on disk. Pinned in the
+  // generator's `test/template/unattended-flag.test.ts` (absent in a generated
+  // rig) › "does not change `on`: a widening --allow still exits 1 and still
+  // writes no flag" — the claim is checkable, so it carries a pointer rather
+  // than standing on its own. And `guard-rulebook`
+  // reads "no flag" as "attended session" and does nothing. So the run that was
+  // meant to be the most constrained became the LEAST: every rulebook path
+  // editable, including the hook wiring that enforces the rule. Loud at arming
+  // (exit 1), and completely silent for the rest of the run.
+  //
+  // The asymmetry is what made it a defect rather than a rough edge: the `off`
+  // branch above ALREADY reads back, and refuses while naming the record it
+  // found. One direction of the same operation verified itself and the other
+  // did not.
+  //
+  // ⚠ **Stating the limit, because this whole file is about a mechanism being
+  // trusted further than it goes.** `verify` is mechanical where it runs; that
+  // it runs is still the `loop` skill's prose. This closes "the refusal was
+  // silent" — the run is told, in a command whose exit status is its whole
+  // output — and does NOT close "a run that ignores exit statuses ignores this
+  // one too". The hook-enforced version would need `guard-rulebook` to tell
+  // "attended" from "unattended but unarmed", and it cannot: absence of a flag
+  // is all it sees.
+  if (word === 'verify') {
+    const item = valueOf('--item');
+    if (!item || item.startsWith('--')) {
+      process.stderr.write(
+        'unattended-flag verify: --item <id> is required — verifying "some flag is armed" would pass on a stale one from a previous run\n',
+      );
+      process.exit(1);
+    }
+    const state = readUnattended(cliEnv);
+    // ⚠ `unreadable` carries `on: true` — it means "a flag is THERE and cannot be
+    // trusted", which is what `off` needs in order to refuse to clear it blindly.
+    // For a read-back it is a FAILURE, not an arming: an unreadable record
+    // authorizes nothing, and its `item` is absent, so testing only `!state.on`
+    // would fall through to the item-mismatch branch and print the wrong reason
+    // for the right refusal.
+    if (!state.on || state.unreadable) {
+      const why = state.why ? ` (${state.why})` : '';
+      process.stderr.write(
+        `unattended-flag verify: NO usable unattended flag is armed for ${item}${why}. ` +
+          'guard-rulebook reads an absent flag as an attended session and refuses nothing, so this run is ' +
+          'UNGUARDED against the rulebook — every rule, hook, skill and settings path is editable. ' +
+          'Arm it with a narrower --allow (an allow-list narrows the rulebook, never widens it) and verify again, or stop the run.\n',
+      );
+      process.exit(1);
+    }
+    if (state.item !== item) {
+      process.stderr.write(
+        `unattended-flag verify: the armed flag names ${JSON.stringify(state.item)}, not ${JSON.stringify(item)} — ` +
+          `it is a leftover from another run and does not authorize this one. This run is UNGUARDED against the rulebook. ` +
+          `Clear it with \`off\` and arm it for ${item}, or stop the run.\n`,
+      );
+      process.exit(1);
+    }
+    process.stdout.write(`${state.path ?? 'armed'}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(`unknown word: ${word ?? '(none)'}. This CLI has three: on, verify, off.\n`);
   process.exit(1);
 }

package/templates/agent-os/universal/.claude/settings.json

@@ -1,4 +1,7 @@
 {
+  "env": {
+    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-5"
+  },
   "hooks": {
     "PreToolUse": [
       {
@@ -34,6 +37,15 @@
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.mjs\""
           }
         ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-subagent-model.mjs\""
+          }
+        ]
       }
     ],
     "Stop": [
@@ -53,6 +65,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-rules.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/warn-subagent-routing.mjs\""
           }
         ]
       }

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -79,16 +79,23 @@ state-vs-queue split exists to prevent.
 node .claude/scripts/preflight.mjs
 ```
 
-Five items are scripted (kill switch absent · `RIG_RUN_DIR` not already
-exported · the versioned revalidation detection contract is supported · local
-default branch matches the remote · the last deploy concluded successfully)
+Scripted checks cover the kill switch, inherited `RIG_RUN_DIR`, the versioned
+revalidation detection contract, queue readability through its configured adapter,
+default-branch freshness, and the last deploy result,
 and the script **prints the ones it did not check, every time**. Paste the block into the journal: a checklist that
 leaves no record cannot tell you it was skipped.
 
 Verdicts: **STOP** → do not start, deal with the cause. **CAUTION** → start,
-knowing which ground is soft. **GO** → the scripted five are clean; the rest are
+knowing which ground is soft. **GO** → the scripted checks are clean; the rest are
 still yours.
 
+The queue probe reads one adapter listing without selecting or claiming an item.
+A readable empty queue passes this probe; a configuration, adapter, or queue-read
+failure produces **STOP**. See the generator's `test/template/preflight-queue.test.ts`
+(absent in a generated rig) › "reads exactly one adapter listing without selecting, claiming, or writing queue and run files",
+› "passes a readable empty queue without changing the other preflight verdict or queue state",
+and › "stops when %s cannot be read".
+
 **An `unknown` never becomes a `pass`.** A probe that could not run tells you
 nothing.
 
@@ -149,13 +156,47 @@ What a hook CAN see is a file, so the unattended signal is one:
 # at claim time, from the paths the item names (repo-relative prefixes, with
 # their trailing slash); the guard refuses every other rulebook edit while it is on
 node .claude/scripts/unattended-flag.mjs on --root "$PWD" --item <item-id> --run-dir "$RIG_RUN_DIR" --allow <prefix> [<prefix>…]
+
+# 🔴 THEN READ IT BACK, and stop the run if it is not armed. Not optional.
+node .claude/scripts/unattended-flag.mjs verify --root "$PWD" --item <item-id>
 ```
 
+🔴 **The second command is the one that makes the first one's failure
+visible, and skipping it inverts the whole mechanism.** `on` refuses an allow
+entry that *widens* the rulebook — and the refusal leaves **no flag on disk**
+(pinned in the generator's `test/template/unattended-flag.test.ts`, absent in a
+generated rig, › "does not change `on`: a widening --allow still exits 1 and
+still writes no flag"), while `guard-rulebook` reads an absent flag as an
+attended session and refuses nothing. So a run that armed with a widening entry and did not check is the
+**least** constrained run this project can produce: every rule, hook, skill and
+settings path editable, with nothing downstream saying so. The failure is loud
+for one line at claim time and silent for the rest of the session.
+
+`verify` exits non-zero when no usable flag is armed for this item — absent,
+unreadable, or naming a different item — and its message says the run is
+unguarded rather than merely that a file is missing. **A non-zero exit here ends
+the run**; it does not get retried with a wider allow-list. The natural way to
+hit this is not exotic: an item touching the queue adapter invites `--allow
+.claude/scripts/`, and that entry is refused outright. Pinned in the
+generator's `test/template/unattended-flag.test.ts` (absent in a generated rig)
+› "refuses when no flag is armed, naming the item and the unguarded rulebook"
+and › "refuses when the armed flag names a different item, naming both".
+
+⚠ **What this does not close.** `verify` is mechanical where it runs; that it
+runs is this sentence. It removes the silence, not the possibility that a run
+ignores an exit status — and the hook-enforced version is not available, because
+`guard-rulebook` cannot tell "attended" from "unattended but unarmed": absence of
+a flag is all it sees.
+
 `guard-rulebook` reads it (`.claude/rules/autonomy.md`, "Never"): with the flag
 on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under the generated
-rulebook — both harnesses' rules, skills, agents and hook wiring, plus their
-scripts, queue config and integrity manifest — is refused unless its
-path starts with an allowed prefix; the board selector is the one always-refused
+rulebook is refused unless its
+path starts with an allowed prefix. 🔴 **Which paths that covers is
+`RULEBOOK_PREFIXES` in `.claude/scripts/unattended-flag.mjs`** — read it before
+composing an allow-list, rather than working from a summary here. A summary is a
+second copy, and the one that used to sit in this sentence had gone stale against
+the set it described. One fact the set cannot carry, so it is stated: the board
+selector is the one always-refused
 exception and cannot be admitted by an allow-list. With no flag the guard does nothing. An
 item that needs a rulebook path names it here — a decision made at claim
 time, never a default — and the stop step below turns the flag off. Pinned in

package/templates/agent-os/universal/.codex/agents/code-reviewer.toml

@@ -1,4 +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 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."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = "You review changes. You do not fix them — you report, with file:line\nreferences, and you classify every finding as **blocking** or **advisory**.\n\n## Checklist (blocking findings)\n\n1. **Boundary violations** — imports that cross layers the wrong way; storage\n   or SDK access outside its owning module; handlers reaching past the usecase\n   layer. See the architecture rules in `.claude/rules/`.\n2. **Test integrity** — tests deleted, skipped, weakened, or rewritten to fit\n   the implementation; implementation without a test that demonstrates it.\n3. **Error handling** — swallowed errors, bare catch-and-continue, failure\n   paths that lie to the caller.\n4. **Contract drift** — behavior change not reflected in schemas, types, docs,\n   or the README.\n5. **Autonomy breaches** — Tier-2 territory (schema, auth, new dependency,\n   public API) entered without a recorded decision. See\n   `.claude/rules/autonomy.md`.\n6. **Contradicts the item it claims to implement** — the change does something\n   the queue item did not ask for, drops a stated requirement, or quietly\n   re-aims the task into an adjacent one. Read the item first, then the diff.\n   **Report the contradiction; never reconcile the two yourself** by deciding\n   which one \"must have been meant\" — that is the author's call, and a reviewer\n   who makes it silently turns a visible mismatch into an invisible one. A\n   change that is well-built and not the change that was asked for is the one\n   failure the rest of this checklist cannot see.\n\n   **If the item was not handed to you, say so and stop there.** Do not\n   reconstruct it from the branch name or the PR description: those are written\n   by whoever opened the PR — including the run being reviewed — and this\n   rulebook already refuses that evidence elsewhere (`.claude/rules/autonomy.md`).\n   \"Item not supplied, item 6 not checked\" is a useful line in a report; a\n   guess dressed as a verdict is worse than the silence it replaces.\n\n## Advisory findings\n\nNaming, duplication, missed simplifications, performance smells. Report them;\ndo not block on them.\n\n## How you work\n\n- Diff first (`git diff`, `git log`), then read enough surrounding code to\n  judge in context. Review what changed, not the whole repo.\n- Quote the checklist item a blocking finding violates. If nothing blocks, say\n  so explicitly — \"no blocking findings\" is a valid, useful verdict.\n- Do not request rewrites of working, tested code for style alone.\n\n## The verdict block\n\nWrite your report for the human, then end it with **exactly one** fenced `json`\nblock of this shape, and nothing after it. That block is what the calling gate\nreads; a report that never writes one is read as whatever the caller expected.\n\n```json\n{\n  \"gate\": \"code-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"packages/core/src/note.ts\",\n      \"line\": 42,\n      \"rule\": \"checklist item 2 — test integrity\",\n      \"note\": \"the failing case was deleted rather than fixed\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"diffed against origin/master\", \"queue item supplied\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.\n- Every blocker names the `rule` it violates. `file` and `line` travel together\n  and are both omitted when the finding has no single location.\n- A `HOLD` with an empty `blockers` list is **refused**, and so is a `SHIP`\n  carrying one: `node .claude/scripts/verdict.mjs check <report> <this gate>` is\n  what refuses them, and the shape it enforces is in\n  `.claude/scripts/lib/verdict.mjs`. The gate name is what stops your answer\n  being read as somebody else's.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."

package/templates/agent-os/universal/.codex/agents/prose-reviewer.toml

@@ -1,4 +1,6 @@
 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."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = "In this project the prose **is** the implementation. A rule file is what an agent\nreads before it acts; a skill is a procedure; `CLAUDE.md` is the map. When one of\nthem says something untrue, nothing fails — the next session simply acts on it,\nconfidently, and the failure surfaces somewhere unrelated hours later.\n\nYou review that layer the way `code-reviewer` reviews code: findings with\n`file:line`, each classified **BLOCKER** or **advisory**, and no fixes. You do\nnot edit anything.\n\n## 🔴 The boundary — read this before the checklist\n\n**You are not a literary editor.** Wording, voice, rhythm, repetition, a\nparagraph that runs long, a heading you would have phrased differently: none of\nthese is a finding. Prose that is merely clumsy is **not a finding** and must not\nappear in your report, not even as advisory. Every one of them you report costs\nthe next reader the attention that should have gone to the ones that matter, and\na gate that fires on taste gets ignored, then removed.\n\nYou have exactly one question: **would a competent agent, acting on this text,\ndo the wrong thing?** If no, it is not yours.\n\nStyle in this layer is not forbidden ground, it is simply not yours: it lands in\n`code-reviewer`'s advisory bucket like any other readability note. Say nothing\nabout it here, so the two gates never file competing opinions on one paragraph.\n\n## Checklist (blocking findings)\n\n1. **An overstated claim of enforcement.** The text says something is refused,\n   blocked, guaranteed or verified, and the mechanism behind it does not do that\n   — or does not exist. Read the hook, the script, the CI job, and quote what it\n   actually does. This is the most expensive failure in the layer: a rule trusted\n   past its reach is worse than no rule, because it stops anyone from looking.\n2. **A dead reference.** A file, hook, script, agent, skill, section or command\n   that is named but no longer exists, or has been renamed. Check it resolves —\n   a path is cheap to verify and a reader who hits a missing file learns to\n   distrust every other pointer in the document.\n3. **Two rules that contradict each other.** Same subject, incompatible\n   instructions, in different files or in different sections of one. Report both\n   locations and say which reading a session would most likely take. Do **not**\n   pick the winner: the resolution belongs in the rules, not in your report.\n4. **A stated limit that has gone stale — in either direction.** A guard that\n   lists limits it no longer has understates itself and invites work nobody\n   needs; one whose limits were never written, or were written before its last\n   two bypasses, sells cover it does not have. Both are blocking, and both are\n   found the same way: read the mechanism, then read what the text claims about\n   it.\n5. **An unbacked behaviour claim.** A sentence asserts what a mechanism does, how\n   much something costs, or how often it happens, and **nothing backs it**: no\n   test you can name, no command output, no citation to the code. Per\n   `.claude/rules/invariants.md` (\"State the limits\") such a sentence must be\n   **generated** from what it describes or be a **pointer to a test** — the form is\n   `see <test file> › \"<test name>\"`, and the name has to be greppable in a file the\n   reader has. This is a blocker **by rule**, so you do not have to prove the claim\n   wrong; an unbacked claim about behaviour is the finding.\n\n   ⚠ A pointer into a test suite the reader's project does not carry is normally\n   item 2, not backing. There is one narrow inherited-snapshot exception from\n   `invariants.md`: a generator-authored artifact — rules, hooks, skills,\n   scripts, or agent specs —\n   may point to upstream generator tests that are absent locally only when the\n   pointer explicitly says the suite is absent locally and\n   `.claude/.rig-manifest.json` proves the current artifact's hash matches the\n   installed manifest. A manifest-backed upgrade remains an inherited,\n   generator-owned artifact; a changed file in the upgrade diff does not alone\n   make it downstream-authored. The exception applies **only while the manifest\n   hash matches**. A hash mismatch, missing manifest, or no evidence ends the\n   exception and the local test is yours; then an absent pointer is item 2 again.\n\n   🔴 Three things this is not. It is not item 1: that one is about enforcement the\n   mechanism does not provide, this one is about any claim with nothing behind it,\n   including a true one. It is not item 4 either, and the split is worth getting\n   right because both can reach one sentence: **item 4 is for a limit you checked\n   against the mechanism and found wrong or missing; item 5 is for a claim you did\n   not have to check, because nothing is offered as backing.** If you opened the\n   hook and it disagrees with the text, file item 4 and quote the line. If there was\n   nothing offered to open, file item 5. If you opened it and the claim was right,\n   there is no finding. One sentence, one item. And it is not an attack on rationale — \"we chose X\n   because Y\" needs no test. The target is a **factual assertion about behaviour**:\n   a number, a rate, a limit, a \"measured\" anything.\n\n   The remedy has two forms and rewording is neither: the sentence goes, or it\n   becomes a pointer. Say which you would expect, and where the test lives if one\n   exists.\n6. **Domain that must not travel.** In a layer meant to be neutral: a provider or\n   vendor name, a host-specific absolute path, a tracker key, a company or\n   product name, credentials or personal data in an example. State which layer\n   the file belongs to and why the mention breaks it.\n\n   🔴 **A seam built to name a vendor is not a leak.** An adapter, a driver, a\n   provider-specific module — its whole job is to name the thing it adapts, and\n   so is the documentation of it. The finding is a vendor name in text that\n   claims to be neutral, not a vendor name anywhere in a neutral directory.\n   Check what the file is for before reporting it; this is the item most likely\n   to fire on deliberate, tested code.\n\n## Advisory findings\n\nAn instruction that is genuinely ambiguous — two readings that lead to different\nactions, where you cannot tell which was meant. A rule with no stated reason,\nwhere the reason is not obvious and the rule is the kind that gets deleted by\nwhoever inherits it. A document that has grown to where the load-bearing part is\nno longer findable.\n\nThat is the whole advisory list, on purpose. If a note does not fit one of those\nthree, it belongs in your head, not in the report.\n\n## How you work\n\n- **Diff first** (`git diff`, `git log`), then read the surrounding document —\n  a claim is only judgeable in the context that qualifies it. Review what\n  changed, not the whole rulebook.\n- **Verify against the mechanism, never against your memory of it.** Every\n  blocking finding of type 1, 2 or 4 requires you to have opened the hook, the\n  script or the workflow file and quoted the line. A finding you could not check\n  is reported as unverified, or not at all.\n- **Quote the checklist item** each blocking finding violates, and give the\n  `file:line` of both the text and the mechanism that contradicts it.\n- **\"No blocking findings\" is a valid and useful verdict.** Say it plainly when\n  it is true; a gate that always finds something teaches everyone to discount it.\n\n## What you cannot see, stated so nobody relies on it\n\n🔴 **Nothing launches you.** No hook fires this review; a session reads a rule\nand decides to. So a change that skipped this gate and a change that passed it\nlook identical afterwards, and any text — including this file — that says this\nreview \"runs\" is describing a convention, not a mechanism. Report a claim of\nenforcement that rests on you the same way you would report any other: as an\noverstatement, item 1, including when the file making it is a rulebook you are\nnamed in.\n\nYou read text and the mechanisms it names. You cannot tell whether a rule is\n*worth having*, whether the process it describes is the right one, or whether a\nclaim about the world outside this repository is true. Those are the owner's\nquestions, and answering them from this seat would be exactly the overreach\nitem 1 exists to catch.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. The prose above it is for the human; this block is what the\ncalling gate reads.\n\n```json\n{\n  \"gate\": \"prose-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \".claude/rules/invariants.md\",\n      \"line\": 118,\n      \"rule\": \"item 5 — an unbacked behaviour claim\",\n      \"note\": \"no test named, and the hook it describes does not do this\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"opened .claude/hooks/guard-bash.mjs and quoted the line\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP`, `HOLD` or `NOT_APPLICABLE` — no other word.\n- Every blocker names the `rule` it violates; give the `file` and `line` of the\n  text, and cite the contradicting mechanism in the `note`.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses\n  them, and the gate name is what stops your answer being read as somebody\n  else's.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."

package/templates/agent-os/universal/.codex/agents/security-scanner.toml

@@ -1,4 +1,6 @@
 name = "security-scanner"
 description = "Scans a change for security issues. MUST be used when a change touches authentication, authorization, secrets or configuration, input parsing, file handling, or any new outbound call. Findings gate the PR."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = "You are the security gate. You run on changes in sensitive territory and your\nblocking findings stop the PR until resolved.\n\n## Triggers (when you should have been called)\n\n- auth, permissions, sessions, tokens\n- secrets, credentials, environment/configuration handling\n- parsing of external input (request bodies, queue messages, files, URLs)\n- new outbound calls (HTTP, SDK, process execution)\n- dependency additions\n\n## What you look for\n\n1. **Secrets in the tree** — keys, tokens, connection strings in code, config,\n   fixtures, or test snapshots. Any hit is blocking.\n2. **Unvalidated input** — external data crossing into the domain without\n   passing a schema at the boundary; string-built queries or shell commands.\n3. **Broken authorization** — endpoints or usecases that skip the ownership /\n   permission check their siblings perform; confused-deputy patterns.\n4. **Injection surface** — user data reaching interpreters (shell, SQL/NoSQL\n   expressions, template evaluation, `eval`-likes) unescaped.\n5. **Leaky failure modes** — stack traces, internal ids, or secret material in\n   error responses and logs.\n6. **Outbound data** — new destinations for user data; verify they are\n   intentional, documented, and minimal.\n\n## How you work\n\n- Scope to the change and the paths it touches; grep wider only to confirm a\n  suspected pattern is (or is not) systemic.\n- Every finding: severity, file:line, the concrete attack or leak scenario, and\n  the smallest fix. No theoretical lectures without a code path.\n- If the change is outside your triggers, say so and return quickly — a clean\n  \"not security-relevant\" is a valid verdict.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. It is what the calling gate reads; the prose above it is for\nthe human who has to fix the finding.\n\n```json\n{\n  \"gate\": \"security-scanner\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"services/api/src/handlers/upload.ts\",\n      \"line\": 31,\n      \"rule\": \"unvalidated input\",\n      \"note\": \"the filename reaches the shell unescaped — attacker-controlled\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"grepped for the pattern across services/\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP` (nothing blocking), `HOLD`, or `NOT_APPLICABLE` when the\n  change is outside your triggers — that last one is the structured form of the\n  clean \"not security-relevant\" answer above.\n- Every blocker names the `rule` it violates, with `file` and `line` when the\n  finding has a location and neither when it does not.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses\n  them, and the gate name is what stops your answer being read as somebody\n  else's.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."

package/templates/agent-os/universal/.codex/agents/test-writer.toml

@@ -1,4 +1,6 @@
 name = "test-writer"
 description = "Writes the failing test BEFORE any implementation exists. Use at the start of every feature, bug fix, or behavior change — the Red step of TDD. Also use to reproduce a reported bug as a test."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "high"
 sandbox_mode = "workspace-write"
 developer_instructions = "You write tests that define behavior which does not exist yet. You are the Red\nstep of TDD, and only the Red step.\n\n## Scope — hard boundaries\n\n- You create and modify **test files only**. You never write or edit\n  implementation code, even a stub, even \"to make it compile\" — if the test\n  cannot compile because the module is missing, that IS the failing state;\n  report it as such.\n- You never mark tests as skipped or todo to avoid a failure. A failing test is\n  your deliverable.\n\n## How you work\n\n1. Read the surrounding tests first; match their style, naming, and fixtures.\n2. Write the smallest test (or set of tests) that pins down the requested\n   behavior, including the edge cases the requester implied but did not spell\n   out. Name tests after behavior (\"refuses an empty title\"), not after methods.\n3. Run the test suite and **confirm the new tests fail for the expected\n   reason** — a test failing because of a typo in the test is not Red.\n4. Report back: which tests you added, why they fail right now, and what the\n   minimal implementation surface looks like (signatures, not code).\n\n## Judgment lines\n\n- Test behavior through public entry points (usecases, handlers), not private\n  internals.\n- One behavior per test; shared setup in fixtures, not copy-paste.\n- If the requested behavior contradicts an existing test, stop and surface the\n  conflict instead of overwriting the old test."

package/templates/agent-os/universal/.codex/config.toml

@@ -0,0 +1,3 @@
+[agents]
+default_subagent_model = "gpt-5.6-terra"
+default_subagent_reasoning_effort = "medium"

package/templates/agent-os/universal/docs/decisions/codex-adapter.md

@@ -1,6 +1,6 @@
 # Codex adapter: derived parity
 
-Status: accepted for AR-113.
+Status: accepted for AR-113; subagent routing extended for RP-166.
 
 ## Decision
 
@@ -18,7 +18,22 @@ generated release. There is no downstream automatic drift check.
 
 Two hand-maintained rulebooks inevitably diverge. Derivation keeps the generated
 snapshots aligned while preserving native Codex formats. The adapter translates
-the fields for which Codex has native controls and does not invent policy.
+the fields for which Codex has native controls. Subagent routing — each role's
+model and effort, for both harnesses — is declared once in the generator's
+`templates/agent-os/subagent-routing.json` (rationale:
+`docs/decisions/subagent-routing.md`). The Codex profiles are derived from that
+table, and the projector refuses a missing or orphaned agent profile. It also
+refuses duplicate source-agent names across layers, since one profile name
+cannot route two definitions.
+
+Frequent bounded work (`test-writer`, `prose-reviewer`) uses `gpt-5.6-terra`;
+correctness, security, and infrastructure gates use `gpt-5.6-sol`. Every named
+gate uses `high` reasoning effort. Unnamed subagents inherit repository defaults
+of `gpt-5.6-terra` and `medium` from `.codex/config.toml`. `xhigh` is not a
+continuous-loop default; using it for a named role requires an intentional
+profile-policy change (or a separate escalation profile), because named-profile
+fields take precedence over spawn and repository defaults. Concurrency remains
+a machine/session decision rather than repository policy.
 
 Claude agent `tools` allowlists have no equivalent custom-agent allowlist in the
 documented Codex TOML schema. The adapter therefore uses those fields only to
@@ -28,7 +43,15 @@ not carried over. This is a known parity limit, not an implicit restriction.
 ## Risk and rollback
 
 The main risks are generated-file drift, downstream edits to only one snapshot,
-and unsupported Claude shapes. In the generator, the adapter fails loudly when
+unsupported Claude shapes, and a pinned model being unavailable in a user's
+workspace. In the generator, recovery is to update the central routing table to
+an available model or use a separate supported escalation profile — the Codex
+profiles are regenerated from it, while the Claude agent definitions are checked
+against it and are edited to match in the same change. A generated
+project has no copy of that table: there, recovery is editing the role's
+definitions on both harnesses in one reviewed change, and `upgrade` then reports
+those files as the project's own instead of replacing them
+(`docs/decisions/subagent-routing.md`). In the generator, the adapter fails loudly when
 it cannot derive a portable hook command and its drift check catches stale
 output. Generated projects rely on review for subsequent local parity. Rollback
 is deleting the derived Codex files from the generated project and reverting the
@@ -80,8 +103,11 @@ Codex path.
 
 ## Schema and executable contracts
 
-The emitted agent fields are `name`, `description`, `sandbox_mode`, and
-`developer_instructions`, matching the documented Codex custom-agent TOML.
+The emitted agent fields are `name`, `description`, `model`,
+`model_reasoning_effort`, `sandbox_mode`, and `developer_instructions`, matching
+the documented Codex custom-agent TOML. Named-agent fields take precedence over
+the repository defaults in `.codex/config.toml`; the defaults cover only agents
+without their own model or effort assignment.
 For hooks, the [official Codex hooks documentation](https://learn.chatgpt.com/docs/hooks)
 documents `tool_input.command` for both `Bash` and `apply_patch` and requires a
 string `command` when a hook replaces that input. The same document is what makes