create-agent-rig 0.10.1 → 1.0.0

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// The one repo-root-safe entry point for filing an improvement-triage
+// proposal (RP-209). It resolves its config, and through it the active
+// board's adapter and plan path, from its OWN location — exactly like
+// `index.mjs`'s `projectRoot` — so a session standing in a subdirectory
+// files into the project's real PLAN.md rather than a cwd-relative one
+// that happens not to exist there.
+//
+//   node .claude/scripts/queue/propose.mjs --file <proposal.json>
+//   node .claude/scripts/queue/propose.mjs --file -                # stdin
+//   node .claude/scripts/queue/propose.mjs --file <path> --config <queue.json>
+//
+// The proposal object is whatever the active adapter's `proposeTriage`
+// already accepts. The result prints as one JSON line on stdout; the
+// process exits 0 only when `ok === true`. When `RIG_RUN_DIR` is declared,
+// one `proposal` event is recorded in the run journal either way, so a
+// failed filing is journalled as a failure rather than going nowhere
+// silently.
+//
+// See the generator's test/template/queue-propose.test.ts (absent in a
+// generated rig).
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, optionsWithPlanPath, resolveAdapter } from './index.mjs';
+
+const parseArgs = (argv) => {
+  const args = { file: null, config: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--file') args.file = argv[++i];
+    else if (argv[i] === '--config') args.config = argv[++i];
+  }
+  return args;
+};
+
+const readStdin = () =>
+  new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    process.stdin.on('error', reject);
+  });
+
+const readProposalRaw = (file) => (file === '-' ? readStdin() : Promise.resolve(readFileSync(file, 'utf8')));
+
+/**
+ * Small, deliberately: the journal is a trace of the filing decision, not a
+ * second copy of the proposal or of the adapter's whole response.
+ */
+const journalDataFor = (result, reason) => {
+  const data = { ok: result?.ok === true };
+  if (result?.item?.fingerprint !== undefined) data.id = result.item.fingerprint;
+  if (result?.filed !== undefined) data.filed = result.filed;
+  if (result?.incremented !== undefined) data.incremented = result.incremented;
+  if (reason !== undefined) data.reason = reason;
+  return data;
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.file) {
+    process.stderr.write('propose: --file <proposal.json> is required (or --file - for stdin).\n');
+    process.exit(1);
+  }
+
+  let raw;
+  try {
+    raw = await readProposalRaw(args.file);
+  } catch (error) {
+    process.stderr.write(`propose: could not read ${args.file}: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  let proposal;
+  try {
+    proposal = JSON.parse(raw);
+  } catch (error) {
+    process.stderr.write(`propose: ${args.file} is not valid JSON: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  // Resolved against this file's own URL, not the cwd — the same rule
+  // `index.mjs` follows, for the same reason: the CLI runs from the project
+  // root, from a worktree, and from a subdirectory the session happens to be
+  // standing in.
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const projectRoot = join(scriptDir, '..', '..', '..');
+  const configPath = args.config ?? join(projectRoot, '.claude', 'queue.json');
+
+  let result;
+  let reason;
+  try {
+    const config = loadConfig(configPath);
+    const adapter = await resolveAdapter(config.adapter ?? 'plan-md');
+    const options = optionsWithPlanPath(config.options, configPath);
+    result = await adapter.proposeTriage(proposal, options);
+    if (result?.ok !== true) reason = result?.why ?? 'proposeTriage returned ok: false';
+  } catch (error) {
+    reason = error.message ?? String(error);
+    result = { ok: false, reason };
+  }
+
+  const exitCode = result?.ok === true ? 0 : 1;
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (exitCode !== 0) process.stderr.write(`propose: ${reason}\n`);
+
+  const runDir = process.env.RIG_RUN_DIR;
+  if (runDir) {
+    let journal = null;
+    try {
+      journal = await import('../run-journal.mjs');
+      journal.recordEvent({
+        runDir,
+        kind: 'proposal',
+        data: journalDataFor(result, reason),
+        now: new Date().toISOString(),
+      });
+    } catch (error) {
+      const classify = journal?.isTraceExhausted;
+      if (typeof classify === 'function' && classify(error)) {
+        // The trace is over; the filing already happened and stands. Loud on
+        // stderr, exit code stays whatever the filing decided — mirrors the
+        // pattern in `index.mjs` and the `loop` skill's own journal section.
+        process.stderr.write(
+          `run journal: ${error.message}\n` +
+            `  the proposal result above was NOT recorded in ${runDir}. This run's ` +
+            "trace ends here; the filing above stands.\n",
+        );
+      } else {
+        process.stderr.write(`run journal: ${error.message}\n`);
+        process.exit(1);
+      }
+    }
+  }
+
+  process.exit(exitCode);
+};
+
+main();

package/templates/agent-os/universal/.claude/scripts/release-evidence.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * release-evidence.mjs — read-only, deterministic. Turns existing run-journal
+ * evidence (gate-blocker patterns, filed triage proposals) into a
+ * REPEATED_PAIN or GATHER_MORE_EVIDENCE verdict, for the `release-propose`
+ * skill to read (RP-203). It files nothing itself — see
+ * test/template/release-evidence.test.ts (absent in a generated rig).
+ *
+ *   node .claude/scripts/release-evidence.mjs --since <ISO> [--runs <dir>] [--json]
+ *
+ * Reads `<runs>/<run-id>/` the same way `revalidation-report.mjs` does — this
+ * script reuses that script's `readRuns` (default `--runs` also resolves
+ * through `queue/checkout.mjs`'s `mainCheckoutRoot`, the same main-checkout
+ * rule) and `run-journal.mjs`'s `readRun`. A run `readRun` refuses is counted
+ * under `runs.skipped`, with why, never dropped silently.
+ *
+ * Grouping keys: `gate-blocker|<gate>|<norm(rule)>` for each blocker on a
+ * `decisions.jsonl` record; `proposal|<data.id>` for each `events.jsonl`
+ * record with `kind === 'proposal'` and `data.ok === true`. A group is
+ * `repeated` only when its records come from at least `REPEATED_MIN_RUNS`
+ * distinct run directories — any number of records inside one run is one
+ * anecdote.
+ *
+ * Limits: grouping is lexical (exact gate plus a normalised blocker rule, or
+ * a proposal fingerprint) — merging rules that mean the same thing but read
+ * differently is inference this script does not attempt. Run independence is
+ * assumed, not proven: one PR can span more than one run directory, which
+ * this script has no way to detect and would then double-count as two.
+ */
+
+import { realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mainCheckoutRoot } from './queue/checkout.mjs';
+import { readRuns } from './revalidation-report.mjs';
+
+export const REPEATED_MIN_RUNS = 2;
+
+const norm = (rule) => rule.trim().toLowerCase().replace(/\s+/g, ' ');
+
+/** The report over already-read runs — pure, so the grouping is testable alone. */
+export const evidenceOf = ({ runs, since }) => {
+  const sinceMs = Date.parse(since);
+  const read = [];
+  const skipped = [];
+  const groups = new Map();
+
+  const addRecord = (key, source, gate, label, run, at, pointer) => {
+    let group = groups.get(key);
+    if (!group) {
+      group = { key, source, gate, label, records: 0, runsSeen: new Set(), firstAt: at, lastAt: at, pointers: [] };
+      groups.set(key, group);
+    }
+    group.records += 1;
+    group.runsSeen.add(run);
+    if (Date.parse(at) < Date.parse(group.firstAt)) group.firstAt = at;
+    if (Date.parse(at) > Date.parse(group.lastAt)) group.lastAt = at;
+    group.pointers.push(pointer);
+  };
+
+  for (const entry of runs) {
+    if (entry.error) {
+      skipped.push({ run: entry.run, why: entry.error });
+      continue;
+    }
+    read.push(entry.run);
+
+    for (const record of entry.decisions ?? []) {
+      if (!(Date.parse(record.at) >= sinceMs)) continue;
+      for (const blockerItem of record.blockers ?? []) {
+        const rule = blockerItem?.rule;
+        if (typeof rule !== 'string' || rule.trim() === '') continue;
+        const gate = record.gate ?? 'unknown';
+        const label = norm(rule);
+        addRecord(`gate-blocker|${gate}|${label}`, 'gate-blocker', gate, label, entry.run, record.at, {
+          run: entry.run,
+          file: 'decisions.jsonl',
+          seq: record.seq,
+        });
+      }
+    }
+
+    for (const event of entry.events ?? []) {
+      if (event.kind !== 'proposal') continue;
+      if (event.data?.ok !== true) continue;
+      const id = event.data?.id;
+      if (id === undefined || id === null) continue;
+      if (!(Date.parse(event.at) >= sinceMs)) continue;
+      addRecord(`proposal|${id}`, 'proposal', null, String(id), entry.run, event.at, {
+        run: entry.run,
+        file: 'events.jsonl',
+        seq: event.seq,
+      });
+    }
+  }
+
+  const groupList = [...groups.values()].map((group) => ({
+    key: group.key,
+    source: group.source,
+    gate: group.gate,
+    label: group.label,
+    records: group.records,
+    runs: group.runsSeen.size,
+    repeated: group.runsSeen.size >= REPEATED_MIN_RUNS,
+    firstAt: group.firstAt,
+    lastAt: group.lastAt,
+    pointers: group.pointers,
+  }));
+
+  groupList.sort((a, b) => {
+    if (a.repeated !== b.repeated) return a.repeated ? -1 : 1;
+    if (a.runs !== b.runs) return b.runs - a.runs;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+  });
+
+  const verdict = groupList.some((group) => group.repeated) ? 'REPEATED_PAIN' : 'GATHER_MORE_EVIDENCE';
+  const why =
+    verdict === 'REPEATED_PAIN'
+      ? `at least one group recurred across ${REPEATED_MIN_RUNS}+ distinct run directories`
+      : 'no group recurred across distinct run directories since the window opened; an anecdote is not evidence';
+
+  return {
+    schemaVersion: 1,
+    since,
+    rule: {
+      repeatedMinRuns: REPEATED_MIN_RUNS,
+      unit: 'distinct run directory',
+      grouping: 'exact gate + normalised blocker rule; proposal fingerprint',
+    },
+    runs: { read: read.length, skipped },
+    groups: groupList,
+    verdict,
+    why,
+    limits: [
+      'grouping is lexical; merging similar rules is inference',
+      'run independence is assumed, not proven (one PR can span runs)',
+    ],
+  };
+};
+
+const parseArgs = (argv) => {
+  const args = { since: null, runs: null, json: false, bad: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') args.json = true;
+    else if (arg === '--since') args.since = argv[++i] ?? null;
+    else if (arg === '--runs') args.runs = argv[++i] ?? null;
+    else if (args.bad === null) args.bad = arg;
+  }
+  return args;
+};
+
+const invokedDirectly = () => {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+};
+
+if (invokedDirectly()) {
+  const args = parseArgs(process.argv.slice(2));
+  const refuse = (message) => {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+  };
+  if (args.bad !== null) refuse(`unrecognised argument: ${args.bad}`);
+  if (!args.since || Number.isNaN(Date.parse(args.since))) {
+    refuse(`--since needs an ISO date (got ${args.since ?? '(none)'}); a report with no window reports nothing honest.`);
+  }
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const runsDir = args.runs ?? join(mainCheckoutRoot(join(scriptsDir, '..', '..')), '.claude', 'runs');
+  let runs;
+  try {
+    runs = readRuns(runsDir);
+  } catch (error) {
+    refuse(error.message);
+  }
+  const evidence = evidenceOf({ runs, since: new Date(args.since).toISOString() });
+  // Always JSON: the one output shape `release-propose` reads. `--json` is
+  // accepted (every call site may pass it) but does not change the shape —
+  // there is no separate human-summary mode to opt out of.
+  process.stdout.write(`${JSON.stringify(evidence, null, 2)}\n`);
+}

