create-agent-rig 0.5.0 → 0.6.1

package/templates/agent-os/universal/.claude/scripts/verdict.mjs

@@ -3,11 +3,18 @@
  * The verdict CLI — what a gate runs before it believes a reviewer.
  *
  *   node .claude/scripts/verdict.mjs check <file> [gate]   # `-` reads stdin
+ *   node .claude/scripts/verdict.mjs coverage <commit>    # reads the run journal
  *
- * It reads a gate's report, hands it to `lib/verdict.mjs`, and either prints the
- * parsed verdict on stdout (exit 0) or refuses with a diagnosis on stderr
+ * `check` reads a gate's report, hands it to `lib/verdict.mjs`, and either prints
+ * the parsed verdict on stdout (exit 0) or refuses with a diagnosis on stderr
  * (exit 1). All the deciding lives in the module; this file is the call site.
  *
+ * `coverage` answers the question one report cannot: did every reviewer this
+ * round asked for actually answer, for the commit being merged? It compares the
+ * three sets the run journal already holds — routed, launched, answered — through
+ * `lib/gate-coverage.mjs`, and it is a READ. It never launches a reviewer and it
+ * never writes.
+ *
  * 🔴 **Name the gate you launched.** The module reads the report's LAST block
  * (its limit 3), so a capture holding two reviewers' answers end to end says
  * only what the second one said — a stop that vanishes behind a later pass.
@@ -27,11 +34,15 @@
 
 import { readFileSync } from 'node:fs';
 
-import { parseVerdict, safeForDiagnosis } from './lib/verdict.mjs';
+import { coverageOf } from './lib/gate-coverage.mjs';
+import { isCommitId, parseVerdict, safeForDiagnosis } from './lib/verdict.mjs';
+import { readRun } from './run-journal.mjs';
 
 const USAGE =
   'usage: node .claude/scripts/verdict.mjs check <file> [gate]   ' +
