create-agent-rig 0.4.0 → 0.6.0

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

@@ -12,24 +12,32 @@
 // 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';
+import { duplicateOf, fingerprintOf, validateProposal, lifecycleOf } from './core.mjs';
+import { withAsOf } from './as-of.mjs';
+import { recordEscalation } from '../run-state.mjs';
 
 export const name = 'plan-md';
 
 const AGENT_QUEUE = /^##\s+Agent queue\s*$/i;
+const OPERATOR_QUEUE = /^##\s+Operator queue\s*$/i;
 const ANY_HEADING = /^##\s+/;
 
 /**
- * Locate the Agent queue by LINE RANGE, and say whether it was found at all.
+ * Locate a `## ` section 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.
+ *
+ * Parameterised by heading because there are now two callers and the alternative
+ * was a second copy of this scan — and two implementations of one mechanism
+ * disagree eventually, with the unwatched one being the wrong one
+ * (`invariants.md`). The Agent-queue caller keeps its own name below.
  */
-export const readQueue = (plan) => {
+const sectionRange = (plan, heading) => {
   const lines = String(plan ?? '').split('\n');
-  const start = lines.findIndex((line) => AGENT_QUEUE.test(line));
+  const start = lines.findIndex((line) => heading.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) {
@@ -41,6 +49,8 @@ export const readQueue = (plan) => {
   return { found: true, lines, start: start + 1, end };
 };
 
+export const readQueue = (plan) => sectionRange(plan, AGENT_QUEUE);
+
 /**
  * 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
@@ -51,6 +61,17 @@ const MARKERS = {
   triage: /\[triage\]/i,
   triggerAuto: /\[trigger-auto\]/i,
   triggerHuman: /\[trigger-human\]/i,
+  // `[owner:<name>]` — the repository the item belongs to (AR-132), the same
+  // fact the tracker adapters read out of an `owner-<name>` label. Case-exact,
+  // because the name is compared exactly to `options.owner`.
+  owner: /\[owner:([^\]\s]+)\]/,
+  // AR-144: the lifecycle vocabulary and the scheduling flag, the same words the
+  // tracker adapters read as labels. Case-insensitive, as the tier and trigger
+  // markers are (the owner marker is case-exact, because it is compared to a name).
+  keepCore: /\[keep-core\]/i,
+  reScope: /\[re-scope\]/i,
+  obsolete: /\[obsolete\]/i,
+  parked: /\[parked\]/i,
 };
 
 /**
@@ -82,7 +103,10 @@ export const parsePlan = (plan) => {
     if (!match) continue;
     const raw = match[1];
     const title = raw
-      .replace(/\[(elevated|triage|trigger-auto|trigger-human)\]/gi, '')
+      .replace(
+        /\[(elevated|triage|trigger-auto|trigger-human|keep-core|re-scope|obsolete|parked|owner:[^\]\s]+)\]/gi,
+        '',
+      )
       .replace(/\s+/g, ' ')
       .trim();
     items.push({
@@ -105,12 +129,29 @@ export const parsePlan = (plan) => {
       blocks: [],
       priority: items.length,
       createdAt: null,
+      // A flat list carries no marker at all, so revalidation at SELECT records
+      // `changed: null` for it — a blind spot, never an "unchanged".
+      updatedAt: null,
       triage: MARKERS.triage.test(raw),
       trigger: MARKERS.triggerAuto.test(raw)
         ? 'auto'
         : MARKERS.triggerHuman.test(raw)
           ? 'human'
           : null,
+      owner: MARKERS.owner.exec(raw)?.[1] ?? null,
+      // The markers present, handed to the one precedence rule (`core.mjs` ›
+      // lifecycleOf) rather than re-deriving it here. Hygiene cannot report a
+      // contradiction on this adapter: a flat list carries no labels for it to read.
+      ...lifecycleOf(
+        [
+          ['keep-core', MARKERS.keepCore],
+          ['re-scope', MARKERS.reScope],
+          ['obsolete', MARKERS.obsolete],
+          ['parked', MARKERS.parked],
+        ]
+          .filter(([, marker]) => marker.test(raw))
+          .map(([label]) => label),
+      ),
     });
   }
   return items;
@@ -134,6 +175,12 @@ export const closeInPlan = (plan, id) => {
   return lines.join('\n');
 };
 
+// 🔴 The bare default is cwd-relative on purpose. This module is imported
+// directly as well as driven by the CLI, and a direct caller's cwd is the only
+// project it can mean. The CLI, which knows where its config lives, supplies an
+// absolute `planPath` instead — see `optionsWithPlanPath` in `index.mjs`.
+// Resolving this default from the module's own location would point every call at
+// the rig's own tree.
 const planPath = (options) => options?.planPath ?? 'PLAN.md';
 const readPlan = (options) => readFileSync(planPath(options), 'utf8');
 
@@ -175,27 +222,44 @@ export const claim = (ticket) => ({
     'its own worktree and say so in the journal.',
 });
 
+/** One item by position; a flat list has no closed state, so an absent line is `null`. */
+export const find = (id, options = {}) =>
+  parsePlan(readPlan(options)).find((ticket) => ticket.id === String(id)) ?? null;
+
 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 };
+  const before = readFileSync(file, 'utf8');
+  const present = parsePlan(before).some((item) => item.id === String(ticket.id));
+  writeFileSync(file, closeInPlan(before, ticket.id));
+  // `transitioned` means the line was there and is now gone — an id the plan
+  // never carried closed nothing, and saying otherwise would publish a close
+  // that changed no state (AR-135).
+  const gone = !parsePlan(readFileSync(file, 'utf8')).some((item) => item.id === String(ticket.id));
+  return { ok: true, prUrl, transitioned: present && gone };
 };
 
 /** 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.',
+  why: 'PLAN.md has no comment thread: write it as a journal entry in journal/YYYY-MM.md for the current month.',
 });
 
-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.',
-});
+export const escalate = (ticket, diagnosis, { env = process.env } = {}) => {
+  // The count is recorded even though this adapter cannot mark the item: the two
+  // are different facts. "This queue has no per-item state" is a plan-md limit;
+  // "two tasks in a row hit a wall" is about the run, and it must stop the run
+  // whichever tracker it is reading.
+  recordEscalation(env.RIG_RUN_DIR);
+  return {
+    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.
@@ -220,8 +284,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.',
@@ -232,14 +298,212 @@ export const triageItemFor = (proposal) => {
   };
 };
 
-export const proposeTriage = (proposal, { planPath: p } = {}) => {
+/**
+ * The trailing fields this adapter writes, and the only thing it will ever edit.
+ *
+ * 🔴 Both patterns are anchored to the END of the line, and that is the whole
+ * point. An unanchored `seen ×(\d+)` matched the FIRST such token in the bullet —
+ * and a proposal is free text, so a proposal *about* the counter ("render
+ * `seen ×2` as twice") put one there itself. Observed: the count read back as 3
+ * then 4 while the file still said ×1, and the increment rewrote the number
+ * inside the finding — silently altering the human-facing record of what the loop
+ * found, which `core.mjs` forbids for queue metadata in as many words.
+ */
+const TAIL = /·\sfingerprint: `([^`]*)`\s·\sseen ×(\d+)\s*$/;
+const COUNT = /seen ×(\d+)\s*$/;
+
+/**
+ * Fold a field onto one line.
+ *
+ * 🔴 A bullet is spliced into the file as a single array element and joined with
+ * newlines, so a `\n` inside a proposal's own prose became REAL lines in the
+ * plan. Two things broke at once: the `fingerprint … seen ×N` tail landed on a
+ * different physical line from the bullet, which defeated dedup permanently; and
+ * a pasted `## Agent queue` line became a heading — on a plan whose Operator
+ * queue comes first, `selectNext` then handed the run its own proposal as
+ * ordinary work, with the `[triage]` marker stranded on the line above.
+ *
+ * Not an exotic input: `autonomy.md` tells an escalating run to report "verbatim
+ * errors, not summaries", so a stack trace in `finding` is the expected case.
+ * The text survives; its layout does not — and "layout" includes interior runs
+ * of tabs and spaces, which collapse to one space each. `parsePlan` normalises
+ * titles the same way, so this is the house convention rather than a special
+ * case, but it is wider than "newlines are folded" and worth knowing before
+ * relying on a field surviving byte-for-byte.
+ *
+ * 🔴 One quantifier over one class, because the obvious spelling was quadratic:
+ * putting an unbounded whitespace quantifier in front of a line-terminator class
+ * — which is a SUBSET of whitespace — makes the engine re-split a whitespace run
+ * at every offset. Measured at 6.7s on 65k spaces, 103s on 256k, and 0s the
+ * moment a newline appears after the run, which is why every injection fixture
+ * missed it. That is the fourth time this shape has landed in this queue layer;
+ * `core.mjs` already says remembering it once was not enough.
+ *
+ * JS `\s` covers U+2028 and U+2029 as well as the ASCII set, so those fold too.
+ * U+0085 and NUL do not, and they survive verbatim — harmless, because
+ * `split('\n')` is this adapter's whole line model, but a renderer may show them
+ * as breaks.
+ *
+ * Exported for its cost guard. Measuring the fold through `proposeTriage` meant
+ * measuring the plan file it rewrites per call — which grew as the measurement
+ * ran, and read DEARER on a faster machine. The guard measures this function
+ * directly instead; nothing outside the test imports it.
+ */
+export const oneLine = (text) => String(text ?? '').replace(/\s+/g, ' ').trim();
+
+/**
+ * The proposal as ONE Operator-queue bullet: a flat list cannot hold a body.
+ *
+ * The counter goes LAST, after the fingerprint, so the anchors above land on the
+ * adapter's own fields whatever the proposal's prose happens to contain.
+ */
+const bulletFor = (item, proposal, seen) =>
+  `- **${oneLine(item.title)}** — finding: ${oneLine(proposal.finding)} · ` +
+  `part: ${oneLine(proposal.part)} · proof: ${oneLine(proposal.proof)} · ` +
+  `${proposal.measured ? `measured: ${oneLine(proposal.measured)} · inferred: ${oneLine(proposal.inferred)} · ` : ''}` +
+  `${proposal.asOf ? `asOf: ${proposal.asOf} · ` : ''}` +
+  `fingerprint: \`${item.fingerprint}\` · seen ×${seen}`;
+
+/**
+ * The proposals on file, as `{ id, body }` — every Operator-queue line carrying
+ * this adapter's trailing field shape, the whole line as the body so `asOfOf`
+ * and `citedPathsOf` can read it. An absent Operator queue lists nothing.
+ */
+export const listProposals = ({ planPath: p } = {}) => {
+  const plan = readFileSync(p ?? 'PLAN.md', 'utf8');
+  const { found, lines, start, end } = sectionRange(plan, OPERATOR_QUEUE);
+  if (!found) return [];
+  const proposals = [];
+  for (let i = start; i < end; i += 1) {
+    if (TAIL.test(lines[i])) proposals.push({ id: String(i), body: lines[i] });
+  }
+  return proposals;
+};
+
+/**
+ * File a proposal into the **Operator queue** — never the Agent queue.
+ *
+ * This adapter used to return `ok: false` and instruct a human to file it by
+ * hand, which is a channel only in form: over the loop's entire history that
+ * instruction produced one triage ticket. A channel nobody walks is where
+ * findings go to die, and the findings it loses are the ones about the loop
+ * itself.
+ *
+ * 🔴 Two invariants, and the writing is what puts them at risk:
+ * - it appends **only** inside the Operator queue's line range, so the agent can
+ *   never file itself selectable work;
+ * - the `[triage]` marker rides in the title, so even a proposal moved under the
+ *   wrong heading by hand is still refused by `selectionOf`.
+ *
+ * Deduping is the shared `duplicateOf` from `core.mjs`, so the three adapters
+ * cannot drift into three different answers about what counts as the same
+ * proposal. Twenty "queue empty" stops must leave ONE proposal counted twenty
+ * times, not twenty proposals.
+ *
+ * Bounded by construction: work is linear in the section's length, no recursion,
+ * no rescanning, and `validateProposal` throws before the file is read — an
+ * incomplete proposal cannot leave a partial write behind.
+ *
+ * One difference from the other two adapters, deliberate and worth knowing:
+ * `incremented` is the **fingerprint** here, where `github-issues` returns an
+ * issue number and `jira` an issue key. A flat list has no per-item identifier
+ * that survives an edit — the line index shifts the moment anything above it
+ * changes — and the fingerprint is the only stable name this adapter can give.
+ *
+ * What this cannot see, stated so nobody relies on cover it lacks:
+ * - a filed bullet whose trailing `fingerprint … seen ×N` fields a human has
+ *   edited away no longer matches, so the next call files a second bullet
+ *   rather than incrementing. That is the deliberate direction to fail in: a
+ *   duplicate is visible and cheap, editing somebody else's line is not;
+ * - a HUMAN line ending in this adapter's exact `· fingerprint: \`x\` · seen ×N`
+ *   shape is indistinguishable from one the adapter wrote, and gets incremented
+ *   instead of the proposal being filed. Reachable only by hand — a proposal's
+ *   own prose cannot trigger it, because the real tail is always appended after
+ *   every field — but the check is a shape test, not an authorship proof;
+ * - two *distinct* proposals can still be treated as one, by two separate
+ *   mechanisms in `core.mjs`, both shared by all three adapters and neither
+ *   fixable here. `fingerprintOf` truncates each part to 40 characters, so two
+ *   long proposals differing only past that point produce the SAME fingerprint;
+ *   and `duplicateOf` matches by substring, so a short fingerprint that is a
+ *   prefix of a longer one matches it even when both are well under 40
+ *   characters (`f:p:rename-the` against `f:p:rename-the-counter`). The prefix
+ *   case bites in one direction only: the short one filed second is swallowed,
+ *   the reverse order files both. When it bites, the caller is told
+ *   `{ok: true, incremented: <the short fingerprint>}` for a bullet that carries
+ *   the long one — the same "incremented something that does not exist" shape
+ *   this adapter has a test for in the quoted-prose case;
+ * - a CRLF plan file comes back mixed — `sectionRange` splits on `\n`, so every
+ *   pre-existing line keeps its `\r` and the appended bullet has none. An
+ *   increment drops the `\r` from the line it rewrites, because the counter
+ *   pattern's trailing whitespace is inside the match;
+ * - only the FIRST `## Operator queue` is ever written to: `sectionRange` uses
+ *   `findIndex`, so a second one later in the file is invisible;
+ * - a missing plan file throws `ENOENT` from the read rather than returning
+ *   `ok: false` — loud, so nothing is lost, but it is not one of the structured
+ *   refusals;
+ * - `seen` is returned only by this adapter; the other two report no count at
+ *   all;
+ * - `sectionRange` does not know about code fences, so a fenced
+ *   "## Operator queue" line inside another section captures the write. The
+ *   line arithmetic still holds and `parsePlan` truncates at the same line, so
+ *   the bullet stays unselectable — but a reader sees it under the wrong
+ *   heading.
+ */
+export const proposeTriage = (rawProposal, { planPath: p } = {}) => {
+  const proposal = withAsOf(rawProposal);
   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.',
-  };
+  const file = p ?? 'PLAN.md';
+  const plan = readFileSync(file, 'utf8');
+  const { found, lines, start, end } = sectionRange(plan, OPERATOR_QUEUE);
+  if (!found) {
+    return {
+      ok: false,
+      item,
+      why:
+        `${file} has no "## Operator queue" heading, so a proposal has nowhere to ` +
+        'land that the selection query cannot reach. Add the heading rather than ' +
+        'filing this into the Agent queue.',
+    };
+  }
+
+  // 🔴 Only lines carrying THIS adapter's trailing field shape are candidates —
+  // which is a test of shape, not proof of authorship, and the limits list above
+  // says what a hand-written mimic costs. The other two adapters get
+  // that restriction free from their tracker (`--label triage`); plan-md has no
+  // label, and "every line in the section" — the first version of this — handed
+  // the Operator queue's human prose to the deduper. Observed: a human's
+  // "we discussed <fingerprint> in March and decided against it" became the
+  // counter for that very proposal, which was then never filed while the caller
+  // was told ok: true. The humans' page is not the agent's to edit.
+  //
+  // And the body handed to `duplicateOf` is the fingerprint FIELD, never the
+  // whole bullet: `duplicateOf` matches by substring, so a proposal whose prose
+  // quoted another proposal's fingerprint — which the loop does, since that
+  // string is what `incremented` returns and what the journal cites — captured
+  // that proposal's counter and was never filed, while the caller was told it
+  // had incremented a bullet that does not exist.
+  const candidates = [];
+  for (let i = start; i < end; i += 1) {
+    const tail = TAIL.exec(lines[i]);
+    if (tail) candidates.push({ id: String(i), body: tail[1] });
+  }
+  const existing = duplicateOf(item, candidates);
+
+  if (existing) {
+    const at = Number(existing.id);
+    const current = Number(TAIL.exec(lines[at])[2]);
+    lines[at] = lines[at].replace(COUNT, `seen ×${current + 1}`);
+    writeFileSync(file, lines.join('\n'));
+    return { ok: true, incremented: item.fingerprint, seen: current + 1, item };
+  }
+
+  // Append after the section's last non-empty line, so any blank line before the
+  // next heading survives and the file stays diff-clean. A section that has no
+  // blank line — an empty Operator queue whose heading is followed straight by
+  // the next one — gains none: the bullet lands flush against that heading.
+  let at = end;
+  while (at > start && lines[at - 1].trim() === '') at -= 1;
+  lines.splice(at, 0, bulletFor(item, proposal, 1));
+  writeFileSync(file, lines.join('\n'));
+  return { ok: true, filed: item.title, seen: 1, item };
 };

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