package/templates/agent-os/universal/.claude/scripts/revalidation-report.mjs

@@ -124,8 +124,10 @@ export const readRuns = (runsDir) => {
   }
   return names.sort().map((run) => {
     try {
-      const { events } = readRun({ runDir: join(runsDir, run) });
-      return { run, events };
+      // `decisions` rides along unused here — added for release-evidence.mjs
+      // (RP-203), which reuses this same reader for its own grouping.
+      const { decisions, events } = readRun({ runDir: join(runsDir, run) });
+      return { run, decisions, events };
     } catch (error) {
       return { run, error: String(error?.message ?? error) };
     }

package/templates/agent-os/universal/.claude/scripts/unattended-flag.mjs

@@ -94,6 +94,14 @@ export const RULEBOOK_PREFIXES = Object.freeze([
   '.codex/',
   'AGENTS.md',
   'CLAUDE.md',
+  // the detection contract preflight and claim-records both read: it decides
+  // whether preflight STOPs and what the scope fingerprint watches, so an
+  // unattended run does not rewrite what its own revalidation checks against
+  // — outside its item's allow-list, like every other entry here and unlike
+  // `.claude/queue.board`, which `guard-rulebook` refuses even when the
+  // allow-list names it. The exact file, never `.rig/` — a SELECT still needs to
+  // write its own baseline under `.rig/claims/`, which stays unlisted here.
+  '.rig/revalidation.json',
 ]);
 
 /** Is this repo-relative path part of the rulebook? */

package/templates/agent-os/universal/.claude/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/.claude/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/.claude/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/.claude/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/.claude/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.