-  '(`-` reads the report from stdin)\n';
+  '(`-` reads the report from stdin)\n' +
+  '       node .claude/scripts/verdict.mjs coverage <commit>   ' +
+  '(reads the run journal in $RIG_RUN_DIR)\n';
 
 const refuse = (message) => {
   process.stderr.write(message);
@@ -58,6 +69,92 @@ const [subcommand, source, expectedGate] = process.argv.slice(2);
 // either: an operator told the subcommand is unknown goes looking for a typo
 // that is not there.
 if (subcommand === undefined) refuse(USAGE);
+
+if (subcommand === 'coverage') {
+  // The four cases and the fix each one needs, said in the line that names the
+  // reviewer — a single "missing" list makes the reader guess between
+  // relaunching a reviewer and going to read why one stayed silent.
+  const CASES = [
+    ['neverLaunched', 'the route asked for it and the fan-out never launched it — launch it'],
+    ['unanswered', 'launched, and it did not answer — no verdict of its own parsed'],
+    ['unattributed', 'it answered, and its verdict named no commit — so it cannot say it answered for this one'],
+    ['stale', 'it answered for another commit — the head moved after the verdict'],
+  ];
+
+  const commit = source;
+  // The same two arms `check` keeps apart: the subcommand was right and the
+  // argument was not supplied. Reporting the opposite sends the operator
+  // looking for a typo that is not there.
+  if (commit === undefined) {
+    refuse(
+      'verdict: `coverage` needs the commit the round is about; no commit was given. ' +
+        'It is the head the reviewers were launched against — `git rev-parse HEAD` in the ' +
+        `reviewed checkout.\n${USAGE}`,
+    );
+  }
+
+  // The one commit field this command owns, and the only one shaped before it is
+  // compared: the journal is the other way in and `recordDecision` takes any
+  // non-blank string, which is why `sameCommit` enforces its own floor and
+  // ceiling rather than trusting an upstream check. Without this arm
+  // `coverage <a-full-sha>garbage` prefix-matched its way to "covered" — the
+  // answer that ends in a merge.
+  if (!isCommitId(commit)) {
+    refuse(
+      `verdict: \`${safeForDiagnosis(commit)}\` is not a commit to ask about. ` +
+        'It is 7 to 64 hex characters (0-9a-f), the same shape a verdict may name — ' +
+        '`git rev-parse HEAD` in the reviewed checkout.\n',
+    );
+  }
+
+  const runDir = process.env.RIG_RUN_DIR;
+  if (!runDir) {
+    // 🔴 Exit 0 with nothing printed is indistinguishable from a clean round,
+    // and an unattended session reads it as one. The skip is the honest answer —
+    // this run kept no trace — and it has to be said out loud.
+    process.stdout.write(
+      'verdict: coverage skipped — no run directory is declared (RIG_RUN_DIR is unset), so ' +
+        'this run journalled no fan-out and no verdicts. Nothing was checked, which is not ' +
+        'the same as nothing being outstanding.\n',
+    );
+    process.exit(0);
+  }
+
+  let decisions;
+  try {
+    ({ decisions } = readRun({ runDir }));
+  } catch (error) {
+    refuse(
+      `verdict: the run journal in ${runDir} could not be read, so coverage was not ` +
+        `checked (${error?.message ?? 'unknown error'}).\n`,
+    );
+  }
+
+  const coverage = coverageOf({ records: decisions, headSha: commit });
+  if (coverage.ok) {
+    process.stdout.write(
+      `verdict: coverage complete for ${safeForDiagnosis(commit)} — ` +
+        `${coverage.launched.length} reviewer(s) launched, every one of them answered for ` +
+        'that commit.\n',
+    );
+    process.exit(0);
+  }
+
+  const lines = [];
+  if (coverage.reason !== undefined) lines.push(`  ${coverage.reason}`);
+  for (const [key, why] of CASES) {
+    // Through the sanitiser like every other quoted value here: the names come
+    // from the fan-out record, which `recordDecision` checks as strings and
+    // nothing more, and a name carrying a cursor sequence repaints this refusal
+    // as a pass for whoever is watching the scrollback.
+    for (const reviewer of coverage[key]) lines.push(`  ${safeForDiagnosis(reviewer)} — ${why}`);
+  }
+  refuse(
+    `verdict: the fan-out for ${safeForDiagnosis(commit)} is not covered.\n` +
+      `${lines.join('\n')}\n`,
+  );
+}
+
 if (subcommand !== 'check') {
   refuse(`verdict: \`${subcommand}\` is not a subcommand of this tool.\n${USAGE}`);
 }

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

@@ -2,7 +2,7 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|apply_patch",
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -15,6 +15,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-secret-file.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-rulebook.mjs\""
           }
         ]
       },

package/templates/agent-os/universal/.claude/skills/check-premises/SKILL.md

@@ -173,7 +173,8 @@ inside the block; both forms are the contract.
     }
   ],
   "advisories": [],
