create-agent-rig 0.9.0 → 0.10.0

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

@@ -680,6 +680,23 @@ export const escalate = async (ticket, diagnosis, { env = process.env } = {}) =>
   return { ok: true };
 };
 
+/**
+ * Jira refuses a summary longer than this, and creates nothing: `400
+ * {"errors":{"summary":"Summary can't exceed 255 characters."}}` (RP-121). The
+ * summary is therefore a prefix; the full `change` stays in the description,
+ * where the fingerprint lives too, so the dedupe does not depend on the cut.
+ * The cut never leaves half of a surrogate pair behind. Pinned in
+ * `test/template/queue-jira.test.ts` › "bounds the POSTed summary so a
+ * 2186-character change still files, keeping the full text in the body".
+ */
+const MAX_SUMMARY_LENGTH = 255;
+
+const boundedSummary = (text) => {
+  if (text.length <= MAX_SUMMARY_LENGTH) return text;
+  const cut = text.slice(0, MAX_SUMMARY_LENGTH);
+  return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut;
+};
+
 /**
  * 🔴 INVARIANT 2: the agent never creates its own work. A proposal is labelled
  * `triage`, which `buildJql` excludes explicitly, and it never receives a ready
@@ -689,7 +706,7 @@ export const triageItemFor = (proposal) => {
   validateProposal(proposal);
   const fingerprint = fingerprintOf(proposal);
   return {
-    title: `proposal: ${proposal.change}`,
+    title: boundedSummary(`proposal: ${proposal.change}`),
     body: [
       `- finding — ${proposal.finding}`,
       `- part to change — ${proposal.part}`,

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

@@ -138,7 +138,7 @@ export const recordCompletedTier = ({ changedFiles, projectRoot, statePath, runD
   if (!declared || declared.length === 0) {
     throw new Error(
       'nothing in this project declares an elevated path, so no tier can be ' +
-        'computed: add an `elevated-paths` block to CLAUDE.md or a rule file. ' +
+        'computed: add an `elevated-paths` block to AGENTS.md or a rule file. ' +
         'Treating the absence as `normal` would ration on a declaration that ' +
         'does not exist.',
     );
@@ -157,7 +157,7 @@ export const recordCompletedTier = ({ changedFiles, projectRoot, statePath, runD
   // and silently relocating it would make it useless.
   //
   // Note the asymmetry, which is deliberate: the DECLARATION is read from the
-  // given `projectRoot` (the worktree's own `CLAUDE.md` is the rulebook the
+  // given `projectRoot` (the worktree's own `AGENTS.md` is the rulebook the
   // change was written against), while the STATE goes to the checkout that
   // outlives the task.
   const file = statePath ?? join(mainCheckoutRoot(projectRoot), '.claude', 'queue.state.json');

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

@@ -22,10 +22,14 @@ import { dirname, join } from 'node:path';
 // Imported, never copied: one home for the elevated declaration and one home for
 // the lane rule. A second copy of either would drift, and each copy would keep
 // passing on its own.
-// `readDeclaredPaths` unions CLAUDE.md with every .claude/rules/*.md declaration,
-// so this sweep sees exactly what the gate sweep sees — including the paths a
-// stack layer contributes for its own shape.
+// `readDeclaredPaths` unions AGENTS.md (the canonical rulebook since RP-186)
+// and CLAUDE.md with every .claude/rules/*.md declaration, 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 +214,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 +495,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/revalidate.mjs

@@ -179,6 +179,7 @@ const parseArgs = (argv) => {
     json: false,
     actionChanged: null,
     note: null,
+    mergeCommit: null,
     bad: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -201,6 +202,15 @@ const parseArgs = (argv) => {
       const value = revisionOrNull(argv[++i]);
       if (value === null) args.bad = arg;
       else args.base = value;
+    }
+    else if (arg === '--merge-commit') {
+      // Read only at BEFORE_CLOSE (below); ignored elsewhere, the same way
+      // BEFORE_CLOSE ignores --base. A value starting with '-' would be read
+      // as another option, so it is rejected the same defensive way --ticket
+      // and --base already are.
+      const value = revisionOrNull(argv[++i]);
+      if (value === null) args.bad = arg;
+      else args.mergeCommit = value;
     } else if (args.bad === null) args.bad = arg;
   }
   return args;
@@ -806,6 +816,12 @@ if (invokedDirectly()) {
       // target SELECT pinned, so a missing `origin/master` cannot turn an
       // otherwise current local rig into claim:scope drift.
       targetSha: targetShaOf(claimRoot),
+      // Optional (RP-175): the SHA the caller resolved, from the tracker's own
+      // PR metadata, as THIS item's own merge commit. Omit it and a target
+      // that moved for any reason still holds, exactly as before this
+      // existed — see claim-records.mjs's isOwnMergeAdvance for what this
+      // does and does not prove.
+      mergeCommit: args.mergeCommit,
     });
     const result = {
       ...claim,

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

@@ -7,14 +7,6 @@
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit|apply_patch",
         "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-core-purity.mjs\""
-          },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-web-boundary.mjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-secret-file.mjs\""

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

@@ -28,7 +28,7 @@ same four steps with the diff as the code, and §4 carries what is different.
 
 **What "rulebook prose" means here is not a new list** — it is the set
 `.claude/rules/workflow.md` already uses for the `prose-reviewer` trigger: a rule
-file, a skill, an agent spec, a decision record, `CLAUDE.md`, the README. Where a
+file, a skill, an agent spec, a decision record, `CLAUDE.md`, `AGENTS.md`, the README. Where a
 rulebook file exists twice (a template source and a generated copy), check the
 **source**; the copy is composed from it. A comment in a test or a hook is in scope
 too when it asserts behaviour — the file it lives in does not change what a claim is.
@@ -36,8 +36,8 @@ too when it asserts behaviour — the file it lives in does not change what a cl
 🔴 **`PREMISE FALSE` belongs to the first entry point only.** At the second one the
 claims are your own and the remedy is an edit, so a false one is not an escalation:
 it is `UNMEASURED`'s neighbour — delete or correct the sentence and carry on. Reading
-it as the escalation `loop` §6 defines would send a finished branch back to the queue
-over one sentence.
+it as the escalation `loop` §6 (opt-in workflow layer) defines would send a
+finished branch back to the queue over one sentence.
 
 ## Why it sits here and not in review
 
@@ -185,9 +185,13 @@ inside the block; both forms are the contract.
   actually says, and `file`/`line` is the citation §3 requires.
 - `PREMISES_HOLD` carries an empty `blockers` list; the other three name at
   least one. A stop verdict without one is not an answer the caller can act on,
-  and the caller is what checks: the `loop` skill runs
-  `node .claude/scripts/verdict.mjs check <report> check-premises` on what you
-  return. Nothing in this skill runs it — this skill writes nothing at all.
+  and the caller is what checks: `node .claude/scripts/verdict.mjs check
+  <report> check-premises` on what you return — `verdict.mjs` is Core and runs
+  standalone, so the caller is whichever session invoked this skill (this is a
+  Core skill, meant to run with no queue and no loop); the `loop` skill (opt-in
+  workflow layer) runs the same command the same way when it is the one that
+  invoked you. Nothing in this skill runs it — this skill writes nothing at
+  all.
 - **`headSha` is the commit you read** — `git rev-parse HEAD` in the checkout
   you examined. A premise check answers about a tree, and the tree moves.
 
@@ -231,6 +235,6 @@ is invisible to every gate downstream.
   when a task starts building on an unchecked claim, and no artifact outlives the
   step — so a run that skipped it and a run that passed it look identical
   afterwards. That is the honest description of every rule of this shape here
-  (the `loop` skill says the same about its own no-hand-feeding rule), and it is
-  why the citation matters: a `file:line` in the report is the one part of this a
-  later reader can re-check.
+  (the `loop` skill — opt-in workflow layer — says the same about its own
+  no-hand-feeding rule), and it is why the citation matters: a `file:line` in
+  the report is the one part of this a later reader can re-check.

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

@@ -12,7 +12,7 @@ decisions. This skill is the driver in between: what gets picked,
 what keeps the loop going, what stops it, and where the report goes.
 
 Per-task procedure: (worktree if another session may run) → `check-premises` on the
-item → failing test first → implement → **`check-premises` again, on your own prose**
+item → failing test first (`test-writer`) → implement (`implementation-agent`) → **`check-premises` again, on your own prose**
 → `pr-ship` → merge on the named criterion → verify the deployed surface if one
 changed.
 
@@ -344,7 +344,7 @@ it only here. A tier outside that vocabulary **holds**, never releases
 (`docs/decisions/spacing-rations-mechanisms.md`).
 
 **The tier marker is a pre-filter, not the authority.** If an item passed as normal
-and the work turns out to touch an elevated path (`CLAUDE.md` →
+and the work turns out to touch an elevated path (`AGENTS.md` →
 `elevated-paths`), run the gate anyway, record the verdict on the PR, and treat it
 as this run's elevated item for spacing.
 
@@ -842,8 +842,8 @@ unbounded improvement list is another diary, and three forces a choice. Each nam
 four things, and a proposal missing any of them is not ready to file:
 
 1. the finding it came from, cited as the journal line it appears on;
-2. the part to change — a skill, an agent spec, a hook, a rule file, `CLAUDE.md`,
-   the CI workflow;
+2. the part to change — a skill, an agent spec, a hook, a rule file, `AGENTS.md`,
+   `CLAUDE.md`, the CI workflow;
 3. the change, concretely enough to diff;
 4. how the next run would prove it worked — the observation that would differ.
 
@@ -858,7 +858,7 @@ node --input-type=module -e '
   const a = await import("./.claude/scripts/queue/plan-md.mjs");   // or github-issues / jira
   console.log(await a.proposeTriage({
     finding: "<the journal line it came from>",
-    part:    "<skill | agent | hook | rule | CLAUDE.md | workflow>",
+    part:    "<skill | agent | hook | rule | AGENTS.md | CLAUDE.md | workflow>",
     change:  "<concretely enough to diff>",
     proof:   "<the observation that would differ next run>",
     // a pair: what the probe touched, and what is concluded from it. The
@@ -961,9 +961,34 @@ three poisons the only channel by which this project learns.
   underneath it:
 
   ```bash
-  node .claude/scripts/revalidate.mjs --point BEFORE_CLOSE --ticket <item-id>
+  node .claude/scripts/revalidate.mjs --point BEFORE_CLOSE --ticket <item-id> \
+    --merge-commit "$(gh pr view <pr> --json mergeCommit -q .mergeCommit.oid)"
   ```
 
+  `--merge-commit` names the exact SHA the tracker's own PR metadata records as
+  THIS item's merge commit — one piece of evidence among several that let a
+  `targetSha` move which is nothing but that merge read as `CURRENT` instead
+  of `claim:scope` drift. Resolve it from the PR just merged, by name, never by
+  reading `git log` text, and only after the merge has landed and been
+  fetched. Omitting it (the item has not merged yet, or an older loop that
+  predates this flag) leaves any target movement holding exactly as it did
+  before this flag existed — it is purely additive to that default. Naming the
+  SHA is necessary but never sufficient: the exemption also requires the
+  target to have advanced by EXACTLY ONE commit — a genuine squash merge; a
+  merge commit or any multi-commit range still holds
+  (`test/template/revalidate.test.ts` (absent in a generated rig) › "a foreign
+  commit plus the real merge in the same range, --merge-commit correctly
+  naming the real one") — and it binds to THIS checkout: the named commit's
+  tree must equal `HEAD`'s tree here, and `HEAD` must still be the pre-merge
+  checkout, not one already fast-forwarded onto the merge
+  (`test/template/revalidate.test.ts` (absent in a generated rig) › "a single
+  FOREIGN commit named as --merge-commit does not exempt it — reproduces the
+  gate-hold attack and proves it now holds" and › "HEAD already at the merge
+  commit is vacuous, and still holds (a fast-forwarded checkout must not
+  self-satisfy the exemption)"). That binding stops a lazy or mistaken flag,
+  not an adversary who controls this run's own checkout — see
+  `isOwnMergeAdvance` in `claim-records.mjs` for the exact limit.
+
   It compares the tracked claim's `scope` and `commentary` fingerprint sets;
   commentary becomes hold-authoritative only here. Marker/take-up movement is
   retained in evidence but cannot decide drift. A missing claim is

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

@@ -94,9 +94,9 @@ is a booby trap: someone will hit it, not understand it, and route around it.
 - [ ] The rule is written down, with the hook named next to it
 - [ ] The hook guards **one** invariant, and its scope is as narrow as the rule
 
-## A candidate that is already sitting there
+## Choosing a candidate
 
-The stack rules say service code logs through the shared structured logger, never
-`console.log` — and nothing enforces it. That is the invariant the shipped example
-encodes, so if the rule matters in your project, promoting the example into a real
-hook is a copy, a rename and a wiring line.
+Start from a rule that already matters in this project and has been violated or
+missed in review. Do not invent a sample architecture rule just to exercise this
+skill: the hook must protect a real local invariant, and its test must demonstrate
+the exact violation it blocks.

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

@@ -257,7 +257,7 @@ blockers.
    - `security-scanner` when the diff touches auth, secrets or configuration,
      input parsing, file handling, new outbound calls, dependency changes;
    - `prose-reviewer` when the diff touches a rule file, a skill, an agent spec,
-     a decision record under `docs/decisions/`, `CLAUDE.md` or the README — a
+     a decision record under `docs/decisions/`, `CLAUDE.md`, `AGENTS.md` or the README — a
      rulebook that overstates its own enforcement fails silently and in the
      direction of false confidence;
    - an infrastructure review when it touches infrastructure (the stack layer

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

@@ -12,9 +12,9 @@ directories, with one `.git`. Without it, an unattended run and a hand-driven
 session share a working tree and overwrite each other's edits.
 
 **Use one when** anything else may touch this repo while you work — an
-unattended `loop` run, a colleague, a second Claude session. A single attended
-session on a quiet repo can just use a branch; the discipline that is never
-optional is the branch, not the worktree.
+unattended `loop` run (opt-in workflow layer), a colleague, a second Claude
+session. A single attended session on a quiet repo can just use a branch; the
+discipline that is never optional is the branch, not the worktree.
 
 ## Start
 

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

@@ -1,6 +1,6 @@
 name = "code-reviewer"
-description = "Reviews a completed change against the checklist before a PR is opened or merged. Use after any non-trivial implementation work, and always before opening a PR 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."
+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 that reaches the `model` lane — everything the two cheap lanes do not claim (code, a rulebook document, an unclassifiable path, a derived artifact git does not report as drift, or anything a risk flag escalated), decided by `decision-router.mjs` where the opt-in workflow layer is installed, or by the same rule applied by hand otherwise. 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."
+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** — changes that bypass module ownership or layer\n   boundaries the repository itself declares. See any applicable architecture\n   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 whoever runs that check holds on it —\n  `pr-ship` where the opt-in workflow layer is installed, the session itself\n  running `node .claude/scripts/verdict.mjs coverage` by hand otherwise: no\n  hook runs it either way, so skipping the gate skips this with it."

package/templates/agent-os/universal/.codex/agents/implementation-agent.toml

@@ -0,0 +1,6 @@
+name = "implementation-agent"
+description = "Writes the minimum production code that makes an existing failing test pass — the Green step of TDD, and the Refactor that follows it. Use for ordinary implementation work once test-writer has produced the failing test."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = "You make a failing test pass. You are the Green step of TDD, and the Refactor\nthat keeps it green — never the Red step, and never the reviewer of your own\nwork.\n\n## Scope — hard boundaries\n\n- You start from a failing test that already exists. If there is none, stop\n  and say so: the test comes first, from `test-writer`.\n- You never delete, skip, weaken or rewrite a test to make it pass. If a test\n  looks wrong, stop and surface the conflict instead of editing it.\n- You change only what the task needs. Unrelated files, formatting sweeps and\n  speculative abstractions are out of scope.\n- You do not commit, push, merge or open pull requests; the session that\n  dispatched you owns the branch and the gates.\n\n## How you work\n\n1. Read the failing test and the code around it; follow the repository's\n   rules in `AGENTS.md` and `.claude/rules/`.\n2. Write the smallest change that makes the test pass, in the style of the\n   surrounding code.\n3. Run the new test, then the suite, lint and typecheck the rules name.\n   Report a red check as information; never retry it until it passes.\n4. Refactor only with the tests green, then run them again.\n5. Report back: what you changed and why, which checks you ran with their\n   results, and anything you found but did not change.\n\n## Judgment lines\n\n- When the change reaches an elevated area the task was not already tiered\n  for, stop and say so before changing it.\n- When two rules in the repository conflict, stop and name both.\n- Prefer deleting code to adding it when both satisfy the test."