create-agent-rig 0.4.0 → 0.6.0

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

@@ -6,13 +6,15 @@ argument-hint: [max-tasks]
 ---
 
 You drive an unattended session. `.claude/rules/autonomy.md` sets the behaviour
-boundaries; the **queue** holds the work; `PLAN.md` holds state, standing
-decisions and the journal. This skill is the driver in between: what gets picked,
+boundaries; the **queue** holds the work; the journal is `journal/YYYY-MM.md`,
+one file per month, newest-on-top; `PLAN.md` holds state and standing
+decisions. This skill is the driver in between: what gets picked,
 what keeps the loop going, what stops it, and where the report goes.
 
-Per-task procedure is unchanged: (worktree if another session may run) →
-`check-premises` → failing test first → implement → `pr-ship` → merge on the
-named criterion → verify the deployed surface if one changed.
+Per-task procedure: (worktree if another session may run) → `check-premises` on the
+item → failing test first → implement → **`check-premises` again, on your own prose**
+→ `pr-ship` → merge on the named criterion → verify the deployed surface if one
+changed.
 
 ## 0. The queue is behind an adapter
 
@@ -23,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
@@ -51,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
@@ -67,6 +69,67 @@ nothing.
 unattended only after the escalation path and the post-deploy verdict have each
 been seen working at least once.
 
+### Declare the run directory here, before the first selection
+
+🔴 **This is not optional, and it is not only about the trace.** The run's
+**stop conditions** live in that directory too (§3) — the escalation streak, the
+deploy verdict, the budget flag. With `RIG_RUN_DIR` unset the escalation count
+is recorded nowhere, silently, so an undeclared run is not a run with a missing
+journal: it is a run whose main brake is off and which looks exactly like a
+healthy one (`docs/decisions/run-directory.md`).
+
+The machine trace (§7) is the other half, and its first call site is
+**selection**, which runs before every task. Declared later, it misses
+everything that already happened — so this goes in preflight or not at all:
+
+```bash
+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
+seamless trace with nothing able to say so. A fresh directory per run is the
+only thing that prevents it, and it is yours to do — the exact boundary is in
+`docs/decisions/run-directory.md`.
+
 ## 2. Selection — filters in order, then the sort
 
 The queue is queried **fresh before every task**, never from a cached list: the
@@ -87,21 +150,168 @@ metadata destroys the evidence that the metadata is unreliable.
 
 🔴 **A missing trigger marker means unconditional, not missing data.** Work that is
 genuinely conditional says so. A `trigger-human` item — a "security pass", a
-"window", "user demand" without a named metric — is **never self-taken**; the human
-hands it over explicitly. A `trigger-auto` item needs its trigger verified *this
-run*: unverified is not fired, and rationalising a trigger into firing builds for
-scale that does not exist.
+"window", "user demand" without a named metric — is **never taken on that marker
+alone**; the human hands it over explicitly. A `trigger-auto` item needs its
+trigger verified *this run*: unverified is not fired, and rationalising a
+trigger into firing builds for scale that does not exist.
+
+⚠ **An item carrying BOTH markers is taken as `trigger-auto`.** Every adapter
+resolves `auto` first, nothing refuses the combination, and no hygiene check
+reports it — so one recorded declaration takes an item whose author also marked
+it human-gated. The reachable path is an owner tightening an auto-gated item and
+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:
+
+```bash
+node .claude/scripts/run-state.mjs trigger <item-id>
+```
+
+🔴 **This does nothing for a `trigger-human` item, and the command will not tell
+you so.** Selection refuses that kind outright — it never consults the record —
+so the only thing that makes one takeable is a human changing the item's own
+marker. Recording a "declaration" against it succeeds, prints, and leaves the
+item exactly as unselectable as before.
+
+⚠ **It is keyed by the item's id — and under `plan-md` that id is the item's
+POSITION in the list.** So a declaration made for the third bullet transfers to
+whatever occupies the third slot after someone edits `PLAN.md`, for the rest of
+the run. Re-check the item the declaration names before acting on it, or use an
+adapter whose ids are stable (`github-issues`, `jira`). There is no un-fire
+word: a new run starts with a clean state, which is the same remedy the budget
+stop relies on.
 
 **The elevated tier is rationed by spacing, not by counting** — a per-run count is
-meaningless when the run has no end. Never two elevated items back to back: land a
-normal item on a healthy runtime in between. One unreviewed permissions or schema
-change is recoverable; a chain of them compounding overnight is not.
+meaningless when the run has no end. Never two elevated items back to back **when
+the first one touched a mechanism** (next paragraph): land a normal item on a
+healthy runtime in between. One unreviewed permissions or schema change is
+recoverable; a chain of them compounding overnight is not.
+
+**Only a change that EXECUTES spaces the next item.** The close records
+`normal` | `elevated-prose` | `elevated-mechanism`, computed from the diff's
+paths (`queue/state.mjs`): an elevated change whose elevated paths are all
+documents is `elevated-prose` and clears the ration, because a document cannot
+compound into a broken runtime overnight. Prose keeps its tier everywhere it is
+*reviewed* — model lane, cold readers, `human-review`, the gate sweep — and loses
+it only here. A tier outside that vocabulary **holds**, never releases
+(`docs/decisions/spacing-rations-mechanisms.md`).
 
 **The tier marker is a pre-filter, not the authority.** If an item passed as normal
 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
@@ -109,17 +319,130 @@ claims rather than checking them. On `PREMISE FALSE` the item is escalated (§6)
 not repaired in place: a run that silently re-aims its own task has authored work
 for itself, which is the one thing this loop does not do (§8).
 
+🔴 **And again at the other end, before `pr-ship`: `check-premises` on the prose the
+task itself wrote** — the rulebook prose the diff touches (the skill defines that set,
+and it is the one `workflow.md` already uses for the `prose-reviewer` trigger), plus
+the PR description once one exists. The verdict is `UNMEASURED`, with two exits:
+delete the sentence, or make it a pointer to the test that proves it. Run it before
+the gate: a reviewer reaches the same sentence only after loading the whole diff, and
+that is a round spent on what an edit would have fixed.
+
+`PREMISE FALSE` stays with the first pass. At the second one the claims are your own
+and the remedy is an edit, so nothing escalates.
+
+**Both passes end in a block, and you check it before you act on it** — the skill
+returns one fenced `json` verdict like every other gate, and this loop is its caller:
+
+```sh
+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
-reviewer verdict, a false premise in the item itself) **do not end the run**:
-escalate that item (§5) and take the next one.
+reviewer verdict, an exhausted gate-round cap, a false premise in the item itself)
+**do not end the run**: escalate that item (§6) and take the next one.
 
 The run-level conditions are in `stopConditionOf` in `core.mjs`, checked in
 severity order: **queue unreadable** · **runtime regression** · **kill switch** ·