-  "evidence": ["read the validator and both call sites"]
+  "evidence": ["read the validator and both call sites"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -187,6 +188,8 @@ inside the block; both forms are the contract.
   and the caller is what checks: the `loop` skill runs
   `node .claude/scripts/verdict.mjs check <report> check-premises` on what you
   return. Nothing in this skill runs it — this skill writes nothing at all.
+- **`headSha` is the commit you read** — `git rev-parse HEAD` in the checkout
+  you examined. A premise check answers about a tree, and the tree moves.
 
 ## Examples — the three shapes this actually catches
 

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -25,7 +25,7 @@ Selection never reads a tracker directly. It goes through
 ```bash
 node .claude/scripts/queue/index.mjs next      # the item to take, and why the rest were skipped
 node .claude/scripts/queue/index.mjs next --json
-node .claude/scripts/queue/index.mjs hygiene   # stale labels, link anomalies
+node .claude/scripts/queue/index.mjs hygiene   # stale labels, link anomalies, overtaken proposals
 ```
 
 - **`plan-md`** (default) — the Agent queue in `PLAN.md`. The only adapter that
@@ -39,6 +39,28 @@ node .claude/scripts/queue/index.mjs hygiene   # stale labels, link anomalies
   (`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`) and never from a file in the
   repo; the project or the JQL goes in `.claude/queue.json`.
 
+A config may declare several boards (`boards: { <name>: options }` plus a
+default `board`); the active one is chosen per checkout, not by editing the
+composed file:
+
+```bash
+node .claude/scripts/queue/index.mjs board        # the active board and the declared ones
+node .claude/scripts/queue/index.mjs board RP     # switch this checkout: writes .claude/queue.board
+```
+
+The selector is per-checkout runtime state, the same class as
+`.claude/queue.state.json`: it needs its own `.gitignore` line, which a generated
+project ships and an `init`-installed rig adds by hand. An undeclared name is
+refused, never read as "no board" (see `test/template/queue-board.test.ts` ›
+"refuses a board nobody declared instead of falling back" — in the generator,
+absent in a generated rig). It is a rulebook path for `guard-rulebook`:
+`.claude/queue.board` is refused even when an item allow-list names it,
+and the `board` command itself refuses a switch while the checkout is unattended. This
+does not prevent an arbitrary direct shell write to the selector — edit-tool
+hooks cannot see one. `.claude/queue.state.json` stays per config, not per board:
+the tier the last close recorded rations the next selection whichever board it
+lands on.
+
 Adding a fourth is an adapter, not a rewrite: `core.mjs` holds every selection
 decision and each adapter only maps its tracker's records onto the neutral shape.
 
@@ -53,13 +75,13 @@ state-vs-queue split exists to prevent.
 node .claude/scripts/preflight.mjs
 ```
 
-Three items are scripted (kill switch absent · local default branch matches the
-remote · the last deploy concluded successfully) and the script **prints the ones
-it did not check, every time**. Paste the block into the journal: a checklist that
+Four items are scripted (kill switch absent · `RIG_RUN_DIR` not already
+exported · local default branch matches the remote · the last deploy concluded
+successfully) and the script **prints the ones it did not check, every time**. Paste the block into the journal: a checklist that
 leaves no record cannot tell you it was skipped.
 
 Verdicts: **STOP** → do not start, deal with the cause. **CAUTION** → start,
-knowing which ground is soft. **GO** → the scripted three are clean; the rest are
+knowing which ground is soft. **GO** → the scripted four are clean; the rest are
 still yours.
 
 **An `unknown` never becomes a `pass`.** A probe that could not run tells you
@@ -87,6 +109,43 @@ export RIG_RUN_DIR="$PWD/.claude/runs/$(date +%Y%m%d-%H%M%S)"   # one per run
 mkdir -p "$RIG_RUN_DIR"
 ```
 
+⚠ **That export reaches the commands THIS shell runs and nothing else.** A
+`PreToolUse` hook is spawned by the harness with the harness's own environment,
+never with a variable the session exported — pinned in the generator's
+`test/template/guard-rulebook.test.ts` (absent in a generated rig) › "only a
+flag arms it — an exported RIG_UNATTENDED=1 with no flag changes nothing" —
+and in some harnesses the export does not even survive to the next Bash call,
+which is why every command in this skill can also take the run directory per
+invocation. What a hook CAN see is a file, so the unattended signal is one:
+
+```bash
+# at claim time, from the paths the item names (repo-relative prefixes, with
+# their trailing slash); the guard refuses every other rulebook edit while it is on
+node .claude/scripts/unattended-flag.mjs on --root "$PWD" --item <item-id> --run-dir "$RIG_RUN_DIR" --allow <prefix> [<prefix>…]
+```
+
+`guard-rulebook` reads it (`.claude/rules/autonomy.md`, "Never"): with the flag
+on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under the generated
+rulebook — both harnesses' rules, skills, agents and hook wiring, plus their
+scripts, queue config and integrity manifest — is refused unless its
+path starts with an allowed prefix; the board selector is the one always-refused
+exception and cannot be admitted by an allow-list. With no flag the guard does nothing. An
+item that needs a rulebook path names it here — a decision made at claim
+time, never a default — and the stop step below turns the flag off. Pinned in
+the generator's `test/template/guard-rulebook.test.ts` — absent in a generated
+rig — › "blocks a hook-config edit with an empty allow-list, naming path, item and the rule".
+
+⚠ **The export outlives the run's own calls.** Everything the session spawns
+inherits it — and a test suite that spawns the queue CLI would write fixture
+records into this run's trace (AR-139: 38 fixture selections and 22 fixture
+revalidation events in one session, two tests exiting 1). So preflight refuses
+to start on a `RIG_RUN_DIR` already exported. The generator's own test harness
+also scrubs the variable before any test file loads — its `test/setup-env.ts`,
+pinned by its `test/template/rig-run-dir-scrub.test.ts` › "holds with the
+variable exported around the whole vitest process" — and **neither file ships
+into a generated rig**: here, nothing scrubs it, and a rig's own test setup is
+the place to do the same.
+
 🔴 **One directory per run, never shared and never reused — and the journal
 cannot enforce this for you.** A collision or an already-ended directory is
 refused loudly; two runs whose records merely do not collide are merged into one
