create-agent-rig 0.4.0 → 0.6.0

package/templates/agent-os/universal/docs/decisions/gate-coverage.md

@@ -0,0 +1,83 @@
+# Why the fan-out is checked in `pr-ship`, and never in a hook
+
+The check lives in the `pr-ship` skill, step 5 ("Coverage"), and its rule is one
+sentence: *a merge is not gated by a fan-out whose reviewers did not all answer
+for the commit being merged.* This file explains why that check sits in a skill
+rather than in `guard-bash`. The hook version is the one that keeps being
+proposed, and a refusal nobody wrote down gets proposed again. It is not loaded
+into any session.
+
+## The shape that was refused
+
+The proposal: `guard-bash` denies a merge command unless the run journal holds a
+`SHIP` from every reviewer the router named, for the PR's head commit. It is the
+attractive version — mechanical, at the tool layer, impossible for a hurried
+session to skip.
+
+It was refused on four costs, each of them a rule this project already paid for.
+
+**1. It needs to recognise a merge command while the brake is off.** The kill
+switch can be coarse — it denies the network clients *as a class of binaries*,
+reading no merge semantics at all, while still allowing the wind-down it asks
+for — because a false block is cheap when the session is already stopped. `invariants.md` states that
+directly: match a rule's precision to the cost of a false positive. A merge gate
+runs during ordinary work, where a false block lands on the last step of finished
+work. The one attempt at enumerating merge routes was reverted, and what it cost
+is recorded where the attempt was made rather than restated here:
+`.claude/hooks/guard-bash.mjs`, the comment above `NETWORK_CLIENTS`.
+
+**2. It needs the head commit, inside a hook that must stay pure.** For
+`gh pr merge <number>` the head is only knowable over the network, and
+`guard-bash` records what an unbounded hook costs: killed by its own timeout, and
+a killed hook does not block — so **every** rule silently switched off, not just
+the new one.
+
+**3. It needs to parse the journal in a guard that fails open.** The journal
+reader refuses a malformed line by throwing, which is right for a reader and
+fatal for a fail-open guard: the throw resolves to *allow*, again for every rule
+at once. `stop-flag.mjs` is not the precedent it resembles — that is `existsSync`
+over a capped list of fixed paths, not a parse.
+
+**4. Its sweep half cannot exist.** The natural companion — audit merged PRs from
+outside — has nothing to read: the run directory is gitignored, and the sweep
+sees labels and PR bodies only.
+
+## And the reason the four costs were not worth paying
+
+Even fully built, the guard would read a file **the audited run wrote itself**.
+For the threat model a hook actually has — drift, not an adversary — that is
+tolerable, and it is why the skill-level check below is worth having at all. What
+it is not is the *guarantee* the hook version promised, and the four costs above
+were being paid for that word.
+
+## What was built instead
+
+`.claude/scripts/lib/gate-coverage.mjs` compares the three sets the journal already holds —
+routed, launched, answered — and `pr-ship` runs it through
+`verdict.mjs coverage <commit>` before its own verdict. It sits in the layer that
+already knows the head commit, is allowed to run git, and is allowed to throw.
+
+Two limits, and both are stated in the skill beside the step rather than only
+here:
+
+- with no `RIG_RUN_DIR` there is no journal, so the check says it was skipped and
+  exits 0 — an honest nothing, never a pass;
+- a session that skips `pr-ship` entirely skips this with it. That is the gap the
+  hook version was reaching for, and it stays open.
+
+So `CLAUDE.md` keeps its sentence unchanged: *no hook launches the gates, so "the
+gate ran" is a claim, not a guarantee.* What changed is narrower and worth
+having on its own — the driver can no longer accept a fan-out that did not
+answer, or one that answered about a commit two pushes ago.
+
+## The variant that removes self-report, and why it is not the default
+
+Running the reviewers as CI check runs is the only shape where the evidence is
+authored by something other than the audited run, and where the driver cannot
+skip the gate at all. It is not refused on its merits.
+
+It is refused **as a default for this layer**: everything under `.claude/` ships
+into every project this rulebook generates, so making it the shape would require
+a model credential in every generated project's CI and a per-PR cost, for
+projects that never asked for either. A project that wants that guarantee should
+adopt it deliberately; the check above is what every project gets.