@@ -0,0 +1,197 @@
+/**
+ * The queue's own state — today, exactly one field: the tier of the last item
+ * the loop closed.
+ *
+ * 🔴 **Why this file exists at all.** `selectNext` rations the elevated tier by
+ * spacing: never two elevated items back to back — where the FIRST one is the
+ * half of the tier that executes (`tierOf` below), and the second is still any
+ * item whose marker says `elevated`. The asymmetry is not an oversight: a
+ * candidate has no diff yet, so there is nothing to classify it from, while a
+ * close does. It reads
+ * `config.lastCompletedTier` — and nothing anywhere wrote it, so the filter was
+ * called with `null` on every selection and **the ration never fired between
+ * tasks**. The rule was upheld by whichever session happened to read it, which
+ * is precisely the guarantee a mechanical filter exists to replace. A filter
+ * whose input nobody supplies is indistinguishable from a filter that agrees
+ * with you, and neither a green suite nor a reading of `core.mjs` shows it.
+ *
+ * 🔴 **The tier is computed from the change, never taken from the item's
+ * marker.** `autonomy.md`: *"the tier is decided by what the change touches, not
+ * by what the task said it would touch"*, and the `loop` skill calls the marker
+ * *"a pre-filter, not the authority"*. Rationing on the marker would mean a
+ * marker written one tier low silently buys a second elevated item in a row —
+ * which is the failure this repo has already recorded, on the very item that
+ * produced this module. The marker stays useful as a hint and a hygiene signal;
+ * it is not the value anything rations on.
+ *
+ * That costs no judgement: the gate sweep already decides this question
+ * mechanically, and this module calls the sweep's own functions rather than
+ * re-deriving the rules. **One mechanism, one implementation**
+ * (`invariants.md`) — two files deciding "is this path elevated" would disagree,
+ * and the one nobody is looking at would be the wrong one.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { elevatedPathsIn, executesNothing, readDeclaredPaths } from '../detect-missed-gate.mjs';
+import { updateState } from '../run-state.mjs';
+import { mainCheckoutRoot } from './checkout.mjs';
+
+
+/**
+ * The tier of a close, from the elevated paths the change crossed.
+ *
+ * 🔴 **The elevated tier splits in two, and only the ration reads the split.**
+ * `elevated-prose` is still an elevated change everywhere it is REVIEWED — the
+ * model lane, the cold readers, the `human-review` label, the gate sweep. It
+ * simply does not space the next item, because the rule's own stated purpose is
+ * about what compounds: *"one **unreviewed** schema or permissions change is
+ * recoverable; a chain of them compounding overnight is not"*. A rule file
+ * cannot compound into a broken runtime overnight, because nothing executes it —
+ * and in a repository whose rulebook lives under a declared path, spacing on the
+ * undivided word halts the queue rather than pacing it.
+ *
+ * A mixed diff is `elevated-mechanism`: the half that runs decides. Reading the
+ * tier off the first path, or off "most of them are documents", would ship a
+ * ration any diff can opt out of by also touching a `.md`.
+ *
+ * The predicate is `executesNothing` — **`.md` only, not `.mdx`** — imported
+ * from `detect-missed-gate.mjs` so it sits beside the sweep's own markdown test
+ * rather than drifting from it. The two are deliberately different and the
+ * difference is the ration's whole subject: the sweep asks *does this need a
+ * reviewer*, this asks *can it compound overnight*, and MDX is a program that
+ * renders (`docs/decisions/review-lanes.md`).
+ *
+ * ⚠ **The limit worth knowing before trusting this:** a skill's `SKILL.md` is
+ * prose by this test, and some of them carry shell snippets an agent copies and
+ * runs. The owner's ruling is that skills stay prose for rationing — they are
+ * reviewed like the rules they are, and rewriting a procedure is not the chain
+ * of unreviewed compounding changes the ration was bought to stop. It is,
+ * however, the weakest ground the "no runtime executes it" justification stands
+ * on, and the place to look first if the ration ever turns out too loose.
+ *
+ * ⚠ Two more limits, both erring toward holding: the test is case-sensitive, so
+ * `RULES.MD` records `elevated-mechanism`; and only paths `elevatedPathsIn`
+ * already returned reach here, so a non-rulebook `.md` was dropped as inert long
+ * before and records `normal` — which clears the ration outright rather than as
+ * prose (`docs/decisions/review-lanes.md`).
+ */
+const tierOf = (elevated) => {
+  if (elevated.length === 0) return 'normal';
+  return elevated.every(executesNothing) ? 'elevated-prose' : 'elevated-mechanism';
+};
+
+/**
+ * Record the tier of the change that just closed an item.
+ *
+ * `changedFiles` is the diff's file list — `git diff --name-only <base>...<head>`
+ * for the merged PR. It is a required argument and not a defaulted one, which is
+ * the whole point of the two refusals below.
+ *
+ * Returns `{ tier, elevatedPaths }`: the value written, and the files that
+ * earned it, so the close step can journal *why* rather than just *what*.
+ * `elevatedPaths` is always an array — empty on a normal change, never absent,
+ * and **unaffected by the prose/mechanism split above**. `elevatedPaths` answers
+ * "what did this change cross", which is the gate's question and not the
+ * ration's: a prose merge that stopped listing its rulebook files would look
+ * clean to the sweep that exists to catch exactly those merges.
+ *
+ * 🔴 **It writes a state file BESIDE the queue config, never into it — and that
+ * is not a preference.** `.claude/queue.json` is composed from the rig's
+ * template layer, so a runtime value written into it is drift: the repository's
+ * own sync check fails, and in a generated project the next `upgrade` has a
+ * conflict on a file the project never edited. The item that asked for this
+ * named the config as the target ("the file `selectNext` already reads"); it was
+ * right about the reader and wrong about the file, and the drift check is what
+ * proved it. Config is composed and tracked; state is per-checkout and ignored.
+ *
+ * ⚠ **The limit this cannot see, stated rather than covered by a test that
+ * would only look like coverage:** a file list that arrived **truncated** — a
+ * split on the wrong separator, a hand-trimmed array, a caller that filtered
+ * before passing — is indistinguishable here from a complete one, and a
+ * truncated list that drops the elevated file records `normal`. The empty-list
+ * refusal below does not catch it, because a short list is not an empty one.
+ * The caller owns completeness. (A `maxBuffer` overflow is NOT one of these
+ * cases: `execFileSync`, which the documented snippet uses, throws `ENOBUFS`
+ * rather than returning a short string — measured, so it fails loudly.)
+ */
+export const recordCompletedTier = ({ changedFiles, projectRoot, statePath, runDir } = {}) => {
+  // 🔴 An absent file list is NOT a normal change. A zero and an unknown look
+  // identical in a count and mean opposite things, and guessing `normal` here
+  // would rebuild the exact blind spot this module closes: the permissive
+  // answer, written confidently, with nothing to show it was never measured.
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    throw new Error(
+      'recordCompletedTier needs the changed file list of the closing change ' +
+        '(`git diff --name-only <base>...<head>`). An empty or missing list is an ' +
+        'absence, not a normal-tier change, and writing a tier from it would ration ' +
+        'the queue on a value nobody measured.',
+    );
+  }
+
+  // Same refusal, one layer up: a project that declares no elevated path at all
+  // would make every change look `normal` forever. `readDeclaredPaths` returns
+  // null rather than [] for exactly this case, and the sweep treats it as its
+  // own finding rather than as "no findings".
+  const declared = readDeclaredPaths(projectRoot);
+  if (!declared || declared.length === 0) {
+    throw new Error(
+      'nothing in this project declares an elevated path, so no tier can be ' +
+        'computed: add an `elevated-paths` block to CLAUDE.md or a rule file. ' +
+        'Treating the absence as `normal` would ration on a declaration that ' +
+        'does not exist.',
+    );
+  }
+
+  const elevated = elevatedPathsIn(changedFiles, declared);
+  const tier = tierOf(elevated);
+
+  // State only. It deliberately does NOT carry `adapter` or `options`: two files
+  // answering "which queue is this" is two answers with no rule for which wins,
+  // and the loser is whichever one nobody is looking at.
+  //
+  // The default lands in the MAIN checkout even when the close runs inside a
+  // worktree — see `mainCheckoutRoot`. An explicit `statePath` is used verbatim
+  // and never re-resolved: it is the escape hatch tests and odd layouts need,
+  // and silently relocating it would make it useless.
+  //
+  // Note the asymmetry, which is deliberate: the DECLARATION is read from the
+  // given `projectRoot` (the worktree's own `CLAUDE.md` is the rulebook the
+  // change was written against), while the STATE goes to the checkout that
+  // outlives the task.
+  const file = statePath ?? join(mainCheckoutRoot(projectRoot), '.claude', 'queue.state.json');
+  writeFileSync(file, `${JSON.stringify({ lastCompletedTier: tier }, null, 2)}\n`);
+
+  // The run's own state, when the run declared a directory. Two files because
+  // the two values have different lifetimes: the tier rations ACROSS runs and
+  // belongs to the checkout, while the escalation streak means "twice in a row
+  // in THIS run" — see `run-state.mjs`. Writing either into the other's file
+  // silently breaks the rule it exists for.
+  //
+  // 🔴 A close BREAKS the streak, and that is the point of writing it here.
+  // "Two escalations in a row" ends when something lands in between; a counter
+  // nothing resets turns the second escalation of a long, otherwise healthy run
+  // into a permanent stop.
+  //
+  // `updateState` merges, so the budget and the trigger record this run has
+  // accumulated survive — unlike the whole-file write above, which owns its
+  // file outright.
+  //
+  // The tier goes into both files, and only one of them is read back: selection
+  // takes it from the per-checkout file above. The run-state copy is a trace of
+  // what this run closed — the item's own state shape names it — not a second
+  // input to the ration, and reading it as one would be the per-run clean slate
+  // this module exists to prevent.
+  //
+  // ⚠ **Deliberately untried, unlike the same call inside `recordEscalation`.**
+  // There the caller has already mutated a tracker, so a throw would report a
+  // successful escalation as a failure and invite a double-posted comment. Here
+  // the durable half — the tier the ration reads — is already on disk one line
+  // above, and the half that can still fail is the streak reset, whose loss
+  // stops the run EARLIER than it needed to. A failure that errs toward
+  // stopping is one to hear about, not one to swallow.
+  if (runDir) updateState(runDir, { lastCompletedTier: tier, escalations: 0 });
+
+  return { tier, elevatedPaths: elevated };
+};