create-agent-rig 0.10.0 → 1.0.0

package/CHANGELOG.md

@@ -14,6 +14,161 @@ second recorded departure; its own entry states the direction and the reason,
 and this paragraph deliberately does not restate them — a numbering rule with
 two copies of its exceptions is the shape 0.8.0 exists to remove.
 
+## 1.0.0
+
+**The harness-configuration contract is frozen.** Nothing here changes what a
+`create` or `init` installs in a way a 0.10.x rig would notice; what changes is
+that the surface those commands present — their flags, their JSON shapes, their
+exit codes, their verdict and outcome vocabularies, the manifest they write —
+is now a contract with a stated deprecation policy, and a test suite that goes
+red when the document and the code disagree. The major number says that, and
+only that: from here, removing or renaming something in that surface is a major
+bump, and adding to it is a minor.
+
+The rest of this entry is what the rigs themselves gain, down to the last
+section — which is the changes that stayed in the generator, named there so a
+reader does not go looking for them in a rig.
+
+### The contract
+
+What a rig gains here is the promise, not a file: the document and its tests
+live in the generator, and the section at the end of this entry says so.
+
+- **The 1.0 public surface is stated, and so is how it may change** — what is
+  promised, what is explicitly not, and what a deprecation costs (RP-184).
+- **Seven correspondences keep it honest**, each red when either side drifts:
+  the `upgrade` verdict union, the closed set of seven `doctor` check ids, the
+  `setup` outcome values, the manifest keys a fresh `init` writes, the
+  integrations declaration schema against a real `setup add`, the packed tarball
+  carrying no third-party provider payload, and the CI Node matrix against
+  `engines.node` (RP-184).
+
+### Added
+
+- **`failure-diagnostician`** — a read-only agent that reproduces a red check or
+  a claimed defect on the current default branch and answers with one of six
+  checked verdicts, so "is this still live?" is measured before work is planned
+  on it (RP-195).
+- **`diagnose`** — the Core skill that dispatches it, for a failure whose cause
+  is not obvious (RP-195).
+- **`skill-authoring`** — the Core skill for writing a new skill, with
+  structural checks over the ones a rig ships (RP-195).
+- **`plan-slices`** — the workflow-layer skill that cuts a large item into
+  slices that can each be shipped on their own (RP-195).
+- **`release-propose`**, and the `release-evidence.mjs` it reads through — the
+  workflow-layer skill that proposes a release only from repeated,
+  pointer-backed evidence, never from one bad run (RP-203).
+- **`queue/propose.mjs`** — one root-safe entry point for filing a triage
+  proposal, so a session standing in a subdirectory files into the project's
+  real queue rather than a cwd-relative one that does not exist (RP-209).
+
+### Changed
+
+- **The gate-round cap defaults to three**, not two — one round to find, one to
+  fix, one to confirm (RP-210).
+- **The verdict vocabulary carries the diagnosis words** and an optional
+  `classification`, so a diagnostician's answer is checked the same way every
+  other gate's is (RP-195).
+- **An escalation names the diagnostician's verdict.** The `loop` skill no
+  longer escalates a failure as a bare stop; it carries the checked verdict that
+  says whether the failure is live (RP-195).
+
+### Fixed
+
+- **The Definition-of-Done gate no longer leaks the run directory into its own
+  checks.** `gate-stop-dod` passed `RIG_RUN_DIR` down to every configured
+  command, so a project whose tests spawn the queue CLI wrote fixture records
+  into the live run's trace (RP-207).
+- **A closed issue can no longer push open work out of the GitHub queue.** The
+  adapter asks for open and closed items in separate windows and says so on
+  stderr when a window is capped (RP-208).
+- **`upgrade --dry-run` exits 1 where the real run refuses** a symlinked
+  manifest, instead of 0 (RP-206).
+- **`guard-rulebook` no longer loses the path an `apply_patch` actually wrote
+  to.** When a guarded prefix such as `.claude/hooks` is a junction or symlink
+  to a directory inside the same checkout, the resolved spelling no longer
+  starts with a protected prefix, and an unattended `apply_patch` through it was
+  allowed. Both spellings are now compared. The four Claude edit surfaces were
+  never affected, and a junction pointing outside the checkout already failed
+  closed (RP-60).
+
+### Rulebook
+
+- **The revalidation detection contract is governance input.**
+  `.rig/revalidation.json` decides whether preflight stops and what the scope
+  fingerprint watches, and an unattended run could rewrite it. It joins the
+  protected rulebook set — as the exact file, because `.rig/claims/` must stay
+  writable for a SELECT to record its own baseline. The matching elevated-path
+  declaration landed in this repository's own rulebook, not in the payload's
+  seed (RP-61).
+- **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; `code-reviewer` enforces it as a checklist
+  item, and the rule says plainly that no hook can (RP-187).
+
+### Generator repository (not a rig-facing change)
+
+- `layers.json` is a declared elevated path of this repository. It is the
+  manifest `init` installs _from_ — it names the paths of each layer and never
+  names itself — so no rig receives it (RP-211).
+- The Memory conformance probe, `scripts/memory-conformance.mjs`, reports a
+  buffer overflow as what it is — a killed child — rather than as a child that
+  could not start. The script is not packed (RP-206).
+- The 1.0 contract document, `docs/command-contract.md`, and the seven
+  correspondence tests that pin it live in this repository; what a rig gains is
+  the promise they hold the commands to, not the files (RP-184).
+
+## 0.10.1
+
+**A fixes-only patch on 0.10.0, plus one narrowing.** Every other entry
+corrects existing behaviour or states a rule the rulebook already follows;
+nothing is added to what `create`, `init` or `upgrade` install beyond the
+corrected files and the Node floor below, and no agent, skill, hook or routing
+row is new.
+
+### Changed
+
+- **The Node floor is raised from `>=20` to `>=22`** (`package.json`'s
+  `engines.node`), matching the only runtime every CI lane still tests — Node
+  20 has been end-of-life since April 2026. The CLI still runs unchanged on
+  any Node 22 or newer (RP-184).
+
+### Fixed
+
+- **`upgrade` no longer crashes on a directory where a rig-owned file
+  belongs.** A tracked path that is a directory or another non-regular entry
+  is reported as a conflict with a reason and left untouched, in `--dry-run`
+  and `--yes` alike, instead of ending in an `EISDIR` stack trace (RP-189).
+- **`upgrade` re-checks a leftover `AGENTS.md.rig-new` before removing it.**
+  The file is removed only while it still holds exactly the rendered
+  `AGENTS.md` bytes, so one edited after the plan was shown is kept, one
+  removed in the meantime no longer crashes the run, and the closing notice
+  reports a removal only when one happened (RP-202).
+- **`upgrade --dry-run` exits 1 where the real run refuses** a non-file at
+  `AGENTS.md.rig-new`, instead of 0 (RP-202).
+- **The Stop gate's budget is measured on the monotonic clock.**
+  `gate-stop-dod` computed its shared deadline from the wall clock, so a clock
+  step lengthened or shortened it (RP-204).
+
+### Rulebook
+
+- `workflow.md` states the review-findings rule as a Core section of its own:
+  a blocking finding closes by a fix the reviewer reads again, or by evidence
+  the reviewer can re-check that its premise is false — with or without the
+  opt-in workflow layer (RP-194).
+- `check-premises` treats a claim about an external API, CLI or library as a
+  premise: backed by a four-part record (version, authoritative source, date,
+  quote or pointer), it holds or is `PREMISE FALSE`; without one it stays
+  `UNVERIFIABLE` (RP-194).
+
+### Generator repository (not a rig-facing change)
+
+- `packages/cli/src/commands/integrations.ts` is a declared elevated path.
+- `scripts/memory-conformance.mjs` names why a rig spawn failed — exit code or
+  signal plus the child's error code — instead of a bare "exit 1" (RP-188).
+- `docs/decisions/agent-roles-1.0.md` records the 1.0 agent-role targets; it
+  is repository-local and not shipped.
+
 ## 0.10.0
 
 Platforms: the packed release candidate is accepted on Linux, Windows and