@@ -127,6 +186,60 @@ not deleting the old marker, and the silent resolution goes to the **less**
 restrictive gate. Until that is fixed, treat a double-marked item as
 human-gated by hand.
 
+🔴 **An item marked for another repository is held, never taken.** A label
+`owner-<name>` names the repository an item belongs to; the checkout names
+itself in `options.owner` of `.claude/queue.json`, and a mismatch — or an
+owned item in a checkout that declares no owner — is the holding cause `owner`,
+reported by `hygiene` as `owner-mismatch`. It clears the way `trigger-human`
+does: a human moves the item or re-marks it. An unmarked item is unconditional.
+Two items of another product once entered this queue as normal spacers and
+escalated `PREMISE FALSE` back to back — a run-level stop spent on work that
+was never this checkout's (AR-132). Pinned in the generator's
+`test/template/queue-owner.test.ts` — absent in a generated rig — › "holds an
+item whose owner is another repository, with the cause named".
+
+🔴 **An item's lifecycle is a label a human wrote, and the loop infers none of
+it** (AR-144). Four words, read by `lifecycleOf` in `core.mjs` so every adapter
+means the same thing — three of lifecycle, one of scheduling:
+
+- `keep-core` — the problem and the responsibility are valid and the item is
+  executable as written. A statement about the item, never a condition on taking
+  it: a bare `keep-core` item is selected like an unmarked one.
+- `re-scope` — the problem is valid but the item is **not executable
+  literally**: a path, a mechanism, a boundary or an acceptance criterion has
+  drifted. It is the holding cause `re-scope`, reported by `hygiene` as
+  `re-scope-pending` until it clears — and it clears **only** by a human
+  re-reading the code, rewriting the item and removing the label. It is a
+  short-lived quarantine, not a backlog category, and never a synonym for
+  obsolete, low priority or parked. The loop surfaces it and never rewrites it:
+  a re-aimed item is work the agent authored (§8).
+- `obsolete` — the responsibility is gone or fully superseded by a proven
+  mechanism. A **human verdict, terminal**: the loop never applies it and never
+  closes an item because it believes another mechanism supersedes it. Closing as
+  obsolete needs external evidence and a comment naming the replacement or the
+  reason — so an obsolete item is out of play (the cause `obsolete`), not held,
+  and the stop line says so.
+- `parked` — valid work deliberately not active now. The **scheduling** axis,
+  orthogonal to the three above: `keep-core + parked` is the ordinary shape of a
+  deferred item and means "still needed, not now". It is the holding cause
+  **`deferred`**, freed by a human un-parking it. The cause is not spelled
+  `parked` on purpose: §3 already uses that word for the **out-of-play pile** —
+  items waiting on a human that no session will take — and a parked-labelled
+  item is the opposite, held and takeable. So the stop line reads "held by
+  deferred" for the label, and "are parked" for the pile; `obsolete` lands in
+  the pile, the `parked` label never does.
+
+The rule under all four: **nothing infers `obsolete`** — not age, not a key
+range, old terminology, `parked`, absence from a roadmap, or a migration marker.
+`legacy-backlog` is that marker, retired: `hygiene` reports an open item still
+carrying it (`stale-legacy-backlog-label`), and two lifecycle labels on one item
+(`contradictory-lifecycle-labels`) — selection meanwhile reads the most
+restrictive one. Reported, never corrected: which label is wrong is the human's
+call. Pinned in the generator's `test/template/queue-lifecycle.test.ts` — absent
+in a generated rig — › "holds a re-scope item and says a human rewrites it" and
+› "refuses an obsolete item and says a human closes it with a comment naming the
+evidence".
+
 **For a `trigger-auto` item, record the declaration** — it has to outlive the
 turn it was made in, or the next selection holds the item back again:
 