-**two escalations in a row** · **budget** · **queue empty**.
+**two escalations in a row** · **budget** · **nothing selectable** · **queue
+empty**.
+
+🔴 **Their inputs come from a file, not from your memory — and that is why they
+fire at all.** `escalations` and `lastDeployVerdict` live in
+`<RIG_RUN_DIR>/state.json`, written by `run-state.mjs`. A stop condition held in
+a session's memory is absent exactly when it is needed, because compaction is
+what a long run does (`docs/decisions/stop-conditions-in-a-file.md`).
+
+**One of the three writes itself; two you write.** The escalation count needs
+nothing from you beyond using the documented calls — but it has two writers, and
+both have to be the documented one:
+
+- it **rises** through every adapter's `escalate()` (§6), which is why
+  escalating by hand-labelling the item counts nothing;
+- it **resets** through the close step's `recordCompletedTier`, and **only when
+  you pass it `runDir`** (§9 has the command; it is one of that call's
+  load-bearing arguments, not an optional extra). Omit it and the count is
+  monotonic: two escalations an hour apart end the run however many tasks
+  landed in between.
 
-Three of them deserve their reasons repeated:
+The other two are yours, after the checks that produce them:
+
+```bash
+# the post-deploy check answers in a block like every other gate, and the word
+# below is retyped out of it — so check the block before you trust the word
+node .claude/scripts/verdict.mjs check <report> post-deploy-verify
+
+# after the post-deploy check (`.claude/rules/autonomy.md`, "Post-deploy
+# verification") — REGRESSION stops the next selection, HEALTHY clears it
+node .claude/scripts/run-state.mjs deploy REGRESSION
+
+# when the declared budget (§4) cannot fit another task
+node .claude/scripts/run-state.mjs budget exhausted
+```
+
+Both **refuse** a word outside their vocabulary and refuse to run with no
+`RIG_RUN_DIR`, rather than writing something the stop conditions cannot match: a
+file that looks recorded and stops nothing is worse than no file.
+
+**Only the deploy verdict can be taken back**, and the asymmetry is deliberate:
+`HEALTHY` names a real later event — the revert landed — while un-exhausting a
+budget would name only a decision taken by the run that declared the stop
+(`docs/decisions/stop-conditions-in-a-file.md`). A new run gets a clean state;
+that is the way back from both.
+
+Selection itself — `node .claude/scripts/queue/index.mjs next`, §0 — is what
+*reads* these and stops on them. It is still the command you run to get work.
+
+⚠ **The kill switch is not among them.** It stays mechanical in `guard-bash`
+and scripted in preflight; `next` does not check for the flag, so **keep
+checking it between tasks** — the brake block later in this section says how.
+
+Four of them deserve their reasons repeated:
 
 - **Runtime regression** → deploy the revert first, diagnose second, start no new
   work on top. A regression compounds into everything built above it.
