create-agent-rig 0.10.1 → 1.0.1

package/CHANGELOG.md

@@ -14,12 +14,178 @@ 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.1
+
+**1.0.1 is a patch on the 1.0 line.** It closes guard gaps an unattended run
+could use to rewrite the rulebook, fixes a `doctor` side effect, and moves the
+reviewer tier of both harnesses to newer models. The 1.0 contract is
+unchanged: no flag, JSON shape, exit code, verdict or outcome word, and no
+manifest key is added, removed or renamed.
+
+### Changed
+
+- **The Claude reviewer tier runs on Opus 5.5.** `code-reviewer`,
+  `security-scanner` and `failure-diagnostician` route to `claude-opus-5-5`
+  (was `claude-opus-5`), effort `high` unchanged (RP-232).
+- **The Codex reviewer tier runs on GPT-6 Sol.** The same three roles route to
+  `gpt-6-sol` (was `gpt-5.6-sol`), reasoning effort `high` unchanged. Under
+  ChatGPT-account auth, Codex CLI 0.156.1 dispatched it and 0.154.0 rejected
+  the model id; versions in between were not tested (RP-233).
+
+### Fixed
+
+- **`guard-rulebook` judges the paths an `apply_patch` removes.** A
+  `*** Delete File:` section, and the source of a `*** Move to:`, were never
+  judged, so an armed unattended run could delete or move a rulebook file —
+  including the guard itself (RP-214).
+- **A miscased rulebook path is recognised.** `.Codex/config.toml` or
+  `.AGENTS/…` passed where the lowercase spelling was refused, and on a
+  case-insensitive filesystem the write landed on the real file. A miscased
+  allow-list entry is refused like its canonical spelling (RP-215).
+- **A Win32 trailing dot or space in a path component no longer hides a
+  rulebook path.** Windows strips them, so `.claude./settings.json` is
+  `.claude/settings.json` (RP-243).
+- **A Win32 verbatim or device path no longer hides a rulebook path.**
+  `\\?\C:\…`, `\\.\C:\…` and a `..` run above the drive root are judged as the
+  plain path Windows writes to. A UNC or other device-namespace path that does
+  not resolve under the repository root is refused while unattended rather
+  than judged as outside the rulebook (RP-244). One case stays open: when the
+  repository root is itself spelled as a UNC admin share, the local drive
+  spelling of the same file is not caught (RP-246).
+- **`doctor` no longer leaves an unattended flag in your home directory.** Its
+  guard fixture armed the flag in the invoking user's real `~/.claude` as well
+  as in its temporary home, and never cleared it (RP-238).
+- **The workflow layer's seed declares the revalidation contract elevated.**
+  `.rig/revalidation.json` was already protected from an unattended edit but
+  was missing from the `elevated-paths` seed, so the gate sweep could not see a
+  merge that rewrote it (RP-217).
+
+### Generator repository (not a rig-facing change)
+
+- The evidence-pointer check resolves a directory-qualified citation against
+  that exact path instead of any file with the same name (RP-216).
+- The package-manager CLI-start test bounds its child process and reports a
+  timeout as one (RP-212); a credential-masking test no longer serialises 41
+  fixture rewrites, which made it time out under sibling disk load (RP-218).
+
+## 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.** Every 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 no agent, skill,
-hook or routing row is new.
+**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
 

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.1",
+  "version": "1.0.1",
   "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

