create-agent-rig 0.2.0 → 0.3.1

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

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// The queue CLI — one command over whichever adapter this project uses.
+//
+//   node .claude/scripts/queue/index.mjs next            # the item to take, and why
+//   node .claude/scripts/queue/index.mjs next --json
+//   node .claude/scripts/queue/index.mjs list            # every item, with skip reasons
+//   node .claude/scripts/queue/index.mjs hygiene         # stale labels and link anomalies
+//
+// The adapter comes from `.claude/queue.json` (`{"adapter": "plan-md"}`) and
+// defaults to `plan-md`, which is the only adapter that works in a freshly
+// generated project. An unknown adapter is a hard error, never a fallback: a loop
+// that silently reads the wrong queue is worse than one that refuses to start.
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { hygieneOf, selectNext, stopConditionOf } from './core.mjs';
+
+const ADAPTERS = {
+  'plan-md': './plan-md.mjs',
+  'github-issues': './github-issues.mjs',
+  jira: './jira.mjs',
+};
+
+export const resolveAdapter = async (adapterName) => {
+  const modulePath = ADAPTERS[adapterName];
+  if (!modulePath) {
+    throw new Error(
+      `unknown queue adapter: ${adapterName}. Known adapters: ${Object.keys(ADAPTERS).join(', ')}.`,
+    );
+  }
+  // Resolved against this file's own URL, not the cwd: the CLI runs from the
+  // project root, from a worktree, and from a test harness.
+  return import(new URL(modulePath, import.meta.url).href);
+};
+
+export const COMMANDS = ['next', 'list', 'hygiene'];
+
+/**
+ * A missing config is the normal state of a fresh project. A config that exists
+ * and does not parse is NOT — it used to fall back to `plan-md` silently, so a
+ * trailing comma in `queue.json` made the loop read a different queue than the one
+ * configured, which is the exact failure this file's header refuses for adapters.
+ */
+export const loadConfig = (configPath) => {
+  let raw;
+  try {
+    raw = readFileSync(configPath, 'utf8');
+  } catch {
+    return {};
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${configPath} exists but is not valid JSON, so the configured queue cannot be ` +
+        `read: ${String(error?.message ?? error).split('\n')[0]}. Fix the file — ` +
+        'silently reading a different queue is worse than refusing to start.',
+      { cause: error },
+    );
+  }
+};
+
+const parseArgs = (argv) => {
+  const args = { command: argv[0] ?? 'next', json: false, config: null };
+  for (let i = 1; i < argv.length; i += 1) {
+    if (argv[i] === '--json') args.json = true;
+    else if (argv[i] === '--config') args.config = argv[++i];
+  }
+  return args;
+};
+
+const renderNext = (result, stop) => {
+  if (stop) {
+    const label = stop.kind.replaceAll('-', ' ');
+    return `queue: ${label}${stop.success ? '' : ' (needs attention)'}\n  ${stop.why}\n`;
+  }
+  const lines = [`next: ${result.ticket.id} — ${result.ticket.title} [${result.ticket.tier}]`];
+  if (result.skipped.length > 0) {
+    lines.push('', 'skipped:');
+    for (const skip of result.skipped) lines.push(`  ${skip.id} — ${skip.reason}`);
+  }
+  return `${lines.join('\n')}\n`;
+};
+
+/**
+ * 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)), '..', '..', '..');
+
+  // An unrecognised command used to behave as `next`, discarding its argument —
+  // so `claim 1` silently printed a selection and claimed nothing.
+  if (!COMMANDS.includes(args.command)) {
+    process.stderr.write(
+      `unknown command: ${args.command}. Known commands: ${COMMANDS.join(', ')}. ` +
+        'The write operations (claim, close, comment, escalate, proposeTriage) are ' +
+        "the adapter's own API — import the adapter module rather than this CLI.\n",
+    );
+    process.exit(1);
+  }
+
+  let config;
+  let adapter;
+  try {
+    config = loadConfig(args.config ?? join(projectRoot, '.claude', 'queue.json'));
+    adapter = await resolveAdapter(config.adapter ?? 'plan-md');
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+
+  let tickets;
+  try {
+    // Awaited so an adapter may be async (jira) or plain (plan-md, github-issues)
+    // without the CLI caring which.
+    tickets = await adapter.listEligible(config.options ?? {});
+  } catch (error) {
+    // Never fall back to memory or to a stale copy for a queue.
+    const stop = stopConditionOf({ queueReadable: false });
+    process.stdout.write(
+      args.json
+        ? `${JSON.stringify({ stop, error: String(error.message ?? error) }, null, 2)}\n`
+        : `queue: ${stop.kind}\n  ${stop.why}\n  ${error.message ?? error}\n`,
+    );
+    process.exit(1);
+  }
+
+  if (args.command === 'hygiene') {
+    const findings = tickets.map(hygieneOf).filter(Boolean);
+    process.stdout.write(
+      args.json
+        ? `${JSON.stringify({ findings }, null, 2)}\n`
+        : findings.length === 0
+          ? `queue hygiene: ${tickets.length} item(s) checked — nothing stale.\n`
+          : `${findings.map((f) => `  [${f.kind}] ${f.id} — ${f.why}`).join('\n')}\n`,
+    );
+    process.exit(0);
+  }
+
+  const result = selectNext(tickets, {
+    lastCompletedTier: config.lastCompletedTier ?? null,
+    triggersFired: config.triggersFired ?? null,
+  });
+  const stop = result.ticket ? null : stopConditionOf({ candidates: 0 });
+
+  if (args.command === 'list') {
+    process.stdout.write(`${JSON.stringify({ tickets, ...result }, null, 2)}\n`);
+    process.exit(0);
+  }
+
+  process.stdout.write(
+    args.json
+      ? `${JSON.stringify({ ticket: result.ticket, skipped: result.skipped, stop }, null, 2)}\n`
+      : renderNext(result, stop),
+  );
+}

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

@@ -0,0 +1,345 @@
+// Queue adapter: Jira issues, via the REST API.
+//
+// The second adapter exists to prove the seam holds: everything about *selection*
+// lives in `core.mjs` and is imported, not re-derived. An adapter that answers
+// "is this takeable?" for itself is a second answer to the same question, and the
+// two will disagree the first time one of them is edited.
+//
+// Credentials come from the environment and nowhere else:
+//
+//     JIRA_BASE_URL   https://your-site.atlassian.net
+//     JIRA_EMAIL      the account the token belongs to
+//     JIRA_API_TOKEN  an API token, never a password
+//
+// There is deliberately no default, no fallback and no example value: a
+// placeholder that looks like a credential is a credential someone will commit.
+// Configure the project in `.claude/queue.json`:
+//
+//     { "adapter": "jira", "options": { "project": "ABC" } }
+//     { "adapter": "jira", "options": { "jql": "project = ABC AND ..." } }
+import { duplicateOf, fingerprintOf, validateProposal } from './core.mjs';
+
+export const name = 'jira';
+
+/** Jira's own default priority ladder. An unrecognised name sorts last, never first. */
+const PRIORITY = { highest: 1, high: 2, medium: 3, low: 4, lowest: 5 };
+
+/**
+ * The link types that express a dependency. "relates to" and "duplicates" are
+ * neither, and treating them as blockers would stall the queue on commentary.
+ */
+const BLOCKED_BY = /^(is blocked by|blocked by)$/i;
+const BLOCKS = /^blocks$/i;
+
+const statusCategory = (fields) => String(fields?.status?.statusCategory?.key ?? '').toLowerCase();
+
+/** Jira timestamps use +0000 rather than Z; normalise so string compare sorts right. */
+const toIso = (created) => {
+  if (!created) return null;
+  const parsed = new Date(created);
+  return Number.isNaN(parsed.getTime()) ? String(created) : parsed.toISOString();
+};
+
+/**
+ * Flatten an Atlassian-document description down to its text.
+ *
+ * Only the fingerprint line needs to be findable, so a recursive text harvest is
+ * enough — and it tolerates a plain-string description from an older API shape.
+ */
+export const descriptionTextOf = (issue) => {
+  // Depth-capped: the document is written by whoever filed the issue, and an
+  // unbounded walk overflows the stack at ~10k levels — which would stop the loop
+  // filing or deduplicating any proposal at all.
+  const walk = (node, depth) => {
+    if (depth > 64) return '';
+    if (typeof node === 'string') return node;
+    if (Array.isArray(node)) return node.map((child) => walk(child, depth + 1)).join('\n');
+    if (node && typeof node === 'object') {
+      return [node.text ?? '', walk(node.content ?? [], depth + 1)].filter(Boolean).join('\n');
+    }
+    return '';
+  };
+  return walk(issue?.fields?.description ?? '', 0);
+};
+
+/** Map one Jira issue onto the neutral Ticket shape. */
+export const toTicket = (issue) => {
+  const fields = issue?.fields ?? {};
+  const labels = fields.labels ?? [];
+  const links = fields.issuelinks ?? [];
+  const category = statusCategory(fields);
+
+  // 🔴 INVARIANT 1: the dependency is the LINK, and the blocker's own status
+  // decides. A `blocked` label is a snapshot nobody updates when the blocker
+  // lands; this is re-read from the blocker every time selection runs. A blocker
+  // whose status is not readable counts as unresolved — "could not look" is never
+  // "it is fine".
+  const blockedBy = links
+    .filter((link) => BLOCKED_BY.test(String(link?.type?.inward ?? '')) && link?.inwardIssue)
+    .map((link) => ({
+      id: link.inwardIssue.key,
+      resolved: statusCategory(link.inwardIssue.fields) === 'done',
+    }));
+
+  const blocks = links
+    .filter((link) => BLOCKS.test(String(link?.type?.outward ?? '')) && link?.outwardIssue)
+    .map((link) => link.outwardIssue.key);
+
+  return {
+    id: issue.key,
+    title: fields.summary ?? '',
+    url: issue.self ?? null,
+    state: category === 'done' ? 'closed' : category === 'indeterminate' ? 'in-progress' : 'open',
+    labels,
+    tier: labels.includes('human-review') ? 'elevated' : 'normal',
+    blockedBy,
+    blocks,
+    priority: PRIORITY[String(fields.priority?.name ?? '').toLowerCase()] ?? 999,
+    createdAt: toIso(fields.created),
+    triage: labels.includes('triage'),
+    trigger: labels.includes('trigger-auto')
+      ? 'auto'
+      : labels.includes('trigger-human')
+        ? 'human'
+        : null,
+  };
+};
+
+/**
+ * The selection query.
+ *
+ * `labels != triage` is belt and braces, and it is deliberate: excluding a
+ * proposal only by the absence of a ready marker means one careless hand adding
+ * that marker closes the loop's feedback path into its own input. Excluded
+ * explicitly, an item carrying BOTH markers is still unselectable.
+ *
+ * ⚠ JQL gotcha that makes the parenthesised form necessary: `labels != x` does
+ * **not** match issues whose labels field is empty. Without `OR labels IS EMPTY`
+ * this query would silently skip every unlabelled item — which is most of them.
+ */
+export const buildJql = ({ project = null, jql = null } = {}) => {
+  if (jql) return jql;
+  if (!project) {
+    throw new Error(
+      'the jira adapter needs either options.project or options.jql in ' +
+        '.claude/queue.json. It will not guess a project: reading the wrong queue ' +
+        'is worse than refusing to start.',
+    );
+  }
+  return (
+    `project = ${project} AND statusCategory != Done ` +
+    'AND (labels != triage OR labels IS EMPTY) ' +
+    'ORDER BY priority DESC, created ASC'
+  );
+};
+
+export const requireCredentials = (env = process.env) => {
+  const missing = ['JIRA_BASE_URL', 'JIRA_EMAIL', 'JIRA_API_TOKEN'].filter((key) => !env[key]);
+  if (missing.length > 0) {
+    throw new Error(
+      `the jira adapter needs ${missing.join(', ')} in the environment. ` +
+        'Set them in your shell or your secret manager — never in a file in this repo.',
+    );
+  }
+  const baseUrl = String(env.JIRA_BASE_URL).replace(/\/$/, '');
+  // Basic auth carries the token in a trivially reversible header, so the
+  // transport is part of the credential handling: a mis-set or tampered
+  // JIRA_BASE_URL over http would put it on the wire in clear.
+  if (!/^https:\/\//i.test(baseUrl)) {
+    throw new Error(
+      `JIRA_BASE_URL must use https (got ${baseUrl.split(':')[0]}://…). Basic auth ` +
+        'sends the API token on every request; over http it is readable in transit.',
+    );
+  }
+  return { baseUrl, email: env.JIRA_EMAIL, token: env.JIRA_API_TOKEN };
+};
+
+const request = async (route, { method = 'GET', body = null, env = process.env } = {}) => {
+  const { baseUrl, email, token } = requireCredentials(env);
+  const response = await fetch(`${baseUrl}${route}`, {
+    method,
+    headers: {
+      Authorization: `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`,
+      Accept: 'application/json',
+      ...(body ? { 'Content-Type': 'application/json' } : {}),
+    },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  if (!response.ok) {
+    // The status alone; never echo the response body, which can carry the token
+    // back in an error envelope.
+    throw new Error(`jira ${method} ${route} failed: ${response.status} ${response.statusText}`);
+  }
+  return response.status === 204 ? null : response.json();
+};
+
+// `description` is requested because the triage dedupe matches the fingerprint
+// inside it. Without it the dedupe silently never matched, so every "queue empty"
+// stop filed a fresh issue instead of incrementing the one already there.
+const FIELDS = 'summary,status,labels,priority,created,issuelinks,description';
+
+// --- the adapter contract ------------------------------------------------------
+
+/**
+ * Query fresh every time — the queue changes as the loop closes items and
+ * unblocks their dependents, so a list read at the start of a run is wrong by the
+ * second task. `issues` is the offline seam the tests use.
+ */
+export const listEligible = async ({
+  issues = null,
+  project = null,
+  jql = null,
+  limit = 100,
+  env = process.env,
+} = {}) => {
+  // `issues` is the offline seam: the mapping is pure, so every shape it has to
+  // handle is testable without a network or a credential.
+  const response = issues ? { issues } : await search({ project, jql, limit, env });
+  return response.issues.map(toTicket).filter((ticket) => ticket.state !== 'closed');
+};
+
+export const search = async ({ project = null, jql = null, limit = 100, env = process.env } = {}) =>
+  request(
+    `/rest/api/3/search?jql=${encodeURIComponent(buildJql({ project, jql }))}` +
+      `&maxResults=${limit}&fields=${FIELDS}`,
+    { env },
+  );
+
+export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) => !b.resolved);
+
+/**
+ * Claim it before the first file is edited, not when the PR opens: an item being
+ * worked while it still reads as available is invisible to the human and
+ * re-selectable by the very next query.
+ */
+export const claim = async (ticket, { transitionId = null, env = process.env } = {}) => {
+  if (!transitionId) {
+    const available = await request(`/rest/api/3/issue/${ticket.id}/transitions`, { env });
+    const target = available.transitions.find(
+      (transition) => statusCategory(transition.to ? { status: transition.to } : {}) === 'indeterminate',
+    );
+    if (!target) {
+      throw new Error(
+        `no in-progress transition available for ${ticket.id} — the board's workflow ` +
+          'differs from the default. Pass options.transitionId.',
+      );
+    }
+    transitionId = target.id;
+  }
+  await request(`/rest/api/3/issue/${ticket.id}/transitions`, {
+    method: 'POST',
+    body: { transition: { id: transitionId } },
+    env,
+  });
+  return { ok: true };
+};
+
+export const comment = async (ticket, body, { env = process.env } = {}) => {
+  await request(`/rest/api/3/issue/${ticket.id}/comment`, {
+    method: 'POST',
+    body: {
+      body: { type: 'doc', version: 1, content: [{ type: 'paragraph', content: [{ type: 'text', text: body }] }] },
+    },
+    env,
+  });
+  return { ok: true };
+};
+
+export const close = async (ticket, { prUrl = null, transitionId = null, env = process.env } = {}) => {
+  await comment(ticket, prUrl ? `Landed in ${prUrl}.` : 'Closed by the run.', { env });
+  if (transitionId) {
+    await request(`/rest/api/3/issue/${ticket.id}/transitions`, {
+      method: 'POST',
+      body: { transition: { id: transitionId } },
+      env,
+    });
+  }
+  return { ok: true, transitioned: Boolean(transitionId) };
+};
+
+/**
+ * Escalate: the diagnosis goes on the item and the item is labelled so the next
+ * selection cannot pick it up. It stays IN PROGRESS on purpose — moving it back to
+ * a selectable state is how one stuck task gets worked three times.
+ */
+export const escalate = async (ticket, diagnosis, { env = process.env } = {}) => {
+  await comment(ticket, diagnosis, { env });
+  await request(`/rest/api/3/issue/${ticket.id}`, {
+    method: 'PUT',
+    body: { update: { labels: [{ add: 'escalated' }] } },
+    env,
+  });
+  return { ok: true };
+};
+
+/**
+ * 🔴 INVARIANT 2: the agent never creates its own work. A proposal is labelled
+ * `triage`, which `buildJql` excludes explicitly, and it never receives a ready
+ * marker — so the only route from proposal to work runs through a human.
+ */
+export const triageItemFor = (proposal) => {
+  validateProposal(proposal);
+  const fingerprint = fingerprintOf(proposal);
+  return {
+    title: `proposal: ${proposal.change}`,
+    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,
+  };
+};
+
+/** File the proposal, or increment the one already carrying this fingerprint. */
+export const proposeTriage = async (
+  proposal,
+  { project = null, existing = null, env = process.env } = {},
+) => {
+  const item = triageItemFor(proposal);
+  // Compared against the issue's DESCRIPTION, which is where the fingerprint was
+  // written. The previous version mapped candidates through `toTicket` — which
+  // emits no body at all — so the predicate was always false and twenty identical
+  // stops filed twenty issues against the tracker.
+  const found =
+    existing ??
+    (await search({ jql: 'labels = triage ORDER BY created DESC', env })).issues.map((issue) => ({
+      id: issue.key,
+      body: descriptionTextOf(issue),
+    }));
+  const duplicate = duplicateOf(item, found);
+
+  if (duplicate) {
+    await comment(duplicate, `Seen again (fingerprint ${item.fingerprint}). Incrementing.`, { env });
+    return { ok: true, incremented: duplicate.id, item };
+  }
+  if (!project) {
+    throw new Error('filing a triage proposal needs options.project');
+  }
+  await request('/rest/api/3/issue', {
+    method: 'POST',
+    body: {
+      fields: {
+        project: { key: project },
+        summary: item.title,
+        issuetype: { name: 'Task' },
+        labels: item.labels,
+        description: {
+          type: 'doc',
+          version: 1,
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: item.body }] }],
+        },
+      },
+    },
+    env,
+  });
+  return { ok: true, filed: item.title, item };
+};