create-agent-rig 0.5.0 → 0.6.1

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

@@ -14,8 +14,10 @@
 //   {
 //     id, title, url,
 //     state:     'open' | 'in-progress' | 'closed',
-//     labels:    string[],                       // informational, never decisive
+//     labels:    string[],                       // informational — see the note below
 //     tier:      'normal' | 'elevated',
+//     lifecycle: 'keep-core' | 're-scope' | 'obsolete' | null,   // AR-144, from labels
+//     parked:    boolean,                        // scheduling, orthogonal to lifecycle
 //     blockedBy: [{ id, resolved }],             // FROM LINKS — see invariant 1
 //     blocks:    string[],                       // ids this one unblocks
 //     priority:  number,                         // lower is more urgent
@@ -48,6 +50,14 @@
 //
 // `raw` is the adapter's own record of the line or record it parsed. It is
 // deliberately NOT read by this file: it exists for the adapter's writes.
+//
+// **"Labels are informational, never decisive" is a statement about
+// DEPENDENCIES** (invariant 1 below): a `blocked`/`ready` label is a snapshot of
+// a fact the links carry authoritatively. It is not a ban on reading labels at
+// all — `tier`, `trigger`, `triage`, `owner`, and (AR-144) `lifecycle` and
+// `parked` are facts that exist ONLY as a marker, so the marker is the source
+// and the adapter maps it onto a named field. The rule is: a label is never
+// read in place of a source that says the same thing better.
 
 /**
  * The operations every adapter provides. A second tracker is an adapter, not a
@@ -55,12 +65,19 @@
  */
 export const ADAPTER_CONTRACT = [
   'listEligible',
+  // One item by id, WITHOUT the closed filter `listEligible` applies: the close
+  // point has to see an item somebody already closed (AR-135). Each adapter
+  // owns how — the decision is not made above the seam.
+  'find',
   'resolveBlockers',
   'claim',
   'close',
   'comment',
   'escalate',
   'proposeTriage',
+  // The proposals on file, as `{ id, body }`, so hygiene can read each one's
+  // `asOf` and cited paths back (AR-116). Reads only — never a selection input.
+  'listProposals',
 ];
 
 /**
@@ -80,6 +97,17 @@ export const SKIP_CAUSES = Object.freeze([
   'trigger-auto',
   'trigger-human',
   'spacing',
+  'owner',
+  // AR-144: the lifecycle vocabulary. `re-scope` and `deferred` (the `parked`
+  // label) hold takeable work back until a human acts; `obsolete` is out of play
+  // until a human closes it with the evidence — see `lifecycleOf` below.
+  // 🔴 The cause for the `parked` LABEL is `deferred`, not `parked`: this module
+  // already uses "parked" for the out-of-play pile (`partitionSkipped`), and a
+  // parked-labelled item is the opposite — held, takeable, waiting on an un-park.
+  // One word for two states is how a stop line gets read backwards.
+  're-scope',
+  'deferred',
+  'obsolete',
 ]);
 
 /**
@@ -120,8 +148,105 @@ export const HOLDING_CAUSES = Object.freeze([
   'spacing',
   'trigger-auto',
   'trigger-human',
+  // Another repository's item (AR-132). It clears the way `trigger-human`
+  // does — a human moves the item or re-marks it — never by this checkout
+  // doing anything, and never by refilling the queue.
+  'owner',
+  // AR-144: both are real, takeable work waiting on one human act — a rewrite
+  // that removes `re-scope`, or an un-park. `obsolete` is deliberately NOT
+  // here: it waits on a human CLOSE, so it is out of play, and reporting it as
+  // "held" would tell the owner to wait for something that only they can do.
+  're-scope',
+  'deferred',
 ]);
 
+/**
+ * The repository an item belongs to, read out of its labels: `owner-<name>`,
+ * one word for one fact on every tracker. `null` when there is none — and
+ * absence means unconditional, exactly as it does for the trigger markers.
+ * A bare `owner-` names nobody and is read as no marker.
+ *
+ * Why (AR-132): AR-129 and AR-130 were Rig Platform items sitting in this
+ * repository's project. Both were selected as normal spacers and both escalated
+ * PREMISE FALSE at the first premise check, consecutively — a run-level stop,
+ * spent on work that was never this checkout's to do.
+ */
+export const ownerOfLabels = (labels) => {
+  for (const label of Array.isArray(labels) ? labels : []) {
+    if (typeof label === 'string' && label.startsWith('owner-') && label.length > 6) {
+      return label.slice(6);
+    }
+  }
+  return null;
+};
+
+/**
+ * The lifecycle vocabulary (AR-144), closed and ordered from least to most
+ * restrictive. It says what the ITEM is, never when it runs:
+ *
+ * - `keep-core` — the problem and the responsibility are valid for the current
+ *   project and the item is executable as written. A statement, not a condition.
+ * - `re-scope` — the problem is valid but the item is NOT executable literally:
+ *   a path, mechanism, boundary or acceptance criterion drifted. A short-lived
+ *   quarantine: a human re-reads the code, rewrites the item, removes the label.
+ *   The loop surfaces it (hygiene) and never invents the new scope itself.
+ * - `obsolete` — the responsibility is gone or fully superseded. A human verdict:
+ *   the loop never applies it and never closes an item because it believes
+ *   another mechanism supersedes it. Closing as obsolete needs a comment naming
+ *   the evidence or the replacement.
+ *
+ * `parked` is a separate axis — SCHEDULING, not lifecycle: valid work
+ * deliberately not active now. `keep-core + parked` is the normal shape of a
+ * deferred item and means "still needed, not now"; the hold is the `parked`.
+ *
+ * 🔴 None of these is inferred. Not from age, not from a key range, not from old
+ * terminology, not from `parked`, not from a migration marker such as
+ * `legacy-backlog` — which is retired, and which hygiene reports on any open item
+ * still carrying it. A label that looks like "old" is no evidence that the work
+ * is unnecessary — the owner's migration audit on AR-144 closed nothing as obsolete.
+ */
+export const LIFECYCLE_LABELS = Object.freeze(['keep-core', 're-scope', 'obsolete']);
+
+/**
+ * Read the lifecycle and the scheduling flag out of a label list — one
+ * function for every tracker adapter, so the semantics live above the seam.
+ *
+ * Several lifecycle labels on one item is a contradiction hygiene reports
+ * (`contradictory-lifecycle-labels`); selection meanwhile takes the MOST
+ * restrictive reading, because the permissive one is how an item marked
+ * `obsolete` by one hand and `keep-core` by another gets worked.
+ */
+export const lifecycleOf = (labels) => {
+  const list = Array.isArray(labels) ? labels : [];
+  let lifecycle = null;
+  for (const label of LIFECYCLE_LABELS) if (list.includes(label)) lifecycle = label;
+  return { lifecycle, parked: list.includes('parked') };
+};
+
+/** The lifecycle labels an item carries, for the contradiction check. */
+const lifecycleLabelsOn = (labels) => {
+  const list = Array.isArray(labels) ? labels : [];
+  return LIFECYCLE_LABELS.filter((label) => list.includes(label));
+};
+
+/**
+ * Why an owned item is not this checkout's, or null when it is (or claims no
+ * owner). One predicate for selection and for hygiene, so the two cannot
+ * disagree about the same item. A checkout that declares no owner cannot
+ * confirm a match, and "could not look" is never "it is fine".
+ */
+const ownerMismatchOf = (ticket, owner) => {
+  if (!ticket.owner) return null;
+  if (owner === null || owner === undefined || owner === '') {
+    return (
+      `owned by ${ticket.owner}, and this checkout declares no owner ` +
+      '(options.owner in .claude/queue.json) — a match cannot be confirmed'
+    );
+  }
+  if (ticket.owner === owner) return null;
+  return `owned by ${ticket.owner}, and this checkout is ${owner}`;
+};
+
 /**
  * Is this item takeable, and if not, why not?
  *
@@ -130,7 +255,7 @@ export const HOLDING_CAUSES = Object.freeze([
  * `cause` tag, so the stop line can say what is holding the queue back without
  * reading the prose back.
  */