@@ -719,6 +719,27 @@ 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.
@@ -742,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;

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';
@@ -500,7 +500,14 @@ async function runUpgrade(rawArgs) {
         if (notice !== null)
             process.stdout.write(notice);
         // The same exit the real run gives: `applyUpgrade` refuses this status.
-        return plan.agentsRescue.holdBack && plan.agentsRescue.status === 'unsafe' ? 1 : 0;
+        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
     // anything is written. On a terminal that is a question; off one it is a

package/packages/cli/dist/integrations/doctor-guards.js

@@ -48,12 +48,13 @@ const root=fs.mkdtempSync(path.join(os.tmpdir(),'rig-guard-fixtures-'));
 const parent=path.resolve(os.tmpdir()),resolved=path.resolve(root);
 if(!resolved.startsWith(parent+path.sep)||!path.basename(resolved).startsWith('rig-guard-fixtures-'))throw new Error('unsafe fixture root');
 let code=1;
+let flag,env;
 try {
  const home=path.join(root,'home'); fs.mkdirSync(path.join(root,'.claude','agents'),{recursive:true});
  fs.writeFileSync(path.join(root,'.claude','agents','code-reviewer.md'),'---\nmodel: gpt-5.6-sol\n---\n');
- const env={...process.env,HOME:home,APPDATA:home,CLAUDE_PROJECT_DIR:root};
+ env={...process.env,HOME:home,APPDATA:home,CLAUDE_PROJECT_DIR:root};
  const unattended=path.join(source,'.claude','scripts','unattended-flag.mjs');
- const flag=await import(url.pathToFileURL(unattended).href); flag.writeUnattended({item:'fixture',runDir:root,allow:[]},env);
+ flag=await import(url.pathToFileURL(unattended).href); flag.writeUnattended({item:'fixture',runDir:root,allow:[]},env);
  const run=(rel,input)=>cp.spawnSync(process.execPath,[path.join(source,...rel.split('/'))],{cwd:root,env,input:JSON.stringify(input),encoding:'utf8',timeout:5000,maxBuffer:8192}).status;
  const pre=(tool_input)=>({hook_event_name:'PreToolUse',tool_name:tool_input.command?'Bash':'Write',tool_input});
  const cases=[
@@ -69,7 +70,10 @@ try {
   ['.claude/hooks/guard-subagent-model.mjs',{hook_event_name:'PreToolUse',tool_name:'Agent',tool_input:{subagent_type:'code-reviewer'}},true]
  ];
  for(const [rel,input,allowed] of cases){const status=run(rel,input);if(allowed ? status!==0 : status!==2){code=1;break;} code=0;}
-} finally { fs.rmSync(resolved,{recursive:true,force:true}); }
+} finally {
+ try { if(flag&&typeof flag.clearUnattended==='function') flag.clearUnattended(env); } catch {}
+ fs.rmSync(resolved,{recursive:true,force:true});
+}
 process.exitCode=code;
 })().catch(()=>{process.exitCode=1;});
 `;

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

@@ -1,6 +1,6 @@
 {
   "claudeModels": {
-    "claude-opus-5": ["low", "medium", "high", "xhigh", "max"],
+    "claude-opus-5-5": ["low", "medium", "high", "xhigh", "max"],
     "claude-sonnet-5": ["low", "medium", "high", "xhigh", "max"]
   },
   "unnamed": {
@@ -21,12 +21,16 @@
       "codex": { "model": "gpt-5.6-terra", "effort": "high" }
     },
     "code-reviewer": {
-      "claude": { "model": "claude-opus-5", "effort": "high" },
-      "codex": { "model": "gpt-5.6-sol", "effort": "high" }
+      "claude": { "model": "claude-opus-5-5", "effort": "high" },
+      "codex": { "model": "gpt-6-sol", "effort": "high" }
     },
     "security-scanner": {
-      "claude": { "model": "claude-opus-5", "effort": "high" },
-      "codex": { "model": "gpt-5.6-sol", "effort": "high" }
+      "claude": { "model": "claude-opus-5-5", "effort": "high" },
+      "codex": { "model": "gpt-6-sol", "effort": "high" }
+    },
+    "failure-diagnostician": {
+      "claude": { "model": "claude-opus-5-5", "effort": "high" },
+      "codex": { "model": "gpt-6-sol", "effort": "high" }
     }
   }
 }

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

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.