create-agent-rig 0.6.0 → 0.6.1

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

@@ -22,18 +22,25 @@
 // so plainly where none does — a limits comment nothing checks drifts into
 // overstatement, which is the direction that gets a reader hurt. ⚠ Those tests live in the GENERATOR this rig came from, not here;
 // `.claude/rules/invariants.md` ("About the hooks you were given") says the same
-// of this hook's own tests, and the moment you edit it they are yours.
+// of this hook's own tests. A manifest-backed generator upgrade remains inherited
+// while `.claude/.rig-manifest.json` matches; once the hash differs, the local test
+// is yours.
 //
-// There are FOUR:
+// There are FIVE:
 //
 //   - It sees ONE edit fragment, not the resulting file. A credential assembled
-//     across two edits is not seen — see guard-secret-file.test.ts › "does not
+//     across two edits is not seen — see guard-secret-file.test.ts (absent in a generated rig) › "does not
 //     see a credential split across two edits, because it is shown one fragment
 //     at a time". This is the same limit every guard in this directory has,
 //     stated in full in `.claude/rules/invariants.md`, "What the enforcement
 //     actually is — stated exactly".
+//   - A `MultiEdit` is capped at 256 fragments and REFUSES before mapping a
+//     longer list, so the tail is never silently dropped — see
+//     guard-secret-file.test.ts (absent in a generated rig) › "refuses a
+//     MultiEdit beyond the fragment cap instead of silently dropping the tail".
 //   - It sees only what the AGENT writes. The `toolName` branch in `main` below
-//     names the complete surface: `Write`, `Edit`, and `apply_patch`; every other
+//     names the complete surface: `Write`, `Edit`, `MultiEdit`, `NotebookEdit`,
+//     and `apply_patch`; every other
 //     tool returns before inspection. A human editing the file, or a
 //     `git commit` of something already on disk, never reaches a PreToolUse hook
 //     at all, and no test here can show that: it is a property of the harness,
@@ -51,15 +58,16 @@
 //     `findSecretValues` applies by default so a fail-open guard cannot be made
 //     to hang. A credential past that point is not seen. ⚠ No test here pins
 //     this one: the case is pinned one layer down, on the module, by
-//     secrets-lib.test.ts › "has a limit even when the caller names none". The CI sweep lifts the
+//     secrets-lib.test.ts (absent in a generated rig) › "has a limit even when the caller names none". The CI sweep lifts the
 //     cap; this hook cannot, and that asymmetry is the point.
 //   - It FAILS OPEN on what it cannot understand — see guard-secret-file.test.ts
+//     (absent in a generated rig)
 //     › "allows a payload that is not JSON at all" and its neighbours. An
 //     unparseable payload, a missing field, or an internal throw all allow the
 //     edit; a crashed guard that blocks everything gets deleted within the hour.
 //
 //     ⚠ **An `apply_patch` command that is PRESENT and is not a shape this guard
-//     reads is the other case, and it now REFUSES** — see codex.test.ts ›
+//     reads is the other case, and it now REFUSES** — see codex.test.ts (absent in a generated rig) ›
 //     "refuses, rather than failing open, when apply_patch command is supplied
 //     as %s". The line between them is whether the guard can tell: an absent
 //     field is a payload it does not understand, a container it detects and
@@ -92,40 +100,27 @@ function main() {
     return 0; // unparseable payload: not ours to judge
   }
 
-  const toolName = input?.tool_name;
-  if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'apply_patch') return 0;
+  const editTools = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'apply_patch']);
+  if (!editTools.has(input?.tool_name)) return 0;
 