@@ -168,6 +281,60 @@ and the work turns out to touch an elevated path (`CLAUDE.md` →
 `elevated-paths`), run the gate anyway, record the verdict on the PR, and treat it
 as this run's elevated item for spacing.
 
+**Selection also revalidates the item against its last take-up.** `next`
+records the selected item's `updatedAt` marker in the run state (`takeUps`) and,
+when the item is offered again, compares the two — against this run's take-up
+when it has one, otherwise against the newest earlier run's under `.claude/runs/`
+(AR-138: before that, an item taken up yesterday compared against nothing and
+read as a first sight). A proposal the loop files carries its own baseline: the
+`jira` and `github-issues` adapters record the filed item's marker as a take-up
+in the run that filed it. The event names which it used — `baseline:
+this-run | previous-run | null` — pinned in the generator's
+`test/template/revalidation-baseline.test.ts` — absent in a generated rig — ›
+"holds when the marker moved past the earlier run’s take-up, and names that
+baseline". A marker that
+moved prints a `revalidate:` line and the JSON carries `revalidation.changed:
+true`: **re-read the item before acting on it**, then record what the re-read
+concluded — whether the change altered the action is the evidence this exists to
+collect, and the comparison alone cannot supply it:
+
+```bash
+node .claude/scripts/revalidate.mjs outcome --point SELECT --ticket <item-id> --action-changed <true | false> --note '<what changed, or why it changes nothing>'
+```
+
+It appends one `revalidation-outcome` record whose `answers` names the
+revalidation it resolves, so the report can pair the two without guessing. The
+note is stored verbatim from argv, so keep it in single quotes: inside double
+quotes the shell expands a backtick or a `$` before the command sees it.
+Nothing forces this record — a `revalidation` event with no matching outcome is
+counted as `unresolved`, which is the honest word for a re-read the run skipped.
+
+Under a declared run directory, every selection logs one `revalidation` event
+`{ticket, point: SELECT, changed, source, action, task}` — the same shape the
+BEFORE_PR and BEFORE_CLOSE points write. **No-change is always recorded**, one
+line per selection and no sampling: the rule is explicit so the report's
+`opportunities` is a count and not an estimate. An adapter with no marker
+(`plan-md`) logs `changed: null`, never "unchanged". ⚠ The marker also moves on
+the run's own claim and comments. The `jira` and `github-issues` adapters
+re-record the take-up after each write they make — claim, comment, close,
+escalate — so a move made through the adapter is not a hold (AR-140, from the
+journal's RX3/RX4 entry: every BEFORE_PR catch of that run was the run's own
+comment, counted by `revalidation-report.mjs`); a
+comment posted by any other route — a REST call by hand, a connector — still
+moves it like anyone else's, and a `true` can still be self-inflicted that way
+— the re-read decides, which is why the outcome is recorded separately, and a
+hold the re-read overturns is counted as a false hold with its source named.
+Pinned in the generator's `test/template/self-inflicted-marker.test.ts` — absent
+in a generated rig — › "%s leaves the take-up at the marker the write produced",
+an `it.each` over claim, comment, close and escalate. The
+four-week view is `node .claude/scripts/revalidation-report.mjs --since <date>`,
+over this rig's `.claude/runs/` (or a `--runs <dir>`). The behaviour is pinned in the
+generator's `test/template/queue-revalidation.test.ts` — absent in a generated
+rig — › "an adapter with no marker records a blind spot, not \"unchanged\"", ›
+"a moved marker holds on task:updatedAt, re-snapshots, and journals the change"
+and › "the loop skill's outcome command records what the re-read concluded", and
+in `test/template/revalidation-evidence.test.ts`.
+
 **Then, before the Red step: `check-premises`.** The item was written by someone
 who was not reading the code at the time, and everything downstream — the failing
 test, the implementation, the reviewer comparing diff to item — inherits its
