create-agent-rig 0.4.0 → 0.5.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
 
@@ -67,6 +69,31 @@ 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"
+```
+
+🔴 **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,15 +114,54 @@ 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.
+
+**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` →
@@ -109,17 +175,90 @@ 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
+```
+
+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.
+
 ## 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.
+
+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
 
-Three of them deserve their reasons repeated:
+# 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 +269,27 @@ 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). 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
+  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 +321,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 +348,19 @@ 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 (two rounds of fixes did not
+converge), 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 +398,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 +464,66 @@ 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.
 
 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 +537,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 '
@@ -269,6 +556,21 @@ node --input-type=module -e '
 
 A proposal missing any of the four parts is refused rather than filed half-formed.
 
+**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 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.
+
 🔴 **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 +590,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 |
 
@@ -302,7 +604,52 @@ three poisons the only channel by which this project learns.
   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.
+  post-merge verdict — not in a cleanup pass. **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