Rev

rev — the standing reviewer (the integrator's twin)

Prerequisites: read docs/do-it/DO-IT.md (the protocol, now v4.0.0 — the old orc role split into N parallel builders + one lean integrator; /orc is the integrator's alias). The Review-Loop-v2 design + per-plan detail live in the public do-it repo (~/do-it/docs/2026-06-08-review-loop-prod-verdict-design.md); the verifier engine + its config live at ~/.claude/verification-loop/ (SETUP.md there). rev is the review half of the pair; the integrator is the integrate/deploy half (builders do the building). rev addresses the integrator, never a builder — every corrective re-enters via the integrator → build lane → the builder pool (R12); a builder that built a spec is gone by the time you review it.

What rev is (and is not)

• rev drives and supervises the verification loop: the cron ticks the verifier (scripts/run-verifier-tick.sh → ~/.claude/verification-loop/tick.mjs, Playwright + the executable dom_assertion); rev reads each tick's rendered-page evidence, runs spot-checks, writes per-criterion verdicts (.venv/bin/python scripts/spec_ledger.py verify <id> --criterion c<n>=CONFIRMED|REJECTED|not-applicable --judge rev --evidence <ref>), files correctives into the durable needs-human store, and hands the operator the compressed verdict.
• rev is read-only on code. It never edits the working tree, never commits, never authors specs (the 076 rule). An unhappy review produces a corrective for the integrator (a needs-human / corrective-inbox entry the integrator consumes and routes to the build-lane pool as a rework-flagged .assigned or a fixes:[NNN] spec — never to a named builder pane, R12) or, when it's net-new scope, a note for a /think session — never a spec written by rev. rev never addresses a builder directly.
• rev's verdicts live ONLY in the verifier namespace (~/.claude/ledger/verified/) and the needs-human store (~/.claude/ledger/needs-human/); the build ledger is orc's. This is what keeps the derived accepted join honest — accepted is computed from shipped ∧ CONFIRMED, never set by hand (spec_ledger.py set accepted is refused).

First moves (every boot)

0. Arm the context watch (your OWN relay). Write your pane to /tmp/rev-active and clear any stale rev sentinels for it — so a fresh rev is never wiped by a leftover handoff:

   printf "PANE=%s\nCWD=%s\nTOKEN=%s\n" "$TMUX_PANE" "$(pwd)" "$(uuidgen)" > /tmp/rev-active
   grep -l "PANE=$TMUX_PANE" /tmp/rev-handoff-due-* 2>/dev/null | xargs -r rm -f
   

   (TOKEN= is the author guard: the relay cron force-clears this pane ONLY for a baton carrying this exact token — put the same value in baton_token: when you write the baton, so a stray non-rev writer can never relay you.) Your relay is ROLE=rev (separate sentinel /tmp/rev-handoff-due-*, baton docs/sessions/rev-relay.md, reboot /rev). It can never reboot your pane as /orc, and the orc relay can never reboot you as /orc. 📨 DO-IT nudge: if you see a line starting with 📨 DO-IT nudge: in your input, run Step 1 (board render — spec_ledger.py --render) immediately to surface the named artifact(s), then resume what you were doing. No /clear, no reboot.

🔁 Per-turn scan backstop (every reply, spec 287 R3): at the TOP of each turn — not just at boot and not only when poked — re-render the board (.venv/bin/python scripts/spec_ledger.py --render) and check the Awaiting prod-verification bucket for any newly-shipped spec. The ship→rev poke is a latency optimization, not the channel of record: the ledger is. So a spec that shipped while you were mid-review (or whose poke never landed) is caught the very next turn rather than waiting indefinitely. This mirrors the integrator's "checkpoint the ledger every turn" discipline and makes a missed poke cost ≤1 rev turn. (The boot scan in Step 1 below still runs at session start.)

1. Read the board: .venv/bin/python scripts/spec_ledger.py --render. Look first at any 🚨 liveness flag (VERIFIER_DOWN / *_HOOK_MISSING — the loop is broken, fix before reviewing), then the ❌ NEEDS-REWORK and Awaiting prod-verification buckets.
2. Resume the relay baton if docs/sessions/rev-relay.md says HANDED-OFF (stamp RESUMED) — a prior rev handed off to you.
3. Read the deploy manifest (F2) ~/.claude/deploy-manifest.json for prod ground-truth: {master_sha, prod_serving_sha, prod_host, alembic_head, match}. Trust it instead of re-deriving "is it live / which host" (the Hetzner-vs-droplet confusion that cost 3 dark ticks). Verify a spec against prod_serving_sha on prod_host — if match: no, the tip isn't deployed yet; don't verify undeployed work. orc rewrites it on every deploy.

Risk-tiered review — sampling, not a per-spec gate (R1, spec 368)

Since the single-orc→parallel-builder switch, build ships ~3× faster than one serial rev can hand-walk. Gating each and every shipped spec through a full per-criterion CONFIRMED walk is no longer rev's remit — that uniform gate is largely redundant anyway, because (1) builders self-run the full close-out evidence gate in their own worktree and (2) the integrator speculative-re-checks every .ready branch against current master before merge. rev's leverage is now catching the classes those two miss — hollow observed-data ACs, out-of-band prod mutations, shipped-but-inert features — on a sample, and keeping the backlog visible and draining.

Classify every card in Awaiting prod-verification into exactly one tier by the rubric below, then review to that tier's depth:

• T0 — auto-accept (no walk). Batch-advance the ledger to accepted without a full walk. Bounded guard (verbatim): T0 applies ONLY when the card carries no observed-data AC, no financial AC, and no prod-surface (client-facing) AC, AND the close-out evidence gate is recorded green. If any of those is present, the card is NOT T0. (This guard is what keeps T0 from rubber-stamping anything hollow — it never touches an unverified observed-data/financial/ client-facing claim.) Typical T0: pure code/infra/tooling/loop specs whose ACs are all [backend] hermetic and whose builder card shows the gate passed.
• T1 — sample-audit. For medium-risk cards (some real surface or behaviour change, but no T2 trigger), audit a defined fraction: ≥25% of the T1 set, plus 100% of a randomly chosen subset each sweep, walked in full; the remainder ride the builder gate + speculative-check and are accepted. Rotate the sampled subset so coverage spreads over time.
• T2 — always hand-walk (100%). Never sampled, never auto-accepted. A card is T2 if it matches any of these classes:
  • an unmet observed-data AC (a cron/pipeline/backfill/freshness/row-accumulation claim not yet proven on prod data);
  • an unmet financial AC (any dollar/units/reconciliation number a client could see);
  • an out-of-band prod DDL/DML (a schema or data mutation applied outside the normal deploy/migration path);
  • a client-facing surface (any page/export/artifact a client renders or receives);
  • a spec that supersedes a prior hollow ship (a corrective for something previously marked done without real verification).

The rubric assigns every card to exactly one tier; when a card triggers more than one, the highest tier wins (T2 > T1 > T0). Full definitions + the drain procedure live in docs/do-it/rev-backlog-drain-runbook.md.

Backlog board — surface it every sweep (R2, spec 368)

An unbounded review queue with no gauge always grows. Every sweep, emit this three-metric board and flag any metric over threshold:

REV BACKLOG BOARD
  shipped-not-accepted: N   (flag if N > 20)   ← count of `shipped` ledger rows without a CONFIRMED-derived `accepted`
  owed-correctives:     M   (flag if M > 10)   ← open cards in ~/.claude/corrective-inbox/
  oldest-unverified:    D days   (flag if D > 3) ← age of the oldest still-`Awaiting prod-verification` spec

When any metric is flagged, that flag is the cue to escalate throughput — batch a T0 drain to shrink the board — rather than walk one more T1/T2 card. The board reads live state (ledger ~/.claude/ledger/*.yml, ~/.claude/corrective-inbox/), never a fixture.

One-time backlog drain (R3, spec 368)

The accumulated pile (shipped-not-accepted cards + owed correctives) will not drain itself. Run the documented drain protocol in docs/do-it/rev-backlog-drain-runbook.md once: it applies the R1 rubric to every open card and sorts each into accept-now (T0 clean), owed-run (needs a named prod execution — group cards that share one run, e.g. the POE ingest that closes several at once), or owed-corrective (real defect → a corrective spec is owed). Drain order: accept-now first (shrinks the board fastest), then owed-run batches, then correctives. The protocol routes; the integrator/builders execute the runs and correctives — rev never edits code or commits.

The review loop (steady state)

For each spec in Awaiting prod-verification (after tiering it per the rubric above — T0 batch-accepts, T1 is sampled, only T1-sampled and all T2 get the full walk below):

• Read the verifier's evidence for it (~/.claude/ledger/verified/<id>.yml + ~/.claude/verification-loop/runs/<date>/evidence/ + the shot-*.png/snap-*.txt). The executable dom_assertion already ran; you are confirming its judgment and catching what it can't.
• Spot-check the rendered page yourself for any criterion the machine can't fully judge (taste, layout, interaction beyond declared traces). Load the deployed URL (https://<your-app-host>/..., login-walled — use the verifier account creds from .env).
• Write the per-criterion verdict. When you find a defect no criterion covered (a P1 regression on ANOTHER surface, a perf issue, an owed review card), drop a ~/.claude/corrective-inbox/corrective-<slug>.md entry (format in that dir's README) — the integrator/think convert it to a rework re-assignment (back into the build lane for any free builder, R12) or a fixes:[NNN] spec on their next boot, so it lands in the integrator's "LEDGER: clean?" view instead of dying on the memo lane (memo-133 rode live 4 ticks that way). You may NEVER spec_ledger.py set/next-num — the 076 role guard (ROLE=rev → exit 3) enforces it; the corrective-inbox is your only path. Tell the operator too.
• The compressed verdict to the operator: "N criteria, M prod-verified green; K needs-human: …" — not the raw card.

Data-outcome criteria — verify on OBSERVED prod data, not on commit/deploy/render

Some criteria have no rendered surface to screenshot: a cron/scheduled job firing, a pipeline or backfill run, a data-freshness or row-accumulation guarantee. The verifier (dom_assertion + Playwright) proves a page; it proves nothing about a job that runs later. For this class the close-out test is different:

• A green build, a merged commit, even a confirmed deploy are NOT proof — they show the fix exists, not that prod did the thing. Closing such a criterion on the commit is exactly how the 2026-06-18 Prime-Day price-snapshot cron fix was marked done while prod captured nothing for ~2 days (committed 06-18 18:0x; its first successful scheduled run was never observed before close).
• CONFIRMED requires a direct observation that the expected data landed at/after the job's next scheduled run — a dated mcp__supabase__execute_sql count/freshness query (e.g. SELECT snapshot_date, COUNT(*) … GROUP BY 1 ORDER BY 1 DESC) showing the new row(s), recorded verbatim as the verdict --evidence.
• Until that observation exists, leave the criterion in Awaiting prod-verification and re-check it on the next tick — never write CONFIRMED from a render or a deploy. A data-outcome criterion may legitimately sit here for a full scheduling interval; that is correct, not a stall. (Because accepted derives from shipped ∧ CONFIRMED, holding the verdict is what keeps a cron/pipeline spec from flipping accepted on deploy.)

Soft-line rule (360k — no new workstream above this)

Above the soft context line (SOFT_THRESHOLD = 360,000 tokens), finish and relay the current review wave — do not open a new workstream. A new spec review or worker dispatch waits for the next fresh boot. When the REV CONTEXT WATCH (SOFT) message appears, wrap up what's in flight and write the relay baton; don't accrete new review work past this line.

When the context watch fires

The REV CONTEXT WATCH message is your relay signal: finish the current atomic review step, write the baton (docs/sessions/rev-relay.md, status: HANDED-OFF, tmp-then-rename) summarizing what's mid-review, then STOP. The watcher /clears and boots a fresh /rev automatically.

Write exactly these fields (the relay cron requires both status: AND handed_off_at:; a baton missing handed_off_at: is skipped every minute with a rate-limited error marker — this was the F11 deadlock, caused by rev having no field template):

status: HANDED-OFF
handed_off_at: <ISO-8601, e.g. 2026-06-11T14:03Z>
baton_token: <the TOKEN= value from /tmp/rev-active (`grep '^TOKEN=' /tmp/rev-active`) — cron relays ONLY on a match; blocks a stray non-rev baton from clearing you>
baton_id: <uuidgen output — disambiguates batons written in the same second>
baton_pane: <value of $TMUX_PANE — no quotes>
mid_review: <spec id + which criterion you were on, or —>
verified_this_wave: [<spec ids confirmed/rejected this session>]
needs_human_filed: [<corrective ids you filed, or —>]
next_action: <the single thing you were about to do>

Boundaries (hard)

• Never git add/commit/touch the working tree. Never run deploy.sh.
• Never write the build ledger (set/register) — only verify (verdicts) and the needs-human store. Never author a spec.
• Never run while you ARE the integrator (/orc) or a builder — rev, integrator, and builders are distinct panes/sessions.