create-agent-rig 0.5.0 → 0.6.0

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

@@ -14,8 +14,9 @@
 // be a snapshot that nothing updates when the blocker lands; this cannot go stale,
 // because it is re-resolved from the blockers themselves on every selection.
 import { execFileSync } from 'node:child_process';
-import { duplicateOf, fingerprintOf, validateProposal } from './core.mjs';
-import { recordEscalation } from '../run-state.mjs';
+import { duplicateOf, fingerprintOf, lifecycleOf, ownerOfLabels, validateProposal } from './core.mjs';
+import { withAsOf } from './as-of.mjs';
+import { recordEscalation, recordTakeUp } from '../run-state.mjs';
 
 export const name = 'github-issues';
 
@@ -75,6 +76,11 @@ export const toTicket = (issue, states = {}) => {
     blocks: [],
     priority: priorityLabel ? Number(priorityLabel[1]) : 999,
     createdAt: issue.createdAt ?? null,
+    // The take-up marker for revalidation at SELECT: the tracker's own
+    // last-modified field, whose contract (moves on edits, comments and state
+    // changes) is assumed and not checked here. `null` when the listing did not
+    // carry it.
+    updatedAt: issue.updatedAt ?? null,
     // The body travels on the neutral shape so the hygiene checks live in one
     // place (core.mjs) instead of once per adapter. This adapter also parses it
     // internally for blocker links — the two readings are independent on
@@ -87,6 +93,10 @@ export const toTicket = (issue, states = {}) => {
       : labels.includes('trigger-human')
         ? 'human'
         : null,
+    // The repository this item belongs to (AR-132): `owner-<name>`, or null.
+    owner: ownerOfLabels(labels),
+    // The lifecycle and the scheduling flag (AR-144), read above the seam.
+    ...lifecycleOf(labels),
   };
 };
 
@@ -120,7 +130,7 @@ const ghText = (args) =>
 
 const ghJson = (args) => JSON.parse(ghText(args));
 
-const FIELDS = 'number,title,body,state,labels,url,createdAt';
+const FIELDS = 'number,title,body,state,labels,url,createdAt,updatedAt';
 
 // --- the adapter contract ------------------------------------------------------
 