@@ -193,10 +360,50 @@ returns one fenced `json` verdict like every other gate, and this loop is its ca
 node .claude/scripts/verdict.mjs check <report> check-premises
 ```
 
+**`<report>` is a file you write, not one the harness leaves behind.** The
+subagent's answer arrives as text in the conversation; its transcript on disk is
+a JSONL file whose last fenced block does not parse, so pointing the check at it
+exits 1 whatever the reviewer said. Save the whole answer to a file under the run
+directory — `$RIG_RUN_DIR/check-premises.md`, one file per gate so two answers
+never overwrite each other — and pass that path (`-` reads stdin instead). The
+same holds for every `<report>` in this skill, as `pr-ship` already does for its
+reviewers (AR-117). Pinned in the generator's `test/template/loop-report-file.test.ts`
+— absent in a generated rig — › "states that the report is a file the session
+writes from the subagent answer, before the first check".
+
 Exit 1 means it did not answer: a stop verdict naming no premise, or no block at all.
 That is `incomplete` — neither "the premises hold" nor a reason to escalate — so run
 the pass again rather than reading the silence as a pass.
 
+**Then journal the block that parsed**, exactly as `pr-ship` journals a reviewer's —
+the paths a premise check names are what `revalidate.mjs` reads at BEFORE_PR as the
+task's cited paths, and a verdict held only in context cites nothing after a
+compaction:
+
+```sh
+node --input-type=module -e '
+  const runDir = process.env.RIG_RUN_DIR;
+  if (!runDir) process.exit(0);          // an undeclared run has no trace to write
+  if (!process.argv[1]) process.exit(0); // `check` printed nothing: nothing to record
+  const journal = await import("./.claude/scripts/run-journal.mjs");
+  const v = JSON.parse(process.argv[1]);
+  try {
+    console.log(journal.recordDecision({
+      runDir,
+      gate:     "check-premises",
+      verdict:  v.verdict,
+      blockers: v.blockers,
+      headSha:  v.headSha,
+      now:      new Date().toISOString(),
+    }));
+  } catch (error) {
+    // The same split pr-ship makes: an exhausted trace is over, the task is not.
+    if (!journal.isTraceExhausted?.(error)) throw error;
+    process.stderr.write(`run journal: ${error.message}\n  the premise verdict above was NOT recorded.\n`);
+  }
+' "$(node .claude/scripts/verdict.mjs check <report> check-premises)"
+```
+
 ## 3. What keeps the loop running, and what stops it
 
 Per-task stops (three strikes, attempt budget, invariant conflict, a blocking
@@ -282,10 +489,13 @@ Four of them deserve their reasons repeated:
   queue**: the elevated spacing (a normal or prose-only item lands), a blocker (its item
   closes), in-progress (the other session finishes), a trigger (a human
   declares it — and for a `trigger-auto` item that declaration is **written**,
-  §2, so this is the one hold that needs a command rather than only time). The
+  §2, so this is the one hold that needs a command rather than only time), and
+  an owner (§2: the item is another repository's, and a human moves it or
+  re-marks it — neither time nor interleaving frees it). The
   stop line names how many and by which, because the two endings ask the owner
   for opposite things: an empty queue wants refilling, a held one wants
-  interleaving or simply time. 🔴 **A parked cause outranks a holding one on the
+  interleaving, time, or — for a trigger or an owner — a human act the line
+  names. 🔴 **A parked cause outranks a holding one on the
   same item** — an escalated item is left claimed on purpose, so it arrives
   carrying `in-progress` too. **Neither ending is an invitation to refill the
   queue or invent work.** Why the two are split, and how the parked pile grows
@@ -351,8 +561,9 @@ perfectly good reason having produced something nobody should build on.
 🔴 **What `documented-stall` requires is the STAGE and the wall, not a full
 inventory of findings** — and this had to be settled, because the two readings
 disagreed the first time a stop arrived without an inventory. An exhausted
-gate-round cap names its stage (the gate) and its wall (two rounds of fixes did not
-converge), while the individual blockers behind it are not persisted anywhere until
+gate-round cap names its stage (the gate) and its wall (the branch's rounds are
+spent — the count, not a verdict on whether the fixes were converging, which the
+counter never measured; AR-115), while the individual blockers behind it are not persisted anywhere until
 per-round verdicts exist. That is a `documented-stall`: the record locates the wall
 and the next reader knows where to look.
 
@@ -525,6 +736,23 @@ If no run directory was declared, there is nothing to close and this step is
 skipped — say so in the journal entry rather than leaving the reader to guess
 which of the two happened.
 
+**And turn the unattended flag off** — it outlives the run otherwise, and the
+next attended session would find its rulebook edits refused in the name of an
+item nobody is working:
+
+```bash
+node .claude/scripts/unattended-flag.mjs off --root "$PWD"
+```
+
+If that command reports a legacy machine-wide flag, it deliberately leaves a
+foreign pre-upgrade authorization in place and the checkout stays fail-closed.
+Inspect the exact reported record and confirm that no pre-upgrade run still uses
+it, then remove only that record with
+`node .claude/scripts/unattended-flag.mjs off --legacy --path <reported-path>`.
+Run scoped `off --root "$PWD"` again to surface the next record, and repeat the
+inspection one at a time; do not record the flag as off until the scoped command
+succeeds.
+
 At every **stop** — not at a checkpoint — turn the run's findings into **at most
 three** improvement proposals. **The cap is the mechanism, not a budget:** an
 unbounded improvement list is another diary, and three forces a choice. Each names
@@ -550,12 +778,54 @@ node --input-type=module -e '
     part:    "<skill | agent | hook | rule | CLAUDE.md | workflow>",
     change:  "<concretely enough to diff>",
     proof:   "<the observation that would differ next run>",
-  }));
+    // a pair: what the probe touched, and what is concluded from it. The
+    // mechanism accepts a proposal without them; this procedure does not.
+    measured: "<the paths the probe actually exercised>",
+    inferred: "<the conclusion, citing only surfaces named in measured>",
+  }, { project: "<KEY>" }));   // jira only — the ACTIVE board's key: `queue/index.mjs board --json` → options.project;
+                               // plan-md and github-issues take no second argument
 '
 ```
 
 A proposal missing any of the four parts is refused rather than filed half-formed.
 
