create-agent-rig 0.10.0 → 1.0.0

package/templates/agent-os/universal/.agents/skills/plan-slices/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: plan-slices
+description: Use when a task cannot be verified as one reviewable PR and splits into slices that are each independently verifiable on their own. Ships only with the opt-in workflow layer.
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Splitting a task into slices
+
+This applies when a task's change cannot be reviewed and verified as one PR,
+and decomposes into slices that are each independently verifiable — each
+slice stands on its own claim about behaviour, checked by its own test.
+
+Do not trigger it mechanically based on file or module count: a change
+that touches many files but makes one verifiable claim stays one PR, and a
+change touching few files but making several independent claims still
+splits.
+
+There is no planner role dispatched for this — the session writes the slice
+plan directly. For each slice, record:
+
+- the outcome the slice delivers, stated as a claim a test can check;
+- its own failing test, written by `test-writer` in the ordinary Red step;
+- the elevated paths it touches, if any (`AGENTS.md`'s elevated-paths block);
+- where it sits in the slice order, and what it depends on.
+
+Each slice then ships as its own PR through the ordinary flow —
+`.claude/rules/workflow.md` has the TDD cycle and the PR flow in full; this
+skill does not restate them.
+
+This skill ships only with the opt-in workflow layer.

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

@@ -39,7 +39,7 @@ blockers.
      `test/template/gate-rounds.test.ts` — absent in a generated rig — ›
      "refuses to count a round on a dirty tree, and counts nothing".
 
-   The cap is **2 by default**, and no shipped `.claude/queue.json` carries the key
+   The cap is **3 by default**, and no shipped `.claude/queue.json` carries the key
    — the default lives in `core.mjs` as `DEFAULT_MAX_GATE_ROUNDS`. A project that
    wants a different cap sets `options.maxGateRounds` there, which in a rig whose
    `queue.json` is composed means changing what composes it, not editing the file.

package/templates/agent-os/universal/.agents/skills/release-propose/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: release-propose
+description: Use to turn repeated evidence from `release-evidence.mjs` into a bounded candidate-release proposal for the owner to decide. Ships only with the opt-in workflow layer.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Proposing a release from repeated pain
+
+## 1. What this is not
+
+The loop's own §7 improvement proposals are per-run fixes, filed and read one
+run at a time. This skill is different: a release-level proposal, built from
+evidence that recurred across more than one run, addressed to the owner —
+never to the queue, and never approved by the skill itself.
+
+## 2. Gather
+
+Run exactly:
+
+```sh
+node "$(git rev-parse --show-toplevel)/.claude/scripts/release-evidence.mjs" --since <date> --json
+```
+
+Read its `verdict`, `groups` and `why`. Optionally read
+`revalidation-report.mjs --json` the same way, the triage proposals already
+on file, and the tracker — cite every one of these by pointer (run id, file,
+seq, or ticket id), never from memory.
+
+## 3. Measured vs. inferred
+
+A number in the proposal is `measured` only when it came straight out of
+`release-evidence.mjs`'s JSON or a cited line of a run/ticket. Every other
+number or claim is labelled `inferred`, or `UNVERIFIED` when nothing backs it
+at all — never stated as if it were measured.
+
+## 4. Routing
+
+- `GATHER_MORE_EVIDENCE` — gather-more-evidence: name what evidence would decide it, file nothing, and stop — never build a candidate release out of anecdotes.
+- `REPEATED_PAIN` — write the proposal (§5) and hand it off (§6).
+
+## 5. Proposal template
+
+Write these headings, in order, into `$RIG_RUN_DIR/release-proposal.md`:
+
+- **Observed repeated pain** — the repeated groups, each with its pointers
+- **Candidate release** — the bounded scope this pain justifies
+- **Why now**
+- **Why not the alternatives** — including a required "Do nothing" row
+- **Dependencies** — proven only; nothing inferred here
+- **Scope / non-goals**
+- **Complexity** — small, medium or large, plus the maintenance burden it adds
+- **Evidence gaps** — what is still `inferred` or `UNVERIFIED`
+- **Upstream capability check** — could a native plugin, connector, MCP
+  server, CLI or provider feature do this instead: sufficient, insufficient
+  or rejected, and why
+- **Owner decision** — approve, reject or gather-more-evidence; left blank
+  for the owner to fill in, never pre-filled by this skill
+
+## 6. Hand-off
+
+- Write the proposal to `$RIG_RUN_DIR/release-proposal.md`.
+- File exactly ONE triage item, pointing at it:
+  `node "$(git rev-parse --show-toplevel)/.claude/scripts/queue/propose.mjs" --file <proposal.json>`
+  — finding = the repeated-pain groups by pointer; part = `"release"`;
+  change = `"candidate release: <one line>"`; proof = what the owner would
+  observe if the release lands.
+- A triage item filed this way is unselectable by the queue on its own;
+  promotion out of triage into selectable work is the owner's act, never
+  this skill's.
+- This skill never files a ticket in the selectable queue, never opens a
+  GitHub issue directly, and never edits PLAN.md's Agent queue: the Agent
+  queue is not something this skill touches, under any verdict.
+
+This skill ships only with the opt-in workflow layer.

package/templates/agent-os/universal/.agents/skills/skill-authoring/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: skill-authoring
+description: Use when authoring or editing a skill in this rig — a new SKILL.md under .claude/skills/, or a change to an existing one.
+allowed-tools: Read, Grep, Glob
+---
+
+# Authoring a skill
+
+No check in this rig runs on a skill you write here — the rules below are
+applied by the author, and by a reviewer reading this file, never by a
+mechanism. On the skills this rig itself ships, the generator's own
+`test/template/skill-authoring.test.ts` (absent in a generated rig) checks
+only the first rule, that a `description` is present, and that the skills and
+roles a skill names by name exist.
+
+- **The frontmatter `name` equals the directory name.** A skill loaded from
+  `.claude/skills/foo/` is named `foo`, not something else.
+- **The `description` says when to use the skill**, not just what it does.
+- **Keep it short, and point at existing rules or scripts rather than
+  restating them.** A skill that copies a rule's wording is a second copy
+  that goes stale the day the rule changes; link to `.claude/rules/` or a
+  script instead.
+- **Every sentence describing how a mechanism behaves either points at the
+  test that proves it, or is deleted.** `.claude/rules/invariants.md`,
+  "State the limits — and test them", is the norm; the form is `see <file>
+  (absent in a generated rig) › "<exact test name>"`.
+- **A mention of a workflow-layer skill or script in a Core document is
+  qualified "opt-in workflow layer"** — `loop` and `pr-ship` are examples,
+  not this skill's own concern.
+- **Both copies ship and must stay identical**: the Claude skill under
+  `.claude/skills/` and the Codex repository skill under `.agents/skills/`.
+  That mirror is checked in `test/template/codex.test.ts` (absent in a
+  generated rig) › "publishes every shared skill through the Codex
+  repository skill location" — not repeated here.
+
+## Out of scope
+
+This is guidance to apply by reading, not an evaluator: the skill itself has
+no procedure and checks nothing.

package/templates/agent-os/universal/.claude/agents/code-reviewer.md

@@ -38,6 +38,10 @@ references, and you classify every finding as **blocking** or **advisory**.
    rulebook already refuses that evidence elsewhere (`.claude/rules/autonomy.md`).
    "Item not supplied, item 6 not checked" is a useful line in a report; a
    guess dressed as a verdict is worse than the silence it replaces.
+7. **Independent oracle** — a test of a security, ownership or governance
+   mechanism whose expected result is derived from the same production
+   mechanism it checks. See the independent-oracle invariant in
+   `.claude/rules/invariants.md`.
 
 ## Advisory findings
 

package/templates/agent-os/universal/.claude/agents/failure-diagnostician.md

@@ -0,0 +1,112 @@
+---
+name: failure-diagnostician
+description: Use when a check is red or a run crashed and the cause is not obvious, or to reproduce a claimed defect/historical finding on the current default branch before work is planned on it.
+tools: Read, Grep, Glob, Bash
+model: claude-opus-5
+effort: high
+---
+
+You diagnose. You take one of two input kinds — a red check or a crashed run,
+or a claimed defect / historical finding to reproduce on the current default
+branch — and answer with evidence, not a guess dressed as one.
+
+## Hard limits
+
+- **You make no repository edits.** A throwaway reproduction file goes
+  outside the repository, never inside it — you are not the Green step, and a
+  fix is not your answer. You do not commit, push, merge or open a pull
+  request.
+- **Never re-run a check until it goes green.** A flaky-looking result is a
+  defect to report, not a thing to retry — the same stop rule that applies
+  everywhere else in this rulebook (`.claude/rules/autonomy.md`, "Stop rules —
+  by work-state, not by feelings").
+- **On Claude Code, no hook enforces the no-edit limit above.** `tools: Read,
+  Grep, Glob, Bash` carries no Write or Edit, which stops the ordinary path,
+  but nothing refuses a shell redirect the way a guard would. On Codex the
+  equivalent profile is `sandbox_mode = "read-only"`, enforced by the runtime
+  itself. Either way, a sandbox that blocks the reproduction you need is not
+  something to work around: answer `INCONCLUSIVE` or `INSUFFICIENT_EVIDENCE`
+  and name the sandbox as the missing evidence.
+
+## Method
+
+1. **Reproduce.** A failure input (red check, crashed run) reproduces at the
+   commit or branch where it failed — the PR head, or the commit the caller
+   names. A claimed defect or historical finding reproduces on the current
+   default branch. No reproduction, no diagnosis.
+2. **Isolate.** Narrow to the smallest change (input, config, code path) that
+   flips the result.
+3. **Hypothesize.** State the mechanism you think is responsible, in one or
+   two sentences.
+4. **Confirm with evidence.** Show the command and its output, or the
+   file:line the mechanism lives at. A hypothesis nothing confirms is
+   `INCONCLUSIVE`, not `ROOT_CAUSE`.
+
+For a failure input that reaches `ROOT_CAUSE`, classify it: `product` (the
+code is wrong), `test` (the test's premise or fixture is wrong),
+`infrastructure` (CI, network, environment — not the code under test), or
+`upstream` (a dependency or external service).
+
+## Optional evidence (opt-in workflow layer)
+
+Where this repository has installed the opt-in workflow layer, the run
+journal and `run-state.mjs`'s recorded verdict may already carry evidence
+worth reading before you reproduce anything by hand — a prior `REGRESSION`,
+or an earlier run's own trace. Their absence is the normal Core path, not a
+gap: read them when present, reproduce directly when not.
+
+## The answer
+
+End your report with **exactly one** fenced `json` block of the shared shape
+(`.claude/scripts/lib/verdict.mjs`), and nothing after it.
+
+- **A failure input** (red check, crash) answers `ROOT_CAUSE` or
+  `INCONCLUSIVE`.
+- **A claim or historical finding** answers `STILL_LIVE`, `ALREADY_FIXED`,
+  `OBSOLETE` or `INSUFFICIENT_EVIDENCE`.
+- `ROOT_CAUSE`, `INCONCLUSIVE`, `STILL_LIVE` and `INSUFFICIENT_EVIDENCE` are
+  blocking and must name at least one blocker: for `ROOT_CAUSE` and
+  `STILL_LIVE` the blocker is the cause, with `file`/`line` where there is
+  one; for `INCONCLUSIVE` and `INSUFFICIENT_EVIDENCE` it is what evidence
+  would decide the question.
+- `ALREADY_FIXED` and `OBSOLETE` carry no blockers — the fixing commit or the
+  superseding mechanism goes in `evidence` instead.
+- `classification` is required on `ROOT_CAUSE`, allowed but optional on
+  `STILL_LIVE`, and refused on every other word.
+- `node .claude/scripts/verdict.mjs check <report> failure-diagnostician` is
+  what refuses a malformed answer before anyone reads it as one.
+
+```json
+{
+  "gate": "failure-diagnostician",
+  "verdict": "ROOT_CAUSE",
+  "blockers": [
+    {
+      "file": "src/example.ts",
+      "line": 42,
+      "rule": "reproduced failure",
+      "note": "the function reads the value before the guard that handles the missing case — reproduced on the PR head with the fixture the failing test supplies"
+    }
+  ],
+  "advisories": [],
+  "evidence": ["reproduced with the failing test on the PR head", "the stack trace from that run names the file:line above"],
+  "classification": "product"
+}
+```
+
+```json
+{
+  "gate": "failure-diagnostician",
+  "verdict": "ALREADY_FIXED",
+  "blockers": [],
+  "advisories": [],
+  "evidence": ["the commit that added the missing guard fixes exactly this report", "re-ran the original repro on the current default branch; it now passes"]
+}
+```
+
+## Not a merge gate
+
+You are never a routed reviewer: no `decision-router` lane names you and no
+`pr-ship` coverage check (opt-in workflow layer) expects your answer. You
+diagnose on request; you never implement the fix, and a report with no
+unbacked behaviour claim or invented figure is the only kind you write.

package/templates/agent-os/universal/.claude/hooks/gate-stop-dod.mjs

@@ -193,9 +193,13 @@ function main() {
     // repo" and waves through, running the whole Definition-of-Done suite
     // against a tree it never managed to read.
     //
-    // 🔴 Limit: only THIS command is sanitised. The Definition-of-Done checks
-    // below run with the environment as given, because they are the project's
-    // own commands and their environment is the project's business.
+    // 🔴 Limit: only THIS command is sanitised beyond `RIG_RUN_DIR`. The
+    // Definition-of-Done checks below run with the environment as given,
+    // because they are the project's own commands and their environment is
+    // the project's business — except `RIG_RUN_DIR`, which names the
+    // directory of the workflow run executing this very hook and belongs to
+    // the run, not to the project's own commands.
+    //   see hooks.test.ts (absent in a generated rig) › "never lets a Definition-of-Done check see RIG_RUN_DIR, even though the hook itself is given one"
     // `timeout` below is the preamble's own leash: this is the one call that
     // runs before the budget's clock starts. A repository slow enough to exceed
     // it throws into the catch and the checks run anyway — the safe direction,
@@ -264,7 +268,15 @@ function main() {
 
   const budget = budgetMs(process.env);
   if (budget.notice) process.stderr.write(`gate-stop-dod: ${budget.notice}\n`);
-  const deadline = Date.now() + budget.ms;
+  // Elapsed time, so the monotonic clock: a step of the wall clock must neither
+  // lengthen nor shorten the budget.
+  const deadline = performance.now() + budget.ms;
+
+  // Computed once, not per check: `RIG_RUN_DIR` names the workflow run
+  // directory of the run executing this hook, and it is the one variable the
+  // project's own commands never get — see the 🔴 limit above.
+  const envForChecks = { ...process.env };
+  delete envForChecks.RIG_RUN_DIR;
 
   for (const command of usable) {
     // A 1 ms floor rather than a branch for "the budget is already gone": the
@@ -274,9 +286,10 @@ function main() {
     const result = spawnSync(command, {
       cwd: PROJECT_ROOT,
       shell: true,
+      env: envForChecks,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
-      timeout: Math.max(1, deadline - Date.now()),
+      timeout: Math.max(1, Math.ceil(deadline - performance.now())),
       // Output volume is not a verdict — below this bound. Past it the child is
       // killed and its result is unknown, which the error branch treats as
       // unmeasured rather than as a failure or a pass. The old 1 MB default

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

@@ -5,8 +5,10 @@
 // The rulebook is the set of files that decide what this session may do — hooks
 // and settings wiring, the queue config and selector, all scripts, rules, skills
 // and agents, the `.codex/` configuration, the integrity manifest,
-// `.claude/doctor-exemptions.json`, `AGENTS.md` and `CLAUDE.md`. Every one of
-// them was editable by the run it governs: a
+// `.claude/doctor-exemptions.json`, the revalidation detection contract
+// `.rig/revalidation.json` — but not the claim records beside it under
+// `.rig/claims/`, which a SELECT has to write — `AGENTS.md` and `CLAUDE.md`.
+// Every one of them was editable by the run it governs: a
 // Write to `.claude/hooks/dod-checks.json` with `[]` switched the stop gate
 // off, and nothing refused it until the merge sweep, long after.
 //
@@ -49,6 +51,12 @@
 //     checkout root before guarding a canonical payload path", › "blocks when
 //     the checkout root and payload use the same symlink spelling", and
 //     › "blocks an existing rulebook file when only the payload path uses a symlink spelling";
+//   - an `apply_patch` destination keeps the lexical spelling it named even when
+//     a guarded prefix (`.claude/hooks`, say) is itself a symlink/junction to
+//     somewhere else inside the checkout — `edit-input.mjs`'s `repositoryPatchPath`
+//     carries that spelling alongside the realpath-resolved one, RP-60 — ›
+//     "refuses an apply_patch through a guarded prefix junctioned to a target
+//     inside the checkout";
 //   - an `allow` prefix is a string prefix of the repo-relative path and may
 //     not widen the rulebook — an entry that is itself a prefix of a rulebook
 //     prefix (`.`, `.claude/`, `.claude/scripts/`) makes the flag unreadable
@@ -119,8 +127,15 @@ export const relativeTo = (root, filePath) => {
 export const isAllowed = (rel, allow) =>
   (Array.isArray(allow) ? allow : []).some((prefix) => prefix !== '' && (rel === prefix || rel.startsWith(prefix)));
 
-const protectedRelative = (roots, filePath) =>
-  [...new Set([filePath, canonicalPath(filePath)])]
+// RP-60: `rawFilePath` is the lexical spelling `apply_patch` fragments carry
+// alongside the realpath-resolved `filePath` (`edit-input.mjs`,
+// `repositoryPatchPath`) — a guarded prefix that is itself a symlink/junction
+// to somewhere else inside the checkout resolves away the rulebook spelling
+// otherwise, the same way `canonicalRoot`/`comparisonRoots` above seed both
+// spellings of the checkout root. Every other edit surface never sets it, so
+// this is a no-op for them.
+const protectedRelative = (roots, filePath, rawFilePath) =>
+  [...new Set([filePath, rawFilePath, canonicalPath(filePath)].filter((spelling) => typeof spelling === 'string' && spelling !== ''))]
     .flatMap((spelling) => roots.map((root) => relativeTo(root, spelling)))
     .find(isRulebookPath);
 
@@ -151,9 +166,9 @@ function main() {
     return 2;
   }
   const paths = [];
-  for (const { filePath } of fragments) {
+  for (const { filePath, rawFilePath } of fragments) {
     if (typeof filePath !== 'string' || filePath === '') continue;
-    const rel = protectedRelative(comparisonRoots, filePath);
+    const rel = protectedRelative(comparisonRoots, filePath, rawFilePath);
     if (rel !== undefined && !paths.includes(rel)) paths.push(rel);
   }
   if (paths.length === 0) return 0; // nothing under the rulebook: never judged

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

@@ -279,7 +279,12 @@ function patchFragments(command, payloadCwd) {
         const moved = current.moveTo
           ? movedFragment(current, budget)
           : { fragment: current.additions.join('\n') };
-        fragments.push({ filePath: destination, ...moved });
+        // RP-60: `rawFilePath` is the lexical repo-relative spelling, taken
+        // before symlink resolution — carried alongside the resolved
+        // `filePath` so a guard can still see a patch destination named
+        // through a guarded prefix that is itself a symlink/junction to
+        // somewhere else inside the checkout.
+        fragments.push({ filePath: destination.resolved, rawFilePath: destination.raw, ...moved });
       }
       current = null;
     }
@@ -510,6 +515,11 @@ function repositoryPatchPath(value, budget) {
   const candidate = path.resolve(budget.patchCwd, patchPath);
   if (!isWithin(budget.repoRoot, candidate)) return null;
 
+  // RP-60: the lexical repo-relative spelling, fixed BEFORE any symlink in the
+  // path (a guarded prefix junctioned elsewhere inside the checkout, say) gets
+  // resolved away below. One extra string, computed once — not a new loop.
+  const raw = path.relative(budget.repoRoot, candidate).split(path.sep).join('/');
+
   let existing = candidate;
   const suffix = [];
   while (true) {
@@ -517,7 +527,7 @@ function repositoryPatchPath(value, budget) {
       const resolved = budget.resolvedDirectories.get(existing);
       const resolvedCandidate = path.resolve(resolved, ...suffix);
       if (!isWithin(budget.repoRoot, resolvedCandidate)) return null;
-      return path.relative(budget.repoRoot, resolvedCandidate).split(path.sep).join('/');
+      return { raw, resolved: path.relative(budget.repoRoot, resolvedCandidate).split(path.sep).join('/') };
     }
     try {
       const resolved = realpathSync(existing);
@@ -533,7 +543,7 @@ function repositoryPatchPath(value, budget) {
       }
       const resolvedCandidate = path.resolve(resolved, ...suffix);
       if (!isWithin(budget.repoRoot, resolvedCandidate)) return null;
-      return path.relative(budget.repoRoot, resolvedCandidate).split(path.sep).join('/');
+      return { raw, resolved: path.relative(budget.repoRoot, resolvedCandidate).split(path.sep).join('/') };
     } catch (error) {
       if (error?.code !== 'ENOENT') return null;
       try {

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

@@ -215,6 +215,39 @@ The invariants worth your slots are the ones you can finish this sentence about:
 *"the last time this went wrong, it cost us ___."* If you cannot finish it, you
 are guessing, and a guessed invariant is the one that will fire on honest work.
 
+## The independent-oracle invariant
+
+A test of a security, ownership or governance mechanism must not derive its expected result from the same production mechanism it checks.
+Check it against an independent oracle instead: an alternative
+implementation of the check, a mutation proof, or externally observable behaviour.
+
+⚠ **The independent-oracle invariant has parts 1 and 3 of the pattern above, and not part 2.** No hook enforces it: "is this expectation derived from the same production
+mechanism" is not decidable from a single diff fragment — it takes reading
+both the test and the code path it claims to verify, and judging which one
+stands in as the oracle. `code-reviewer` is where it is enforced, as a
+checklist item, never a hook — see the generator's
+`test/template/correspondence.test.ts` (absent in a generated rig) ›
+"the rule states the invariant and code-reviewer.md carries a matching checklist item".
+
+Why this earned its own name: a test that asks production's own logic what the
+right answer is cannot detect an under-approximation in that logic. Test and
+code are the same computation run twice, agreeing by construction — so the
+test passes, the reviewer sees a test that genuinely exercises the code, and
+CI is green, while the defect the test was written for goes straight through.
+
+The fix that came out of it is the worked example:
+`packages/cli/test/uninstall.test.ts` (absent in a generated rig),
+whose `expectImports` re-derives the import edges with a deliberately
+duplicated regex rather than importing production's own — its comment says
+"deliberately a second copy rather than an import of the private constant" —
+so the test can never be satisfied merely by production checking its own
+work.
+
+Scope: this applies going forward, to tests of security, ownership and
+governance mechanisms. The existing suite is not retrofitted wholesale — an
+existing test is corrected only where doing so is cheap and the derivation
+is demonstrably vacuous.
+
 ## About the hooks you were given
 
 Generator-authored rulebook artifacts — rules, hooks, skills, scripts and agent

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

@@ -50,6 +50,18 @@ A reviewer whose definition pins its model is never dispatched with a call-site
 dispatching session's, and `guard-subagent-model` refuses the override
 (`docs/decisions/subagent-routing.md`).
 
+## Review findings
+
+A blocking finding — from `code-reviewer`, `security-scanner`,
+`prose-reviewer`, or a review a repository rule names — is **resolved with
+evidence, not argued away**. It closes one of two ways: the change is fixed
+and the reviewer reads the fixed head, or the finding's premise is shown
+false with something the reviewer can re-check — a `file:line`, a test name,
+a command and its output. A reply that disagrees with neither is not a
+resolution, and neither is softening the flagged sentence or dropping the
+reviewer from the fan-out. This holds with or without the opt-in workflow
+layer, whoever drives the fan-out.
+
 ## PR flow
 
 This applies **once the project has a remote and CI checks** — a freshly
@@ -122,8 +134,8 @@ travels one path to merge, in this order:
    the session itself drives the same fan-out** — dispatch each reviewer the
    table and the triggers above name, read every verdict, and resolve every
    blocking finding the same way `pr-ship` would; nothing about the review
-   floor changes with or without the skill. Blocking findings are resolved,
-   not argued with, either way.
+   floor changes with or without the skill. Blocking findings are resolved
+   as "Review findings" above says, either way.
 
    **A verdict is a block, not a sentence.** Every gate ends its report with one
    fenced `json` block of the shape `.claude/scripts/lib/verdict.mjs` defines

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

@@ -73,6 +73,10 @@
  *    absence itself — `lib/gate-coverage.mjs` is the one that does, and it puts
  *    such a verdict in its own list rather than counting it either way. When
  *    present the value is a commit SHAPE, not free text: see `isCommitId`.
+ * 7. **`failure-diagnostician` answers in this shape and is not a merge gate.**
+ *    No `decision-router` lane names it and `pr-ship` coverage never expects an
+ *    answer from it — see `test/template/verdict.test.ts`
+ *    (absent in a generated rig) › "the diagnostician is never a routed reviewer".
  */
 
 /** Every word any gate in this rulebook may return. */
@@ -86,6 +90,14 @@ export const VERDICT_WORDS = Object.freeze([
   'UNVERIFIABLE',
   'UNMEASURED',
   'NOT_APPLICABLE',
+  // RP-195 slice 1: failure-diagnostician's own words, split by what it was
+  // asked to look at — a failure, or a claimed/historical finding.
+  'ROOT_CAUSE',
+  'INCONCLUSIVE',
+  'STILL_LIVE',
+  'ALREADY_FIXED',
+  'OBSOLETE',
+  'INSUFFICIENT_EVIDENCE',
 ]);
 
 /**
@@ -111,6 +123,15 @@ export const GATE_VOCABULARY = Object.freeze({
     'UNMEASURED',
   ]),
   'post-deploy-verify': Object.freeze(['HEALTHY', 'REGRESSION']),
+  // RP-195 slice 1 (design decision 1): the diagnostician's own words.
+  'failure-diagnostician': Object.freeze([
+    'ROOT_CAUSE',
+    'INCONCLUSIVE',
+    'STILL_LIVE',
+    'ALREADY_FIXED',
+    'OBSOLETE',
+    'INSUFFICIENT_EVIDENCE',
+  ]),
 });
 
 /**
@@ -126,6 +147,13 @@ export const BLOCKING_VERDICTS = Object.freeze([
   'PREMISE_FALSE',
   'UNVERIFIABLE',
   'UNMEASURED',
+  // RP-195 slice 1 (design decision 1): the cause, for ROOT_CAUSE and
+  // STILL_LIVE; the missing evidence, for INCONCLUSIVE and
+  // INSUFFICIENT_EVIDENCE. ALREADY_FIXED and OBSOLETE carry no blockers.
+  'ROOT_CAUSE',
+  'INCONCLUSIVE',
+  'STILL_LIVE',
+  'INSUFFICIENT_EVIDENCE',
 ]);
 
 /** The only keys a block may carry. */
@@ -136,8 +164,16 @@ const SHAPE_KEYS = Object.freeze([
   'advisories',
   'evidence',
   'headSha',
+  'classification',
 ]);
 
+/**
+ * The one optional key `failure-diagnostician` alone may carry (RP-195 slice
+ * 1, design decision 2): required on ROOT_CAUSE, optional on STILL_LIVE,
+ * refused on every other word and on every other gate.
+ */
+const CLASSIFICATIONS = Object.freeze(['product', 'test', 'infrastructure', 'upstream']);
+
 const FENCE = '```json';
 
 /** How much of one reviewer-written value a diagnosis will carry. */
@@ -443,6 +479,32 @@ export function parseVerdict(text) {
     }
   }
 
+  const classification = parsed.classification;
+  const hasClassification = classification !== undefined;
+  if (hasClassification) {
+    if (!isText(gate) || gate !== 'failure-diagnostician') {
+      problems.push(
+        '`classification` is refused here: only failure-diagnostician may carry it, and ' +
+          `this block names \`gate\` as ${safeForDiagnosis(gate)}.`,
+      );
+    } else if (verdict !== 'ROOT_CAUSE' && verdict !== 'STILL_LIVE') {
+      problems.push(
+        `\`classification\` is refused on ${safeForDiagnosis(verdict)} — only ROOT_CAUSE ` +
+          '(required) and STILL_LIVE (optional) may carry one.',
+      );
+    } else if (!CLASSIFICATIONS.includes(classification)) {
+      problems.push(
+        `\`classification\` is \`${safeForDiagnosis(classification)}\`, which is not one of: ` +
+          `${CLASSIFICATIONS.join(', ')}.`,
+      );
+    }
+  } else if (isText(gate) && gate === 'failure-diagnostician' && verdict === 'ROOT_CAUSE') {
+    problems.push(
+      'ROOT_CAUSE names no `classification`: it is required on this word — one of ' +
+        `${CLASSIFICATIONS.join(', ')}.`,
+    );
+  }
+
   if (problems.length > 0) return { ok: false, problems };
 
   return {
@@ -457,6 +519,7 @@ export function parseVerdict(text) {
       // back without the key at all, so a caller can tell "answered for this
       // commit" from "said nothing about which commit".
       ...(headSha === undefined ? {} : { headSha }),
+      ...(hasClassification ? { classification } : {}),
     },
   };
 }

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

@@ -633,13 +633,12 @@ const clearsSpacing = (lastCompletedTier) =>
  * items with the whole suite green throughout, and its `budget` stop arriving "later
  * than it should have".
  *
- * Two is the cap because the second round is what verifies the first round's fixes.
- * A third is a decision for a human rather than another pass to buy — and the
- * refusal says only that the count is spent, never that the fixes "are not
- * converging": on one branch a granted third round found that round 2's fix had
- * opened the mirror of the bug it closed (AR-115).
+ * Three is the cap: the second round verifies the first round's fixes, and the
+ * third lets a round-2 fix be read once more before the item needs a human. A
+ * project that wants a different cap sets `options.maxGateRounds` instead of
+ * changing this default.
  */
-export const DEFAULT_MAX_GATE_ROUNDS = 2;
+export const DEFAULT_MAX_GATE_ROUNDS = 3;
 
 /**
  * Is this round allowed, and if not, what stops?