create-agent-rig 0.10.1 → 1.0.0

package/CHANGELOG.md

@@ -14,12 +14,124 @@ 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.** 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.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

@@ -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/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/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.

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