-export const selectionOf = (ticket, { triggersFired = null } = {}) => {
+export const selectionOf = (ticket, { triggersFired = null, owner = null } = {}) => {
   const reasons = [];
   const causes = [];
   const labels = ticket.labels ?? [];
@@ -181,6 +306,33 @@ export const selectionOf = (ticket, { triggersFired = null } = {}) => {
   // that claim, and it would be false for the item most likely to carry both:
   // one an owner tightened from auto-gated to human-gated without deleting the
   // old marker, where the silent resolution goes to the LESS restrictive gate.
+  // Another repository's item is held, not taken (AR-132). The marker is the
+  // adapter's `owner` field; a checkout names itself in `options.owner`.
+  const foreign = ownerMismatchOf(ticket, owner);
+  if (foreign) reject('owner', `${foreign} — moving or re-marking it is a human act`);
+
+  // AR-144: the lifecycle vocabulary, read from the adapter's `lifecycle` and
+  // `parked` fields (`lifecycleOf`). `keep-core` never rejects — it is a
+  // statement that the item is executable, not a condition on taking it.
+  if (ticket.lifecycle === 're-scope') {
+    reject(
+      're-scope',
+      're-scope: the problem is valid but the item is not executable as written — ' +
+        'a human rewrites it against the current code and removes the label; the ' +
+        'loop never invents the new scope',
+    );
+  }
+  if (ticket.parked === true) {
+    reject('deferred', 'parked (deferred): valid work deliberately not active now — a human un-parks it');
+  }
+  if (ticket.lifecycle === 'obsolete') {
+    reject(
+      'obsolete',
+      'obsolete: a human verdict — a human closes it, with a comment naming the ' +
+        'evidence or the replacement; the loop neither takes it nor closes it',
+    );
+  }
+
   if (ticket.trigger === 'human') {
     reject(
       'trigger-human',
@@ -210,10 +362,54 @@ export const selectionOf = (ticket, { triggersFired = null } = {}) => {
  * Reported, never silently corrected: a loop that quietly rewrites the queue's
  * own metadata removes the evidence that the metadata is unreliable.
  */
-export const hygieneOf = (ticket) => {
+export const hygieneOf = (ticket, { owner = null } = {}) => {
   const labels = ticket.labels ?? [];
   const open = (ticket.blockedBy ?? []).filter((blocker) => !blocker.resolved);
 
+  const foreign = ownerMismatchOf(ticket, owner);
+  if (foreign) {
+    return {
+      kind: 'owner-mismatch',
+      id: ticket.id,
+      why: `${foreign} — it sits in this queue but is not this repository's to do`,
+    };
+  }
+
+  // AR-144: the retired migration marker, and the lifecycle contradictions.
+  // Reported, never corrected: which label is the wrong one is a human call.
+  if (labels.includes('legacy-backlog') && ticket.state !== 'closed') {
+    return {
+      kind: 'stale-legacy-backlog-label',
+      id: ticket.id,
+      why:
+        'still carries legacy-backlog, which is retired — it says nothing about ' +
+        'whether the work is needed. Re-mark it keep-core, re-scope or obsolete ' +
+        '(and parked if deferred); the loop infers none of those from it',
+    };
+  }
+  const lifecycles = lifecycleLabelsOn(labels);
+  if (lifecycles.length > 1) {
+    return {
+      kind: 'contradictory-lifecycle-labels',
+      id: ticket.id,
+      why:
+        `carries ${lifecycles.join(' and ')} at once, and an item has one lifecycle — ` +
+        `selection reads the most restrictive (${lifecycleOf(labels).lifecycle}); ` +
+        'a human removes the wrong one',
+    };
+  }
+  if (ticket.lifecycle === 're-scope' && ticket.state !== 'closed') {
+    return {
+      kind: 're-scope-pending',
+      id: ticket.id,
+      why:
+        'marked re-scope: the problem is valid but the item is not executable as ' +
+        'written. It waits on a human rewrite against the current code — a ' +
+        'quarantine, not a backlog category, so it is reported until the label ' +
+        'comes off',
+    };
+  }
+
   if (labels.includes('blocked') && open.length === 0) {
     return {
       kind: 'stale-blocked-label',
@@ -395,8 +591,10 @@ const clearsSpacing = (lastCompletedTier) =>
  * than it should have".
  *
  * Two is the cap because the second round is what verifies the first round's fixes.
- * A third means they are not converging, which is a diagnosis for a human rather
- * than another pass to buy.
+ * A third is a decision for a human rather than another pass to buy — and the
+ * refusal says only that the count is spent, never that the fixes "are not
+ * converging": on one branch a granted third round found that round 2's fix had
+ * opened the mirror of the bug it closed (AR-115).
  */
 export const DEFAULT_MAX_GATE_ROUNDS = 2;
 
@@ -442,12 +640,15 @@ export const gateRoundVerdict = (rounds, max = DEFAULT_MAX_GATE_ROUNDS) => {
  * items back to back — one unreviewed schema or permissions change is
  * recoverable; a chain of them compounding overnight is not.
  */
-export const selectNext = (tickets, { lastCompletedTier = null, triggersFired = null } = {}) => {
+export const selectNext = (
+  tickets,
+  { lastCompletedTier = null, triggersFired = null, owner = null } = {},
+) => {
   const skipped = [];
   const candidates = [];
 
   for (const ticket of tickets) {
-    const selection = selectionOf(ticket, { triggersFired });
+    const selection = selectionOf(ticket, { triggersFired, owner });
     if (!selection.eligible) {
       skipped.push({
         id: ticket.id,
@@ -474,6 +675,93 @@ export const selectNext = (tickets, { lastCompletedTier = null, triggersFired =
   return { ticket, skipped, candidates: candidates.length };
 };
 
+/**
+ * Revalidation at SELECT — is the item the run is about to take the item the
+ * last take-up saw?
+ *
+ * The snapshot is the ticket's `updatedAt` marker as recorded at the previous
+ * take-up in THIS run (`run-state.mjs` › recordTakeUp). One string compare on
+ * the tracker's last-modified field, no second network call — the unchanged
+ * case costs nothing. That the field moves on every edit, comment and status
+ * change is the tracker's contract, assumed here and not checked.
+ *
+ * 🔴 **`changed` is three-valued, and `null` is the honest one.** An adapter
+ * with no marker (`plan-md`) cannot say "unchanged"; it can only say it did not
+ * look. Collapsing that into `false` would report a blind spot as a pass, which
+ * is the one thing an evidence log must never do. `true` is reserved for a
+ * marker that moved: a first sight (no snapshot yet) is `false` with the baseline
+ * recorded, not a change.
+ *
+ * `action` says what the run does with it: `hold` — re-read the item before
+ * acting; `continue` — nothing moved; `unverifiable` — no marker to compare.
+ *
+ * ⚠ Limit: the marker moves on the run's OWN claim and comments too. The
+ * tracker adapters re-record the take-up after each write they make (AR-140),
+ * so a move made THROUGH the adapter is not a hold — one made by any other
+ * route (a hand-posted comment, a connector) still is. This function cannot
+ * tell who moved it; the re-read can, and the `loop` skill records that
+ * conclusion as a separate `revalidation-outcome` event.
+ */
+export const revalidationOf = ({ ticket, snapshot = null }) => {
+  const to = typeof ticket?.updatedAt === 'string' ? ticket.updatedAt : null;
+  const from = typeof snapshot === 'string' ? snapshot : null;
+  // One shape at every point (AR-136): `source` is the list of what moved,
+  // `action` the same three words BEFORE_PR and BEFORE_CLOSE use, and the two
+  // markers sit under `task` — so a reader of the evidence log needs one parser.
+  const base = { ticket: ticket?.id ?? null, point: 'SELECT', task: { from, to } };
+  if (to === null) return { ...base, changed: null, source: [], action: 'unverifiable' };
+  const changed = from !== null && from !== to;
+  return {
+    ...base,
+    changed,
+    source: changed ? ['task:updatedAt'] : [],
+    action: changed ? 'hold' : 'continue',
+  };
+};
+
+/**
+ * Revalidation at BEFORE_PR — the aggregate over two sources, pure.
+ *
+ * `task` is what {@link revalidationOf} returned for the ticket against the
+ * take-up snapshot; `mainChanged` is the list of cited paths the default branch
+ * changed since the branch forked (`revalidate.mjs` computes it from git). One
+ * source name per finding — `task:updatedAt`, `main:<path>` — so a hold names
+ * exactly what moved, never "something changed".
+ *
+ * `changed` keeps the three values of the SELECT point: `true` when any source
+ * moved; `null` when nothing moved but the task could not be checked (no
+ * snapshot, no marker, no run) — a blind spot on one side is not a clean pass
+ * on both; `false` only when both sides were compared and neither moved.
+ */
+export const beforePrRevalidationOf = ({ ticket, task = { changed: null }, mainChanged = [] }) => {
+  const source = [
+    ...(task?.changed === true ? ['task:updatedAt'] : []),
+    ...mainChanged.map((path) => `main:${path}`),
+  ];
+  const changed = source.length > 0 ? true : task?.changed === null ? null : false;
+  const action = changed === true ? 'hold' : changed === null ? 'unverifiable' : 'continue';
+  return { ticket, point: 'BEFORE_PR', changed, source, action };
+};
+
+/**
+ * Revalidation at BEFORE_CLOSE — the aggregate over the item's marker and its
+ * state, pure. `task` is what {@link revalidationOf} returned against the last
+ * validation; `state` is the item's neutral state now. At close the item is
+ * expected `in-progress`: `closed` means someone else published it, `open`
+ * means someone moved it back, and either is a change the close must not
+ * paper over. Same three-valued `changed` and the same actions as BEFORE_PR;
+ * `task:updatedAt` is named before `task:state`.
+ */
+export const beforeCloseRevalidationOf = ({ ticket, task = { changed: null }, state = null }) => {
+  const source = [
+    ...(task?.changed === true ? ['task:updatedAt'] : []),
+    ...(state !== 'in-progress' ? ['task:state'] : []),
+  ];
+  const changed = source.length > 0 ? true : task?.changed === null ? null : false;
+  const action = changed === true ? 'hold' : changed === null ? 'unverifiable' : 'continue';
+  return { ticket, point: 'BEFORE_CLOSE', changed, source, action };
+};
+
 /**
  * Split the skipped records into the ones holding takeable work back and the
  * ones that are simply out of play.
@@ -556,7 +844,12 @@ const parkedNote = (parked) =>
     ? ''
     : ` A further ${parked.length} item(s) are parked — ${breakdownOf(parked)}. ` +
       'Those are not work this run can take and they wait on a human, never on ' +
-      'time.';
+      'time' +
+      (parked.includes('obsolete')
+        ? '; an obsolete item waits on a human close with a comment naming the ' +
+          'evidence or the replacement, which the loop never writes'
+        : '') +
+      '.';
 
 /**
  * The trigger remedies, composed from the tags actually present.
@@ -597,6 +890,35 @@ const triggerNote = (held) => {
   );
 };
 
+/**
+ * The owner remedy (AR-132), present only when the pile carries the tag: an item
+ * another repository owns is freed by a human moving or re-marking it — never by
+ * waiting, and never by refilling this queue.
+ */
+const ownerNote = (held) =>
+  held.includes('owner')
+    ? ' An item held as owner belongs to another repository (its `owner-<name>` ' +
+      "label is not this checkout's `options.owner`): a human moves it to that " +
+      "repository's queue or re-marks it; nothing this checkout does frees it."
+    : '';
+
+/**
+ * The lifecycle remedies (AR-144), each present only when its tag is in the pile.
+ * Both are human acts on the item itself — neither time nor interleaving frees
+ * them, and the loop must not perform either: rewriting a `re-scope` item is
+ * authoring its own work, and un-parking is a scheduling decision.
+ */
+const lifecycleNote = (held) =>
+  (held.includes('re-scope')
+    ? ' An item held as re-scope is valid work that is not executable as written: ' +
+      'a human rewrites it against the current code and removes the label; the ' +
+      'loop never invents the new scope.'
+    : '') +
+  (held.includes('deferred')
+    ? ' An item held as deferred carries the parked label — valid work deliberately ' +
+      'not active now: a human un-parks it; nothing this run does frees it.'
+    : '');
+
 /**
  * Should the whole run stop? Checked in severity order, because a regression must
  * not be reported as an empty queue.
@@ -675,7 +997,7 @@ export const stopConditionOf = ({
           'and the two ask for opposite things: an empty queue wants refilling, ' +
           'whereas this one still holds work. Spacing clears when a normal item ' +
           'lands, a blocker when its item closes, in-progress when the other ' +
-          `session finishes.${triggerNote(held)} Otherwise the action is to ` +
+          `session finishes.${triggerNote(held) + ownerNote(held) + lifecycleNote(held)} Otherwise the action is to ` +
           'interleave or to wait, never to refill and never to invent work.',
       };
     }
@@ -737,5 +1059,153 @@ export const validateProposal = (proposal) => {
         'run would prove it worked)',
     );
   }
+  checkInferenceAgainstMeasurement(proposal);
   return proposal;
 };
+
+/**
+ * What a proposal MEASURED and what it INFERRED from that, as two paired
+ * optional fields (AR-142).
+ *
+ * A proposal whose premise was never true had no check at filing, only at
+ * take-up: AR-124 was filed, promoted and claimed before anyone found that its
+ * platform conclusion rested on a probe that had touched one hook. So the two
+ * halves are named separately, and an inference that cites a path the
+ * measurement does not cite is refused here, with both fields and the path
+ * named — the author has to either measure that surface or stop claiming it.
+ *
+ * A "surface" is a cited path, read by `citedPathsOf`: a text scan, so a
+ * surface named indirectly ("the platform") is invisible to this check — it
+ * catches the path-shaped overreach and nothing subtler. Neither field given
+ * files as before; one without the other is refused, because a measurement
+ * without its inference (or the reverse) is exactly the half-formed shape the
+ * pairing exists to make visible.
+ */
+const checkInferenceAgainstMeasurement = ({ measured, inferred } = {}) => {
+  const has = (value) => typeof value === 'string' && value.trim().length > 0;
+  if (!has(measured) && !has(inferred)) return;
+  if (!has(measured) || !has(inferred)) {
+    const present = has(measured) ? 'measured' : 'inferred';
+    const absent = has(measured) ? 'inferred' : 'measured';
+    throw new Error(
+      `a proposal that names what it ${present} must also name what it ${absent}: ` +
+        `\`${present}\` is given and \`${absent}\` is not — the two are a pair`,
+    );
+  }
+  const touched = new Set(citedPathsOf(measured));
+  const overreach = citedPathsOf(inferred).filter((path) => !touched.has(path));
+  if (overreach.length > 0) {
+    throw new Error(
+      `a proposal's inference names a surface its measurement did not touch: ` +
+        `\`inferred\` cites ${overreach.join(', ')}, which \`measured\` does not. ` +
+        'Measure that surface, or keep the inference inside what was measured.',
+    );
+  }
+};
+
+/**
+ * The commit a proposal was measured against, read back out of its body — or
+ * null when the body carries none (AR-116).
+ *
+ * Seven to forty hex characters, after the literal `asOf: `. An absent marker is
+ * `null`, never "HEAD": the hygiene finding for it is "unanswerable", and a
+ * default that quietly said "current" is the failure this field exists to name.
+ */
+const AS_OF_IN_BODY = /(?:^|[\s(`"'])asOf: ([0-9a-f]{7,40})(?![0-9a-z])/;
+
+export const asOfOf = (body) => {
+  const text = typeof body === 'string' ? body : '';
+  const match = AS_OF_IN_BODY.exec(text.slice(0, 20_000));
+  return match ? match[1] : null;
+};
+
+/**
+ * The repository paths a proposal's text cites, in order of first mention.
+ *
+ * A path here is a token ending in a source or document extension, with any
+ * directory prefix — `queue/core.mjs`, `.claude/rules/workflow.md`,
+ * `journal/2026-08.md`. It is a text scan, so a path named indirectly ("the
+ * router") is invisible, and a bare word with an extension counts even when it
+ * is not a file — the finding it feeds says "possibly", for exactly this reason.
+ *
+ * Bounded: one pass over at most 20 000 characters, at most 200 matches.
+ */
+const PATH_IN_TEXT =
+  /(?<![\w./-])((?:[\w.-]+\/)*[\w-][\w.-]*\.(?:mjs|cjs|js|ts|tsx|md|mdx|json|ya?ml|sh|txt))(?![\w/])/g;
+
+export const citedPathsOf = (text) => {
+  const source = (typeof text === 'string' ? text : '').slice(0, 20_000);
+  const seen = new Set();
+  let match;
+  while (seen.size < 200 && (match = PATH_IN_TEXT.exec(source)) !== null) {
+    seen.add(match[1]);
+  }
+  PATH_IN_TEXT.lastIndex = 0;
+  return [...seen];
+};
+
+/**
+ * Has the code a proposal describes moved since the proposal was written?
+ *
+ * Pure: `changedSince` is the list of paths git reports changed between `asOf`
+ * and `head`, or `null` when git could not answer — an unknown commit, a
+ * shallow clone, no checkout at all. The caller runs git; this decides.
+ *
+ * Why it exists: AR-47 and AR-87 both escalated PREMISE FALSE because the merge
+ * that falsified each landed after the proposal was filed, and selection hands
+ * out the oldest proposal first. Nothing on the item said which commit the
+ * finding described, so nothing could say it had been overtaken.
+ *
+ * Every answer short of "clean" is a finding. A proposal without `asOf` is
+ * reported as unanswerable, never as current; one citing no path cannot be
+ * checked by path and says so; a git that could not diff is reported as such.
+ * Silence means: filed against HEAD, or every cited path unchanged since.
+ */
+export const overtakenOf = ({ id, asOf = null, citedPaths = [], head = null, changedSince = null }) => {
+  if (!asOf) {
+    return {
+      kind: 'proposal-asof-missing',
+      id,
+      why:
+        'the proposal does not say which commit it was measured against, so whether ' +
+        'the code it describes has moved since cannot be answered — unanswerable, ' +
+        'not clean',
+    };
+  }
+  const paths = Array.isArray(citedPaths) ? citedPaths : [];
+  if (paths.length === 0) {
+    return {
+      kind: 'proposal-cites-no-path',
+      id,
+      why:
+        `measured against ${asOf}, but its text names no repository path, so a change ` +
+        'that overtook it cannot be seen by path — read it before acting on it',
+    };
+  }
+  const current = typeof head === 'string' && (head.startsWith(asOf) || asOf.startsWith(head));
+  if (current) return null;
+  if (changedSince === null) {
+    return {
+      kind: 'proposal-asof-unanswerable',
+      id,
+      why:
+        `git could not list what changed since ${asOf} — an unknown commit, a shallow ` +
+        'clone, or no checkout — so whether the proposal was overtaken is unanswered',
+    };
+  }
+  // By suffix on a path boundary, because findings cite the way people write —
+  // `queue/core.mjs` for `.claude/scripts/queue/core.mjs` — and an exact match
+  // would read that citation as clean, the one direction of miss this exists to
+  // prevent. `x/not-core.mjs` is not a match for `core.mjs`.
+  const moved = changedSince.filter((changed) =>
+    paths.some((cited) => changed === cited || changed.endsWith(`/${cited}`)),
+  );
+  if (moved.length === 0) return null;
+  return {
+    kind: 'proposal-possibly-overtaken',
+    id,
+    why:
+      `measured against ${asOf}, and ${moved.join(', ')} changed since — re-read the ` +
+      'proposal against the code before taking it; its premise may have rotted',
+  };
+};