create-agent-rig 0.2.0 → 0.3.1

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

@@ -0,0 +1,239 @@
+// Queue adapter: the Agent queue in PLAN.md.
+//
+// This is the DEFAULT because it is the only adapter that works the moment a
+// project is generated — a fresh project has no remote, no tracker and no CI, and
+// a loop that cannot read its queue until someone provisions one is a loop that
+// never runs on day one.
+//
+// 🔴 **Its limit, stated rather than discovered:** a flat list carries no
+// dependency links. `blockedBy` is therefore always empty here, which means the
+// blocker filter is vacuous — not satisfied, absent. Nothing goes stale either,
+// because there is nothing to keep in step; but the moment work in this project
+// has real dependencies, move to an adapter whose tracker can express them
+// (`github-issues`). Ordering the list by hand is not a dependency graph.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fingerprintOf, validateProposal } from './core.mjs';
+
+export const name = 'plan-md';
+
+const AGENT_QUEUE = /^##\s+Agent queue\s*$/i;
+const ANY_HEADING = /^##\s+/;
+
+/**
+ * Locate the Agent queue by LINE RANGE, and say whether it was found at all.
+ *
+ * "No such heading" and "heading present, nothing under it" used to collapse into
+ * the same empty string, so a renamed heading or a bad merge read as a legitimately
+ * empty queue — reported as a successful end of session. They are different
+ * answers and only one of them is good news.
+ */
+export const readQueue = (plan) => {
+  const lines = String(plan ?? '').split('\n');
+  const start = lines.findIndex((line) => AGENT_QUEUE.test(line));
+  if (start === -1) return { found: false, lines, start: -1, end: -1 };
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (ANY_HEADING.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return { found: true, lines, start: start + 1, end };
+};
+
+/**
+ * Inline markers, so a flat list can still carry the few facts selection needs.
+ * Anything unmarked is a normal, unconditional item — which is the common case
+ * and should stay the cheapest thing to write.
+ */
+const MARKERS = {
+  elevated: /\[elevated\]/i,
+  triage: /\[triage\]/i,
+  triggerAuto: /\[trigger-auto\]/i,
+  triggerHuman: /\[trigger-human\]/i,
+};
+
+/**
+ * Parse the Agent queue into neutral tickets. Order in the file IS the priority.
+ *
+ * Each ticket records the **physical line** it came from, and that — not its text
+ * — is what identifies it for a later write.
+ */
+export const parsePlan = (plan) => {
+  const { found, lines, start, end } = readQueue(plan);
+  if (!found) return [];
+
+  const items = [];
+  let inComment = false;
+  for (let index = start; index < end; index += 1) {
+    const line = lines[index];
+    // A fresh project ships its example items commented out, and a loop that
+    // picks up the instructions as work is worse than useless.
+    if (inComment) {
+      if (line.includes('-->')) inComment = false;
+      continue;
+    }
+    if (line.includes('<!--')) {
+      if (!line.includes('-->')) inComment = true;
+      continue;
+    }
+
+    const match = /^\s*[-*]\s+(.*\S)\s*$/.exec(line);
+    if (!match) continue;
+    const raw = match[1];
+    const title = raw
+      .replace(/\[(elevated|triage|trigger-auto|trigger-human)\]/gi, '')
+      .replace(/\s+/g, ' ')
+      .trim();
+    items.push({
+      id: String(items.length + 1),
+      title,
+      raw,
+      line: index, // the identity a write uses — never the text
+      url: null,
+      state: 'open',
+      labels: [],
+      tier: MARKERS.elevated.test(raw) ? 'elevated' : 'normal',
+      // No links are expressible in a flat list — see the limit at the top.
+      blockedBy: [],
+      blocks: [],
+      priority: items.length,
+      createdAt: null,
+      triage: MARKERS.triage.test(raw),
+      trigger: MARKERS.triggerAuto.test(raw)
+        ? 'auto'
+        : MARKERS.triggerHuman.test(raw)
+          ? 'human'
+          : null,
+    });
+  }
+  return items;
+};
+
+/**
+ * Remove a closed item's line: a queue states what is next, not what is done.
+ *
+ * Deletes the recorded line index, which is inside the Agent queue by
+ * construction. The previous version searched the whole file for a line
+ * *containing* the item's text and deleted the first hit — so an item whose title
+ * was a prefix of another silently destroyed the wrong entry, and a human's
+ * Operator-queue line could be destroyed instead. Verified: closing item 2 of
+ * ["fix the parser bug in edge cases", "fix the parser"] deleted item 1.
+ */
+export const closeInPlan = (plan, id) => {
+  const target = parsePlan(plan).find((ticket) => ticket.id === String(id));
+  if (!target) return plan;
+  const lines = String(plan).split('\n');
+  lines.splice(target.line, 1);
+  return lines.join('\n');
+};
+
+const planPath = (options) => options?.planPath ?? 'PLAN.md';
+const readPlan = (options) => readFileSync(planPath(options), 'utf8');
+
+// --- the adapter contract ------------------------------------------------------
+
+/**
+ * Throws when the Agent queue section is absent, rather than returning [].
+ *
+ * A renamed heading or a bad merge is a queue that cannot be read — and the CLI
+ * turns that into `queue-unreadable`, not into the `queue-empty` success that a
+ * genuinely empty section produces. Collapsing the two meant a structural bug in
+ * PLAN.md was reported as "a legitimate end of session".
+ */
+export const listEligible = (options = {}) => {
+  const plan = readPlan(options);
+  if (!readQueue(plan).found) {
+    throw new Error(
+      `${planPath(options)} has no "## Agent queue" heading, so the queue cannot be ` +
+        'read. That is a structural problem in the file, not an empty queue — fix ' +
+        'the heading rather than treating this as a finished session.',
+    );
+  }
+  return parsePlan(plan);
+};
+
+/** Vacuously empty here, and honestly so — a flat list cannot express a dependency. */
+export const resolveBlockers = () => [];
+
+/**
+ * There is nothing to claim in a text file that two sessions could both hold, so
+ * this returns the instruction instead of pretending to lock. The real isolation
+ * for concurrent sessions is a worktree (`.claude/skills/worktree-task`).
+ */
+export const claim = (ticket) => ({
+  ok: true,
+  note:
+    `PLAN.md cannot express "in progress", so claiming ${ticket.id} is not ` +
+    'observable by another session. If a second session may run, take the task in ' +
+    'its own worktree and say so in the journal.',
+});
+
+export const close = (ticket, { prUrl = null, planPath: p } = {}) => {
+  const file = p ?? 'PLAN.md';
+  writeFileSync(file, closeInPlan(readFileSync(file, 'utf8'), ticket.id));
+  return { ok: true, prUrl };
+};
+
+/** A flat list has no comment thread; the journal is where this lands. */
+export const comment = (ticket, body) => ({
+  ok: false,
+  journalInstead: `${ticket.id} — ${body}`,
+  why: 'PLAN.md has no comment thread: write it as a journal entry in the same file.',
+});
+
+export const escalate = (ticket, diagnosis) => ({
+  ok: false,
+  journalInstead: `escalated ${ticket.id}: ${diagnosis}`,
+  why:
+    'PLAN.md has no per-item state, so an escalated item cannot be marked ' +
+    'unselectable. Move it to the Operator queue in the same edit, or the next ' +
+    'run picks it straight back up.',
+});
+
+/**
+ * A proposal, forced into triage.
+ *
+ * 🔴 INVARIANT 2: the agent never creates its own queue items. A proposal is not
+ * work — it goes to a state the selection query cannot reach, and promoting it is
+ * a human act. Without this, a scheduler plus an improvement loop is a closed
+ * circuit that invents and executes its own work.
+ */
+export const triageItemFor = (proposal) => {
+  validateProposal(proposal);
+  const fingerprint = fingerprintOf(proposal);
+  return {
+    // The `[triage]` marker is load-bearing, not decoration: plan-md has no
+    // persisted label field, so placement under the Operator queue used to be the
+    // ONLY thing keeping a proposal unselectable. With the marker in the title, a
+    // proposal pasted under the wrong heading is still refused by `selectionOf` —
+    // the same belt and braces the other two adapters get from a real label.
+    title: `proposal: ${proposal.change} [triage]`,
+    body: [
+      `- **finding** — ${proposal.finding}`,
+      `- **part to change** — ${proposal.part}`,
+      `- **proposed change** — ${proposal.change}`,
+      `- **how the next run proves it** — ${proposal.proof}`,
+      '',
+      `fingerprint: ${fingerprint}`,
+      '',
+      'The loop proposes; the owner patches. Self-applying a change to its own',
+      'rulebook is how an unattended run drifts irreversibly.',
+    ].join('\n'),
+    labels: ['triage'],
+    selectable: false,
+    fingerprint,
+  };
+};
+
+export const proposeTriage = (proposal, { planPath: p } = {}) => {
+  const item = triageItemFor(proposal);
+  return {
+    ok: false,
+    item,
+    why:
+      `PLAN.md has no triage state. Add "${item.title}" to the **Operator queue** ` +
+      `of ${p ?? 'PLAN.md'} — never the Agent queue — and keep the fingerprint line ` +
+      'so a later run increments it instead of filing a duplicate.',
+  };
+};

package/templates/agent-os/universal/.claude/scripts/reconcile-external-prs.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+// Reconcile the lane the journal never sees.
+//
+// Work reaches the default branch through more than one lane. The queue lane
+// leaves a queue item, a journal entry and a cost figure. Work that arrives from
+// outside — an issue someone filed and someone else fixed, a change the owner
+// asked for directly — leaves none of those. So the journal's output and cost
+// blocks describe ONE lane while reading as if they described the repo.
+//
+// This does not instrument the other lane; it cannot, because that lane does not
+// read these skills. It reconciles **after the fact**, from merged PRs, which is
+// the only vantage point this side actually has.
+//
+//   node .claude/scripts/reconcile-external-prs.mjs --since 2026-07-20
+//   node .claude/scripts/reconcile-external-prs.mjs --since 2026-07-20 --json
+//   node .claude/scripts/reconcile-external-prs.mjs --input prs.json   # offline
+import { execFileSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// Imported, never copied: one home for the elevated declaration and one home for
+// the lane rule. A second copy of either would drift, and each copy would keep
+// passing on its own.
+// `readDeclaredPaths` unions CLAUDE.md with every .claude/rules/*.md declaration,
+// so this sweep sees exactly what the gate sweep sees — including the paths a
+// stack layer contributes for its own shape.
+import { elevatedPathsIn, laneOf, readDeclaredPaths } from './detect-missed-gate.mjs';
+
+/**
+ * The audit trail for work that already happened: a record born **closed**.
+ *
+ * It is a record, not work — and it deliberately carries no `ready`-style
+ * selectable state. A selectable queue item describing work that already merged
+ * is the loop feeding itself, which is the one thing the queue firewall exists
+ * to prevent (.claude/skills/loop/SKILL.md).
+ */
+export const auditRecordFor = (pr, lane = laneOf(pr)) => ({
+  title: `External-lane merge — PR #${pr.number}: ${pr.title}`,
+  body: [
+    'Audit record for work that reached the default branch outside the queue.',
+    '',
+    `- PR: ${pr.url ?? `#${pr.number}`}`,
+    lane.closesIssue ? `- Closes issue: #${lane.closesIssue}` : '- Closed no issue.',
+    `- Merged: ${pr.mergedAt ?? 'unknown'}`,
+    '',
+    'Filed already closed by `.claude/scripts/reconcile-external-prs.mjs`, so the',
+    'merge is traceable from the journal to a record to a PR.',
+    '',
+    'This record is **not work**. It must never become selectable, or a run would',
+    'pick up something that has already shipped.',
+  ].join('\n'),
+  labels: ['external-lane', 'audit'],
+  state: 'closed',
+  pr: pr.number,
+});
+
+/**
+ * Split merged PRs by lane, mark the externally-originated ones that crossed an
+ * elevated path, and collect findings.
+ *
+ * Never throws on a malformed record: a sweep that dies on one bad row reports
+ * nothing about the other forty.
+ */
+export const reconcile = ({ prs = [], elevatedPaths = [], auditRecords = {} } = {}) => {
+  const external = [];
+  const queue = [];
+  const ownerDirected = [];
+  const findings = [];
+
+  const rows = Array.isArray(prs) ? prs : [];
+
+  for (const pr of rows) {
+    if (!pr || typeof pr !== 'object' || pr.number === undefined) continue;
+    // Only `classifyPr` used to check this, so an unmerged PR was rendered as a
+    // merge in the journal block.
+    if (!pr.mergedAt) continue;
+
+    let lane;
+    let elevatedFiles;
+    try {
+      lane = laneOf(pr);
+      // Computed for EVERY lane. It used to run only for `external`, and the lane
+      // is decided by the branch name — which a fork contributor chooses freely.
+      // So a contributor could opt out of the untrusted-origin mark by naming
+      // their branch `feat/12-…`, which is the opposite of what the mark is for.
+      elevatedFiles = elevatedPathsIn(pr.files ?? [], elevatedPaths ?? []);
+    } catch {
+      findings.push({
+        pr: pr.number,
+        kind: 'unreadable-record',
+        why: 'this merged PR could not be read, so its lane and elevated paths are unknown — not clean.',
+      });
+      continue;
+    }
+
+    // `authorAssociation` is the trustworthy signal when the host supplies it: it
+    // comes from the forge, not from the contributor.
+    const association = String(pr.authorAssociation ?? '').toUpperCase();
+    const trustedAuthor = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(association);
+    const entry = {
+      pr: pr.number,
+      title: pr.title,
+      mergedAt: pr.mergedAt,
+      url: pr.url,
+      lane: lane.lane,
+      queueRef: lane.queueRef,
+      closesIssue: lane.closesIssue,
+      elevatedFiles,
+      untrustedOrigin: elevatedFiles.length > 0 && !trustedAuthor,
+    };
+
+    if (lane.finding) {
+      findings.push({
+        pr: pr.number,
+        kind: lane.finding,
+        why:
+          `branch ${pr.headRefName} carries the queue reference ${lane.queueRef} but ` +
+          'the title and body do not. A queue-driven PR should never lose it — and ' +
+          'without the branch this merge would have been counted as external',
+      });
+    }
+
+    if (lane.lane === 'external') {
+      external.push({ ...entry, auditRecord: auditRecords[pr.number] ?? null });
+    } else if (lane.lane === 'queue') {
+      queue.push(entry);
+    } else {
+      ownerDirected.push(entry);
+    }
+  }
+
+  return { external, queue, ownerDirected, findings, sweptPrs: rows.length };
+};
+
+/** The `external lane` block for the journal in PLAN.md. */
+export const renderJournalBlock = (result) => {
+  const lines = ['**external lane**', ''];
+
+  if (result.external.length === 0) {
+    lines.push(
+      `- no externally-originated merges in this window (swept ${result.sweptPrs} merged PR(s)).`,
+    );
+  } else {
+    for (const e of result.external) {
+      const marks = [
+        e.closesIssue ? `closes #${e.closesIssue}` : 'closes no issue',
+        e.untrustedOrigin
+          ? `⚠ crossed an elevated path (${e.elevatedFiles.join(', ')}) — the gate applies here too`
+          : 'no elevated path crossed',
+        `audit record: ${e.auditRecord ?? 'not filed'}`,
+      ];
+      lines.push(`- PR #${e.pr} — ${e.title} · ${marks.join(' · ')}`);
+    }
+  }
+
+  for (const f of result.findings) {
+    lines.push(`- 🔴 finding · PR #${f.pr} — ${f.why}`);
+  }
+
+  lines.push('');
+  lines.push(
+    `_Queue lane this window: ${result.queue.length} PR(s); owner-directed: ` +
+      `${result.ownerDirected.length}. The cost figures in the journal cover the ` +
+      'queue lane only — read the two together, or a "cheap" session will sit ' +
+      'beside an expensive lane the totals never mention._',
+  );
+  return lines.join('\n');
+};
+
+// --- CLI -----------------------------------------------------------------------------
+
+/**
+ * Read an offline fixture, or say plainly why it could not be read.
+ *
+ * A raw SyntaxError stack, or a silent fall-through to the live repo when
+ * `--input` was given without a value, are both worse than a one-line diagnosis:
+ * this tool's whole value is that "could not look" never renders as "clean".
+ */
+const readInput = (file, label) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    process.stderr.write(
+      `${label}: could not read ${file} as JSON — nothing was checked. ` +
+        `${String(error?.message ?? error).split('\n')[0]}\n`,
+    );
+    process.exit(1);
+  }
+  if (!Array.isArray(parsed)) {
+    process.stderr.write(
+      `${label}: ${file} does not contain a JSON array of merged PRs, so nothing ` +
+        'was checked. Expected the shape `gh pr list --json …` produces.\n',
+    );
+    process.exit(1);
+  }
+  return parsed;
+};
+
+const parseArgs = (argv) => {
+  const args = { json: false, since: null, input: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--json') args.json = true;
+    else if (argv[i] === '--since') args.since = argv[++i];
+    else if (argv[i] === '--input') args.input = argv[++i];
+  }
+  return args;
+};
+
+const daysAgo = (n) => new Date(Date.now() - n * 86_400_000).toISOString().slice(0, 10);
+
+/** Same rule as the gate sweep: "could not look" must never render as "clean". */
+const fetchMergedPrs = (since) => {
+  try {
+    return JSON.parse(
+      execFileSync(
+        'gh',
+        [
+          'pr',
+          'list',
+          '--state',
+          'merged',
+          '--limit',
+          '100',
+          '--search',
+          `merged:>=${since}`,
+          '--json',
+          'number,title,body,headRefName,mergedAt,url,files,changedFiles,authorAssociation',
+        ],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+      ),
+    );
+  } catch (error) {
+    process.stderr.write(
+      'lane reconciliation: could not list merged PRs — the `gh` CLI is missing, ' +
+        'unauthenticated, or the API is unreachable. No lane was reconciled; do not ' +
+        'record an empty `external lane` block from this run. Use --input <file> to ' +
+        'work offline.\n' +
+        `  ${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]}\n`,
+    );
+    process.exit(1);
+  }
+};
+
+/**
+ * Was this file invoked directly?
+ *
+ * Compared by REALPATH on both sides: ESM resolves `import.meta.url` through
+ * symlinks while `process.argv[1]` keeps the path as typed, so a project living
+ * under a symlinked directory (a macOS temp dir, a symlinked home, a checkout
+ * behind a link) would fail a naive equality check — and the script would exit 0
+ * having printed nothing, which reads exactly like "no findings".
+ */
+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 projectRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const prs = args.input
+    ? readInput(args.input, 'lane reconciliation')
+    : fetchMergedPrs(args.since ?? daysAgo(7));
+  // Lane sorting still works without a declaration; only the elevated marks go
+  // missing, and they render as "no elevated path crossed" rather than lying.
+  const elevatedPaths = readDeclaredPaths(projectRoot) ?? [];
+  const result = reconcile({ prs, elevatedPaths });
+  process.stdout.write(
+    args.json ? `${JSON.stringify(result, null, 2)}\n` : `${renderJournalBlock(result)}\n`,
+  );
+}

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

