Issues are the unit of work
The big picture: Nothing starts from a prompt. Every change starts from a tracked issue.
Why it matters: An issue is the written agreement about what “done” means. Without one, nobody — human or agent — can later check whether a change did what was asked. And three separate mechanisms in this harness key off the issue number.
scripts/wt new 1234looks up the issue title and derives the branch name (feat/1234-<title>) and worktree path from it.scripts/check-issue-collision.shreads the issue number back out of the branch name on every push, and blocks the push if that issue already has an open MR from another branch. It works however the branch was created, including a plaingit checkout -b.Closes #1234in the MR description is what actually closes it on merge. Without the keyword the issue stays open and the tracker silently drifts from reality.
The loop
Section titled “The loop”glab issue list --assignee @me # what is mineglab issue view 1234 # read it — including the COMMENTSscripts/wt new 1234 # branch + worktree; labels it status::wipcd ../<repo>-wt/1234-short-slug && source .envrc# ... work, with the gate chain from the fast-path table .../mr # opens the MR with Closes #1234# ... merge when green ...scripts/wt prune # from the main checkoutRead the comments before starting, not just the description. A stale branch or a half-done attempt is usually recorded there and nowhere else.
Writing issues the harness can use
Section titled “Writing issues the harness can use”- One issue, one acceptance criterion set. If a discussion surfaces a second problem, file it. A facet recorded as a comment on an open issue is not tracked — it dies the moment the host issue closes on a different facet. The test is simple: does it need its own acceptance criteria? Then it needs its own issue.
- Labels are load-bearing, not decoration. The claim label (
status::wipby default) is applied byscripts/wt new/wt claimand cleared bywt prune,wt remove(once the issue is closed) andwt release;/waveskips issues that carry it unless they are your own leftovers, which its resume step (Step 1b) classifies first and offers to resume, hand back or release. The collision gate (WIP_LABEL) andwt(WT_LOCK_LABEL) read the same default — if you rename it, set both. The gate warns when a pushed branch’s issue carries it but has no MR yet. Priority labels are read by/voc-auditwhen it decides between “file new” and “boost priority”. - Beware label gates that read the tracker rather than the repo. If you add a CI job that fails on a forbidden label, remember its input is not your diff — someone else’s label edit can redden the default branch, in a job log the next person to push has no reason to read. Scope such gates narrowly and say so in the job comment.
- Milestones drive
/dotplanning. It resolves a milestone’s scope into a feature→asset map and flags every screen, endpoint, or decision with no issue behind it. An empty milestone gives you an empty plan. - Blueprint itself uses plain
committed/uncommittedlabels and no dated milestones; an agent asks before moving an issue between them. Projects that do run dated milestones can add the scheme below. - A dated milestone is a promise, so every issue in one states its share of it.
One scoped label per issue —
release::committed(ships or the release slips, and the only issues that become roadmap bullets),release::reserve(a slot held for inbound work from real users),release::stretch(ships if there is time, moves at feature freeze). Scoped labels are mutually exclusive, so the tracker enforces the “exactly one” part. An agent asks which applies on every move into the milestone and never infers it: a guessedcommittedis a promise nobody made, and a guessedstretchquietly drops work someone meant to ship. Unanswered means unlabeled and said out loud — an unlabeled issue in a dated milestone is a visible gap, a guessed label is an invisible one.
Tagging escapes, and what the yield numbers show
Section titled “Tagging escapes, and what the yield numbers show”When a bug turns out to have been introduced by a merged MR, label the issue
escaped-from::<MR iid> (a scoped label, one per issue). The Bug template and
/incident-postmortem both ask for the originating MR, and /tracker-hygiene lists bugs
that name an MR without the label.
scripts/gate-yield.py (called by /kaizen) reads the ## Gates ledger of recent merged
MRs and joins those labels to it. It reports per gate how often the gate ran, how often it
found something, and on MRs that later escaped a defect, whether it ran and reported
0 findings. It also reports cost and turns per merged MR by change class, from the
optional cost: usd <N>, turns: <N>, subagent-tokens: <N>, orchestrator-tokens: <N>, est-cost-usd: <N.NN> (a list-price estimate) and budget-exceeded: <N> ledger lines (the last counts agents that exceeded their /wave budget) and a blockers <k> field in a gate line’s parenthetical (reported as blocker-yield). Per-MR estimated cost is not read from the est-cost-usd: line: it is the sum of the MR’s windowed ## Cost of this MR records (each record’s Allocated: figures when it has that line, its Total row otherwise; see below), and an MR without a usable record is excluded and counted. gate-yield.py also reports the MRs whose subagent-tokens: is above twice the median of the MRs read, as an outliers block, once at least 5 MRs carry the line. Run it offline against saved MR
data with --from-json <file>.
Escapes are also reported per fast-path class. An MR declares its class with a
change-class: <slug> line in its ## Gates section (for example bugfix, docs,
feature; a, b for a union). The script reads which gates that row requires from the
fast-paths table in CLAUDE.md, so each gate shows, over escaping MRs, whether it was
required and ran, required and clean, or required and did not run. An MR without the line
is reported as unmapped, not guessed from its title. python3 scripts/gate-yield.py --check-fastpath fails when the table and the slug list drift.
python3 scripts/gate-yield.py --spec-trace reads the same merged MRs for the spec intake: per imported
spec, the issues imported with an Override:, the share of MRs whose ## Requirements table differs from the
spec’s acceptance criteria at the version the issue names (read from git history, so a spec edited after the
import is not drift; an MR with no Requirements table, one closing several spec-traced issues, or a version missing
from history is listed and left out of the share), and the spec-review find-rate. Drift is a prompt
to read the texts, not a defect count.
What the numbers do not show:
- Yield is not value. A gate that has never found anything may be deterring the defect by existing, and a high-yield gate can still be missing the class that matters.
- An escape nobody tagged is invisible. The escape column is only as complete as the tagging. With no tagged escapes the report says “0 tagged escapes — escape rate not yet measurable”; that is not a 0% escape rate.
- A gate never required for a class reads 0 escapes there by construction, and the
declared class is the author’s own claim. The backticked
pre-MR gate batchexpands toregression-checkonly; the diff-conditionalperf-check,rbac-checkand the like read 0 for the backend, feature and trust-boundary rows. req-notrunis the process escape, with a caveat. A conditional gate (such astest-scaffold“if no coverage”) counts as required, so an absent one shows asreq-notruneven when its condition was false.- The slug list is a hand-maintained hint.
python3 scripts/gate-yield.py --print-fastpathis the authority. - Cost is what the MR reported, not a bill. MRs without a
cost:line are left out of the cost columns rather than counted as free. - A disabled ledger is not 0 and not a drop in cost. An MR with
cost-ledger: offhas no cost or token lines; it is left out of those columns, so a stretch of off MRs shows asdisabled, never as cheaper work. - The
## Cost of this MRcomments are the per-MR cost record. ThePostToolUsehook posts record 1 withscripts/cost-table.pywhen the MR is opened, so a person can read one MR’s tokens and estimated cost at a glance, and each later window of work on the MR (a fix round, a/fix-mrpass) adds a numbered record with a running total, never an edit of an earlier one.gate-yield.pyreads the## Gateslines for gates, turns andsubagent-tokens:, but takes per-MR estimated cost from the windowed records themselves (notes by the token user or the MR’s author only, strictly parsed; macrodream/blueprint#390), so a## Cost of this MRnote by anyone else excludes the MR: it is left out of the cost means and counted. So does a record posted with no session cost state (a session’s first record, or a state file that was lost), which says its window starts at the session’s start and may count tokens another MR’s record counts (macrodream/blueprint#391). The comments follow the samecost-ledgersetting and are absent when the ledger is off.
Feedback from outside the team
Section titled “Feedback from outside the team”People who use Blueprint, and are not in your tracker’s daily flow, can file a Feedback
issue from the template in .gitlab/issue_templates/Feedback.md. The
Giving feedback guide shows them the steps.