package/templates/agent-os/universal/docs/decisions/review-lanes.md

@@ -0,0 +1,72 @@
+# Why the router's prose set and the gate sweep's inert set differ
+
+The rule lives in `.claude/rules/workflow.md`, under "PR flow". This file
+explains the one part of it that reads like an inconsistency and is not, so that
+nobody "tidies" the two sets into agreement. It is not loaded into any session.
+
+## The sets
+
+Three different mechanisms each carry their own notion of "this file is only
+words":
+
+**The first two carve out the rulebook**, and only then differ; the third runs
+*after* the sweep has already answered, so it sees only what survived:
+
+| mechanism                | rulebook exemption                         | inert / prose after it                     | consequence                                         |
+| ------------------------ | ------------------------------------------ | ------------------------------------------ | --------------------------------------------------- |
+| the Tier-2 gate sweep    | `isRulebook` in `detect-missed-gate.mjs`   | `.md`, `.mdx`, non-provisioning test paths | does not escalate on the elevated-path ground alone |
+| `decision-router.mjs`    | `isRulebookPath`, checked before extension | `.md`, `.txt`                              | may route to the `fast-path` prose lane             |
+| the queue's elevated ration (`queue/state.mjs`) | none of its own — it classifies what `elevatedPathsIn` already returned, so only **rulebook** markdown ever reaches it | `.md` (`executesNothing`) | records `elevated-prose`, which does **not** space the next item |
+
+The third row is the one added last, and its question is different again: not
+"does this need the gate" nor "can a prose reviewer judge it alone", but **"can
+a merge of this compound into a broken runtime overnight"**. That is why it
+excludes `.mdx` where the sweep includes it — same reasoning as the router's,
+one row below — and why it is `.md` only rather than the sweep's set. Its two
+predicates live in `detect-missed-gate.mjs` side by side so *those two* cannot
+drift; that is a statement about one file, **not** a rule that every markdown
+test in the rig belongs there. The router's sets stay where they are, for the
+reason this whole record exists.
+
+**Neither row applies to a decision record, including this one.** Both
+predicates recognise `CLAUDE.md` anywhere, everything under `.claude/`, and —
+since these records were extracted — everything under `docs/decisions/`, through
+the one shared `isDecisionRecord`. A change here escalates the sweep and takes
+the `model` lane, exactly as the rule it explains would. The router's call is
+not a redundant copy of the sweep's; deleting it silently drops this file to the
+prose lane.
+
+Without that exemption, declaring a path elevated was a no-op for every `.md`
+under it — the defect that put it there — and it is why moving this rationale
+out of `.claude/` needed a code change rather than only a declaration:
+`isInert` is consulted first, so the declaration alone would have reported clean
+over every record.
+
+The **remaining** difference is the inert/prose column, and no set contains
+another. That is deliberate, and every difference earns its keep. One more
+asymmetry belongs to the router alone: it **folds case** before its rulebook
+check, because there folding can only escalate, while a sweep that folded would
+name a path the repository does not have.
+
+## Why the sweep does not also take `.txt`
+
+Widening the sweep to `.txt` would stop `requirements.txt` inside an elevated
+directory from escalating. A dependency manifest is the opposite of inert — it
+is one of the risk flags — and its extension happens to be `.txt`.
+
+## Why neither the router nor the ration takes `.mdx`
+
+Copying the sweep's `.mdx` into the router's prose set would put executable MDX
+back on the prose lane. MDX carries components and imports; it is a program that
+renders, not a document that is read. The ration reads it the same way and for
+the same reason (`spacing-rations-mechanisms.md`): calling it prose there would
+clear the spacing hold on a file this rig treats as a program, on the permissive
+side.
+
+## The shape of the mistake this prevents
+
+Both edits look like clean-ups. Each removes an apparent inconsistency between
+two lists that "obviously" mean the same thing, and each one silently downgrades
+a real review. The lists mean different things because the questions differ:
+"does this change need the elevated gate?" is not "can a prose reviewer judge
+this alone?"

