create-agent-rig 0.10.0 → 1.0.0

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

@@ -144,6 +144,21 @@ const ghJson = (args) => JSON.parse(ghText(args));
 
 const FIELDS = 'number,title,body,state,labels,url,createdAt,updatedAt,comments';
 
+/**
+ * A `--state` (or triage) window that came back exactly at its cap: older
+ * items may have been left unread, and a window this shape cannot tell the
+ * difference from a repository that happens to have exactly `limit` items.
+ * See queue-github-pagination.test.ts (absent in a generated rig) ›
+ * "a --state %s window that comes back exactly at the limit is announced on
+ * stderr" and › "a triage window that comes back exactly at the cap (100) is
+ * announced on stderr".
+ */
+const announceCap = (label, limit) => {
+  process.stderr.write(
+    `github-issues: ${label} window capped at ${limit} issues — older ${label} items may be missing; raise limit\n`,
+  );
+};
+
 // --- the adapter contract ------------------------------------------------------
 
 /**
@@ -151,18 +166,42 @@ const FIELDS = 'number,title,body,state,labels,url,createdAt,updatedAt,comments'
  *
  * Deliberately queries fresh on every call and never caches: the queue changes as
  * the loop itself closes items and unblocks their dependents.
+ *
+ * Open and closed issues are read as two separate `--state` windows rather
+ * than one shared `--state all` window: a shared window lets closed history
+ * push an older open issue out of it, which used to be silent. See
+ * queue-github-pagination.test.ts (absent in a generated rig) › "keeps an
+ * older OPEN issue even when 100 CLOSED issues would fill a shared window".
  */
 export const listEligible = ({ limit = 100, issues = null } = {}) => {
-  const raw =
-    issues ?? ghJson(['issue', 'list', '--state', 'all', '--limit', String(limit), '--json', FIELDS]);
+  let raw;
+  let openIssues = null;
+  if (issues) {
+    raw = issues;
+  } else {
+    openIssues = ghJson(['issue', 'list', '--state', 'open', '--limit', String(limit), '--json', FIELDS]);
+    if (openIssues.length === limit) announceCap('open', limit);
+    const closedIssues = ghJson([
+      'issue',
+      'list',
+      '--state',
+      'closed',
+      '--limit',
+      String(limit),
+      '--json',
+      FIELDS,
+    ]);
+    if (closedIssues.length === limit) announceCap('closed', limit);
+    raw = [...openIssues, ...closedIssues];
+  }
   const states = Object.fromEntries(raw.map((issue) => [String(issue.number), issue.state]));
   const blocks = blocksIndex(raw);
-  return raw
-    .filter((issue) => String(issue.state ?? '').toUpperCase() !== 'CLOSED')
-    .map((issue) => {
-      const ticket = toTicket(issue, states);
-      return { ...ticket, blocks: blocks[ticket.id] ?? [] };
-    });
+  const eligible =
+    openIssues ?? raw.filter((issue) => String(issue.state ?? '').toUpperCase() !== 'CLOSED');
+  return eligible.map((issue) => {
+    const ticket = toTicket(issue, states);
+    return { ...ticket, blocks: blocks[ticket.id] ?? [] };
+  });
 };
 
 export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) => !b.resolved);
@@ -293,12 +332,30 @@ export const triageItemFor = (proposal) => {
  * hand out nothing — "queue empty" and "nothing selectable";
  * twenty such stops must produce one proposal with a count of twenty.
  */
-/** The proposals on file, as `{ id, body }` — every `triage`-labelled issue. */
-export const listProposals = ({ existing = null } = {}) =>
-  (
-    existing ??
-    ghJson(['issue', 'list', '--label', 'triage', '--state', 'all', '--limit', '100', '--json', FIELDS])
-  ).map((issue) => ({ id: String(issue.number), body: issue.body }));
+/**
+ * The proposals on file, as `{ id, body }` — every `triage`-labelled issue.
+ * A window that comes back exactly at its cap is announced on stderr, same
+ * as `listEligible`'s.
+ */
+export const listProposals = ({ existing = null, limit = 100 } = {}) => {
+  let raw = existing;
+  if (!raw) {
+    raw = ghJson([
+      'issue',
+      'list',
+      '--label',
+      'triage',
+      '--state',
+      'all',
+      '--limit',
+      String(limit),
+      '--json',
+      FIELDS,
+    ]);
+    if (raw.length === limit) announceCap('triage', limit);
+  }
+  return raw.map((issue) => ({ id: String(issue.number), body: issue.body }));
+};
 
 export const proposeTriage = (rawProposal, { existing = null } = {}) => {
   const proposal = withAsOf(rawProposal);

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/check-premises/SKILL.md

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

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