create-agent-rig 0.8.0 → 0.9.1

package/templates/agent-os/universal/.claude/scripts/reconcile-external-prs.mjs

@@ -26,6 +26,9 @@ import { dirname, join } from 'node:path';
 // so this sweep sees exactly what the gate sweep sees — including the paths a
 // stack layer contributes for its own shape.
 import { elevatedPathsIn, laneOf, readDeclaredPaths } from './detect-missed-gate.mjs';
+// The one credential vocabulary (`guard-secret-file`, the commit sweep and this
+// diagnostic all read it): a second list of token shapes here would drift.
+import { SECRET_VALUE_PATTERNS } from './lib/secrets.mjs';
 
 /**
  * The audit trail for work that already happened: a record born **closed**.
@@ -210,37 +213,261 @@ const parseArgs = (argv) => {
 
 const daysAgo = (n) => new Date(Date.now() - n * 86_400_000).toISOString().slice(0, 10);
 
-/** Same rule as the gate sweep: "could not look" must never render as "clean". */
-const fetchMergedPrs = (since) => {
-  try {
-    return JSON.parse(
-      execFileSync(
-        'gh',
-        [
-          'pr',
-          'list',
-          '--state',
-          'merged',
-          '--limit',
-          '100',
-          '--search',
-          `merged:>=${since}`,
-          '--json',
-          'number,title,body,headRefName,mergedAt,url,files,changedFiles,authorAssociation',
-        ],
-        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
-      ),
-    );
-  } catch (error) {
-    process.stderr.write(
-      'lane reconciliation: could not list merged PRs — the `gh` CLI is missing, ' +
-        'unauthenticated, or the API is unreachable. No lane was reconciled; do not ' +
-        'record an empty `external lane` block from this run. Use --input <file> to ' +
-        'work offline.\n' +
-        `  ${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]}\n`,
+// --- Acquisition (RP-99) --------------------------------------------------------
+//
+// Two calls, not one. `gh pr list --json` does not know `authorAssociation` on
+// every supported `gh` (2.71.2 answers `Unknown JSON field`), so the BASE
+// projection asks only for fields every `gh` has, and the association — the
+// trust signal — is fetched afterwards through one GraphQL query. When that
+// second step fails for any reason the base list is returned WITHOUT the field
+// and `reconcile()` treats those PRs as untrusted, and an answer is kept only
+// when it names the same pull request URL the base list did — see the
+// generator's test/template/reconcile-acquisition.test.ts (absent in a generated rig)
+// › "reconcile() treats a PR that lost authorAssociation to a failed enrichment as untrusted when it crosses an elevated path"
+// and › "drops an association whose answer names a different pull request URL — another host or repository never becomes trust".
+
+/** The base projection: fields every supported `gh` serves. */
+const BASE_FIELDS = ['number', 'title', 'body', 'headRefName', 'mergedAt', 'url', 'files', 'changedFiles'];
+/** What GitHub returns for `authorAssociation`: an upper-case enum word. */
+const ASSOCIATION_SHAPE = /^[A-Z_]{1,32}$/;
+const MAX_PRS = 100;
+
+/** The default runner: one `gh` child, stdout as text, a thrown error otherwise. */
+const execGh = (file, args) =>
+  execFileSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+/** A base record the rest of this script can read: an object with a positive PR number. */
+const isPrRecord = (row) =>
+  row !== null &&
+  typeof row === 'object' &&
+  !Array.isArray(row) &&
+  Number.isSafeInteger(row.number) &&
+  row.number > 0;
+
+/**
+ * The merged PRs since `since`, plus the warnings the acquisition produced.
+ *
+ * Throws only from the BASE list — the caller classifies that with
+ * `classifyAcquisitionFailure`. A parsed base list that is not an array is
+ * thrown with `notAnArray: true` (JSON.parse succeeded, so a SyntaxError would
+ * misdescribe it). Enrichment never throws: it degrades to a warning.
+ */
+export const fetchMergedPrs = (since, { exec = execGh } = {}) => {
+  const raw = exec('gh', [
+    'pr',
+    'list',
+    '--state',
+    'merged',
+    '--limit',
+    String(MAX_PRS),
+    '--search',
+    `merged:>=${since}`,
+    '--json',
+    BASE_FIELDS.join(','),
+  ]);
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed)) {
+    throw Object.assign(new Error('gh pr list answered with something other than a JSON array'), {
+      notAnArray: true,
+    });
+  }
+
+  const warnings = [];
+  const prs = [];
+  for (const row of parsed.slice(0, MAX_PRS)) {
+    if (!isPrRecord(row)) {
+      warnings.push('a merged-PR record without a positive numeric `number` was dropped from the sweep');
+      continue;
+    }
+    // Copy the base fields only; whatever else `gh` returned does not travel.
+    const record = {};
+    for (const field of BASE_FIELDS) if (row[field] !== undefined) record[field] = row[field];
+    prs.push(record);
+  }
+  if (prs.length === 0) return { prs, warnings };
+
+  const associations = fetchAuthorAssociations(prs, exec);
+  if (associations === null) {
+    warnings.push(
+      'author association unavailable for this window — every external merge below is treated as untrusted origin',
     );
-    process.exit(1);
+    return { prs, warnings };
+  }
+  for (const pr of prs) {
+    const answer = associations.get(pr.number);
+    if (answer === undefined) continue;
+    // `gh api graphql` asks its own default host, not the remote's: an answer
+    // about another pull request must never lend its association to this one.
+    if (typeof pr.url !== 'string' || answer.url !== pr.url) {
+      warnings.push(`PR #${pr.number}: an author association whose pull request URL does not match the listed one was dropped`);
+      continue;
+    }
+    const value = answer.authorAssociation;
+    if (typeof value === 'string' && ASSOCIATION_SHAPE.test(value)) pr.authorAssociation = value;
+    else warnings.push(`PR #${pr.number}: an author association of an unexpected shape was dropped`);
   }
+  return { prs, warnings };
+};
+
+/**
+ * `number → { url, authorAssociation }` for the listed PRs through one GraphQL
+ * query, or `null` when the answer cannot be trusted: a failed call, unusable
+ * JSON, a repository name of an unexpected shape. Never throws.
+ */
+const fetchAuthorAssociations = (prs, exec) => {
+  try {
+    const repo = JSON.parse(exec('gh', ['repo', 'view', '--json', 'nameWithOwner']));
+    const nameWithOwner = typeof repo?.nameWithOwner === 'string' ? repo.nameWithOwner : '';
+    const parts = nameWithOwner.split('/');
+    if (parts.length !== 2 || !parts.every((part) => /^[A-Za-z0-9_.-]{1,100}$/.test(part))) return null;
+    const [owner, name] = parts;
+    const fields = prs
+      .map((pr) => `pr${pr.number}: pullRequest(number: ${pr.number}) { url authorAssociation }`)
+      .join(' ');
+    const query = `query { repository(owner: "${owner}", name: "${name}") { ${fields} } }`;
+    const answer = JSON.parse(exec('gh', ['api', 'graphql', '-f', `query=${query}`]));
+    const repository = answer?.data?.repository;
+    if (repository === null || typeof repository !== 'object') return null;
+    const out = new Map();
+    for (const pr of prs) {
+      const node = repository[`pr${pr.number}`];
+      if (node === null || typeof node !== 'object' || node.authorAssociation === undefined) continue;
+      out.set(pr.number, { url: node.url, authorAssociation: node.authorAssociation });
+    }
+    return out;
+  } catch {
+    return null;
+  }
+};
+
+// --- Failure diagnostics (RP-99) -----------------------------------------------
+
+const CAUSES = Object.freeze({
+  'gh-missing': 'the `gh` CLI could not be started (not installed, or not on PATH)',
+  'gh-unauthenticated': 'the `gh` CLI is not authenticated for this host — run `gh auth login`',
+  'api-unreachable': 'the GitHub API could not be reached',
+  'unsupported-projection': 'this `gh` version does not serve a field the sweep asked for',
+  'malformed-response': '`gh` answered, but not with the JSON array the sweep expects',
+  unknown: 'the cause is unknown',
+});
+const STDERR_UNAUTHENTICATED = /gh auth login|not logged in|HTTP 401|authentication required/i;
+const STDERR_UNREACHABLE =
+  /dial tcp|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|HTTP 5\d\d|could not connect|connection refused/i;
+const STDERR_UNSUPPORTED = /Unknown JSON field/i;
+// ESC-led sequences (CSI, OSC and the single-character escapes); the
+// whitespace controls, which become a space where they sit next to whitespace
+// and a mark where they sit inside a run (so they cannot split a token into
+// pieces too short to match); and every other character a terminal would not
+// print as itself — the remaining C0/C1 controls except the line feed the next
+// step splits on, the invisible format characters (zero-width, bidi,
+// byte-order mark), the line and paragraph separators, and U+E000, the mark
+// they are all replaced with.
+// eslint-disable-next-line no-control-regex -- the pattern exists to remove these very bytes
+const TERMINAL_SEQUENCES = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])/g;
+const WHITESPACE_CONTROLS = /[\t\v\f\r]/g;
+const WHITESPACE_CONTROLS_INSIDE_A_RUN = /(?<=\S)[\t\v\f\r]+(?=\S)/g;
+// eslint-disable-next-line no-control-regex -- likewise
+const HIDDEN_CHARACTERS = /[\x00-\x08\x0E-\x1F\x7F-\x9F\p{Cf}\p{Zl}\p{Zp}\uE000]/gu;
+const MARK = '\uE000';
+// No leading word boundary: a keyword glued to the word before must still be
+// found, and over-redacting prose is the safe way to be wrong here.
+const AUTHORIZATION_VALUE = /(?:Bearer|Basic|token)\s+[A-Za-z0-9._~+/=-]{8,}|Authorization:\s*[^\s]+(?:\s+[^\s]+)?/gi;
+const DIAGNOSTIC_CAP = 200;
+// Redaction runs on at most this much of the line, and the 200-character cut
+// comes after it: cutting first can shorten a token below what its pattern
+// needs and print the prefix. When the window itself cuts the line, the last
+// whitespace-free run is dropped before redaction, so no token is ever
+// shortened by a cut.
+const REDACTION_WINDOW = 4096;
+// A whitespace-free run that had a hidden character removed from it is masked
+// whole once what is left is at least this long — the shortest value the
+// vocabulary redacts, an authorization value. A removed character can glue a
+// token to the word before it or split it into pieces too short to match, and
+// neither can be told apart from honest text, so such a run is not trusted to
+// the patterns at all.
+const MARKED_RUN_MIN = 8;
+// A masked run that ended in one of these keywords takes the next run with it:
+// the value that followed the keyword can no longer be recognised on its own.
+const AUTHORIZATION_KEYWORD_END = /(?:bearer|basic|token|authorization:)$/i;
+
+/** `text` without its trailing whitespace-free run. One backward pass. */
+const dropTrailingRun = (text) => {
+  let end = text.length;
+  while (end > 0 && !/\s/.test(text[end - 1])) end -= 1;
+  return text.slice(0, end);
+};
+
+const redactPatterns = (text) => {
+  let out = text.replace(AUTHORIZATION_VALUE, '[redacted]');
+  for (const { pattern } of SECRET_VALUE_PATTERNS) {
+    out = out.replace(new RegExp(pattern.source, `${pattern.flags.replace('g', '')}g`), '[redacted]');
+  }
+  return out;
+};
+
+/**
+ * One printable line of a subprocess's stderr: no terminal sequences, control
+ * or invisible format characters, the first non-empty line only, every run a
+ * hidden character was removed from masked when it is long enough to be a
+ * credential, the credential shapes the shared vocabulary knows — plus HTTP
+ * authorization values — replaced by `[redacted]`, and then at most 200
+ * characters.
+ */
+export const sanitizeDiagnostic = (text) => {
+  const source = typeof text === 'string' ? text : String(text ?? '');
+  const marked = source
+    .replace(TERMINAL_SEQUENCES, MARK)
+    .replace(HIDDEN_CHARACTERS, MARK)
+    .replace(WHITESPACE_CONTROLS_INSIDE_A_RUN, MARK)
+    .replace(WHITESPACE_CONTROLS, ' ');
+  const line = marked.split('\n').find((candidate) => candidate.replaceAll(MARK, '').trim() !== '') ?? '';
+  const windowed = line.length > REDACTION_WINDOW ? dropTrailingRun(line.slice(0, REDACTION_WINDOW)) : line;
+  let maskNext = false;
+  const masked = windowed
+    .split(/(\s+)/)
+    .map((run) => {
+      if (run.trim() === '') return run;
+      const visible = run.replaceAll(MARK, '');
+      const hidden = run.includes(MARK) && visible.length >= MARKED_RUN_MIN;
+      const mask = hidden || maskNext;
+      maskNext = mask && AUTHORIZATION_KEYWORD_END.test(visible);
+      return mask ? '[redacted]' : visible;
+    })
+    .join('');
+  return redactPatterns(masked).trim().slice(0, DIAGNOSTIC_CAP);
+};
+
+/**
+ * The cause the evidence supports, and nothing more. `detail` is the sanitized
+ * first non-empty stderr line, whatever the cause, or `null` when there was none. An
+ * `unknown` failure with no stderr falls back to the error's own message; the
+ * other causes never do, because a parse error's message quotes `gh` output.
+ */
+export const classifyAcquisitionFailure = (error) => {
+  const stderr = typeof error?.stderr === 'string' ? error.stderr : '';
+  const detail = stderr.trim() === '' ? null : sanitizeDiagnostic(stderr);
+  if (error?.code === 'ENOENT') return { cause: 'gh-missing', detail };
+  if (error instanceof SyntaxError || error?.notAnArray === true) {
+    return { cause: 'malformed-response', detail };
+  }
+  if (STDERR_UNSUPPORTED.test(stderr)) return { cause: 'unsupported-projection', detail };
+  if (STDERR_UNAUTHENTICATED.test(stderr)) return { cause: 'gh-unauthenticated', detail };
+  if (STDERR_UNREACHABLE.test(stderr)) return { cause: 'api-unreachable', detail };
+  if (detail === null && typeof error?.message === 'string' && error.message.trim() !== '') {
+    return { cause: 'unknown', detail: sanitizeDiagnostic(error.message) };
+  }
+  return { cause: 'unknown', detail };
+};
+
+/** The message the CLI prints for a failed acquisition: one cause, named. */
+export const acquisitionFailureMessage = ({ cause, detail }) => {
+  const named = CAUSES[cause] ?? CAUSES.unknown;
+  return (
+    `lane reconciliation: could not list merged PRs — ${named}. ` +
+    'No lane was reconciled; do not record an empty `external lane` block from this run. ' +
+    'Use --input <file> to work offline.' +
+    (detail ? `\n  ${detail}` : '')
+  );
 };
 
 /**
@@ -267,9 +494,19 @@ const invokedDirectly = () => {
 if (invokedDirectly()) {
   const args = parseArgs(process.argv.slice(2));
   const projectRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
-  const prs = args.input
-    ? readInput(args.input, 'lane reconciliation')
-    : fetchMergedPrs(args.since ?? daysAgo(7));
+  let prs;
+  let warnings = [];
+  if (args.input) {
+    prs = readInput(args.input, 'lane reconciliation');
+  } else {
+    try {
+      ({ prs, warnings } = fetchMergedPrs(args.since ?? daysAgo(7)));
+    } catch (error) {
+      process.stderr.write(`${acquisitionFailureMessage(classifyAcquisitionFailure(error))}\n`);
+      process.exit(1);
+    }
+  }
+  for (const warning of warnings) process.stderr.write(`lane reconciliation: ${warning}\n`);
   // Lane sorting still works without a declaration; only the elevated marks go
   // missing, and they render as "no elevated path crossed" rather than lying.
   const elevatedPaths = readDeclaredPaths(projectRoot) ?? [];

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,8 +156,38 @@ 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 is refused unless its

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