@@ -130,7 +453,30 @@ Three of them deserve their reasons repeated:
   sprees, no polish, no pre-emptive optimisation. An empty filtered queue is a
   legitimate, successful end of session; refilling it is the owner's job.
   **Expect this to be the most common ending** — the queue is finite and the loop
-  drains it. That is the system working.
+  drains it. That is the system working. The stop line also names the **parked**
+  pile if there is one, by cause and count: items out of play, waiting on a
+  human. They are reported next to the verdict, never swept into it. 🔴 Under
+  `plan-md` an escalation leaves no mark on the queue at all — `escalate`
+  returns `ok: false` with the instruction to move the item to the Operator
+  queue **in the same edit**, and skipping that move means the next run takes
+  the stuck item straight back.
+- **Nothing selectable** → also a clean stop, and **not the same finding**.
+  Takeable work is still there and every piece of it is **held back by a
+  condition that clears when something else happens, not by refilling the
+  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), 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, 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
+  per adapter: `docs/decisions/two-empty-endings.md`.
 
 🔴 **The kill switch is a real file, not an intention:**
 
@@ -162,6 +508,21 @@ cost column **will be believed** — by the next reader, and by the next run
 reasoning about its own budget. A field the loop cannot observe stays **visibly
 empty, never estimated.**
 
+**Where the budget lives, and what is honest about it.** The **decision** is
+recorded, not the arithmetic:
+
+```bash
+node .claude/scripts/run-state.mjs budget exhausted
+```
+
+That sets the flag `stopConditionOf` reads, so the next selection stops with
+`queue: budget` — and it survives a compaction, which is the whole reason it is
+a file. **Nothing computes it for you**: the counters above are the ones the
+session observes, and judging that the remaining allowance cannot fit another
+task stays yours. There is deliberately no field holding a spend figure, for the
+same reason the journal has no currency column — a number the run cannot
+observe, written where a stop condition reads, is a fiction with authority.
+
 ## 5. Every task carries an outcome state
 
 The stop conditions say why the loop stopped. None of them says whether what it
@@ -174,6 +535,20 @@ perfectly good reason having produced something nobody should build on.
 | `documented-stall` | it stopped at a real wall, and the diagnosis names **which stage needed what, and which upstream stage should have supplied it** |
 | `incomplete` | it stopped and the record does not explain where or why |
 