package/README.md

@@ -100,13 +100,13 @@ MCP wiring goes into Claude Code's `.mcp.json` entry by entry, but into Codex's
 
 ## What Rig installs
 
-| Area               | What you get                                                                                                                                                        |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Rules              | `AGENTS.md`, `CLAUDE.md` and `.claude/rules/`: autonomy tiers (what an agent may do alone), stop rules, TDD workflow and a Definition of Done                       |
-| Guards             | Hooks that refuse bypassing pre-commit, force-pushing a shared branch, destructive `rm`, writing credentials, and ending a session while a configured check is red  |
-| Agents             | `test-writer` and `implementation-agent` for the TDD steps; `code-reviewer`, `security-scanner` and `prose-reviewer` for review — each pinned to a model and effort |
-| Skills             | `worktree-task`, `new-invariant` and `check-premises`                                                                                                               |
-| Lifecycle metadata | `.claude/.rig-manifest.json`: which bytes Rig installed                                                                                                             |
+| Area               | What you get                                                                                                                                                                                                                             |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rules              | `AGENTS.md`, `CLAUDE.md` and `.claude/rules/`: autonomy tiers (what an agent may do alone), stop rules, TDD workflow and a Definition of Done                                                                                            |
+| Guards             | Hooks that refuse bypassing pre-commit, force-pushing a shared branch, destructive `rm`, writing credentials, and ending a session while a configured check is red                                                                       |
+| Agents             | `test-writer` and `implementation-agent` for the TDD steps; `code-reviewer`, `security-scanner` and `prose-reviewer` for review; `failure-diagnostician` to reproduce a failure or a claimed finding — each pinned to a model and effort |
+| Skills             | `worktree-task`, `new-invariant`, `check-premises`, `skill-authoring` and `diagnose`                                                                                                                                                     |
+| Lifecycle metadata | `.claude/.rig-manifest.json`: which bytes Rig installed                                                                                                                                                                                  |
 
 A guard is a check on each edit or command before it runs, not a sandbox. Each
 one states what it does not catch in its own header — `guard-secret-file`, for