package/templates/agent-os/universal/docs/decisions/run-directory.md

@@ -0,0 +1,44 @@
+# Why one run directory per run, and why nothing can enforce it
+
+The rule lives in the `loop` skill, section 1 ("Declare the run directory here").
+This file explains what the enforcement does and does not reach, so nobody
+mistakes the warning for a guarantee. It is not loaded into any session.
+
+## An undeclared run is not a run with a missing journal
+
+`RIG_RUN_DIR` holds two unrelated things: the machine trace, and the run's
+**stop conditions** — the escalation streak, the deploy verdict, the budget flag.
+
+With `RIG_RUN_DIR` unset, the two verdicts a session writes by hand
+(`run-state.mjs deploy …`, `run-state.mjs budget …`) refuse loudly, so it finds
+out. **The escalation count does not.** It is recorded nowhere, silently, and
+selection then hands out work after two walls in a row with nothing on stderr to
+say why.
+
+So an undeclared run is a run whose main brake is off, and which looks exactly
+like a healthy one from the outside.
+
+The trace's first call site is **selection**, which runs before every task.
+Declared later, it misses everything that already happened — which is why the
+declaration belongs in preflight or nowhere.
+
+## What the reuse check catches
+
+- Two writers landing on the same sequence number.
+- A directory that already carries its run-end marker.
+
+Both are refused. Selection still works and says so on stderr, and that run's
+trace ends there — **loudly**, which is the good case.
+
+## What it cannot catch
+
+Two runs whose records happen not to collide.
+
+A run that died before writing its end marker — and dying unexpectedly is
+exactly the case the checkpoint discipline exists for — leaves an intact
+sequence behind it. The next run pointed at that directory **continues it in
+silence**: one seamless trace of two runs, with nothing in the file able to say
+so.
+
+Nothing detects this after the fact. A fresh directory per run is the only thing
+that prevents it, and it is the session's to do.

package/templates/agent-os/universal/docs/decisions/spacing-rations-mechanisms.md