+**A finding can say what it measured and what it inferred, as two paired 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 its platform conclusion
+was traced to a probe that had touched one hook. So `measured` and `inferred`
+are separate, and `validateProposal` refuses an `inferred` that cites a path
+`measured` does not, naming both fields and the path; one field without the
+other is refused too, and neither files as before. The surface is a cited path
+(`citedPathsOf`), so a conclusion that names no path passes this check — it
+catches the path-shaped overreach and nothing subtler.
+
+⚠ **The pair is how a proposal opts into the check, and a proposal filed without
+it is not checked at all** — `validateProposal` keeps the four-part contract, so
+the AR-124 shape with neither field still files as it always did. That is the
+stated limit, not an oversight: making the fields mandatory would refuse every
+proposal the three adapters already file, and the loop is the author this rule
+is for. So **every proposal this loop files carries both fields** — the snippet
+above supplies them, and a stop that cannot say what it measured has nothing
+to propose. A reviewer reading a filed proposal without the pair reads a
+proposal that skipped this procedure. Pinned in the generator's
+`test/template/queue.test.ts` — absent in a generated rig — › "refuses a
+proposal whose inference names a surface its measurement did not touch", ›
+"files a proposal whose inference stays inside what it measured", › "refuses one
+of the two fields without the other" and › "a proposal with neither field files
+as today".
+
+**The filed item also records the commit it was measured against** — an `asOf:`
+line, HEAD of this checkout unless the call passes its own `asOf` (`null` files
+without one). It is there for `hygiene`, which lists the proposals on file and
+reports one whose cited paths changed since its `asOf` as
+`proposal-possibly-overtaken`, one with no `asOf` as `proposal-asof-missing`, and
+one git cannot diff from as `proposal-asof-unanswerable` — never as clean. Two
+proposals in a row once escalated `PREMISE FALSE` because the merge that
+falsified each landed after it was filed, and selection hands out the oldest
+first (AR-116). The behaviour is pinned in the generator's
+`test/template/proposal-asof.test.ts` — absent in a generated rig — ›
+"names the overtaken one, the unanswerable one, and stays silent on the current one".
+
 **All three adapters write it themselves** — `jira` and `github-issues` create a
 `triage`-labelled issue, `plan-md` appends a bullet to the **Operator queue**, and
 each increments an existing proposal carrying the same fingerprint rather than
