The Gates ledger
The big picture: Every MR that ran a gate carries a ## Gates section: one line per
gate, saying how many findings it produced. It is the only record of gate yield, which
is how a gate that never finds anything gets noticed and narrowed.
Why it matters: Without the ledger, a gate that runs on every MR and never catches anything looks identical to one that catches real defects. The zeros are the signal.
The canonical text is the Gates section in .claude/skills/mr/SKILL.md. Three scripts
read the format and are the source of truth for what is accepted:
scripts/check-gate-ledger.py (the strict lint), scripts/gate-yield.py (the parser and
the yield report), and scripts/mr-verdict.py (the per-MR verdict).
A gate line
Section titled “A gate line”- gate: <name> — <outcome>The outcome after the dash is exactly one of these, optionally followed by a parenthetical:
| Outcome | Means |
|---|---|
<N> findings (also 1 finding) |
The gate ran. <N> counts blocking and should-fix findings from its closing Findings: line, never notes. 0 findings is a real outcome; never omit a zero. |
n/a |
The gate’s scope excludes this diff. Give a reason: n/a (docs only). |
skipped |
The gate applied and the user declined it. Give a reason. |
n/a and skipped are different states and must not be conflated. If a gate applies,
run it and report what it said: a confident n/a is usually an unrun gate. Never inflate
<N>; the ledger exists so gates can be removed.
Prose after a count (0 findings, all fixed) is rejected by the lint. Put it in the
parenthetical.
The parenthetical
Section titled “The parenthetical”Fields are separated by ;. The first names the model that ran an agent gate.
- gate: regression-check — 2 findings (sonnet; stale mock, missed consumer)- gate: rbac-check — 0 findings (opus)- gate: completeness-check — 6 findings (opus; blockers 1; causes: test-weak 5)- gate: changelog-check — 0 findings- gate: security-review — n/a (docs only)| Field | Rule |
|---|---|
| Model | The bare lowercase family name (opus, sonnet, haiku), no version. It goes after the dash, never after the gate name: gate: rbac-check (opus) — … splits the gate’s row in the yield report. A script gate (changelog-check) and an n/a or skipped line carry no model. |
blockers <k> |
For a gate that grades blocking versus should-fix. k counts the blocking findings among the <N> and cannot exceed it. Omit it on a gate that does not grade. |
causes: ... |
The cause tally for completeness-check. |
budget-stopped |
The run was stopped at its /wave budget. Record it this way, never as a plain count. |
Gates with a second mode
Section titled “Gates with a second mode”A distinct second mode gets a /<mode> label, not a new name and not parentheses:
gate: completeness-check/fix-diff — 0 findings (sonnet)is the narrow re-check of the commits made in response to the firstcompleteness-check. Writen/awhen the fix round was docs, tests or comments only; a baren/ais accepted for this line.gate: completeness-check/fix-diff — 0 findings (sonnet; fix-mr)is the same re-check after a CI fix, written by/fix-mr. It is reported as its owncompleteness-check/fix-mrrow.- Round 2 of
completeness-checkis a second line under the same name, withround 2first in the parenthetical:gate: completeness-check — 2 findings (round 2; opus; blockers 1; causes: class-missed 2; overlap 1/3). Do not invent acompleteness-check-r2name.
The other lines in the section
Section titled “The other lines in the section”| Line | Meaning |
|---|---|
change-class: <slug> |
Always emit it. Names the fast-path row the MR took (several slugs for a union). The slugs come from the table in CLAUDE.md (see Fast paths); an unknown or missing one makes the verdict INCOMPLETE. |
rigor: strict (floor: <path>) |
Required when the diff touches the rigor floor; rigor: strict-light (floor: <path>) when it touches only the floor’s lighter tier. That level’s gate lines must then be in the ledger too, or the mr-gate-ledger job fails the MR. |
cost-ledger: off |
The cost ledger is turned off for this MR (see below). The only value; at most one per MR; never names who turned it off. With it, the MR carries none of subagent-tokens:, orchestrator-tokens:, est-cost-usd:, turns: or cost:. |
subagent-tokens: <N> |
Digits only. The cumulative usage of the branch’s agents and their descendants (the implementer’s gate batch included), summed per response from their transcripts by scripts/post-mr-cost.py --measure; written only by /wave; never an estimate (~5k and 1,234 are rejected). At most one per MR; omitted when the script fails. It replaces the retired tokens: line (the latest notification of each agent, a median ~30x below cumulative usage), which is now rejected; gate-yield.py counts old MRs’ tokens: lines apart and never averages them. |
orchestrator-tokens: <N> |
Digits only. The orchestrating session’s own usage over the branch, which subagent-tokens: does not include, in the same unit; written only by /wave, from scripts/post-mr-cost.py --measure. It is session spend over the window, not attribution to the MR, so do not add it to subagent-tokens: as the MR’s cost. It is a go-ahead snapshot that overlaps the other MRs of its session, so gate-yield.py does not read it as per-MR cost: it sums the MR’s windowed ## Cost of this MR records instead and leaves out, with a count, MRs that have none. At most one per MR; omitted when the script fails. |
est-cost-usd: <N.NN> (prices YYYY-MM-DD) |
The branch’s token usage (orchestrator window plus the named agents and their descendants) priced per response at list prices from the dated table .claude/model-prices.json, by scripts/post-mr-cost.py --measure. A list-price equivalent, not what a subscription charged; an estimate in its own labelled line, never added to cost: usd. A go-ahead snapshot, not per-MR cost: gate-yield.py takes per-MR estimated cost from the MR’s windowed ## Cost of this MR records. Digits and at most one decimal point; at most one per MR; omitted, with a ## Notes line saying why, when the table is stale (over 90 days), missing or malformed, a model has no row, a response used fast mode, a non-global inference_geo or a non-standard service_tier, or the script fails. |
turns: <N> |
Only if a turn count is literally reported. |
cost: usd <N> |
Only for a measured (billed) figure, never computed from .claude/model-prices.json. |
budget-exceeded: <N> (<role> <k>, ...) |
How many of the branch’s agents reached their /wave budget. 0 is a real outcome with no split; a split must sum to <N>; at most one per MR. Omit it on a branch that did not run under /wave. |
The template does not carry subagent-tokens:, orchestrator-tokens:, est-cost-usd:, turns:, cost: or budget-exceeded:, so nobody
fills them in from memory.
The cost ledger setting
Section titled “The cost ledger setting”The measured cost lines are a setting, cost-ledger, on by default. /kickoff asks it once;
scripts/cost-ledger status shows the effective value and which layer set it. The project
default is .claude/cost-ledger.json (scripts/cost-ledger on|off, landed through a chore MR);
one person can opt out locally at once with scripts/cost-ledger off --local (a
git config blueprint.costLedger false), but a local setting never turns recording on over a
project that chose off. With the ledger off, /mr and /wave write cost-ledger: off instead of
the cost lines and the ledger reads no transcript; budget-exceeded: is still written. The full rule is in
docs/harness/cost-ledger.md and ADR 0011.
The cost records
Section titled “The cost records”The readable cost table is an MR comment, not a section of the description. GitLab renders the
bare cost lines as one paragraph with change-class:, so /wave posts the figures as
## Cost of this MR (#<issue>) once the MR is open: tokens and estimated cost split by Sonnet and
Opus for the subagents and for the orchestrator, plus the totals. That is record 1, posted by the
PostToolUse hook .claude/hooks/post-mr-cost.sh through scripts/post-mr-cost.py when
glab mr create runs; later work gets a record K from post-mr-cost.py --round. The records of one
session do not overlap, so they add up to its spend, except a record posted with no session state (macrodream/blueprint#391), which the cost readers leave out. A record also counts another session’s subagents
that worked in the MR’s worktree, each over its own session’s watermark, so an MR opened from a
different session than its implementer still carries the implementer; that session’s orchestrator is
left out, and the record says how much of it is unclaimed. MRs opened before
macrodream/blueprint#384 may still carry a ## Cost section in the description; every reader
below parses them the same, because it reads only ## Gates from the description (gate-yield.py also reads the MR’s own ## Cost of this MR notes for per-MR estimated cost).
Work on the MR after record 1 (a fix round, a /fix-mr pass, a re-measure) gets its own comment,
## Cost of this MR (#<issue>) — record K, covering only its window (start and end stated), from
the measuring scripts’ own lines for that window (--ledger <file>), with a running-total row
across records 1..K. A re-run for the same window updates that record; a new window posts a new
one; an earlier record is never edited. Earlier records are read back only from the token’s own
user’s notes that carry the generated heading and footer and parse strictly; anything else makes
the running total n/a with the reason, never 0. A missing figure or a model with no price row
also shows n/a with the reason. With the ledger off or unreadable there is no record. The
## Gates lines are unchanged and stay record 1’s figures. Only gate-yield.py sums the records
(for per-MR estimated cost); no other reader below does. Each state is in docs/harness/cost-ledger.md § The cost records.
Who reads it
Section titled “Who reads it”| Reader | What it does |
|---|---|
scripts/check-gate-ledger.py |
The mr-gate-ledger CI job. Rejects any gate: line whose outcome is free text, a malformed blockers, subagent-tokens: (or a second one, or the retired bare tokens:), orchestrator-tokens: (or a second one), est-cost-usd: (a second one, or a malformed form such as $1.00 or ~1) or budget-exceeded: field, and a cost-ledger: off line that is doubled or sits beside a cost line. It never requires a cost line. It reads the MR description at job time, so editing the description and retrying re-checks it. An MR with no ledger passes this lint. |
scripts/mr-verdict.py --file <body.md> |
Run on the draft before opening the MR. Prints PASS, PASS WITH SKIPS, INCOMPLETE or FAIL, and lists the gates the declared change-class: requires that the ledger never mentions. |
scripts/gate-yield.py |
Parses merged MRs and reports per gate: runs, findings, yield, blocker-yield, n/a and skipped counts, and escapes. --by-model splits by model. MRs that turned the cost ledger off are reported as disabled, never as 0. Per-MR estimated cost and orchestrator tokens are summed from the MR’s windowed ## Cost of this MR records (notes by the token user or the MR’s author), not from the ## Gates snapshot; an MR without a usable record is excluded and counted, never read as 0. |
/kaizen |
Uses the yield report to find gates that have earned a fast-path exemption. |
scripts/cost-table.py --comment |
Not a check: renders and posts the numbered ## Cost of this MR records, record 1 and each later record from the window of tokens no earlier record of the session claimed (scripts/post-mr-cost.py measures and posts). Of the readers above, only gate-yield.py reads them (for per-MR cost). |
Escapes are joined by an escaped-from::<MR iid> label on the bug issue; an untagged
escape is invisible to the yield report.
Related
Section titled “Related”- Fast paths: the table that decides which gates run.
- Harness gates: the shared rules for gate scripts.
- Glossary: the short definition of Gate ledger.