create-agent-rig 0.5.0 → 0.6.0

package/templates/agent-os/universal/.agents/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
@@ -53,13 +53,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 +87,42 @@ 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 --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 `.claude/hooks/`,
+`.claude/settings.json`, `.claude/queue.json`, `.claude/scripts/queue/`, the
+router, the gate sweep, `.claude/rules/` or `CLAUDE.md` is refused unless its
+path starts with an allowed prefix; 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 +163,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 +258,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 +337,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 +466,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 +538,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 +713,14 @@ 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
+```
+
 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 +746,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 project key from .claude/queue.json;
+                               // 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 +805,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 +841,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` › "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` › "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` › "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 '

package/templates/agent-os/universal/.agents/skills/pr-ship/SKILL.md

@@ -27,8 +27,17 @@ blockers.
      is *gate rounds exhausted*, quoting the round count in its `note`. Do not
      run the fan-out.
    - **1** — the command itself failed (unreadable config, unreadable counter,
-     detached checkout). This is **not** an exhausted cap: fix the cause and run
-     step 0 again. Treating it as exhaustion escalates a healthy item.
+     detached checkout), **or the checkout cannot ship**: a dirty working tree,
+     a branch with no upstream, or commits the upstream has not seen. Nothing
+     was counted. This is **not** an exhausted cap: fix the cause — commit and
+     push — and run step 0 again. Treating it as exhaustion escalates a healthy
+     item. A rig with no remote can never pass this step — by design: the PR
+     flow, and this gate with it, begins when the project has a remote
+     (`workflow.md`, "PR flow"). The refusal exists because two rounds were once counted ahead of a
+     commit pre-commit then refused, so the counter and the fan-out's verdicts
+     named a head that never shipped (AR-141) — pinned in the generator's
+     `test/template/gate-rounds.test.ts` — absent in a generated rig — ›
+     "refuses to count a round on a dirty tree, and counts nothing".
 
    The cap is **2 by default**, and no shipped `.claude/queue.json` carries the key
    — the default lives in `core.mjs` as `DEFAULT_MAX_GATE_ROUNDS`. A project that
@@ -42,10 +51,32 @@ blockers.
    removes is the honest failure mode, a run that keeps re-reviewing because no
    check ever went red; it does not stop a session that skips it.
 
-1. **The diff first.** Establish what is actually shipping: fetch, then diff
+1. **The diff first — and the branch's own premises next.** Establish what is actually shipping: fetch, then diff
    against the **remote** default branch (`origin/<default>`), not a local
    copy that may be behind — diagnosing from stale local code produces
    confidently-wrong reviews. Everything below is scoped to this diff.
+
+   Then, on the fetched ref, ask whether the branch is still the branch the run
+   took up (AR-134):
+
+   ```sh
+   node .claude/scripts/revalidate.mjs --point BEFORE_PR --ticket <item-id> --base origin/<default>
+   ```
+
+   It compares two sources and names each one that moved: the item's `updatedAt`
+   against the take-up snapshot `next` recorded (`task:updatedAt`), and what the
+   default branch changed since this branch forked, on the paths the branch
+   touches or a `check-premises` record in this run cited (`main:<path>`). It
+   journals one `revalidation` event at `point: BEFORE_PR`; **exit code 2 is a HOLD**, with one blocker per named source: re-read the item, or the default
+   branch on that path, record what the re-read concluded —
+   `node .claude/scripts/revalidate.mjs outcome --point BEFORE_PR --ticket <item-id> --action-changed <true | false> --note '…'`
+   — and come back through step 0. A hold with no outcome is counted by the
+   report as a re-read the run skipped. Exit 0 with
+   `unverifiable` means the task side could not be compared — no take-up
+   snapshot in this run, or no marker — and is stated in the evidence, not read
+   as a pass. Exit 1 is the command refusing (unknown point, no ticket, a base
+   that is not a revision): fix the call. Its limits are its own header's; the
+   cited-path set is a labelled assumption, not a recorded fact.
 2. **Route the diff before you spend on it.** This gate always ran its most
    expensive path, so a typo fix in a README bought the same fan-out as a
    rewrite of the storage layer. The dispatcher decides which lane the change
@@ -171,6 +202,7 @@ blockers.
    🔴 **Record the set you launched, as you launch it.** The router journals the
    set it *routed*; the triggers above may only add, so what you actually
    launched is a different list and this is the only place that knows it:
+   **Record the fan-out even when the launched set is empty.**
 
    ```sh
    node --input-type=module -e '
@@ -277,11 +309,33 @@ blockers.
    exhausted trace must cost this round its record and nothing else. A round is
    counted and capped, so a crash here spends one on a journal that was never
    the thing under review.
