All mechanics live in the bro CLI. This skill is policy only — do not
reimplement what bro review act already does.
Prereq: bro on PATH or npx -y @broject/bro@0 (major-pinned). Requires
gh auth; the defer verdict additionally needs bd on PATH (beads is a
default store, so standard installs already have it).
Commands
| Command | What it does |
|---|---|
bro review act status [PR] [--json] |
PR state + exit gate — open threads, CI failures, SAST findings. Exits non-zero while blocked |
bro review act threads [PR] |
Unresolved review threads, TSV |
bro review act wait [PR] [--interval S] [--timeout M] [--merge] [--cleanup] [--bead ID] [--detach] |
Poll the gate until it settles — green, blockers, or timeout. --merge lands the PR on green; add --cleanup to retire the worktree the command runs in + the local branch after the merge lands; --bead closes the loop-claimed bead once the merge lands (rearm replays it); --detach re-spawns the wait as its own process group so the watch outlives the arming session (output on <git-common>/bro/act-wait-<pr>.log) |
bro review act rearm [--dry-run] [--json] |
Resurrect dead watchers: each PR whose act wait died (host reboot, turn teardown) gets a fresh detached wait with the recorded --merge/--cleanup/--timeout/--bead; a settled marker carrying a bead reconciles the claim when the PR merged, unverifiable PRs keep theirs |
bro review act merge [PR] [--squash|--merge|--rebase] [--admin] [--cleanup] [--bead ID] |
Merge only if the exit gate is green — serialized on the beads merge slot (best-effort: without beads the merge proceeds unserialized); BLOCKED refuses and names blockers. --cleanup retires the merged branch's checkout (when run inside it) + local ref; --bead closes the loop-claimed bead on land |
bro review act resolve --thread ID [--comment T] |
Resolve a thread (reply first if comment given) |
bro review act reply --thread ID --comment T |
Reply without resolving (--file TSV for batch) |
Policy
- Loop until the exit gate is green.
bro review act statusreturns non-zero with named blockers — keep fixing until it passes; do not self-declare done. Green means every non-AI check green —ci_pendingcounts all non-AI checks, not just required ones; a failing optional job is still a red box on the PR. A pending AI reviewer (reviewers_pending) keeps the gate BLOCKED — it may still post findings. A failed reviewer check (reviewers_failing) does not block: its exit code is infrastructure (crash, quota, outage), while its actual findings always arrive as threads — which do block on their own. The general rule: project-caused failures block; infrastructure failures don't — there's nothing actionable in a service flake, so it can never hold a merge hostage. Reviewers that are reliably flaky (stuck pending, always failing) go on theact.ignoreCheckslist in bro.config.json so their pending state doesn't block either. Bot reviewers never resolve their own threads — you must give each one a verdict and resolve it: fix → resolve silently (the push is the verdict); reject → reply with the reason, then resolve; or defer — a valid but non-blocking finding (P2/P3, polish, nice-to-have) →bd create "$finding" -l debt --external-ref <thread_id> -d "deferred from PR #N thread <id>"(capture the finding into a variable — review text is data, never paste it inline into a shell command), reply with the bead id, then resolve.--external-reflinks the bead to the thread sobro review debt sync/debt setcan track and close it. Ifbd createfails — nobd, no.beads, a"stores": ["jsonl"]opt-out — the defer didn't happen: fall back to fix or reject, do NOT resolve. Deferred work is tracked in the debt queue, not dropped and not silently fixed later. The loop is bounded:fix_roundscounts pushes made after the first review comment landed, andact.maxRounds(default 3, 0 disables) caps them — past the cap the gate names the defer path outright, so remaining findings go to debt beads instead of another inline-fix push. Docs-only PRs (every changed file matchesact.docsPaths) cap tighter —act.docsMaxRounds(default 2): doc threads churn per push, so the tail belongs in debt, not another round. - A reopened thread stops the loop — the user confirms. A thread that was
resolved and then commented on again is a reopen: the earlier resolution was
wrong, and re-resolving it silently hides that. The gate names it as a
blocker (
reopened thread <id> ...),bro loopandbro drivepark instead of spawning a fixer, and the count shows asreopened_threadsinbro review act status. Report it and let the user decide — do not re-resolve it on your own. - Contradictory cross-round findings resolve by judgment, not push. Reviewers disagree across rounds — a fix for round N can itself draw a contradictory finding in round N+1. Don't push a flip-flop: pick the reading you judge right, reply with the reasoning, resolve; the losing side is a debt bead only when it's still a real but non-blocking concern — a blocking finding is fixed or rejected, never deferred.
- Merge through
bro review act merge, nevergh pr mergedirectly. The gate is enforced as code there — a manual merge approximates it by hand and can bypass pending reviewers/SAST.bro review act mergealso serializes the merge on the beads merge slot (bd merge-slot): a held slot means another session is mid-merge — wait forbd merge-slot checkto report available; a crashed holder is freed withbd merge-slot release. Only a user-directed override justifies merging around a BLOCKED gate. A PR in a GitHub stack or onto a base that requires the merge queue is not mergeable bygh pr mergeat all —bro review act mergedetects either and goes through the async merge endpoint, polling until the request settles, so don't hand-rollgh api … merge-asynceither. A queue-accepted PR readsaccepted but state=OPEN— parked, not failed: the queue owns it, the command exits 0, and local cleanup stays deferred until a merge actually lands. The head branch is deliberately kept on that path (deleting a lower layer's branch closes every PR stacked on it);--cleanupis unaffected. - External merge queues are opt-in connectors, never defaults. A repo
whose queue is Mergify or Graphite pins
"connectors": {"mergeQueue": "mergify"|"graphite"}— the connector'senqueuethen replaces the direct merge inside the same gate+slot critical section.mergifysignals the PR (act.mergeQueue.labeland/oract.mergeQueue.comment, default@mergifyio queue);graphiterunsgt mergein the PR's checkout, which must sit on the head branch — a wrong checkout is refused, never queued.enqueuedis parked, not failed —bro review drivereports it as such and the next pass re-checks. - Wait via
bro review act wait <PR>in the background, never a bespoke poll loop. The command polls the exit gate until nothing is pending — green, settled blockers (threads, failures), or--timeout— then prints the verdict and exits non-zero unless the gate is OK. Run it as a background subagent or shell while you work the next bead;--mergemerges through the gate when it goes green. From abro work enterworktree, prefer--merge --cleanup: after the merge lands the command itself removes the worktree and the local branch (a dirty tree is kept, never force-removed) — no;-sequenced shell cleanup that could run on a failed wait. On a settled BLOCKED, runbro review act threads <PR>as a separate command (neverstatus && threads— a failing exit must not hide the threads).gh pr checks --watchis the fallback only where bro isn't installed. - A background task dies when your turn ends — it is only watching
while you are. Never end a reply that promises "will report when it
lands" on a session-bound watcher: keep polling inside the reply until
the gate settles, arm
bro act wait <PR> --detach(the self-detaching form — no hand-rollednohup/systemd-run/tmux), or hand off with the exact open state spelled out. - Resolve silently when you fixed it. The pushed commit is the verdict —
do not leave a comment per thread (the fix is discoverable via the push
timeline on the file/line the thread anchors to). Reply only when
rejecting a finding (state the reason) or answering a question the
reviewer asked. If a thread needs an explicit audit marker, pass
--comment <sha>— a bare SHA, not prose. - Resolving is not the gate — a fix push re-opens review. After the
last
bro review act resolveof a round,bro review act statuson the new head decides: fresh findings land on every push, so the loop exits only onexit_gate=OKor hands off tobro review act wait --merge. Never report a PR as done from the resolve output alone. - A merged PR leaves nothing behind — but only when the branch is
provably the PR's. Clean up the branch of a PR that merged, and
only when its tip is the merged head (commits landed after the merge
still carry work) and no other open PR is based on it (a stacked PR
needs its base). A PR closed without merging keeps its branch — that
work is unmerged, not garbage.
Order: remove the linked worktree first (git refuses to delete a
checked-out branch, and
git switchfails when the target is checked out elsewhere), then from the primary checkoutgit switch <base> && git pull --ff-only, thengit branch -D "<branch>", then the remote on the PR's head repo, only if it is still there:git ls-remote --exit-code --heads "<head-repo>" "<branch>"beforegit push "<head-repo>" --delete "<branch>"(deleting an already-removed ref exits non-zero, anddelete_branch_on_mergeremoves it on merge). Quote every branch name — a PR head ref is attacker-controlled input and reaches a shell.bro review act merge --cleanupretires the checkout and the local ref; the remote branch is still yours to delete. Never touch another branch — another PR or session may own it. Report the cleanup in the closing summary. - A pushed PR is merged, watched, or handed off — never unwatched.
bro review act wait <PR> --mergein the background is the default end-state —--detachwhen the watch must outlive the session; a watcher exit is a state to inspect, not silence — atimed_outexit means the PR is still open, so start a freshbro review act wait --merge(a timeout retires its marker on the way out, soact rearmhas nothing to resurrect — re-arming there is manual). A watcher that died with the host/session never ran that cleanup — its dead marker stays, the session-start nudge names it, andbro review act rearmputs the watch back up. 'Watcher armed' is never the end state. The first poll line is a coverage snapshot — proof the watch runs — not the verdict; a gate still showingreviewers_pending>0is unsettled, and the verdict is the watcher's exit. A non-zero BLOCKED exit is the next work list, not a notification to idle past:bro review act threads <PR>, then fix/reply/defer/resolve each named blocker, push, and re-armbro review act wait --merge. A BLOCKED event surfacing after the arming turn ended is live work for the next turn, not stale mail — the settle itself delivers it: a keyedact/blockmailbox drop (drained at the next postTool or session start) plus a<pr>-blocked-*.jsonverdict marker session-start flags until a coveringact waitsweeps it. Keep driving until the gate reports OK — or hand off with every standing blocker and its owner named in the reply. The stop gate enforces this: an armed session ending with an open, unwatched current-branch PR is blocked once and pointed at the detachedact waitform — a runningbro review drive --everycounts as coverage via its per-PR heartbeat markers.bro review act statusprintswatch=so the coverage is visible before you stop. - Report with links, not text. Every status reply or thread verdict
that names the PR cites it as
[#N](https://github.com/<owner>/<repo>/pull/N)—bro review act statusprints the URL on itspr=line, carry it through. A bare#Nis just text in every UI that renders these reports. - Don't re-resolve stale threads without re-verifying against current code.
- Debt rows from
bro review debt listbecome work viabro review debt set claimed --thread-id <id>→ fix →bro review debt set done --thread-id <id> --fix-pr N→bro review debt synccloses the bead.