-  if (toolName === 'apply_patch') {
-    let refused = false;
-    for (const { filePath, fragment, inspectionRefusal, remedy, appliesToAll } of editFragments(input)) {
-      if (inspectionRefusal) {
-        refused = true;
-        process.stderr.write(
-          `BLOCKED — cannot safely inspect this edit: ${inspectionRefusal}\n` +
-            // The remedy has to match the refusal: splitting cannot change a
-            // container shape, and a fixed line sent the agent into a retry loop
-            // on the one path it could not retry out of.
-            `${remedy ?? 'Split it into a smaller patch and retry.'}\n`,
-        );
-        continue;
-      }
-      if (isCredentialPath(filePath)) {
-        refused = true;
-        process.stderr.write(`BLOCKED — "${filePath}" is a credential file, and this repository never carries one.\n${WHERE_CREDENTIALS_BELONG}\n`);
-        continue;
-      }
-      const findings = findSecretValues(fragment);
-      if (findings.length > 0 || appliesToAll) {
-        refused = true;
-        if (findings.length > 0) process.stderr.write(`BLOCKED — this edit writes a credential value into "${filePath}".\n${WHERE_CREDENTIALS_BELONG}\n`);
-      }
-    }
-    return refused ? 2 : 0;
+  const fragments = editFragments(input);
+  const globalRefusal = fragments.find(
+    ({ inspectionRefusal, appliesToAll }) => appliesToAll && inspectionRefusal,
+  );
+  if (globalRefusal) {
+    const fallbackRemedy = input?.tool_name === 'apply_patch'
+      ? 'Split it into a smaller patch and retry.'
+      : 'Split it into a smaller edit and retry.';
+    process.stderr.write(
+      `BLOCKED — cannot safely inspect this edit: ${globalRefusal.inspectionRefusal}\n` +
+        `${globalRefusal.remedy ?? fallbackRemedy}\n`,
+    );
+    return 2;
   }
 
-  const toolInput = input?.tool_input ?? {};
-  const filePath = String(toolInput.file_path ?? '').replaceAll('\\', '/');
-  if (filePath === '') return 0; // nothing to judge; fail open
+  if (fragments.length === 0 || fragments.every(({ filePath }) => filePath === '')) {
+    return 0; // nothing to judge; fail open
+  }
 
   // The tool sends an absolute path. Judge the repo-relative tail so a checkout
   // living under a directory literally called `secrets` does not make every edit
@@ -134,41 +129,53 @@ function main() {
   // below never matches, every path stays absolute, and a checkout that happens
   // to live under a directory called `secrets` has EVERY edit refused. That is
   // the "deleted within the hour" outcome `.claude/rules/invariants.md` warns
-  // about — see guard-secret-file.test.ts › "judges the repo-relative path even
-  // when the project directory is given with a trailing slash".
+  // about — see guard-secret-file.test.ts (absent in a generated rig) ›
+  // "judges the repo-relative path even when the project directory is given %s".
   const projectDir = String(process.env.CLAUDE_PROJECT_DIR ?? '')
     .replaceAll('\\', '/')
     .replace(/\/+$/, '');
-  const relativePath =
-    projectDir !== '' && filePath.startsWith(`${projectDir}/`)
-      ? filePath.slice(projectDir.length + 1)
-      : filePath;
+  let refused = false;
+  for (const { filePath, fragment, inspectionRefusal } of fragments) {
+    const relativePath =
+      projectDir !== '' && filePath.startsWith(`${projectDir}/`)
+        ? filePath.slice(projectDir.length + 1)
+        : filePath;
+    if (relativePath === '') continue;
 
-  if (isCredentialPath(relativePath)) {
+    if (inspectionRefusal) {
+      refused = true;
+      process.stderr.write(
+        `BLOCKED — cannot safely inspect this edit to "${relativePath}": ${inspectionRefusal}\n` +
+          'Split it into a smaller edit and retry.\n',
+      );
+      continue;
+    }
+    if (isCredentialPath(relativePath)) {
+      refused = true;
+      process.stderr.write(
+        `BLOCKED — "${relativePath}" is a credential file, and this repository never carries one.\n` +
+          `${WHERE_CREDENTIALS_BELONG}\n` +
+          `If this file is a documented placeholder, name it .env.example — that form stays committable.\n`,
+      );
+      continue;
+    }
+
+    const findings = findSecretValues(fragment);
+    if (findings.length === 0) continue;
+    refused = true;
     process.stderr.write(
-      `BLOCKED — "${relativePath}" is a credential file, and this repository never carries one.\n` +
-        `${WHERE_CREDENTIALS_BELONG}\n` +
-        `If this file is a documented placeholder, name it .env.example — that form stays committable.\n`,
+      `BLOCKED — this edit writes a credential value into "${relativePath}":\n` +
+        findings
+          .map((finding) => `  - ${finding.id} on line ${finding.line} of the text being written`)
+          .join('\n') +
+        `\n${WHERE_CREDENTIALS_BELONG}\n` +
+        // Deliberately NOT the matched text. A guard that prints what it found has
+        // copied the credential into a hook transcript and a terminal scrollback —
+        // it has leaked the secret in the act of refusing it.
+        `The matched value is deliberately not shown; open the line above to see it.\n`,
     );
-    return 2;
   }
-
-  const fragment = String((toolName === 'Write' ? toolInput.content : toolInput.new_string) ?? '');
-  const findings = findSecretValues(fragment);
-  if (findings.length === 0) return 0;
-
-  process.stderr.write(
-    `BLOCKED — this edit writes a credential value into "${relativePath}":\n` +
-      findings
-        .map((finding) => `  - ${finding.id} on line ${finding.line} of the text being written`)
-        .join('\n') +
-      `\n${WHERE_CREDENTIALS_BELONG}\n` +
-      // Deliberately NOT the matched text. A guard that prints what it found has
-      // copied the credential into a hook transcript and a terminal scrollback —
-      // it has leaked the secret in the act of refusing it.
-      `The matched value is deliberately not shown; open the line above to see it.\n`,
-  );
-  return 2;
+  return refused ? 2 : 0;
 }
 
 let status;

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

@@ -70,7 +70,17 @@ export function editFragments(input) {
   if (toolName === 'MultiEdit') {
     if (!Array.isArray(toolInput.edits)) return [];
     const filePath = normalisePath(toolInput.file_path);
-    return toolInput.edits.slice(0, MAX_MULTI_EDITS).map((edit) => ({
+    if (toolInput.edits.length > MAX_MULTI_EDITS) {
+      return [
+        {
+          filePath,
+          fragment: '',
+          inspectionRefusal: `MultiEdit carries more than the ${MAX_MULTI_EDITS}-fragment inspection limit`,
+          appliesToAll: true,
+        },
+      ];
+    }
+    return toolInput.edits.map((edit) => ({
       filePath,
       fragment: String(edit?.new_string ?? ''),
     }));

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

@@ -95,10 +95,10 @@ own cost figures are read next to the lane they do not cover.
 - bypass pre-commit (`--no-verify` is hook-blocked anyway)
 - force-push a shared branch
 - put secrets in code, config, logs, or fixtures. One part of this is
-  **mechanical**: `guard-secret-file` refuses an edit through `Write`, `Edit`, or
-  `apply_patch` that names a credential file or carries a credential value,
+  **mechanical**: `guard-secret-file` refuses an edit through `Write`, `Edit`,
+  `MultiEdit`, `NotebookEdit`, or `apply_patch` that names a credential file or carries a credential value,
   reading its vocabulary from `.claude/scripts/lib/secrets.mjs`. ⚠ **Only that
-  part.** The hook sees what an agent writes through those three tools and
+  part.** The hook sees what an agent writes through those five tools and
   nothing else — its own header states the four blind spots — so whether a
   credential typed by a human, or committed from disk, is also refused depends
   on whether this project has a commit-time check. Look at `.husky/` and the CI
@@ -109,8 +109,10 @@ own cost figures are read next to the lane they do not cover.
   a leak.
 - touch production data outside a reviewed migration
 - edit the rulebook from an **unattended** run outside the item's allow-list — `guard-rulebook` refuses it.
-  The rulebook: the hooks, their wiring, `.claude/queue.json`, the queue
-  adapters, the router, the gate sweep, the rules, `CLAUDE.md`. Mechanical:
+  The rulebook is both harnesses' instruction, agent, skill, script and hook
+  trees (`CLAUDE.md`, `AGENTS.md`, `.claude/{agents,hooks,rules,scripts,skills}`,
+  `.agents/`, `.codex/`), plus `.claude/settings.json`, the queue config and its
+  always-refused board selector, and the integrity manifest. Mechanical:
   the hook refuses the edit while the unattended flag the `loop` skill writes
   at claim time is on disk (`.claude/scripts/unattended-flag.mjs`), and does
   nothing in an attended session. ⚠ It sees edit tool calls only — a

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

@@ -216,27 +216,25 @@ are guessing, and a guessed invariant is the one that will fire on honest work.
 
 ## About the hooks you were given
 
-They arrive with their tests **in the generator that produced this project**, not
-in this repository — so by the rule above, as they sit here, they are checks
-without tests. That is deliberate and it has a boundary: it holds only while they
-are untouched.
-
-This is the one narrow exception for a generator-authored hook: it may cite the
-generator's upstream tests **only while unchanged downstream**, and its hook
-header must identify the upstream generator tests as absent locally. That pointer
-records the evidence used to author the inherited snapshot; it does not turn the
-absent test into a local check.
-
-**The moment you edit one, its test is yours.** A guard whose behaviour has
-changed and whose test lives somewhere else is precisely the "quietly stopped
-matching" case this rule names, and nothing here would catch it. The same applies
-if you keep a hook whose invariant you have re-scoped.
+Generator-authored rulebook artifacts — rules, hooks, skills, scripts and agent
+specs — arrive with their tests **in the generator that produced this project**,
+not in this repository. There is one narrow inherited-snapshot exception: such
+an artifact may cite the generator's upstream tests, which are absent locally,
+only when the pointer says they are absent and `.claude/.rig-manifest.json`
+proves the current artifact's hash matches the installed manifest.
+
+A manifest-backed upgrade remains an inherited, generator-owned artifact even
+though the upgrade diff changes its bytes. The exception applies **only while the
+manifest hash matches**. A hash mismatch, missing manifest, or no evidence ends
+the exception and the local test is yours; an owned guard whose behaviour changed
+while its test lives elsewhere is precisely the "quietly stopped matching" case
+this rule names.
 
 If a hook matters enough to keep, it is worth ten minutes to copy the shape from
 `.claude/skills/new-invariant/guard-invariant.example.test.mjs` and pin the
 behaviour you actually rely on.
 
-**That boundary is audited, not remembered.** `node .claude/scripts/doctor.mjs`
+**For hooks, that ownership boundary is audited, not remembered.** `node .claude/scripts/doctor.mjs`
 reads `.claude/.rig-manifest.json` and asks of every hook in `.claude/hooks/` (and
 `.husky/`, when it exists) whether the project owns it — the bytes differ from
 what the generator installed, or the manifest has no entry — and, if so, whether

package/templates/agent-os/universal/.claude/scripts/decision-router.mjs

@@ -1,6 +1,7 @@
 /**
  * The decision router — which gate does this change deserve, and what does that
  * cost.
+ * All upstream test pointers in this script name the generator suite, absent in a generated rig.
  *
  * `pr-ship` is the merge-time gate and it always runs the expensive path: the
  * full suite, then `code-reviewer` on every diff. That is right for a change

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
 // doctor — the harness audits itself (AR-5).
 //
 //   node .claude/scripts/doctor.mjs                 # the report, ready to paste
@@ -10,7 +11,9 @@
 // `.claude/rules/invariants.md` — a stated rule, a mechanical check, a test for
 // the check — is decoration with any part missing, and the part a rig loses
 // first is the third: the shipped hooks arrive with their tests in the generator
-// that produced them, and the moment one is edited its test is the rig's own.
+// that produced them. A manifest-backed generator upgrade remains inherited;
+// the test becomes the rig's own when the current hash no longer matches the
+// manifest evidence below.
 //
 // Ownership is read from `.claude/.rig-manifest.json`, the install manifest the
 // generator writes (its `files` map is install-relative path → sha256 of the

package/templates/agent-os/universal/.claude/scripts/git-env.mjs

@@ -1,5 +1,6 @@
 /**
  * The environment a child `git` should run with — one implementation, imported.
+ * All upstream test pointers in this script name the generator suite, absent in a generated rig.
  *
  * 🔴 **Why this is not inlined at each call site.** A process started under a
  * git hook inherits `GIT_DIR` and `GIT_INDEX_FILE`, and any child then answers

package/templates/agent-os/universal/.claude/scripts/lib/revalidation-points.mjs

@@ -1,5 +1,6 @@
 /**
  * The revalidation points — ONE spelling of the fact (AR-137).
+ * All upstream test pointers in this script name the generator suite, absent in a generated rig.
  *
  * `queue/index.mjs next` writes the SELECT record; `revalidate.mjs` writes the
  * other two and answers outcomes at all three; `revalidation-report.mjs`

package/templates/agent-os/universal/.claude/scripts/lib/secrets.mjs

@@ -1,5 +1,6 @@
 // The credential vocabulary, decided once, so that everything which refuses a
 // credential refuses the same set.
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
 //
 // Every layer that refuses one reads THIS module — which layers exist is a
 // question about the project, not about this file. A freshly generated rig has
@@ -18,7 +19,9 @@
 // GENERATOR this rig came from, not in this repository — the same arrangement
 // `.claude/rules/invariants.md` describes for the hooks themselves under "About
 // the hooks you were given". They are where a claim is proven, not cover you
-// have here. The moment you edit this module, its tests are yours.
+// have here. A manifest-backed generator upgrade remains inherited while
+// `.claude/.rig-manifest.json` matches; once the hash differs, the local test is
+// yours.
 //
 // It answers two different questions, and keeping them apart matters:
 //

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

@@ -6,12 +6,13 @@
 //   node .claude/scripts/queue/index.mjs list            # every item, with skip reasons
 //   node .claude/scripts/queue/index.mjs hygiene         # stale labels, link anomalies, overtaken proposals
 //   node .claude/scripts/queue/index.mjs gate-round --branch <b>   # count a gate round
+//   node .claude/scripts/queue/index.mjs board [<name>]       # the active board; or switch this checkout to <name>
 //
 // The adapter comes from `.claude/queue.json` (`{"adapter": "plan-md"}`) and
 // 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 } from 'node:fs';
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { basename, dirname, join } from 'node:path';
 import {
@@ -48,7 +49,7 @@ export const resolveAdapter = async (adapterName) => {
   return import(new URL(modulePath, import.meta.url).href);
 };
 
-export const COMMANDS = ['next', 'list', 'hygiene', 'gate-round'];
+export const COMMANDS = ['next', 'list', 'hygiene', 'gate-round', 'board'];
 
 /**
  * A missing config is the normal state of a fresh project. A config that exists
@@ -63,8 +64,9 @@ export const loadConfig = (configPath) => {
   } catch {
     return {};
   }
+  let parsed;
   try {
-    return JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch (error) {
     throw new Error(
       `${configPath} exists but is not valid JSON, so the configured queue cannot be ` +
@@ -73,6 +75,83 @@ export const loadConfig = (configPath) => {
       { cause: error },
     );
   }
+  return resolveBoard(parsed, configPath);
+};
+
+/**
+ * The selector that travels with a config: `<name>.json` → `<name>.board`.
+ *
+ * A plain-text file holding one board name. Same class as the state file — a
+ * per-checkout runtime value that must never be committed, because the config it
+ * sits beside is composed and tracked. Derived from the config path for the same
+ * reason `statePathFor` is: a run pointed at a temp config must not switch on
+ * this checkout's real selector.
+ */
+export const boardPathFor = (configPath) => configPath.replace(/(\.json)?$/, '.board');
+
+const isTerminalControl = (char) => {
+  const code = char.codePointAt(0);
+  return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+};
+
+const assertSafeBoardName = (name, source) => {
+  if (typeof name === 'string' && [...name].some(isTerminalControl)) {
+    throw new Error(`${source}: board names must not contain terminal control characters.`);
+  }
+};
+
+const boardNamesOf = (boards, configPath) => {
+  const names = Object.keys(boards);
+  for (const name of names) assertSafeBoardName(name, configPath);
+  return names;
+};
+
+/**
+ * A config may declare several boards and one default:
+ *
+ *   { "adapter": "jira", "board": "AR",
+ *     "boards": { "AR": { "project": "AR", "owner": "x" }, "RP": { … } },
+ *     "options": { "maxGateRounds": 3 } }
+ *
+ * The active board is the selector file if present, else `board`; its entry is
+ * laid over `options`, so a key every board shares stays in `options` and only
+ * what differs is per board. A config with no `boards` is returned exactly as it
+ * was. A name nobody declared — in the selector or as the default — is refused,
+ * never read as "no board": the loop would otherwise run on the shared options
+ * alone, and for `jira` that is a different (or no) project.
+ */
+export const resolveBoard = (config, configPath) => {
+  if (config?.boards === undefined) return config;
+  const boards = config.boards;
+  if (boards === null || typeof boards !== 'object' || Array.isArray(boards)) {
+    throw new Error(`${configPath}: "boards" must be an object of <name> → options.`);
+  }
+  const known = boardNamesOf(boards, configPath);
+  let selected = null;
+  let source = 'the "board" key';
+  try {
+    selected = readFileSync(boardPathFor(configPath), 'utf8').trim();
+    source = boardPathFor(configPath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
+  }
+  // A selector that exists but is empty is refused, not read as "no selector":
+  // a truncated write would otherwise switch the run to the default board while
+  // the file still looks like a choice somebody made.
+  const active = selected === null ? config.board : selected;
+  assertSafeBoardName(active, source);
+  if (!active || !known.includes(active)) {
+    throw new Error(
+      `${source} names board ${JSON.stringify(active ?? null)}, which ${configPath} does not ` +
+        `declare. Declared boards: ${known.join(', ')}. Refusing rather than running on the ` +
+        'shared options alone — that would be a different queue than the one configured.',
+    );
+  }
+  const entry = boards[active];
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error(`${configPath}: boards.${active} must be an object of adapter options.`);
+  }
+  return { ...config, board: active, options: { ...(config.options ?? {}), ...entry } };
 };
 
 /**
@@ -222,11 +301,12 @@ export const loadState = (statePath) => {
 };
 
 const parseArgs = (argv) => {
-  const args = { command: argv[0] ?? 'next', json: false, config: null, branch: null };
+  const args = { command: argv[0] ?? 'next', json: false, config: null, branch: null, name: null };
   for (let i = 1; i < argv.length; i += 1) {
     if (argv[i] === '--json') args.json = true;
     else if (argv[i] === '--config') args.config = argv[++i];
     else if (argv[i] === '--branch') args.branch = argv[++i];
+    else if (!argv[i].startsWith('--') && args.name === null) args.name = argv[i];
   }
   return args;
 };
@@ -288,6 +368,66 @@ if (invokedDirectly()) {
     process.exit(1);
   }
 
+  // `board` is local too: it reads the config and writes the selector beside it,
+  // and never touches the tracker. Switching is refused on a config that declares
+  // no boards — the selector would then be a file nothing reads.
+  if (args.command === 'board') {
+    try {
+      // Resolve before deriving either the checkout root or the selector path.
+      // Otherwise a symlinked `.claude` lets the caller authorize one checkout
+      // while the write follows the link into another unattended checkout.
+      const configPath = realpathSync(args.config ?? join(projectRoot, '.claude', 'queue.json'));
+      const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+      if (raw?.boards === undefined) {
+        throw new Error(`${configPath} declares no boards, so there is nothing to switch between.`);
+      }
+      if (raw.boards === null || typeof raw.boards !== 'object' || Array.isArray(raw.boards)) {
+        throw new Error(`${configPath}: "boards" must be an object of <name> → options. Nothing was written.`);
+      }
+      const boardNames = boardNamesOf(raw.boards, configPath);
+      if (args.name !== null) {
+        assertSafeBoardName(args.name, 'the requested board');
+        if (!boardNames.includes(args.name)) {
+          throw new Error(
+            `${JSON.stringify(args.name)} is not a declared board. Declared: ` +
+            `${boardNames.join(', ')}. Nothing was written.`,
+          );
+        }
+        // Loaded only on the mutation path. `next`, `list` and `hygiene` also
+        // run in partial-install diagnostics where this sibling is deliberately
+        // absent; a static import would replace their own actionable refusal
+        // with ERR_MODULE_NOT_FOUND before the command could start.
+        const { readUnattended } = await import('../unattended-flag.mjs');
+        const callerRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+        const targetRoot = projectRootOfConfig(configPath) ?? callerRoot;
+        const guardedRoots = [...new Set([callerRoot, targetRoot])];
+        const unattended = guardedRoots
+          .map((root) => ({ root, mode: readUnattended({ ...process.env, CLAUDE_PROJECT_DIR: root }) }))
+          .find(({ mode }) => mode.on);
+        if (unattended) {
+          throw new Error(
+            `board switching is refused while checkout ${unattended.root} is unattended. ` +
+              'The read-only `board` report remains available; disarm the loop before re-aiming its queue.',
+          );
+        }
+        writeFileSync(boardPathFor(configPath), `${args.name}\n`);
+      }
+      const config = loadConfig(configPath);
+      const report = { board: config.board, boards: boardNames, options: config.options };
+      process.stdout.write(
+        args.json
+          ? `${JSON.stringify(report)}\n`
+          : `board: ${report.board}${args.name !== null ? ' (switched)' : ''}\n` +
+              `  declared: ${report.boards.join(', ')}\n` +
+              `  selector: ${boardPathFor(configPath)}\n`,
+      );
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`board could not run: ${error.message}\n`);
+      process.exit(1);
+    }
+  }
+
   // 🔴 **`gate-round` returns before the tracker is ever touched, and that is
   // load-bearing rather than an optimisation.** `pr-ship` calls this once per
   // round, and every other command below reaches the adapter — so routing this one

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

@@ -1,4 +1,5 @@
 // Queue adapter: Jira issues, via the REST API.
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
 //
 // The second adapter exists to prove the seam holds: everything about *selection*
 // lives in `core.mjs` and is imported, not re-derived. An adapter that answers

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
 /**
  * Revalidation at BEFORE_PR — is the branch about to ship still the branch the
  * run took up?

package/templates/agent-os/universal/.claude/scripts/revalidation-report.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// All upstream test pointers in this script name the generator suite, absent in a generated rig.
 /**
  * The Revalidation Experiment's report — what the evidence log says, over the
  * run directories of this rig since a date (AR-136).