/act (bro)
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) |
bro review act dismiss [PR] [--dry-run] [--message T] |
Dismiss stale veto reviews — standing CHANGES_REQUESTED reviews with ≥1 referenced thread, all resolved+outdated; a live veto (including a body-only one with zero thread refs) is refused by construction (re-review is the reviewer's call). The review body prints before mutating — a body-level objection is invisible to the thread rule, so read it before confirming the dismissal. --dry-run lists candidates; --message overrides the dismissal note |
bro plan run act.toml |
Batch-apply thread verdicts ([[threads]] resolve/reply/defer) from a validated plan — the authoring schema is schemas/plans/act.schema.json; bro plan describe act prints it (the example as a TOML template) |
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. Static scanners are never advisory — SAST-named checks (codacy, codescene, sonar, codeql, deepsource, …) gate unconditionally: a failed job or an error-level annotation is a real project finding, not reviewer flake, soact.ignoreChecksdoes not shield them and aneutralconclusion still gets its annotations inspected. An ignored-but-failing SAST check still gets its check output read (gh api repos/<r>/check-runs/<id>→.output.summary) before any classification — scanners post verdicts there, never in threads, so "no thread activity" says nothing about whether the tool is down; a named failing condition (duplication %, coverage) is a real finding to fix or debt-bead, not flake. A check you don't recognize is a fact to fetch —gh api check-runsfor the run +git log --followon the workflow file — not a thing to name; anin_progressgate-style check is waiting on the gate, which IS the verdict, not a stall. 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. - Every finding gets a prevention retro, not just a verdict. Code is
agent-written by default, so before fixing ask: "what code shape would
have made this finding class impossible to write?" — then fix to THAT
shape, not to silence the site. Dynamic fs paths → one guarded io
module all calls funnel through;
new RegExpon configured values → a dedicated matcher;obj[key]writes → entries/Object.fromEntries; computed-key reads →Object.getOwnPropertyDescriptor. For a true false positive the fix lives at the rule level — a documented exclusion in.codacy.yml, a.markdownlint.jsonoption — so the same false never reappears in any file, never a one-site suppression. A recurring pattern belongs in AGENTS.md or the relevant skill so the next code is born clean. - Exhaust findings locally before pushing. A push that flies blind on
what remote engines will say is the wave generator — each push
re-triggers reviewers whose next annotations were already computable.
Before any fix-round push, run the local engine parity sweep over every
file in the diff (the transient eslint-plugin-security +
no-non-null-assertion setup, plus tsc; see the check-sast bead for the
repo command), not just the flagged files. Zero local findings is the
bar for "this round is done"; remote annotations landing afterward are
either genuinely new or stale-DB reposts, and the sweep is how you tell
which.
Same sweep, artifact class: before editing any file, grep its basename
across
scripts/andpackage.jsonfor a generator or freshness gate (check:*,gen:*). Generated outputs — schemas, lockfiles, committed dist — get their change at the source and a regeneration; a hand-edit is a guaranteed red freshness check. 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 standing
CHANGES_REQUESTEDvetoes the merge even atopen_threads=0. GitHub'sreviewDecisionis a third gate axis beside threads and checks — every thread resolved does not clear a reviewer's veto.bro review act statusnames the standing reviews and marks each stale (at least one thread it references exists and every one is resolved and outdated — nothing live it could still be talking about) or live. A veto with zero referenced threads — a body-only objection — reads live: no thread anchor is not proof the ask went stale, and dismissal is destructive-leaning. Thread refs only cover inline objections — the review body can carry an independent ask the rule can't see, soact statusprints a body excerpt under each veto andact dismissre-reads staleness immediately before mutating (a veto that went live mid-command is skipped, never cleared off a stale snapshot). Stale vetoes are cleared bybro review act dismiss [PR]— read the printed body first: if it may carry its own objection, that dismissal is your call, not the tool's. Live ones wait for the reviewer's re-review — never dismiss a live veto to unblock a merge (the command refuses by construction, so if it refuses, that IS the answer). - 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. Arming is not done at spawn: runbro review act statusand confirmwatch=names the live watch before reporting — a detached watcher can die between spawn and your reply, and "armed" without the status line is a claim, not a fact. 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.