@@ -279,7 +279,7 @@ attempted pre-commit bypass.
 
 ## Requirements
 
-- Node ≥ 20. The CLI has no runtime dependencies.
+- Node ≥ 22. The CLI has no runtime dependencies.
 - Git.
 - For Spec Kit only: `uv` and `uvx`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.10.0",
+  "version": "1.0.0",
   "description": "Configure an agent operating system (rules, gates, hooks) for Claude Code and Codex in a new or existing repository — no application scaffolding",
   "keywords": [
     "agent",
@@ -29,7 +29,7 @@
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "packageManager": "pnpm@11.16.0",
   "scripts": {

package/packages/cli/dist/commands/upgrade.js

@@ -149,23 +149,20 @@ async function writableOnDisk(repoDir, rel) {
     }
     return dest;
 }
-/**
- * The file's bytes, or `null` when it is genuinely **absent**.
- *
- * Only "not there" is absence. Any other failure — a permission, a directory
- * where a file should be, a path this command refuses to touch — is rethrown,
- * because "I could not read your file" must never become "so I wrote mine over
- * it": every caller of this treats `null` as grounds to install.
- */
 async function readIfPresent(repoDir, rel) {
+    const dest = await writableOnDisk(repoDir, rel);
+    let stat;
     try {
-        return await readFile(await writableOnDisk(repoDir, rel));
+        stat = await lstat(dest);
     }
     catch (error) {
         if (error.code === 'ENOENT')
-            return null;
+            return { kind: 'absent' };
         throw error;
     }
+    if (!stat.isFile())
+        return { kind: 'non-file' };
+    return { kind: 'file', bytes: await readFile(dest) };
 }
 /**
  * The bytes THIS release would render for AGENTS.md, for THIS project,
@@ -394,7 +391,18 @@ export async function planUpgrade(repoDir, options = {}) {
     // CLAUDE.md's CURRENT content when it holds the shim back.
     const currentBytesByRel = new Map();
     for (const file of files) {
-        const currentBytes = await readIfPresent(repoDir, file.rel);
+        const currentFile = await readIfPresent(repoDir, file.rel);
+        if (currentFile.kind === 'non-file') {
+            actions.push({
+                rel: file.rel,
+                verdict: 'conflict',
+                reason: 'a directory or other non-regular entry exists where this rig-owned file belongs — ' +
+                    'move or remove it by hand; upgrade will leave it untouched',
+                templatePath: file.source,
+            });
+            continue;
+        }
+        const currentBytes = currentFile.kind === 'file' ? currentFile.bytes : null;
         if (currentBytes !== null)
             currentBytesByRel.set(file.rel, currentBytes);
         const recordedInManifest = manifest?.files[file.rel];
@@ -620,7 +628,8 @@ export async function planUpgrade(repoDir, options = {}) {
         nextFiles['CLAUDE.md'] = sha256(heldBytes);
     }
     // Round 5, blocker 3: the rescue file's status is decided HERE, once, at
-    // plan time — never re-probed by `applyUpgrade`, so a dry run and a real
+    // plan time — never re-probed by `applyUpgrade` except to re-verify a
+    // `cleanup` before deleting (RP-192 item 4), so a dry run and a real
     // run report the identical status and every refusal is known before a
     // single byte is written. Round 4 cycle 4's blocker 3 was exactly the
     // alternative: probing the filesystem again inside `applyUpgrade`, AFTER
@@ -710,14 +719,36 @@ export async function planUpgrade(repoDir, options = {}) {
         },
     };
 }
+/**
+ * The complete write set `applyUpgrade` will touch — every `update`/`new`
+ * action plus the manifest itself — each resolved with {@link writableOnDisk}
+ * so a symlinked (or otherwise unsafe) destination is refused before any
+ * write happens. Exported so `--dry-run` (in `index.ts`) can run the exact
+ * same check and refuse with the exact same message wherever the real run
+ * would: one implementation, read by both call sites, rather than a second
+ * copy that could drift from it.
+ */
+export async function preflightWritable(repoDir, plan) {
+    const destinations = new Map();
+    for (const rel of [
+        ...plan.actions
+            .filter(({ verdict }) => verdict === 'update' || verdict === 'new')
+            .map(({ rel }) => rel),
+        MANIFEST_REL,
+    ]) {
+        destinations.set(rel, await writableOnDisk(repoDir, rel));
+    }
+    return destinations;
+}
 /**
  * Write the plan: the `update` and `new` files, then the manifest. Everything
  * else in the plan is a sentence for a human, not an edit.
  */
 export async function applyUpgrade(repoDir, plan, options = {}) {
     const written = [];
+    let removedRescue = false;
     if (options.dryRun === true)
-        return { written };
+        return { written, removedRescue };
     // Round 5, blocker 3: refused BEFORE any write at all — not merely before
     // the manifest write. Round 4 cycle 4 measured that probing the rescue
     // path AFTER the ordinary payload writes left files rewritten and the
@@ -732,15 +763,7 @@ export async function applyUpgrade(repoDir, plan, options = {}) {
     // any file. Then re-check each destination after mkdir and immediately before
     // writeFile, so both pre-existing and newly-visible symlink components are
     // refused.
-    const destinations = new Map();
-    for (const rel of [
-        ...plan.actions
-            .filter(({ verdict }) => verdict === 'update' || verdict === 'new')
-            .map(({ rel }) => rel),
-        MANIFEST_REL,
-    ]) {
-        destinations.set(rel, await writableOnDisk(repoDir, rel));
-    }
+    const destinations = await preflightWritable(repoDir, plan);
     for (const action of plan.actions) {
         if (action.verdict !== 'update' && action.verdict !== 'new')
             continue;
@@ -755,12 +778,12 @@ export async function applyUpgrade(repoDir, plan, options = {}) {
         await writeFile(await writableOnDisk(repoDir, action.rel), content);
         written.push(action.rel);
     }
-    // Round 5: no new filesystem probing here — `plan.agentsRescue` already
-    // says exactly what (if anything) this run does, decided before any write
-    // above ever ran. `would-write` is the only status that writes; `identical`
-    // and `differs` are both "leave it exactly as it is"; `cleanup` is the only
-    // status that deletes; `unsafe` already returned above and `none` does
-    // nothing at all — round 4 cycle 4's "must not affect upgrade" case.
+    // Round 5: `plan.agentsRescue` says what (if anything) this run may do,
+    // decided before any write above ever ran. `would-write` is the only status
+    // that writes; `identical` and `differs` are both "leave it exactly as it
+    // is"; `cleanup` is the only status that deletes, and the one that reads the
+    // file again before it does (below); `unsafe` already returned above and
+    // `none` does nothing at all — round 4 cycle 4's "must not affect upgrade" case.
     if (plan.agentsRescue.holdBack) {
         if (plan.agentsRescue.status === 'would-write') {
             const rendered = plan.contents.get('AGENTS.md');
@@ -774,9 +797,24 @@ export async function applyUpgrade(repoDir, plan, options = {}) {
         }
     }
     else if (plan.agentsRescue.status === 'cleanup') {
-        const rescueDest = await writableOnDisk(repoDir, AGENTS_MD_RESCUE);
-        await unlink(rescueDest);
+        // The one deletion here is re-verified at apply time, the way uninstall
+        // re-checks `recordedHash`: an interactive run applies after its prompt,
+        // so the leftover may have been edited or removed since it was matched.
+        const rendered = plan.contents.get('AGENTS.md');
+        const current = await readRescueFile(repoDir);
+        if (rendered !== undefined &&
+            current.kind === 'file' &&
+            current.bytes.equals(Buffer.from(rendered, 'utf8'))) {
+            try {
+                await unlink(await writableOnDisk(repoDir, AGENTS_MD_RESCUE));
+                removedRescue = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
     }
     await writeManifest(repoDir, plan.manifest);
-    return { written };
+    return { written, removedRescue };
 }

package/packages/cli/dist/index.js

@@ -7,7 +7,7 @@ import { InitError, initFileContents, initProject, planInit } from './commands/i
 import { INTEGRATIONS_VERBS, runIntegrationsCommand } from './commands/integrations.js';
 import { runSetupWizard } from './commands/setup-wizard.js';
 import { execFileRunner, setupSubsystems } from './commands/setup.js';
-import { AGENTS_MD_RESCUE, UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
+import { AGENTS_MD_RESCUE, UpgradeError, applyUpgrade, planUpgrade, preflightWritable, } from './commands/upgrade.js';
 import { CHANGED_SINCE_PLANNING_REASON, UninstallError, applyUninstall, isUnverifiedReason, planUninstall, protectedFileReason, } from './commands/uninstall.js';
 import { makePalette } from './lib/colors.js';
 import { readManifest, sha256 } from './lib/manifest.js';
@@ -499,6 +499,14 @@ async function runUpgrade(rawArgs) {
         const notice = renderAgentsRescueNotice(plan.agentsRescue, true);
         if (notice !== null)
             process.stdout.write(notice);
+        // The same exit the real run gives: `applyUpgrade` refuses this status.
+        if (plan.agentsRescue.holdBack && plan.agentsRescue.status === 'unsafe')
+            return 1;
+        // Same preflight `applyUpgrade` runs before writing anything (a symlinked
+        // manifest or destination, RP-206): thrown here, an `UpgradeError`
+        // propagates to `main()`'s own catch below exactly as it does for the
+        // real run, so both modes report the identical message and exit 1.
+        await preflightWritable(cwd, plan);
         return 0;
     }
     // The plan above is the review step, so it has to be answered before
@@ -562,7 +570,12 @@ async function runUpgrade(rawArgs) {
     // blockers 1/2) means genuinely nothing to add: an ordinary, readable,
     // customised AGENTS.md conflict, or unrelated clutter at the rescue path,
     // both print nothing here at all.
-    const notice = renderAgentsRescueNotice(plan.agentsRescue, false);
+    // A `cleanup` the apply step did not carry out (the leftover changed or went
+    // away after the plan) reports nothing rather than a removal.
+    const rescue = plan.agentsRescue.status === 'cleanup' && !result.removedRescue
+        ? { holdBack: false, status: 'none' }
+        : plan.agentsRescue;
+    const notice = renderAgentsRescueNotice(rescue, false);
     if (notice !== null)
         process.stdout.write(notice);
     return 0;

package/templates/agent-os/subagent-routing.json

@@ -27,6 +27,10 @@
     "security-scanner": {
       "claude": { "model": "claude-opus-5", "effort": "high" },
       "codex": { "model": "gpt-5.6-sol", "effort": "high" }
+    },
+    "failure-diagnostician": {
+      "claude": { "model": "claude-opus-5", "effort": "high" },
+      "codex": { "model": "gpt-5.6-sol", "effort": "high" }
     }
   }
 }

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

@@ -91,13 +91,40 @@ At the **second** entry point this inverts for one case: a test is exactly what
 a behaviour claim, so reading it is the point. The rule above is about not letting a
 test's *name* stand in for what the code does; §4 says which artifacts count.
 
+### External premises
+
+A claim about something this repository does not contain — an external API, a
+CLI, a library — is a premise like any other, and §2 decides whether it is
+load-bearing. "The provider accepts a `--json` flag" or "the SDK retries on 429"
+changes what gets built if it is false. The code here cannot settle it, so this
+is the one case where documentation is the evidence, and it is recorded in four
+parts:
+
+- **version** — the exact version this project uses (the lockfile, the installed
+  binary's own version output), not "latest";
+- **source** — an authoritative one for that version: the vendor's reference
+  documentation, its changelog, or the tool's own `--help`;
+- **date** — when you read it, because documentation changes under a fixed URL;
+- **quote** or pointer — the sentence that says it, short enough to re-check, or
+  the exact section it sits in.
+
+A complete record that supports the claim lets it hold. One that contradicts it
+is `PREMISE FALSE`, and the work stops exactly as it does for a claim the code
+contradicts. The four parts go in the report's `evidence`, and in the blocker's
+`note` when there is one.
+
+A claim missing any of the four stays `UNVERIFIABLE`: being widely believed, or
+true of an earlier version, does not promote it to a fact. This skill adds no
+network tooling — where the session cannot reach the source, the claim is
+`UNVERIFIABLE` and travels as a labelled assumption, as §4 says.
+
 ## 4. The verdict
 
 | Verdict | When | What happens next |
 | --- | --- | --- |
 | `PREMISES HOLD` | every load-bearing claim checked out, or there were none | proceed to the Red step |
-| `PREMISE FALSE` | a load-bearing claim is contradicted by the code | **stop and report** |
-| `UNVERIFIABLE` | a load-bearing claim could not be decided from the code | report it as unverifiable, name what would decide it, and proceed only under a **labelled assumption** |
+| `PREMISE FALSE` | a load-bearing claim is contradicted by the code — or, for an external premise, by its four-part record | **stop and report** |
+| `UNVERIFIABLE` | a load-bearing claim could not be decided from the code — or, for an external premise, has no complete four-part record | report it as unverifiable, name what would decide it, and proceed only under a **labelled assumption** |
 | `UNMEASURED` | **second entry point only:** a sentence you wrote asserts behaviour, and nothing you can point at backs it | **delete the sentence, or turn it into a pointer to the test that proves it** — before the gate |
 
 🔴 **The edit belongs to the calling session, not to this skill.** It reports; the
@@ -223,7 +250,9 @@ is invisible to every gate downstream.
 - **It reads the code, so it only catches what the code can contradict.** A claim
   about runtime behaviour ("this times out in production"), about intent, or
   about a system this repository does not contain is `UNVERIFIABLE` here, not
-  false — say so rather than guessing.
+  false — say so rather than guessing. For an external API, CLI or library the
+  way out is the four-part record "External premises" asks for, which can make
+  the claim hold or prove it false.
 - **Each entry point is one pass, at its own end of the task.** A premise that goes
   false *between* them — a merge lands, a dependency moves — is a staleness stop rule
   (`.claude/rules/autonomy.md`), not this skill. Neither pass watches the other's

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

@@ -0,0 +1,43 @@
+---
+name: diagnose
+description: Use when a check is red or a run crashed and the cause is not obvious, or when a claimed defect or historical finding needs confirming before work is planned on it.
+allowed-tools: Read, Grep, Glob, Bash, Task
+---
+
+# Diagnose before you fix
+
+Stop guessing. A red check or a crashed run is never a thing to retry until
+it goes green — that stop rule is already stated in
+`.claude/rules/autonomy.md` ("Flaky ≠ retry"); this skill does not restate
+it.
+
+## Hand it to `failure-diagnostician`
+
+Give the agent what it needs to reproduce, verbatim:
+
+- for a failure — the exact failure output, the command that produced it,
+  and the commit or branch where it failed;
+- for a claim — the claim's own text, and where it came from (a queue item,
+  a review comment, a prior finding).
+
+Dispatch `failure-diagnostician`. Its method is its own —
+`.claude/agents/failure-diagnostician.md` — not repeated here.
+
+## Check the answer, then act on the word
+
+Save its report to a file and run exactly:
+
+```sh
+node .claude/scripts/verdict.mjs check <report> failure-diagnostician
+```
+
+Exit 1 means it did not answer — that is no diagnosis, not a word to act on.
+
+| Verdict | Action |
+| --- | --- |
+| `ROOT_CAUSE` / `STILL_LIVE` | the failing test first, through `test-writer` — the Red step in `.claude/rules/workflow.md` |
+| `INCONCLUSIVE` / `INSUFFICIENT_EVIDENCE` | stop; escalate in the format `.claude/rules/autonomy.md` ("Escalation format") sets, carrying the verdict's blockers as what would decide the question |
+| `ALREADY_FIXED` / `OBSOLETE` | close the item, citing the verdict's `evidence` |
+
+This is a Core skill: it dispatches no opt-in-workflow-layer machinery, and
+routes on the word alone.

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

@@ -420,7 +420,11 @@ who was not reading the code at the time, and everything downstream — the fail
 test, the implementation, the reviewer comparing diff to item — inherits its
 claims rather than checking them. On `PREMISE FALSE` the item is escalated (§6),
 not repaired in place: a run that silently re-aims its own task has authored work
-for itself, which is the one thing this loop does not do (§8).
+for itself, which is the one thing this loop does not do (§8). A claim
+`check-premises` cannot settle by reading — a claimed defect or a historical
+finding that needs reproducing on the current default branch, not just re-reading — goes to
+`failure-diagnostician` in claim mode instead, never to an unnamed built-in
+subagent.
 
 🔴 **And again at the other end, before `pr-ship`: `check-premises` on the prose the
 task itself wrote** — the rulebook prose the diff touches (the skill defines that set,
@@ -703,7 +707,23 @@ Both then follow the same three steps:
    its clauses: what was *observed* (verbatim errors, not summaries), and the
    single question whose answer unblocks the work. So: what fails, what was tried, the
    current hypothesis, and links to the PR and the failing run where they exist
-   — a premise stop has neither, and its citation stands in for both. **Name the outcome
+   — a premise stop has neither, and its citation stands in for both.
+   **For a red check or an unexplained failure, the current hypothesis is the
+   diagnostician's parsed verdict**: dispatch `failure-diagnostician` with the
+   verbatim failure, save its answer to a file under the run directory, and
+   check it —
+
+   ```sh
+   node .claude/scripts/verdict.mjs check <report> failure-diagnostician
+   ```
+
+   — then carry the parsed verdict (word, `classification`, blockers,
+   evidence) as the hypothesis instead of writing the diagnosis from scratch,
+   with the verbatim failure output still in the comment beside it, covering
+   the "observed" clause the list above already names. A `PREMISE FALSE` or
+   exhausted-cap stop keeps the diagnosis the paragraph above already
+   describes (what the item claimed, or the round count).
+   **Name the outcome
    state in the same comment** — `incomplete` if the diagnosis cannot say **where** it
    stopped (§5: a thin diagnosis that still locates the wall is a `documented-stall`).
    Writing `incomplete` on your own task is uncomfortable and
@@ -847,29 +867,52 @@ four things, and a proposal missing any of them is not ready to file:
 3. the change, concretely enough to diff;
 4. how the next run would prove it worked — the observation that would differ.
 
-Filing is the adapter's `proposeTriage`, which the CLI deliberately does **not**
-expose — `index.mjs` never writes to the QUEUE (`next`, `list`, `hygiene` only), so
-that no accidental invocation can change what the next run is handed. Its one
-write is to the run journal above, and only into a directory the run declared —
-a trace of the selection, never a change to it. Call `proposeTriage` directly:
+Filing is the adapter's `proposeTriage`, reached through the one root-safe entry
+point `.claude/scripts/queue/propose.mjs` — never a relative `import()` typed by
+hand, which breaks the moment the session is standing in a subdirectory
+(`ERR_MODULE_NOT_FOUND` from the import, then an `ENOENT` from a cwd-relative
+`PLAN.md` that is not there). The CLI (`index.mjs`) still deliberately does
+**not** expose this — it never writes to the QUEUE (`next`, `list`, `hygiene`
+only), so that no accidental invocation can change what the next run is
+handed. `propose.mjs` resolves its config from its own location, exactly as
+`index.mjs` does, so the proposal lands in the project's real PLAN.md (or
+tracker) and the active board's own options travel with it rather than being
+typed by hand. Write the proposal to a file under the run directory, then run
+the script:
 
 ```bash
 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 | 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
-    // mechanism accepts a proposal without them; this procedure does not.
-    measured: "<the paths the probe actually exercised>",
-    inferred: "<the conclusion, citing only surfaces named in measured>",
-  }, { project: "<KEY>" }));   // jira only — the ACTIVE board's key: `queue/index.mjs board --json` → options.project;
-                               // plan-md and github-issues take no second argument
+  const fs = await import("node:fs/promises");
+  await fs.writeFile(
+    `${process.env.RIG_RUN_DIR}/proposal.json`,
+    JSON.stringify({
+      finding: "<the journal line it came from>",
+      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
+      // mechanism accepts a proposal without them; this procedure does not.
+      measured: "<the paths the probe actually exercised>",
+      inferred: "<the conclusion, citing only surfaces named in measured>",
+    }),
+  );
 '
+# Root-anchored so the same command works whether the session is standing
+# at the repo root or in a subdirectory. Pinned in the generator's
+# test/template/loop-report-file.test.ts (absent in a generated rig) ›
+# "files when the documented command line runs, unmodified, from a project
+# subdirectory".
+node "$(git rev-parse --show-toplevel)/.claude/scripts/queue/propose.mjs" --file "$RIG_RUN_DIR/proposal.json"
 ```
 
+The result prints as one JSON line on stdout, and — because `RIG_RUN_DIR` is
+declared — the same result is also recorded as a `proposal` event in the run
+journal, so a failed filing is journalled as a failure instead of silently
+going nowhere. Pinned in the generator's `test/template/queue-propose.test.ts`
+(absent in a generated rig) › "files a proposal with a multiline finding from
+a project subdirectory, into the project-root PLAN.md" and › "journals a
+proposal event with ok: true on a successful filing under RIG_RUN_DIR".
+
 A proposal missing any of the four parts is refused rather than filed half-formed.
 
 **A finding can say what it measured and what it inferred, as two paired fields.**
@@ -920,9 +963,9 @@ rather than a step in the procedure: `plan-md` returns it when the plan file has
 no `## Operator queue` heading, because a proposal then has nowhere to land that
 the selection query cannot reach. Add the heading — never the Agent queue.
 
-One adapter needs the second argument the snippet above carries: `jira` requires
-`options.project` and throws rather than filing without it — loudly, so nothing
-is lost, but a call that drops it files nothing.
+`jira` still requires `options.project`, and still throws rather than filing
+without it — loudly, so nothing is lost — and there is no
+second argument left to hand-copy.
 
 🔴 **The loop proposes; the owner patches.** Self-applying a change to its own
 rulebook is how an unattended run drifts irreversibly, and it collides head-on