@@ -0,0 +1,62 @@
+// The kill switch — one implementation, imported by everything that reads it.
+//
+// It lived in two places once: `guard-bash.mjs` (the hook that enforces it) and
+// `preflight.mjs` (the check that reports it before a run starts). The hole was
+// fixed in the hook and left open in preflight for a whole review cycle, which is
+// the argument for this file existing at all — a brake with two implementations
+// has two chances to be wrong, and the one nobody is looking at is the one that is.
+//
+// 🔴 The env variable may only ADD a brake, never remove one.
+//
+// `AGENT_LOOP_STOP` used to REPLACE the machine-level path, so any value naming a
+// file that does not exist turned the brake off while the operator's real flag sat
+// untouched in their home directory. An override that can disarm a brake is not an
+// override, it is a bypass — and it was reachable from `.claude/settings.json`,
+// which hooks inherit.
+//
+// Machine-level, not repo-level, on purpose: a git worktree is its own project
+// root, so a flag dropped in the main checkout would be invisible to a session
+// running inside one. A brake that is silently absent is worse than no brake.
+import { existsSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+/** Every path that arms the brake. The machine-level default is always first. */
+export const stopFlags = (env = process.env) => {
+  // BOTH homes: `homedir()` honours $HOME, which `.claude/settings.json` can set —
+  // pointing it at an empty directory disarmed the brake. `userInfo()` reads the
+  // password database and ignores the environment, so the operator's real flag is
+  // always among the paths checked.
+  const homes = new Set([homedir()]);
+  try {
+    homes.add(userInfo().homedir);
+  } catch {
+    // no password entry — the env-derived home is all there is
+  }
+  const paths = [...homes].map((home) => join(home, '.claude', '__PROJECT_NAME__-loop-STOP'));
+  const extra = env.AGENT_LOOP_STOP;
+  if (extra) {
+    // Filtered and CAPPED before the spread, never after. Spreading an
+    // input-derived array is unbounded: 115k empty entries from `':'.repeat(…)`
+    // overflowed the argument limit, and the RangeError was swallowed into
+    // "allow" by the hook's fail-open catch — disarming every rule while the
+    // brake was armed. Bounded work is not a performance concern here, it is the
+    // security property.
+    const extras = extra
+      .split(delimiter)
+      .filter(Boolean)
+      .slice(0, 32);
+    paths.push(extra, ...extras);
+  }
+  return [...new Set(paths)].slice(0, 64);
+};
+
+/** The armed flag file, or null. */
+export const brakeIsOn = (env = process.env) =>
+  stopFlags(env).find((path) => {
+    try {
+      return existsSync(path);
+    } catch {
+      return false;
+    }
+  }) ?? null;

package/templates/agent-os/universal/.claude/settings.json

@@ -20,6 +20,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-no-verify.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.mjs\""
           }
         ]
       }