@@ -0,0 +1,125 @@
+# Why the elevated ration counts mechanisms and not documents
+
+The rule lives in the `loop` skill, section 2; the code is
+`.claude/scripts/queue/state.mjs` (which tier a close records) and
+`.claude/scripts/queue/core.mjs` (which tiers clear the ration). This file
+explains why the elevated tier splits in two, why only one half spaces the next
+item, and why an unrecognised tier holds. It is not loaded into any session.
+
+## What the ration was bought for
+
+The rule's own sentence names it: _one **unreviewed** schema or permissions
+change is recoverable; a chain of them compounding overnight is not._ Two words
+in it do the work. **Unreviewed** — the risk is an unattended run stacking
+changes nobody read. **Compounding** — the second change lands on top of what the
+first one did, so the damage is not additive but multiplied.
+
+A rulebook document satisfies neither. It is reviewed on the model lane by two
+cold readers, and it compounds into nothing overnight because no runtime
+executes it. Yet in any repository whose rulebook lives under a declared
+elevated path — every rig, by construction — a `.md` close recorded the same
+`elevated` as a migration and held the next item exactly as hard.
+
+Two measurements on this repository forced the change, and they are different
+facts — the second is the mechanism's own report, the first is not:
+
+- The `loop` run of 2026-08-17 hit `nothing-selectable` with **56 takeable items
+  held, 53 of them by spacing** — the count `queue/index.mjs next` printed, so
+  this one is the ration speaking. It holds on the item's **marker**, which is
+  what those 53 carried. ⚠ Not reproducible from this repository: the queue is
+  tracker-backed and the run's own record is under the gitignored
+  `.claude/runs/`, so this figure is a report, not a check anyone can re-run.
+- Earlier, the AR-63 run recorded (journal, 2026-08) that of 58 selectable items
+  **56 were elevated in fact — by declared path** — 31 of them marked so and 25
+  marked `normal` while their own bodies named an elevated path. That is a
+  measurement of the queue, not of the ration: it says the pressure is not going
+  to ease, because a rig's rulebook lives under a declared path by construction.
+
+Together: the ration was not pacing the project, it was halting it, and the halt
+was indistinguishable from the rule working.
+
+## The split, and where it does NOT apply
+
+`recordCompletedTier` classifies the elevated paths a close actually crossed:
+
+| what the close crossed | tier recorded | effect on the next elevated item |
+| --- | --- | --- |
+| every elevated path is a document | `elevated-prose` | clears the ration |
+| any elevated path is not | `elevated-mechanism` | spaces it |
+| no elevated path at all | `normal` | clears the ration |
+
+⚠ **"Elevated path" is the sweep's answer, not the diff's.** `elevatedPathsIn`
+drops inert paths *before* this classification runs, and a non-rulebook `.md` is
+inert — so `scripts/notes.md` under a declared directory records `normal`, not
+`elevated-prose`. In practice the only markdown that ever reaches the split is
+**rulebook** markdown: `CLAUDE.md` anywhere, everything under `.claude/`, and the
+decision records. That is pre-existing sweep behaviour, restated here because the
+table above reads more broadly than the code behaves.
+
+The predicate is `executesNothing` — **`.md` only** — and it lives in
+`detect-missed-gate.mjs` beside the sweep's own markdown test so the two cannot
+drift apart.
+
+**They are different tests on purpose, and `.mdx` is where they part.** The
+sweep asks *does this need a reviewer* and calls both flavours inert. The ration
+asks *can a merge of this compound overnight*, and MDX carries components and
+imports — it is a program that renders, not a document that is read, which is why
+`decision-router.mjs` already sends it down the code lane
+(`review-lanes.md`). Calling it prose here would clear the spacing hold on a file
+this same rig treats as a program, on the permissive side.
+
+Two questions, two predicates, **one file** — that pairing is why they cannot
+drift. It is not a rule that every markdown test in the rig belongs there:
+`decision-router.mjs` keeps its own sets on purpose, and `review-lanes.md` — now
+with a row for this ration — exists to stop anyone consolidating them.
+
+**The known soft spot: a skill's `SKILL.md` is prose by this test**, and some
+skills carry shell snippets an agent copies and runs. The ruling is that skills
+stay prose for rationing — they are reviewed like the rules they are, and
+rewriting a procedure is not the chain of unreviewed compounding changes the
+ration was bought to stop. It is still the weakest ground the "no runtime
+executes it" justification stands on, and the first place to look if the ration
+turns out too loose.
+
+**A mixed diff is a mechanism close.** The half that runs decides. Reading the
+tier off the first path, or off "most of them are documents", would ship a ration
+any diff can opt out of by also touching a `.md`.
+
+The split is read by **exactly one** consumer: the ration. `elevated-prose` is
+still an elevated change wherever it is *reviewed* — the model lane, the cold
+readers, the `human-review` label, the gate sweep — and `recordCompletedTier`
+still reports every elevated path it found, unchanged. Narrowing the ration must
+not narrow the report: a prose merge that stopped listing its rulebook files
+would look clean to the sweep that exists to catch exactly those merges.
+
+## Unknown holds; absent does not
+
+`core.mjs` releases on `normal`, on `elevated-prose`, and on an **absent** tier —
+`null`/`undefined`, which is the honest statement that nothing has closed yet and
+what a fresh checkout says. Everything else holds: the legacy `'elevated'` an
+older state file carries, a word in the wrong case, a value that is not a string.
+
+The tempting implementation is `tier === 'elevated-mechanism'`. It is wrong in
+the one direction that matters: every unrecognised value would read as "nothing
+elevated closed" and hand out the next elevated item — un-rationing the queue
+silently, on state files this project itself wrote last week. The whole seam
+exists because a filter whose input nobody supplies is indistinguishable from a
+filter that agrees with you.
+
+The legacy word stays *readable* for the same reason it must not be *permissive*:
+a checkout that upgrades mid-run still has one on disk, and refusing it outright
+would exit 1 on the next selection. `loadState` accepts four words and refuses
+the rest — **for the state file only**. Selection falls back to a tier left in
+`queue.json`, and `loadConfig` validates nothing but JSON syntax, so a word like
+`banana` in the config reaches `selectNext` unrefused — measured: the CLI exits 0
+with no refusal, and then **holds** the elevated item with `causes: ["spacing"]`.
+It holds because `core.mjs` is the layer that reads every unrecognised value
+restrictively — the same layer that holds when `selectNext` is called directly.
+
+## What this does not fix
+
+The livelock where *every* remaining item is elevated-by-mechanism still exists —
+narrowed, not closed. Its operator-only remedy is filed and **not built**: no
+such command exists in this repository today, so a run that hits the livelock
+stops and says so rather than clearing its own tier. Spacing is also still per
+checkout, so a second worktree does not get its own allowance.