-5. **DoD walk.** Check the Definition of Done list in
+5. 🔴 **Coverage — check your own fan-out before you believe it.** You recorded
+   what the route asked for, what you launched and what came back; this is the
+   step that compares them, and it is the only one that does — nothing else in
+   this gate would notice a reviewer that never answered:
+
+   ```sh
+   node .claude/scripts/verdict.mjs coverage "$(git rev-parse HEAD)"
+   ```
+
+   For a **declared run**, exit 0 is coverage. **Exit 1 is a `HOLD`.** A
+   reason-only unreadable-round failure always prints the evidence boundary;
+   remedies appear only when recovery is unambiguous. Reviewer lists cover the
+   four comparable cases — never launched (launch it),
+   launched and silent (go and read why), answered without naming a commit, or
+   answered for another commit (the head moved under the round). Record either
+   kind as a blocker of yours, in the same list as a failing check.
+
+   Two limits, stated because a step that looks mechanical is trusted like one.
+   It reads **this run's journal**, so with unset `RIG_RUN_DIR` the check is
+   skipped; exit 0 is then an honest nothing, not coverage. And it cannot see a
+   round that never reached this skill at all: a session that skips `pr-ship`
+   skips its coverage check with it (`docs/decisions/gate-coverage.md`).
+6. **DoD walk.** Check the Definition of Done list in
    `.claude/rules/workflow.md` item by item — test-first evidence, nothing
    skipped or weakened, boundaries respected, docs updated, autonomy tier
    honored.
-6. **Named checks only.** The merge criterion is the project's *named* required
+7. **Named checks only.** The merge criterion is the project's *named* required
    checks, all green. "Some checks passed" is not a criterion; an unnamed
    green wall hides a red brick. Two traps here, both observed in the wild:
    status watchers can exit while checks are **still unregistered** — poll the
@@ -317,7 +371,8 @@ the author, then **exactly one** fenced `json` block, and nothing after it.
     }
   ],
   "advisories": [],
-  "evidence": ["lane: model", "reviewers: code-reviewer, prose-reviewer"]
+  "evidence": ["lane: model", "reviewers: code-reviewer, prose-reviewer"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -330,6 +385,9 @@ the author, then **exactly one** fenced `json` block, and nothing after it.
   pr-ship` — and fix what it refuses. Nothing downstream re-checks the gate's
   own answer, so this call is the only thing between a malformed verdict and
   whoever acts on it.
+- **`headSha` is the commit you gated** — `git rev-parse HEAD`, the same one
+  step 5 asked coverage about. It is what stops this verdict being read later
+  as an answer about a commit that has since moved.
 
 ## Boundaries
 

package/templates/agent-os/universal/.claude/agents/code-reviewer.md

@@ -69,7 +69,8 @@ reads; a report that never writes one is read as whatever the caller expected.
     }
   ],
   "advisories": [],
-  "evidence": ["diffed against origin/master", "queue item supplied"]
+  "evidence": ["diffed against origin/master", "queue item supplied"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -81,3 +82,9 @@ reads; a report that never writes one is read as whatever the caller expected.
   what refuses them, and the shape it enforces is in
   `.claude/scripts/lib/verdict.mjs`. The gate name is what stops your answer
   being read as somebody else's.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.

package/templates/agent-os/universal/.claude/agents/prose-reviewer.md

@@ -154,7 +154,8 @@ calling gate reads.
     }
   ],
   "advisories": [],
-  "evidence": ["opened .claude/hooks/guard-bash.mjs and quoted the line"]
+  "evidence": ["opened .claude/hooks/guard-bash.mjs and quoted the line"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -165,3 +166,9 @@ calling gate reads.
   `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses
   them, and the gate name is what stops your answer being read as somebody
   else's.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.

package/templates/agent-os/universal/.claude/agents/security-scanner.md

@@ -58,7 +58,8 @@ the human who has to fix the finding.
     }
   ],
   "advisories": [],
-  "evidence": ["grepped for the pattern across services/"]
+  "evidence": ["grepped for the pattern across services/"],
+  "headSha": "9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70"
 }
 ```
 
@@ -71,3 +72,9 @@ the human who has to fix the finding.
   `node .claude/scripts/verdict.mjs check <report> <this gate>` is what refuses
   them, and the gate name is what stops your answer being read as somebody
   else's.
+- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the
+  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage
+  <commit>` tell "this gate answered for the commit being merged" from "it
+  answered two pushes ago". A verdict naming no commit is counted as neither
+  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook
+  runs that check, so a session that skips the gate skips this with it.