+🔴 **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 (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.
+
+`incomplete` is for a record that cannot say **where** it stopped — not for one that
+can say where but not everything about it. Widening `incomplete` to cover a thin
+diagnosis would make it the common case, and it is meant to be the rare one: it is
+the only failing state, and a state that fires on honest stops stops being read.
+
 🔴 **`documented-stall` is a success, and reading it as a failure is how this stops
 working.** A stall that names its under-supply is the most useful thing an
 unattended run produces: it converts a vague gap into a located, fixable defect.
@@ -211,22 +586,61 @@ mechanises fully (`missed`, `.claude/rules/autonomy.md`) needs no self-report.
 ## 6. Escalation — two channels, by scope
 
 **Task-scoped — the item is the home, and the loop continues.** Three strikes, the
-attempt budget, an invariant conflict, a blocking reviewer verdict, or a
-`PREMISE FALSE` verdict from `check-premises` — the last one is a
-`documented-stall` (§5), and its diagnosis is already written: what the item
-claimed, what the code says, and the citation:
-
-1. Comment the diagnosis on the queue item: what fails, what was tried, the
+attempt budget, an invariant conflict, a blocking reviewer verdict, an **exhausted
+gate-round cap**, or a `PREMISE FALSE` verdict from `check-premises` **on the queue
+item**. The last two are
+a `documented-stall` (§5) and their diagnoses differ, so take the one that matches the
+stop: a false premise writes what the item claimed, what the code says, and the
+citation; an exhausted cap writes the round count and what the last gate reported.
+Both then follow the same three steps:
+
+1. Comment the diagnosis on the queue item, in the shape
+   `.claude/rules/autonomy.md` ("Escalation format") sets — **cite it rather
+   than working from this list**, which is a reminder and is short by two of
+   its clauses: what was *observed* (verbatim errors, not summaries), and the
+   single question whose answer unblocks the work. So: what fails, what was tried, the
    current hypothesis, and links to the PR and the failing run where they exist
    — a premise stop has neither, and its citation stands in for both. **Name the outcome
-   state in the same comment** — `incomplete` if the diagnosis cannot say which
-   stage needed what. Writing `incomplete` on your own task is uncomfortable and
+   state in the same comment** — `incomplete` if the diagnosis cannot say **where** it
+   stopped (§5: a thin diagnosis that still locates the wall is a `documented-stall`).
+   Writing `incomplete` on your own task is uncomfortable and
    is the point: the run that produced it is the only witness.
 2. Mark it `escalated` and leave it claimed — **not** back to a selectable state,
    or the next query picks it up and works it twice.
 3. Journal it. 4. **Take the next item.** One stuck task does not end a run; two
    in a row does (§3).
 
+🔴 **The gate-round cap is the stop a run will not reach on its own.** Every other
+stop here has a red thing behind it; a gate that keeps finding fixable prose is all
+green, so three strikes never fires and the run has no reason to stop re-entering it.
+`pr-ship` step 0 counts the round per branch in `.claude/gate-rounds.json` and exits 2
+past the cap. The count outlives the session, which is the point — a counter held in
+context is one the next context does not have.
+
+⚠ **What the cap does not carry, stated because the gap decides what you can write in
+the escalation:** the counter records the round and nothing about it. Findings travel
+separately, and the two do not cover the same ground — the count is **per branch, in
+the main checkout, across runs**, while a verdict is journalled into **this run's**
+directory. So `decisions.jsonl` holds the rounds this run spent and nothing about a
+round spent before it: a branch on its third round in its second run has one round's
+findings here, and the earlier ones in whichever directory that run declared, or
+nowhere if it declared none.
+
+Write the diagnosis from what you can actually read — the round count, plus this run's
+records where there are any — and say which of the rounds that leaves unaccounted for
+rather than reconstructing them from memory. `pr-ship` is told to journal each verdict
+that parsed, and like every gate here that is a step in a skill rather than a
+mechanism: a round whose session skipped it left no record either.
+
+🔴 **Escalate through the adapter, never by hand-labelling the item.** Every
+adapter's `escalate()` counts the escalation into the run state as it marks the
+item, which is what makes "two in a row" a condition the next selection can
+check rather than one you have to remember across a compaction. Adding the
+label yourself marks the item and counts nothing — and the run then grinds past
+the wall this rule exists to stop it at. (`plan-md` still returns `ok: false`,
+because a flat list has no per-item state to mark; the count is recorded all the
+same, and moving the item to the Operator queue is still yours.)
+
 **Run-scoped — the run itself is broken, and it ends.** A runtime regression, two
 escalations in a row, a systemic wall, a queue-data anomaly: open an escalation
 issue with the diagnosis and links, notify the owner if the harness can, and write
@@ -238,7 +652,74 @@ a run still working.
 
 Write a checkpoint entry **every few completed items and at every stop**, not only
 at the end: a run that dies unexpectedly must not take its history with it. The
-field list is in `PLAN.md` under `## Journal`.
+entry goes at the TOP of `journal/YYYY-MM.md` — this month's file, newest-on-top
+— and the field list is in `journal/README.md` next to it.
+
+**Behind that entry there is a machine trace, and it is a different artifact.**
+`.claude/scripts/run-journal.mjs` writes gate verdicts to `decisions.jsonl` and
+everything else to `events.jsonl`, both append-only, inside the run directory
+declared in §1. Five things about it are worth knowing before relying on it:
+
+- **The run declares the directory; nothing invents one.** With `RIG_RUN_DIR`
+  unset, every call site stays silent — the *trace* is opt-in, and a run that
+  never declared one has no journal rather than a journal in a guessed place.
+  🔴 **The stop conditions in the same directory are not opt-in** (§1): an
+  undeclared run also stops counting escalations, and that half is silent too.
+  Read "opt-in" as describing this file, never the declaration.
+- **It answers *what the run decided and on what basis*, never *was that
+  right*.** It replaces neither the month file above nor `PLAN.md`; it is the
+  evidence a reader checks those against. It is also **oldest-first**, where the
+  month file is newest-on-top — reading one as the other is how a reader
+  concludes a run did nothing.
+- **A record after the run-end marker is refused, and a broken sequence is
+  refused on both write and read.** The order is asserted rather than described,
+  so a stale record cannot read as the current one — which is the whole failure a
+  journal exists to prevent.
+- ⚠ **The trace can stop before the run does, and the two failures part ways
+  here.** A journal that can no longer accept records — a sequence already
+  broken, a file that will not parse, a run already marked ended — is a lost
+  trace, **not** a reason to withhold work the queue can still hand out: the
+  selection prints, stderr carries a `run journal:` line, the exit code stays 0.
+  The refusals are the ones where nothing has happened yet and a second fixes
+  it, and there are **four**: the declaration is empty, its directory does not
+  exist, the path is not a directory, or the journal module is missing. Each
+  exits 1 with nothing on stdout.
+- 🔴 A `run journal:` line on stderr is **not** the queue failing. That one is
+  `queue: queue-unreadable` on stdout (§0) and it ends the run; this one does
+  not.
+
+**The marker is written by the stop, and the stop is a step in this skill.** A
+journal whose end nobody writes leaves every run reading as still-running, which
+is exactly the ambiguity the marker exists to remove.
+
+🔴 **At a stop — never at a checkpoint — and after the proposals below, not
+before them.** The marker closes the journal to further records, so a run that
+writes it mid-way keeps working while every later record is refused: a trace
+truncated quietly, which is worse than one that stops loudly. It is the last
+thing the run does, in document order and in wall-clock order both:
+
+```bash
+node --input-type=module -e '
+  const { endRun } = await import("./.claude/scripts/run-journal.mjs");
+  console.log(endRun({
+    runDir: process.env.RIG_RUN_DIR,
+    stop:   "<the stop condition from §3: queue-empty | budget | kill-switch | …>",
+    now:    new Date().toISOString(),
+  }));
+'
+```
+
+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
@@ -252,8 +733,10 @@ four things, and a proposal missing any of them is not ready to file:
 4. how the next run would prove it worked — the observation that would differ.
 
 Filing is the adapter's `proposeTriage`, which the CLI deliberately does **not**
-expose — `index.mjs` is read-only (`next`, `list`, `hygiene`) so that no accidental
-invocation can write to the queue. Call it directly:
+expose — `index.mjs` never writes to the QUEUE (`next`, `list`, `hygiene` only), so
+that no accidental invocation can change what the next run is handed. Its one
+write is to the run journal above, and only into a directory the run declared —
+a trace of the selection, never a change to it. Call `proposeTriage` directly:
 
 ```bash
 node --input-type=module -e '
@@ -263,12 +746,69 @@ 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
+filing a second. `ok: true` means it is filed: there is no "I noted it in the
+summary" version of filing.
+
+`ok: false` is the one case that still needs you, and it is a structural fault
+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 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
 with the rule that the agent authors no work for itself.
@@ -288,10 +828,10 @@ three poisons the only channel by which this project learns.
 | **Re-aim an item whose premise turned out false** | Same rule wearing a disguise: an item silently rewritten into "what it should have said" is a work item the agent authored. Escalate it (§6) |
 | Take items needing a human decision | It cannot unblock itself; those wait in the Operator queue |
 | Take a `trigger-human` item | It would build for scale that does not exist |
-| Take two elevated items back to back | One unreviewed schema/permissions change is recoverable; a chain overnight is not |
+| Take two mechanism-touching elevated items back to back | One unreviewed schema/permissions change is recoverable; a chain overnight is not (a prose-only elevated close clears it) |
 | Merge past a blocking reviewer verdict | The reviewer gate is what replaced the human merge |
 | Trust a `blocked` label over the links | The label is a snapshot; the links are the dependency |
-| "Improve" on an empty queue | An empty filtered queue is the end of the run, not an invitation |
+| "Improve" on a queue that hands out nothing | Whether it stopped as empty or as held back, a run with no item is at its end, not at an invitation |
 | Start new work on an unhealthy runtime | The regression compounds into everything above it |
 | Act on the "Never" tier | A hard stop, enforced by hooks |
 
@@ -301,8 +841,97 @@ 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.
+- **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 '
+    const { recordCompletedTier } = await import("./.claude/scripts/queue/state.mjs");
+    const { withoutGitLocation } = await import("./.claude/scripts/git-env.mjs");
+    const { execFileSync } = await import("node:child_process");
+    const merge = "<merge-sha>";
+    // The merge commit against its first parent: what the PR actually added.
+    const changedFiles = execFileSync(
+      "git", ["diff", "--name-only", "-z", `${merge}^1`, merge],
+      { encoding: "utf8", env: withoutGitLocation() },
+    ).split("\0").filter(Boolean);
+    console.log(recordCompletedTier({
+      changedFiles,
+      projectRoot: process.cwd(),
+      runDir: process.env.RIG_RUN_DIR,
+    }));
+  '
+  ```
+
+  Five details in that command are load-bearing — copy it, do not re-derive it:
+
+  - **`runDir`**, or the escalation streak (§3) never resets;
+  - **`<merge-sha>^1 <merge-sha>`**, never `origin/<default>...<merge-sha>`;
+  - **`-z`, and split on `\0`**, or a quoted path records the wrong tier;
+  - **`execFileSync` with an argument array**, never a shell string;
+  - **`env: withoutGitLocation()`**, or under a git hook it diffs another repo.
+
+  🔴 One of them — `-z` — fails **silently and permissively**: it records
+  `normal` for an elevated change rather than refusing. The wrong diff form
+  refuses loudly, and omitting `runDir` fails quietly toward a stop nobody can
+  clear. Which fails which way, measured rather than assumed, is in
+  `docs/decisions/closing-a-task.md`.
+
+  🔴 **The tier comes from the diff, never from the item's marker.** The marker
+  is a pre-filter (§2); `autonomy.md` decides the tier by what the change
+  *touches*, and rationing on the marker would mean one written a tier low
+  silently buys a second elevated item in a row. A marker that disagrees with
+  the paths is queue hygiene to report, not the value to ration on.
+
+  It **refuses** rather than guessing when the file list is empty or missing:
+  an absence is not a normal-tier change, and the permissive answer written
+  confidently is exactly how this seam went unnoticed in the first place. If it
+  refuses, find the file list — do not pass one to make it quiet.
 - **Write-back:** with the close, record what it **unblocked** — the items that
   were waiting on this one, by name. It is the journal's `unblocked` field, and
   it is **required, not a step for when it applies**: an absent line and an