@@ -567,9 +837,9 @@ rather than a step in the procedure: `plan-md` returns it when the plan file has
 no `## Operator queue` heading, because a proposal then has nowhere to land that
 the selection query cannot reach. Add the heading — never the Agent queue.
 
-One adapter needs more than the snippet above carries: `jira` requires
-`options.project` and throws rather than filing without it. It fails loudly, so
-nothing is lost — but called exactly as written, it does not file.
+One adapter needs the second argument the snippet above carries: `jira` requires
+`options.project` and throws rather than filing without it — loudly, so nothing
+is lost, but a call that drops it files nothing (AR-117).
 
 🔴 **The loop proposes; the owner patches.** Self-applying a change to its own
 rulebook is how an unattended run drifts irreversibly, and it collides head-on
@@ -603,9 +873,53 @@ three poisons the only channel by which this project learns.
   that creates the branch or worktree. 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.
-- **Closing:** close it with the merged PR linked, immediately after the
-  post-merge verdict — not in a cleanup pass. **Record the tier in the same
-  step**, because the next selection rations on it:
+- **Closing:** first ask whether the item is still the item you took up — a
+  late comment or a status somebody else moved is not published as `Done`
+  underneath it (AR-135):
+
+  ```bash
+  node .claude/scripts/revalidate.mjs --point BEFORE_CLOSE --ticket <item-id>
+  ```
+
+  It compares the item's marker against the newer of this run's last
+  validation and its take-up — an adapter re-records the take-up after each
+  write of its own (§2, AR-140), so a comment posted after BEFORE_PR does not
+  hold the close; pinned in the generator's
+  `test/template/self-inflicted-marker.test.ts` (absent in a generated rig) › "continues when the run’s own
+  write moved the marker after the last validation" — and its
+  state against the `in-progress` a close expects, journals one `revalidation`
+  event at `point: BEFORE_CLOSE`, and lists the item's dependants with each
+  one's state re-read for the write-back below — pinned in the generator's
+  `test/template/revalidate.test.ts` (absent in a generated rig) › "appends
+  exactly one BEFORE_CLOSE revalidation event after the BEFORE_PR one, and does
+  not end the run", › "runs the BEFORE_CLOSE revalidation before the close call
+  and reads a hold as a stop" and › "re-reads each dependant's state, and names
+  one the tracker no longer offers". On a `github-issues` queue that list is
+  empty: a single `gh issue view` carries no cross-index, so `find` answers no
+  `blocks` there (`test/template/close-transitioned.test.ts` (absent in a generated rig) › "github asks `gh
+  issue view` with the full field list and maps CLOSED to closed"). A
+  hold (exit 2) stops the close: re-read the item, record the outcome with
+  `node .claude/scripts/revalidate.mjs outcome --point BEFORE_CLOSE --ticket
+  <item-id> --action-changed <true | false> --note '…'`, and close only if the
+  re-read leaves the action standing. Then call the
+  adapter's `close(ticket, { prUrl, transitionId })` with the merged PR linked,
+  immediately after the post-merge verdict — not in a cleanup pass — and read
+  its answer: `ok: true` says the call ran, and only `transitioned` set to
+  `true` says the close landed, because every adapter reads the item back after
+  the transition — `jira` the status category after the POST, `github-issues`
+  `gh issue view --json state`, `plan-md` the line being there and then gone
+  (the generator's `test/template/close-transitioned.test.ts` (absent in a generated rig) › "GETs the issue
+  status after the transition POST and reports transitioned: true when the
+  category is done", › "runs `issue view <id> --json state` after `issue close`
+  and reports transitioned: true on CLOSED", › "reports transitioned: true once
+  the item's line is gone"). A close whose result says `transitioned: false` is
+  not a close: report it, and leave the item as the adapter left it — `jira` its
+  status, `github-issues` its `in-progress` label, which comes off only after a
+  read-back that says CLOSED (› "leaves the in-progress label on an issue whose
+  close did not land"), `plan-md` nothing, because the line was never there. The
+  tier below is recorded only for a close that transitioned; a close that did
+  not is not the "something landed" the escalation streak resets on. **Record
+  the tier in the same step**, because the next selection rations on it:
 
   ```bash
   node --input-type=module -e '