package/templates/agent-os/universal/docs/decisions/stop-conditions-in-a-file.md

@@ -0,0 +1,46 @@
+# Why the run's stop conditions are a file, not a memory
+
+The rule lives in the `loop` skill, section 3 ("What keeps the loop running,
+and what stops it"). This file records why the state was moved out of the
+session, and why only one of the two written verdicts can be taken back. It is
+not loaded into any session.
+
+## The defect the file fixed
+
+`escalations` and `lastDeployVerdict` now live in `<RIG_RUN_DIR>/state.json`,
+written by `run-state.mjs`.
+
+Before that existed, the CLI called `stopConditionOf` with the queue counts
+alone. Every state-dependent branch therefore held its **default** on every real
+selection — the runtime-regression stop, the two-escalations stop, the budget
+stop. None of them could fire. The rules were enforced only by whichever session
+happened to remember them.
+
+Compaction is exactly the moment a long unattended run stops remembering, and a
+long unattended run is the only situation these stops exist for. So the stops
+were reliably absent precisely where they were needed.
+
+## Why the escalation count has two writers, and both must be the documented one
+
+- It **rises** through the adapter's `escalate()`. Hand-labelling an item
+  escalated marks the item and counts nothing, so the run grinds past the wall.
+- It **resets** through the close step's `recordCompletedTier`, and only when
+  that call is passed `runDir` — see `docs/decisions/closing-a-task.md`.
+
+Both halves fail quietly when done the undocumented way, and they fail in
+opposite directions: one never stops a broken run, the other stops a healthy one.
+
+## Why only the deploy verdict can be taken back
+
+The asymmetry is deliberate.
+
+`HEALTHY` names a **real later event** — the revert landed and the runtime was
+re-verified. Without a way to record it, one bad deploy would end every later
+selection in the run, however thoroughly it was fixed.
+
+Spend only accumulates. Un-exhausting a budget would name no event at all — only
+a decision to keep going, taken by the very run that declared the stop. That is
+the shape of a stop condition a run can talk itself out of, which is not a stop
+condition.
+
+A new run starts from a clean state. That is the way back from both.

package/templates/agent-os/universal/docs/decisions/two-empty-endings.md

@@ -0,0 +1,74 @@
+# Why "queue empty" and "nothing selectable" are different endings
+
+The rule lives in the `loop` skill, section 3. This file explains why the two
+stops are reported separately, how the parked pile grows under each adapter, and
+why a parked cause outranks a holding one. It is not loaded into any session.
+
+## The two endings ask the owner for opposite things
+
+- **Queue empty after the filters** — there is no work. Refilling it is the
+  owner's job. Expect this to be the most common ending: the queue is finite and
+  the loop drains it.
+- **Nothing selectable** — the work is there and every piece of it is held back
+  by a condition that clears when _something else happens_: the elevated spacing
+  (a normal item lands — or an elevated one whose paths were all documents, see
+  `spacing-rations-mechanisms.md`), a blocker (its item closes), `in-progress`
+  (the other session finishes), a trigger (a human declares it), an owner (the
+  item is marked for another repository and a human moves or re-marks it —
+  AR-132), a `re-scope` item (a human rewrites it against the current code and
+  removes the label — AR-144), and a `deferred` item (it carries the `parked`
+  label and a human un-parks it — AR-144).
+
+An empty queue wants refilling. A held one wants interleaving, time, or — for a
+trigger or an owner — the human act the stop line names.
+Reporting the second as the first sends the owner to write tickets that already
+exist; reporting the first as the second tells them to wait for nothing.
+
+## The parked pile is reported next to the verdict, never inside it
+
+Parked items are out of play and waiting on a human. They are not work this run
+can take, and they are not why the queue is empty — so they are named separately,
+by cause and count. An `obsolete` item (AR-144) is one of them: it waits on a
+human close with a comment naming the evidence, which the loop never writes.
+
+⚠ "Parked" here is the pile, not the `parked` **label**. The label (AR-144) means
+"valid work, deliberately not now" — takeable, held, freed by an un-park — so its
+cause is spelled `deferred`, and it is never in this pile. The two were named
+before each other existed; this note is the reconciliation rather than a rename,
+because the pile word runs through the stop line, the tests and this record.
+
+How that pile grows is the adapter's business, and the stop line does not guess:
+
+| adapter                                  | what lands in the parked pile                         |
+| ---------------------------------------- | ----------------------------------------------------- |
+| tracker-backed (`github-issues`, `jira`) | an escalated item, a filed proposal (both stay open), and an item labelled `obsolete` (AR-144) |
+| `plan-md`                                | a `[triage]` or an `[obsolete]` line sitting in the Agent queue — nothing else, because a flat list has no per-item state |
+
+Under `plan-md` a filed proposal goes to the Operator queue, where selection
+never looks, and an escalation leaves **no mark on the queue at all** — a flat
+list has no per-item state.
+
+## That absence is not a safety
+
+`plan-md`'s `escalate` writes nothing to the queue and returns `ok: false`,
+handing back the instruction with it: move the item to the Operator queue in the
+same edit. That move is the session's, and skipping it means the next run takes
+the stuck item straight back.
+
+It does still record the escalation into the run state, like every other
+adapter. The two are different facts, which is why escalating must go through
+the adapter rather than by hand-labelling: the count is what ends a run that has
+hit the same wall twice.
+
+## Why a parked cause outranks a holding one
+
+An escalated item is left **claimed** on purpose, so it arrives carrying
+`in-progress` as well as `escalated`.
+
+Reading that as _held_ would report "another session will finish it" about an
+item no session is on — and, worse, would make the empty verdict unreachable
+from the first escalation onward. Reporting a working queue as empty is the
+defect this distinction exists to prevent; reporting a parked one as working is
+the same defect reversed.
+
+Neither ending is an invitation to refill the queue or invent work.

package/templates/agent-os/universal/journal/README.md

@@ -0,0 +1,101 @@
+# The journal
+
+The human record of what sessions did here. **One file per month**, named
+`journal/YYYY-MM.md` — the month is the filename's job, so entries themselves
+stay date-free and their order carries the sequence.
+
+**Newest-on-top inside each file.** A new entry goes directly under the month's
+heading, so the file reads as a stack. Prune freely: this is operational memory,
+not an archive.
+
+**The shape of a month file**, stated because the first session of a new month
+creates it and a shape nobody wrote down is one that has to be guessed:
+
+- it **opens with a single `#` heading** naming the month;
+- **every entry is a `###`** under that heading, and there is nothing at `##`
+  or any other level in between;
+- a new entry is inserted directly beneath the `#` heading, above the previous
+  newest.
+
+**What is mechanically checked, precisely — because this file ships into a
+project and its checks do not.** The generator that produced this rig has tests
+for the first two bullets and for the `YYYY-MM.md` filename; **this project has
+none of them** unless you write them. That is the same arrangement
+`.claude/rules/invariants.md` describes for the hooks, and the same caveat
+applies: what is not tested here is convention, however firmly it is written.
+
+The third bullet — *where* a new entry is inserted — is convention even in the
+generator. Nothing checks entry order anywhere yet; making "newest" decidable
+for date-free entries is its own piece of work. Do not read the presence of a
+shape rule as a guarantee that a misordered file would be caught.
+
+`README.md` is this document, not a month file. Other names: a file that does
+not match `YYYY-MM.md` is never **read** as a month file — but do not read that
+as permission, because in the generator any other `*.md` in this directory
+**fails** the filename check. Keep archives and side notes out of this
+directory, or somewhere with a non-`.md` extension.
+
+An unattended run writes an entry at every stop **and** at checkpoints along the
+way, because a run that dies unexpectedly must not take its history with it.
+
+🔴 **This is not the run trace.** `.claude/runs/<run>/events.jsonl` and
+`decisions.jsonl` are machine-readable, append-only and **oldest-first**, written
+by `run-journal.mjs`. This file is the human record and is newest-on-top. They
+answer different questions — the trace says what the run decided and on what
+basis, this says what a reader needs to know afterwards — and reading one as the
+other is how a reader concludes a run did nothing.
+
+## The entry
+
+The fields exist so an entry can be visibly **incomplete**. A journal with no
+stated shape decays into a diary that reads fine and proves nothing.
+
+Copy the block and drop the fields that do not apply — `unblocked` is the
+exception, and it is stated even when the answer is "nothing".
+
+```markdown
+### <one-line summary of the session>
+
+- **done** — what landed, one line each, with the PR reference
+- **escalated** — what stopped, and the diagnosis: what failed, what was tried,
+  the current hypothesis, and the one question whose answer unblocks it
+- **reviewed** — changes that went through a reviewer gate, and what it returned
+- **stopped at** — which stop condition ended the session (or "checkpoint,
+  still running")
+- **unblocked** — what the session's closes released
+- **queue hygiene** — queue state the session found unreliable and reported
+- **cost** — the counts the session actually observed
+```
+
+## The two fields that are most often got wrong
+
+**`unblocked` is never dropped**, and it has **three** answers that do not
+substitute for each other:
+
+1. the items that were waiting, by name;
+2. "nothing was waiting" — the queue carries dependency links and none pointed
+   here;
+3. "this queue has no dependency links" — it cannot answer at all.
+
+A flat-list queue is **absent, not satisfied**, and writing "nothing was waiting"
+there claims a look that no query could perform. A missing line and an unpaid
+debt read identically from outside, which is why the empty case has to be
+written to mean anything.
+
+**`cost` carries only what the session observed** — reviewer subagents run, CI
+runs consumed (re-runs included, the cheapest signal that a task fought its
+tests), deploys triggered.
+
+## Never estimated — and this governs every field, not just `cost`
+
+**Any** field the session cannot observe stays **visibly empty, never
+estimated**. A plausible number will be believed, by the next reader and by the
+next run reasoning about its own budget — and the same is true of a plausible
+sentence: a guessed `reviewed` or an inferred `unblocked` is the identical
+failure without the digits. Leave the gap; it is information.
+
+## Queue hygiene is reported, never corrected in passing
+
+A stale marker, a dependency already satisfied, an item describing work already
+done — record it here. Quietly fixing the metadata destroys the evidence that the
+metadata is unreliable.

package/templates/agent-os/universal/layers.json

@@ -14,21 +14,62 @@
     ".claude/hooks/guard-bash.mjs",
     ".claude/hooks/gate-stop-dod.mjs",
     ".claude/hooks/inject-rules.mjs",
+    ".claude/hooks/guard-secret-file.mjs",
+    ".claude/hooks/guard-rulebook.mjs",
+    ".claude/hooks/lib/edit-input.mjs",
     ".claude/skills/pr-ship/SKILL.md",
     ".claude/skills/loop/SKILL.md",
     ".claude/skills/check-premises/SKILL.md",
     ".claude/skills/worktree-task/SKILL.md",
+    ".agents/skills/new-invariant/SKILL.md",
+    ".agents/skills/new-invariant/guard-invariant.example.mjs",
+    ".agents/skills/new-invariant/guard-invariant.example.test.mjs",
+    ".agents/skills/pr-ship/SKILL.md",
+    ".agents/skills/loop/SKILL.md",
+    ".agents/skills/check-premises/SKILL.md",
+    ".agents/skills/worktree-task/SKILL.md",
+    ".codex/agents/test-writer.toml",
+    ".codex/agents/code-reviewer.toml",
+    ".codex/agents/security-scanner.toml",
+    ".codex/agents/prose-reviewer.toml",
     ".claude/scripts/detect-missed-gate.mjs",
+    ".claude/scripts/decision-router.mjs",
     ".claude/scripts/reconcile-external-prs.mjs",
     ".claude/scripts/stop-flag.mjs",
+    ".claude/scripts/unattended-flag.mjs",
+    ".claude/scripts/git-env.mjs",
     ".claude/scripts/preflight.mjs",
+    ".claude/scripts/doctor.mjs",
+    ".claude/scripts/run-journal.mjs",
+    ".claude/scripts/run-state.mjs",
+    ".claude/scripts/verdict.mjs",
+    ".claude/scripts/revalidate.mjs",
+    ".claude/scripts/revalidation-report.mjs",
+    ".claude/scripts/lib/gate-coverage.mjs",
+    ".claude/scripts/lib/revalidation-points.mjs",
+    ".claude/scripts/lib/verdict.mjs",
+    ".claude/scripts/lib/secrets.mjs",
     ".claude/scripts/queue/core.mjs",
     ".claude/scripts/queue/plan-md.mjs",
     ".claude/scripts/queue/github-issues.mjs",
     ".claude/scripts/queue/jira.mjs",
     ".claude/scripts/queue/index.mjs",
+    ".claude/scripts/queue/as-of.mjs",
+    ".claude/scripts/queue/checkout.mjs",
+    ".claude/scripts/queue/state.mjs",
+    ".claude/scripts/queue/gate-rounds.mjs",
     ".claude/queue.json",
-    "PLAN.md"
+    "PLAN.md",
+    "journal/README.md",
+    "docs/decisions/gate-coverage.md",
+    "docs/decisions/fail-open-guards.md",
+    "docs/decisions/codex-adapter.md",
+    "docs/decisions/closing-a-task.md",
+    "docs/decisions/review-lanes.md",
+    "docs/decisions/run-directory.md",
+    "docs/decisions/spacing-rations-mechanisms.md",
+    "docs/decisions/stop-conditions-in-a-file.md",
+    "docs/decisions/two-empty-endings.md"
   ],
   "architecture": [
     ".claude/rules/architecture.md",
@@ -37,6 +78,8 @@
   ],
   "meta": [
     ".claude/settings.json",
-    "CLAUDE.md"
+    ".codex/hooks.json",
+    "CLAUDE.md",
+    "AGENTS.md"
   ]
 }