@@ -146,21 +156,63 @@ export const listEligible = ({ limit = 100, issues = null } = {}) => {
 export const resolveBlockers = (ticket) => (ticket.blockedBy ?? []).filter((b) => !b.resolved);
 
 /** `To Do → In Progress` before the first file is edited, not when the PR opens. */
+/**
+ * Re-record the item's marker after a write of this adapter's own (AR-140) —
+ * the same rule and the same limit as `jira.mjs` › rebaseline: only writes
+ * made through this adapter re-baseline, and a read-back that fails is
+ * announced, never thrown.
+ */
+const rebaseline = (ticket) => {
+  const runDir = process.env.RIG_RUN_DIR;
+  if (!runDir) return;
+  try {
+    const after = ghJson(['issue', 'view', ticket.id, '--json', 'updatedAt']);
+    recordTakeUp(runDir, { id: ticket.id, updatedAt: after?.updatedAt ?? null });
+  } catch (error) {
+    process.stderr.write(
+      `#${ticket.id}: the write landed, but its marker was NOT re-recorded in ${runDir} — ` +
+        `${error.message}\n`,
+    );
+  }
+};
+
 export const claim = (ticket) => {
   ghText(['issue', 'edit', ticket.id, '--add-label', 'in-progress']);
+  rebaseline(ticket);
   return { ok: true };
 };
 
+/**
+ * One issue by number, closed included — `gh issue view` sees every state,
+ * where `listEligible` drops CLOSED for selection's sake. The offline `issues`
+ * seam is honoured. `blocks` is empty here: the cross-index needs the whole
+ * list, and a single view does not carry it.
+ */
+export const find = (id, { issues = null } = {}) => {
+  const raw = issues
+    ? (issues.find((issue) => String(issue.number) === String(id)) ?? null)
+    : ghJson(['issue', 'view', String(id), '--json', FIELDS]);
+  return raw ? toTicket(raw, {}) : null;
+};
+
 export const close = (ticket, { prUrl = null } = {}) => {
   const note = prUrl ? `Landed in ${prUrl}.` : 'Closed by the run.';
   ghText(['issue', 'comment', ticket.id, '--body', note]);
   ghText(['issue', 'close', ticket.id]);
-  ghText(['issue', 'edit', ticket.id, '--remove-label', 'in-progress']);
-  return { ok: true };
+  // Read back, never inferred: `gh issue close` exits 0 on an issue that was
+  // already closed, or that a workflow reopened a moment later (AR-135). The
+  // claim label goes only once the read-back says CLOSED — a close that did
+  // not land leaves the item claimed, exactly as it was found.
+  const after = ghJson(['issue', 'view', ticket.id, '--json', 'state']);
+  const transitioned = String(after?.state ?? '').toUpperCase() === 'CLOSED';
+  if (transitioned) ghText(['issue', 'edit', ticket.id, '--remove-label', 'in-progress']);
+  rebaseline(ticket);
+  return { ok: true, transitioned };
 };
 
 export const comment = (ticket, body) => {
   ghText(['issue', 'comment', ticket.id, '--body', body]);
+  rebaseline(ticket);
   return { ok: true };
 };
 
@@ -172,6 +224,7 @@ export const comment = (ticket, body) => {
 export const escalate = (ticket, diagnosis, { env = process.env } = {}) => {
   ghText(['issue', 'comment', ticket.id, '--body', diagnosis]);
   ghText(['issue', 'edit', ticket.id, '--add-label', 'escalated']);
+  rebaseline(ticket);
   // Counted through the one recorder, never a counter of this adapter's own —
   // "twice in a row" has to mean the same thing on every tracker.
   recordEscalation(env.RIG_RUN_DIR);
@@ -196,8 +249,10 @@ export const triageItemFor = (proposal) => {
       `- **part to change** — ${proposal.part}`,
       `- **proposed change** — ${proposal.change}`,
       `- **how the next run proves it** — ${proposal.proof}`,
+      ...(proposal.measured ? [`- **measured** — ${proposal.measured}`, `- **inferred** — ${proposal.inferred}`] : []),
       '',
       `fingerprint: ${fingerprint}`,
+      ...(proposal.asOf ? [`asOf: ${proposal.asOf}`] : []),
       '',
       'The loop proposes; the owner patches. Self-applying a change to its own',
       'rulebook is how an unattended run drifts irreversibly — and it collides with',
@@ -216,15 +271,17 @@ export const triageItemFor = (proposal) => {
  * hand out nothing — "queue empty" and "nothing selectable";
  * twenty such stops must produce one proposal with a count of twenty.
  */
-export const proposeTriage = (proposal, { existing = null } = {}) => {
-  const item = triageItemFor(proposal);
-  const found =
+/** 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]);
-  const duplicate = duplicateOf(
-    item,
-    found.map((issue) => ({ id: String(issue.number), body: issue.body })),
-  );
+    ghJson(['issue', 'list', '--label', 'triage', '--state', 'all', '--limit', '100', '--json', FIELDS])
+  ).map((issue) => ({ id: String(issue.number), body: issue.body }));
+
+export const proposeTriage = (rawProposal, { existing = null } = {}) => {
+  const proposal = withAsOf(rawProposal);
+  const item = triageItemFor(proposal);
+  const duplicate = duplicateOf(item, listProposals({ existing }));
 
   if (duplicate) {
     ghText([
@@ -237,6 +294,23 @@ export const proposeTriage = (proposal, { existing = null } = {}) => {
     return { ok: true, incremented: String(duplicate.number), item };
   }
 
-  ghText(['issue', 'create', '--title', item.title, '--body', item.body, '--label', 'triage']);
-  return { ok: true, filed: item.title, item };
+  const url = ghText(['issue', 'create', '--title', item.title, '--body', item.body, '--label', 'triage']);
+  // The proposal's own baseline (AR-138), as in jira.mjs: `gh issue create`
+  // prints the new issue's URL, whose last segment is its number; the marker
+  // is read back with `gh issue view`. No run directory → nothing recorded.
+  // Best-effort for the same reason as there: the issue exists by now, and a
+  // throw would make the caller file it again.
+  const id = /\/(\d+)\s*$/.exec(String(url ?? ''))?.[1] ?? null;
+  if (id && process.env.RIG_RUN_DIR) {
+    try {
+      const after = ghJson(['issue', 'view', id, '--json', 'updatedAt']);
+      recordTakeUp(process.env.RIG_RUN_DIR, { id, updatedAt: after?.updatedAt ?? null });
+    } catch (error) {
+      process.stderr.write(
+        `proposeTriage: #${id} is filed, but its baseline was NOT recorded in ` +
+          `${process.env.RIG_RUN_DIR} — ${error.message}\n`,
+      );
+    }
+  }
+  return { ok: true, filed: item.title, id, item };
 };

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

@@ -4,7 +4,7 @@
 //   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
+//   node .claude/scripts/queue/index.mjs hygiene         # stale labels, link anomalies, overtaken proposals
 //   node .claude/scripts/queue/index.mjs gate-round --branch <b>   # count a gate round
 //
 // The adapter comes from `.claude/queue.json` (`{"adapter": "plan-md"}`) and
@@ -14,12 +14,21 @@
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { basename, dirname, join } from 'node:path';
-import { hygieneOf, selectNext, stopConditionOf } from './core.mjs';
+import {
+  asOfOf,
+  citedPathsOf,
+  hygieneOf,
+  overtakenOf,
+  revalidationOf,
+  selectNext,
+  stopConditionOf,
+} from './core.mjs';
+import { changedSinceOf, headShaOf } from './as-of.mjs';
 // One resolver, imported rather than re-derived: writer and reader disagreeing
 // about which checkout they are in is the whole of the worktree defect. It lives
 // apart from `state.mjs` so the read path does not drag the tier computation —
 // and `detect-missed-gate.mjs` behind it — into a CLI that never calls either.
-import { mainCheckoutRoot } from './checkout.mjs';
+import { checkoutIsShippable, mainCheckoutRoot } from './checkout.mjs';
 
 const ADAPTERS = {
   'plan-md': './plan-md.mjs',
@@ -222,12 +231,20 @@ const parseArgs = (argv) => {
   return args;
 };
 
-const renderNext = (result, stop) => {
+const renderNext = (result, stop, revalidation = null) => {
   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}]`];
+  // Only a marker that MOVED earns a line: the unchanged case stays quiet and
+  // cheap, and the no-marker case is in the JSON and the event log, not here.
+  if (revalidation?.changed === true) {
+    lines.push(
+      `revalidate: ${revalidation.ticket} hold — ${revalidation.source.join(', ')} ` +
+        `(${revalidation.task.from} → ${revalidation.task.to}) — re-read the item before acting`,
+    );
+  }
   if (result.skipped.length > 0) {
     lines.push('', 'skipped:');
     for (const skip of result.skipped) lines.push(`  ${skip.id} — ${skip.reason}`);
@@ -307,6 +324,15 @@ if (invokedDirectly()) {
       const verdictFor = (rounds) => gateRoundVerdict(rounds, config.options?.maxGateRounds);
       verdictFor(0);
 
+      // 🔴 And refuse a checkout that cannot ship BEFORE counting (AR-141): a
+      // dirty tree or an unpushed HEAD means the round — and the fan-out's
+      // verdicts — would name a head that never reaches CI. Two rounds were once
+      // counted ahead of a commit pre-commit then refused. Thrown, so it lands
+      // in the exit-1 path below: not an exhausted cap, nothing counted.
+      const gitRoot = projectRootOfConfig(configPath) ?? projectRoot;
+      const shippable = checkoutIsShippable(gitRoot);
+      if (!shippable.ok) throw new Error(`${shippable.why} (nothing was counted)`);
+
       const { rounds } = recordGateRound({ branch: args.branch, roundsPath });
       const verdict = verdictFor(rounds);
 
@@ -325,9 +351,9 @@ if (invokedDirectly()) {
         `GATE ROUNDS EXHAUSTED — ${verdict.rounds} rounds on ${args.branch}, cap is ` +
           `${verdict.max}: ${verdict.stop}.\n` +
           '  Do not run another round. The item stops here and goes back to a human ' +
-          'with the round count and whatever the last gate reported — the fixes are ' +
-          'not converging, and another pass buys a full reviewer fan-out to discover ' +
-          'that again.\n' +
+          'with the round count and whatever the last gate reported. Whether those ' +
+          'rounds were paying off is the reader\'s judgement — this command measured ' +
+          'only the count (AR-115).\n' +
           '  Raising the cap to get one more pass on THIS item is the move this ' +
           'refusal exists to prevent.\n',
       );
@@ -336,12 +362,12 @@ if (invokedDirectly()) {
       // 🔴 Exit 1, never 2, and the message says so. Exit 2 means one thing only —
       // the rounds are spent — because `pr-ship` acts on it by ending the task. A
       // broken config, an unreadable counter or a detached checkout must not be
-      // read as a converging-failure stall.
+      // read as a spent cap.
       process.stderr.write(
         `gate-round could not run: ${error.message}\n` +
           '  This is NOT an exhausted cap (that is exit 2). Fix the cause and run step ' +
-          '0 again: a bad config, a bad cap or a detached checkout is refused before ' +
-          'any round is counted, so retrying costs nothing.\n',
+          '0 again: a bad config, a bad cap, a detached checkout, a dirty tree or an ' +
+          'unpushed HEAD is refused before any round is counted, so retrying costs nothing.\n',
       );
       process.exit(1);
     }
@@ -366,8 +392,10 @@ if (invokedDirectly()) {
   // and must keep working exactly as before.
   let readState;
   let stopInputsOf;
+  let recordTakeUp;
+  let previousTakeUp;
   try {
-    ({ readState, stopInputsOf } = await import('../run-state.mjs'));
+    ({ readState, stopInputsOf, recordTakeUp, previousTakeUp } = await import('../run-state.mjs'));
   } catch (error) {
     process.stderr.write(
       `run state: ${error.message}\n` +
@@ -470,12 +498,43 @@ if (invokedDirectly()) {
   }
 
   if (args.command === 'hygiene') {
-    const findings = tickets.map(hygieneOf).filter(Boolean);
+    // The proposals on file are checked too (AR-116): a proposal names the commit
+    // it was measured against, and one whose cited paths moved since is reported
+    // as possibly overtaken. Git runs here, once per distinct `asOf`, against the
+    // project this script belongs to; `core.mjs` only decides.
+    const proposals = await adapter.listProposals(optionsWithPlanPath(config.options, configPath));
+    // The checkout the proposals describe is the project the config names — an
+    // explicit `--config <root>/.claude/queue.json` points at that root — and
+    // this script's own project only when the config implies none.
+    const gitRoot = projectRootOfConfig(configPath) ?? projectRoot;
+    const head = headShaOf({ cwd: gitRoot });
+    const changedByAsOf = new Map();
+    const overtaken = proposals
+      .map((proposal) => {
+        const asOf = asOfOf(proposal.body);
+        if (asOf && !changedByAsOf.has(asOf)) {
+          changedByAsOf.set(asOf, changedSinceOf({ cwd: gitRoot, asOf, head: head ?? 'HEAD' }));
+        }
+        return overtakenOf({
+          id: proposal.id,
+          asOf,
+          citedPaths: citedPathsOf(proposal.body),
+          head,
+          changedSince: asOf ? changedByAsOf.get(asOf) : null,
+        });
+      })
+      .filter(Boolean);
+    const owner = config.options?.owner ?? null;
+    const findings = [
+      ...tickets.map((ticket) => hygieneOf(ticket, { owner })).filter(Boolean),
+      ...overtaken,
+    ];
     process.stdout.write(
       args.json
         ? `${JSON.stringify({ findings }, null, 2)}\n`
         : findings.length === 0
-          ? `queue hygiene: ${tickets.length} item(s) checked — nothing stale.\n`
+          ? `queue hygiene: ${tickets.length} item(s) and ${proposals.length} proposal(s) ` +
+            'checked — nothing stale.\n'
           : `${findings.map((f) => `  [${f.kind}] ${f.id} — ${f.why}`).join('\n')}\n`,
     );
     process.exit(0);
@@ -501,6 +560,9 @@ if (invokedDirectly()) {
     // impossible to retract, so "not this time" would again require editing the
     // generated file this move exists to get out of.
     triggersFired: runState.triggersFired ?? config.triggersFired ?? null,
+    // This checkout's name, for the owner marker (AR-132). Absent means the
+    // checkout cannot confirm a match, and an owned item is held.
+    owner: config.options?.owner ?? null,
   });
   // The skipped records travel with the count: without them "nothing left" and
   // "everything left is held back" both print as an empty queue, and only one of
@@ -524,6 +586,31 @@ if (invokedDirectly()) {
   // a default derived from `projectRoot` would land the trace inside the very
   // template tree this repository publishes.
   const runDir = process.env.RIG_RUN_DIR;
+  // Revalidation at SELECT (AR-133): the selected item against the marker this
+  // run recorded at its last take-up. Computed only under a declared run —
+  // there is no snapshot to compare against anywhere else — and `null` in the
+  // output then, so a reader can tell "not compared" from "compared, unchanged".
+  //
+  // The baseline is this run's take-up when it has one; otherwise the newest
+  // earlier run's (AR-138) — an item taken up yesterday and re-offered today
+  // used to compare against nothing and report a first sight. `baseline` says
+  // which it was (`this-run` | `previous-run` | null), and `baselineRun` names
+  // the earlier run, so the report can tell the three apart. A rig whose
+  // run-state module predates `previousTakeUp` keeps the per-run behaviour.
+  let revalidation = null;
+  if (runDir && result.ticket) {
+    const own = runState.takeUps?.[result.ticket.id];
+    const prior =
+      own === undefined && typeof previousTakeUp === 'function'
+        ? previousTakeUp(runDir, result.ticket.id)
+        : null;
+    const snapshot = own ?? prior?.updatedAt ?? null;
+    revalidation = {
+      ...revalidationOf({ ticket: result.ticket, snapshot }),
+      baseline: own !== undefined ? 'this-run' : prior ? 'previous-run' : null,
+      ...(prior ? { baselineRun: prior.runDir } : {}),
+    };
+  }
   if (runDir) {
     let journal = null;
     try {
@@ -537,6 +624,27 @@ if (invokedDirectly()) {
         // an argument, which is what keeps its records reproducible.
         now: new Date().toISOString(),
       });
+      if (revalidation) {
+        // The selection decision keeps its place as the run's first record; the
+        // evidence log comes next, and only then (below, after the journal) does
+        // the baseline move — a snapshot written before its event would leave a
+        // crashed run with a marker and no record of what it was compared against.
+        if (typeof journal.recordEvent === 'function') {
+          journal.recordEvent({
+            runDir,
+            kind: 'revalidation',
+            data: revalidation,
+            now: new Date().toISOString(),
+          });
+        } else {
+          // A rig carrying a run journal older than this CLI: the selection
+          // stands, the comparison was made, only its record has nowhere to go.
+          process.stderr.write(
+            'run journal: this journal predates revalidation events, so the ' +
+              'revalidation was not recorded.\n',
+          );
+        }
+      }
     } catch (error) {
       // 🔴 Two failures wearing one face, and treating them alike was a defect
       // this gate caught. The journal asks the module which one this is — never
@@ -572,9 +680,24 @@ if (invokedDirectly()) {
     }
   }
 
+  if (revalidation) {
+    // Its own try, after the journal's: a state file that cannot be written is
+    // not the journal failing, and the selection stands either way — the
+    // comparison was made and recorded; only the next baseline is lost.
+    try {
+      recordTakeUp(runDir, { id: result.ticket.id, updatedAt: result.ticket.updatedAt });
+    } catch (error) {
+      process.stderr.write(
+        `run state: the take-up snapshot was NOT recorded in ${runDir} — ${error.message}\n` +
+          '  the selection below stands; the baseline was not moved — the next revalidation ' +
+          'of this item compares against the previous one, if any, or has none.\n',
+      );
+    }
+  }
+
   process.stdout.write(
     args.json
-      ? `${JSON.stringify({ ticket: result.ticket, skipped: result.skipped, stop }, null, 2)}\n`
-      : renderNext(result, stop),
+      ? `${JSON.stringify({ ticket: result.ticket, skipped: result.skipped, stop, revalidation }, null, 2)}\n`
+      : renderNext(result, stop, revalidation),
   );
 }