# Pr Sweep > Batch-review every open GitHub PR and drive it to a terminal state autonomously — fan out a clean-context pr-review per PR (verify claims against live code, obtain a current verification fact through the gate entrypoint), cluster PRs by shared issue + shared files, DEDUP-CLOSE same-issue duplicates (keep the best one, comment + close the twin), and GATED auto-merge every verified non-breaking PR (docs/tests/fixes AND features) while escalating only security / breaking changes / architecture-direction decisions to a human. Independent reviews remain separate; a shared broker prevents duplicate gate executions only for an exact evidence identity. Designed to run on a schedule on an independent machine so PRs get reviewed + merged without a human in the loop. Run /agentloop:pr-sweep (review+comment+dedup-close only), /agentloop:pr-sweep --merge (also auto-merge gated PRs), or /agentloop:pr-sweep --dry-run (report only). - Skill: `arcblock/pr-sweep` (Agent Skill) - Install (CLI): `npx skillmds@latest add arcblock/pr-sweep` - Raw SKILL.md: https://api.skillmd.com/api/skills/arcblock/pr-sweep/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: ArcBlock (https://skillmd.com/u/arcblock) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/arcblock/pr-sweep --- # PR Sweep — batch-review + dedup-close + gated auto-merge > **Repo profile — read `.claude/repo-profile.md` first.** This skill is repo-agnostic; > **arc is the reference implementation.** Use the profile's values wherever this doc shows an > arc default: `repo_slug` (the `gh -R` target), `gate_mode` (arc = `scripts`: no CI on PRs, > so `gh pr checks` is empty and `pre-merge` is the only gate; `ci`/`both` > repos ALSO require `gh pr checks` green), `verification_entry` / `pre_merge_entry`. > Arc's own provenance for the lessons below is not inlined here (fuller case narratives, where they exist, are under `.claude/case-law/`). A **batch driver** over [`pr-review`](../pr-review/SKILL.md). `pr-review` handles ONE PR (read → verify against code → run verification gate → detect conflicts → verdict). `pr-sweep` runs that engine across **all open PRs**, then does the two things a single-PR engine can't: **resolve cross-PR duplicate/conflict clusters** (keep one, comment + close the rest) and **gated auto-merge** the clean ones. This is the thing a cron schedules: one run = sync + review-all + dedup-close + (optionally) merge. It is the PR-world twin of [`issue-sweep`](../issue-sweep/SKILL.md); together they let an independent machine keep both issues and PRs moving with no human in the loop — escalating only the genuinely human-only decisions. > **输出语言按 profile `comment_language`。** 所有面向团队的产出——verdict comment、去重/关闭说明、升级给人的「需人确认块」、 > 本 sweep 自己开的 PR(verification-fix 等)的**描述正文**——按 body 语言写;代码标识符、路径、 > 命令、`path:line`、`gh` 输出保持原样。**PR 与 commit 标题**按 `comment_language` 的标题语言部分, > 不得混用。 > **不堆砌**:先一句话结论,再最少但足够的证据(文档 / 代码 `path:line` / 真实测试输出,**UI 相关 > 必附截图**——ui-verify 的截图/录屏就是这类证据);长日志折叠进 `
`。 > **目标(为什么存在):** 让"定时机器"把 PR 从开放推进到终态——review、去重、合并—— > **尽量不需要人 review**。PR 上已无 CI,门控是 `pre-merge` verification > 脚本;失败看根因,门控/脚本坏了就修脚本。人只在不可逆的高风险拍板点介入。 ## Usage ``` /agentloop:pr-sweep # 全量 review + 评论 + 去重关闭(不自动 merge) /agentloop:pr-sweep --merge # 以上 + 对通过「合并闸」的低风险 PR 自动 merge /agentloop:pr-sweep --dry-run # 只报告 WOULD-DO,不发 comment / 不关 / 不合 /agentloop:pr-sweep # 限定到指定 PR ``` `--dry-run` 语义与所有 loop skill 一致 —— 见插件 README 的 **Dry-run contract**。 Repo 是 ``。本地有 `gh` CLI 时直接用;无则用 `mcp__github__*`,ToolSearch 加载。 ## Step 0 — 先 sync 本地 ``(不可跳过) 下游一切——`git grep` 安全检查、`check-types`、`gh pr diff` 对照、每个 rebase——都必须跑在**最新 ``**(全篇「main」指 ``;部分仓库用 `master`)上,不是容器碰巧 clone 的陈旧树。上一轮 sweep 可能已 merge 了 PR、移动了 ``。 当作**朴素命令**逐条跑、读结果——**你就是控制流**,别包成 shell 循环/条件/`$(…)`(沙箱的 Bash guard 会拒,这一步会在 sweep 开始前就硬失败——实盘踩过)。 ```bash git fetch origin # 偶发失败就再跑一次(你自己就是重试循环) git reset --hard origin/ git log --oneline -1 # 确认在真正的 tip ``` **别用 `git checkout `**:在 git worktree(如 fleet checkout)里该分支被 主 worktree 占着,checkout 必失败;上面的 fetch + reset 在分支上或 detached 都能用。 工作树有上一轮残留 → `git reset --hard` + `git clean -fd`。一次 sweep 从干净、最新的树开始。 ## Step 1 — 枚举所有开放 PR + 元数据 ```bash gh pr list --state open --limit 100 \ --json number,title,author,headRefName,baseRefName,mergeable,files,labels,body,createdAt,updatedAt,isDraft ``` > **`updatedAt` 不是可选字段**——Step 1.5 的**冻结集**完全靠它判定,而且靠的就是**这一次**调用 > 的结果(整个机制的意义就是不为「要不要跳过」再花 per-PR 的 API)。漏掉它,冻结集要么失效、 > 要么退化成每个 PR 多三次调用,那正是它要消灭的开销。 > 门控形态由 profile `gate_mode` 决定:arc = `scripts`(删了 `ci.yml`/`pr-title.yml`,`gh pr checks` 恒为空,`pre-merge` 脚本是唯一门控);`ci`/`both` 的 repo 还要 `gh pr checks` 绿—— > 门控信号来自 Step 3 扇出的 `pre-merge` verification,不再从 status check 读红绿。 ## Step 1.5 — 轮次感知:只处理"有新输入/新可执行"的 PR(定时 routine 的命脉) **最先:识别带 `agent:hold` 的 PR(人类保留)并给它套「终态冻结」。** Step 1 枚举时 `--json` 已带 `labels`,每个 PR 的 labels 已在手。**`agent:hold` 冻结的是不可逆终态动作,不是冻结处理**——人打这个 label 通常意味着"这个 PR 的去留我拍板,没我反馈之前别合",而不是"别理它": - **hold 期间绝对禁止**:merge、close(含去重关闭)、摘 label——直到人摘掉 `agent:hold`。 - **hold 期间照常做**(轮次感知规则同 non-hold PR):**有人类新评论(在最后一条 agent 评论之后)或新 commit → 仍然 review + 响应**——读人类反馈、回 comment、按人类**明确给出的修改要求**在 PR 分支干活(修完 push + 重跑 `pre-merge`,verdict 标注 `held: 等人摘 label 后才可合`)。**无新输入 → 跳过**(和普通已 review PR 一样,不重复刷结论)。 **反例(hold≠别碰):** sweep 曾因 hold 完全跳过人类明确的修改要求,把「hold=别合」错读成「hold=别碰」。人类在 hold PR 上的新评论**恰恰是最高优先级的输入**(人专门来说话了),必须响应。 `agent:hold` 是 issue/PR 通用的「人类保留」(GitHub label 仓库级共享);它与处理中互斥锁正交,PR 侧**不**引入 `agent:processing`(并发去重靠确定性分支 + 认领检查 + disposition label)。 **在 `agent:hold` 之前,先识别并整条排除带 `epic-managed` 的 PR。** 它属于一个 **epic-conductor 独占驱动**的 epic(见 [`epic-conductor`](../epic-conductor/SKILL.md)):那个 conductor 会派自己的 clean-context reviewer、routes findings、跑 merge-gate、自己合并并解锁下一波。sweep **完全不碰**——不 review、不评论、不去重关闭、不合并(即使 verdict 会是 MERGE、即使风险档 🟢)。区别于 `agent:hold`(冻结终态但仍响应人类评论):`epic-managed` 连 review/评论都不做,因为那是 conductor 的职责,sweep 插手会与它的 in-flight worker/reviewer 撞车。epic PR 通常同时带 `agent:hold` 作双保险,但 `epic-managed` 是那条更强、更干净的排除键(一条规则管所有 epic)。**过滤某 epic 的全部 PR**:`gh pr list --label "epic:<父issue#>"`。 **不做这一步,每小时会把同一批"已 review、没人回、又自动合不了"的 PR 重新起 agent + 重复刷 comment——烧 token、刷屏、可能 race。** 规则:**默认信任上一轮结论,只在「有新输入」或「外部阻塞已解除」时才动手。** 这是 [`issue-review`](../issue-review/SKILL.md) "轮次感知"在 PR 侧的对偶。 **先用 gh 元数据廉价分流(不起 agent)。** agent 评论 = 带**机器标记**(sweep-trace / `Generated by [Claude Code]` footer / 作者是 Bot);其余 = 人类(见下方 needsReview 代码块)。**不按 `> 🤖` 头判**——`` 给人和 agent 生成同样的头,人手贴的评论会被误判成 agent 裁决而跳过(实盘 arc#1722 跳了 19h)。presence `> 📡` 心跳是唯一按首行认的例外。给每个**未终结**的 PR 打一个受控 disposition label,下一轮靠它分流: | disposition label | 含义 | 下一轮动作 | |---|---|---| | (无 / 已合 / 已关) | 上轮已终结 | 已不在 open 列表,自然跳过 | | `pr-sweep:needs-fix` | BLOCK,但**修复路线已明确**(review 或人给了确切路径) | **agent 拥有 → 接着修**:在 PR 分支实现那条路线 → 跑绿 → **过 Step 5 合并闸再定合不合**(风险档重算;路线来自人类修改要求的要回人批准)。这是「有明确的活要 agent 干」,**不是等人**(见 Step 5「PR 即工作单元」)。**最多连续 3 轮**(见下方「修复轮次上限」);第 3 轮跑完仍不绿 → 改打 `pr-sweep:awaiting-direction`,不再自动发起第 4 轮 | | `pr-sweep:awaiting-glance` 🟢淡绿 | **看一眼即合**:AI 已全部验证(verification 绿 + 声明核验),UI 面已附对当前 HEAD 的截图,人只需视觉/常识确认一下 | 等人类**明确批准语** → 过 Step 5 通用前置直接合。这是人类负担最轻的一档;comment 里给出「看什么 + 哪张图 + 一句话确认即可」。**AI 侧无未尽事项才准打此标**——证据不全(截图缺/过期)= 还是 `needs-fix`,不是 glance | | `pr-sweep:awaiting-direction` 🔵蓝 | **等方向拍板**:AI 困惑或面临 A/B 选择,需要人给**高层方向**(产品意图、架构取向、范围裁剪)——**不是底层细节**(细节该 AI 自己啃或归 needs-fix) | 等人类新评论。comment 必须把问题抬升到人该管的高度:选项 + 各自后果 + AI 推荐 + 什么证据能 settle;绝不让人替 AI 读代码 | | `pr-sweep:awaiting-judgment` 🟡黄 | **风险拿不准**:AI 感知到潜在风险(语义边界、回退面、影响面)但没把握自决,请人判"这个风险真不真、可不可接受" | 等人类新评论。verdict 里**写明拿不准的具体是什么**(不是"是 feature 所以升级");人判"无风险/可接受"= 批准语 → 可合 | | `pr-sweep:awaiting-caution` 🔴深红 | **制度性审慎**:security 面 / breaking change / 不可逆操作 / 改 verification 门控语义——即 Step 5 的 🔴 档,无论 AI 多有把握都必须人批 | 等人类**明确批准语**;comment **必带 pr-review「需人确认块」**(security 逐条列安全属性 + 验证命令)。红色只保留给这一档——它才配"紧急/危险"的视觉信号 | | `pr-sweep:awaiting-human`(旧,弃用) | 未分档的存量升级 | **迁移**:读最后一条 verdict 的升级理由重分档——纯等确认→glance;方向题→direction;风险疑虑→judgment;security/breaking→caution;理由已不在现行 🔴 表(如仅因"是 feature")或其实有明确的活→按 needsReview 重审/转 `needs-fix`。换标后删旧标,**不再新打此标** | > **awaiting-\* 四档的共同语义**:真·等人输入,agent 本轮 0 动作(直到新 commit 或人类新评论);区别只在**要人付出什么**——glance 是 10 秒确认,direction 是一个方向决定,judgment 是一次风险评估,caution 是一次制度性审查。**打标时按人的负担从轻到重就低不就高**;这一族都只放"等人",不放"有明确的活"(那是 `needs-fix`)。**人类新评论解锁的是「处理」,不是「合并」**(下一条)。 > **★ 修改要求 ≠ 合并批准(铁律)。** `awaiting-*` / 🔴 档 PR 上人类的新评论要**分两类读**: > - **明确批准语**("LGTM" / "可以合" / "approve" / "merge it")→ 解锁合并(仍要过 Step 5 通用前置)。 > - **修改要求**(其余一切:改样式、补功能、换实现——哪怕修法完全明确)→ 只解锁「干活」:agent 在 PR 分支实现 → push → **贴证据(UI 面必附对新 HEAD 的 before/after 截图)** + 重跑 `pre-merge` → **置 `pr-sweep:awaiting-glance`(证据已备齐,人看一眼确认),comment 里@人请其确认**——**绝不因"要求已满足"自行合并**。人提修改要求 = 人在 review 这个 PR = 人要看到改后的样子再拍板(人提修改要求后 agent 未等确认就直接 merge)。 | `pr-sweep:blocked-deps` | 仅因**无关 dependent 包**在 `` 上红而被挡(PR 代码已核验) | **不重 review**;只跑 Step 5 廉价 gate 重查,绿了就合(不新发评论)。dependent 修好它自动落地 | **修复轮次上限(Bounded repair,issue #1204,人类拍板:"自动修复的时候每次最多不超过3轮,也就是三轮依然不行,那么报告现状,请人类给出输入和方向"):** `pr-sweep:needs-fix` 不是无界重试——`needs-fix` 状态下每次 full-review 起 agent 修复都算一轮,连续 3 轮仍不能跑绿(或跑绿但过不了合并闸)就必须停手升级给人,不许第 4 次重试烧 token。 - **计数载体**:轮次计数嵌在 verdict comment 里,与 `sweep-trace` 标记同段,不新开存储:``(`N` = 本轮是第几次修复尝试)。起 agent 前先读最后一条 `🤖 AI Agent PR Review` 评论里的这个标记;没有该标记 = 这是第 1 轮修复(`N=1`)。 - **递增时机**:每次因 `needs-fix` 起 agent 修复并 push 新 commit,新 verdict comment 的 `N` = 上一条 `N + 1`。只读 verdict 重查(廉价 gate、无新代码改动)不计入轮次。 - **重置时机**:第 3 轮升级为 `pr-sweep:awaiting-direction` 之后,人类给出新方向的评论(不是简单"继续"式追问)视为新一轮修复的起点,`N` 从 1 重新计数——旧的 3 次是对旧方向的穷尽,不该沿用到新方向上。 - **第 3 轮仍不绿的升级动作**:改打 `pr-sweep:awaiting-direction`(现有非弃用档位里最贴合"agent 卡住、需要人给方向"的一档,不新造 label),verdict comment 需包含每轮尝试摘要,格式: ``` ## 修复上限已达(3/3 轮),需要人类给方向 - 第 1 轮():尝试了 X,失败原因 Y - 第 2 轮():尝试了 X',失败原因 Y' - 第 3 轮():尝试了 X'',失败原因 Y'' **agent 判断仍缺**:Z(需要人类决定/提供) ``` - **不适用**:因外部依赖(`pr-sweep:blocked-deps`)红而 BLOCK 的不计入轮次(那是等 dependent 修好,不是 agent 自己反复失败)。 **判定"需要重新 full review"(起 agent)—— 满足任一:** > **⛔ 顺序硬性:先剔除[冻结集](#-冻结集久无人动的-awaiting--连判断要不要跳过都不该花钱2026-08-20), > 剩下的 PR 才跑下面这段。** 下面的 needsReview 判定要为**每个** PR 取三个评论面(3 次 API); > 冻结集的整个意义就是让长期无人动的 `awaiting-*` PR **连这三次都不花**。顺序反了 = 钱已经花完 > 了才想起来跳过,冻结集等于没有。 1. 从没 review 过(无 agent 评论 —— 按下方谓词判,不是按某个字面前缀);或 2. **head commit 时间 > 最后一条 agent 评论时间**(代码改了 → 旧结论作废,重判);或 3. 最后一条 agent 评论**之后有人类评论**(新反馈 → 进 resolve 阶段);或 4. **最后一次 Draft → Ready 事件时间 > 最后一条 agent 评论时间**(#1831 盲区二:转 ready 既不动 head 也不产生评论,纯时间戳/sha 比对永远看不见——作者标 ready 就是"请 review"信号)。 ```bash # 每个 PR:head commit vs 最后 agent 评论 vs 最后 human 评论 vs 最后 ready_for_review 事件 # ⚠️ 人类意见散在三个面:①会话 comment ②代码行 inline review comment(pulls/comments) # ③review 总评(pulls/reviews)。只查 --json comments 会漏 ②③,人类 inline 修改要求会看不见。 # 必须三面并集: head=$(gh pr view --json commits --jq '.commits|last|.committedDate') all=$( gh api repos/{owner}/{repo}/issues//comments --paginate --jq '.[]|{t:.created_at, body, bot:(.user.type=="Bot"), login:.user.login}' gh api repos/{owner}/{repo}/pulls//comments --paginate --jq '.[]|{t:.created_at, body, bot:(.user.type=="Bot"), login:.user.login}' gh api repos/{owner}/{repo}/pulls//reviews --paginate --jq '.[]|select(.body!="")|{t:.submitted_at, body, bot:(.user.type=="Bot"), login:.user.login}' ) # 「是 agent 评论」= 带**机器标记**,human = 它的否定。判据不是 `🤖` 头: # 给**人和 agent 生成同样的** `> 🤖 AI Agent @host·runner:…·skills@…` 头, # 人手贴的评论逐字节相同 —— 按头判会把人类指令当成 agent 裁决跳过(实盘 arc#1722 跳了 19h)。 # 机器标记(可靠、人不会手写):① sweep-trace HTML 注释(本 skill 每条 verdict 强制附,见文末); # ② `Generated by [Claude Code]` footer;③ 作者是 Bot(云端 runner 走 GitHub App → claude[bot])。 # 例外:presence board 的 `> 📡` 心跳脚本发的、不带 trace,靠首行 `📡` 认(否则每轮重刷 board)。 # 标记可能 HTML 转义(`<!-- … -->`,#1278),先 decode。老的无标记评论按人类处理(新规范)。 # # ★ Codex / bot-review connector 是第三类时间戳(既不是 hu 也不是「可忽略的 bot 噪声」): # 若把 chatgpt-codex-connector 全算进 isAgent,Codex 在 verdict 之后的 P1 永远不触发 needsReview, # epic/普通 PR 都会「全绿却挂着未处理 bot finding」。单独取 codex 时间;codex > ai → needsReview。 # 它们仍不是人类:不触发「修改要求 → awaiting-glance」那条铁律,只触发「读 finding → needs-fix」。 JQ=' def dec: gsub("<";"<") | gsub(">";">"); def firstline: .body | split("\n") | map(select((test("^[ \t\r]*$")|not) and (test("^[ \t]*` 定位 + PATCH,跨 runner 也能刷同一条;`--edit-last` 只覆盖「上一条恰是自己发的」情形)。**绝不在「无新输入」时重发同一结论。** 缺这些 label 就建,只用这套受控词(`pr-sweep:needs-fix` / `pr-sweep:awaiting-glance` / `pr-sweep:awaiting-direction` / `pr-sweep:awaiting-judgment` / `pr-sweep:awaiting-caution` / `pr-sweep:blocked-deps`),别再造变体、**不再新打已弃用的 `pr-sweep:awaiting-human`**。 > **★ 「canonical upsert」覆盖本 skill 发出的每一条 PR 评论,不只 verdict。** disposition / > 复查 / 「新信息」这类 sweep 自己发的说明,同样走 marker 定位 + PATCH 原地更新——**每个 PR 至多 > 一条 agent 评论载体**。实盘漏洞正在这里:verdict 有 upsert 规则、disposition 没有,于是每轮 > 追加一条,一个 PR 攒到 29 条里只有 11 条带 upsert marker。**新发 comment 只允许在「本 PR 还 > 没有任何 agent 评论」时发生。** > > **★ 发评论前的跨 runner 撞车自检(廉价,替代互斥锁)。** PR 侧不引入 `agent:processing`(见 > Step 0),所以 N 个 runner 同一轮可能同时判 needsReview。**投递前重取一次评论**,若已存在 > 同 `gate` 且同 `val` 的 sweep-trace、`sha` 也等于当前 HEAD → 说明别的 runner 刚发过同一结论, > **本轮改为 0 动作**(不新发、不重复 upsert)。这挡不住纳秒级同时写,但能挡住绝大多数「几分钟内 > 三个 runner 各发一条」的实盘形态。 > **只有 Step 1.5 判定 needsReview 的 PR 才进 Step 2 聚类 + Step 3 review。** 其余只走"廉价 gate 重查 + 可合就合"。这把每轮的 agent 起数从「所有 open PR」压到「真正变了的 PR」,routine 长期稳定、不刷屏。 ## Step 2 — 聚类(去重 + 冲突的基础) **两把主键,先算簇,再 review——这样每个 review agent 能带着"它的 peer 是谁"上下文。** 1. **同 issue 簇**(去重关闭的主战场)。从 `headRefName` 抽 issue 号(`claude/--` → ``),并从 body 抽 `Fixes #N` / `Part of #N`。**同一个 `` 的多个开放 PR = 重复嫌疑簇。** ```bash gh pr list --state open --json number,headRefName,body --jq ' .[] | {n:.number, br:.headRefName, issue:(.headRefName|capture("-(?[0-9]+)-")?.i // (.body|capture("(?:Fixes|Part of) #(?[0-9]+)")?.i))}' \ | python3 -c "import json,sys,collections; \ d=[json.loads(l) for l in sys.stdin]; \ m=collections.defaultdict(list); [m[x['issue']].append(x['n']) for x in d if x['issue']]; \ [print('issue #%s -> PRs %s'%(k,v)) for k,v in m.items() if len(v)>1]" ``` 2. **同文件簇**(行级冲突 / 共享配置风险)。算 `file -> [PRs]` 倒排,>1 的即重叠。**排除噪音**:release-please 自动 PR 会触碰每个 `package.json` + `CHANGELOG.md`,这类全局重叠不算冲突,单独识别 release 簇。 把每个 PR 的 peer 列表喂给它的 review agent(Step 3)。 ## Step 3 — 扇出 pr-review(clean context,每 PR 一个) 每个开放 PR 交给 [`pr-review`](../pr-review/SKILL.md) 引擎,**干净上下文、独立判断**,带上它的 peer 簇信息。返回**结构化 verdict**(5 类 + verification 结果 + 冲突结论 + 证据 + 问题件的 comment 草稿)。每个 pr-review 都调用 `pre-merge` 入口并把结果纳入 verdict(PR 上已无 CI)，但 shared broker 只会为同一 **`{HEAD SHA, scenario=pre-merge, resolved base}`** 实跑一次；并发 reviewer 等待/复用同一完整事实。独立代码审查、diff 核验和 verdict 绝不因 gate 复用而跳过；任一身份字段变化立即失效重测。 > **UI 改动的 PR:** pr-review 的 Step 3.5 会在 diff 命中 profile **UI Face Paths**时条件触发 `ui-verify`(该仓库的 companion，见 repo-profile 的 Companion Skills；没有就 stub 或跳过该步)(截图 + 录屏贴回 PR)——**前提是本 routine 环境有跑着的 daemon**。无 daemon 的纯静态 sweep 环境会打 `ui-verify:pending` label + 注明,由带 daemon 的 routine 用下面的 pending 扫描步骤补跑(#1205)——不再只留一行注记就算数,label 让补跑成为确定性闭环而不是靠人翻 verdict 文本发现遗漏。 ### Step 2.5 — `ui-verify:pending` 补跑扫描(仅本 routine 有 daemon 时) **本 routine 环境有跑着的 daemon** 时,在正常 Step 3 review 扇出之前,先扫一遍这个确定性 label 队列,把无 daemon 环境欠下的 ui-verify 补上: ```bash gh api "repos/{owner}/{repo}/issues?state=open&labels=ui-verify:pending&filter=all" \ --jq '.[] | select(.pull_request != null) | .number' ``` 对每个命中的 PR:HEAD 若在打 label 之后又有新 push(重新走 Step 1.5 fresh 判定),仍按新 HEAD 补跑;跑 `/ui-verify --pr `,截图/录屏贴回 PR 后 `gh pr edit --remove-label ui-verify:pending`。**本 routine 没有 daemon → 跳过本步(静默,不是 fail)**,这是"两路环境互补"的另一半:纯静态环境负责发现+标记,daemon 环境负责补跑+摘标。 > **`ui-verify:pending` ≠ `BLOCKED`(issue #3010,术语不能混用)**:`pending` label 表示"daemon/浏览器 > 本身不可用,这轮根本没跑",不产出任何证据 comment;`BLOCKED` 是 sticky 证据 comment 的一个可能 > `result` 值,表示"跑了、截图存在,但没能发布成公开可读的 URL"。两者都不放行合并,但语义不同—— > **pending 的 PR 永远不能被描述成"UI 已验证"或"截图待处理即可合并"**,补跑成功前它就是缺证据。 - **Model:** per-PR review 是**有界任务**(读 1 个 diff + 关联 issue + 核验 + 调用一次 `pre-merge` 入口以取得当前事实 + 可能 1 个测试)→ **Sonnet**。**跨 PR 综合(定簇胜负、判矛盾真伪、合并闸决策)用强模型(Opus)** 在主控做,别下放。成本差 ~5×。 - **并发/编排——按运行环境分两路(这条决定 routine 能不能无人值守):** - **无人值守(cron routine)→ 串行 inline review,绝不调 Workflow。** `Workflow` 工具需要**交互式 opt-in 确认**,且通常不在 routine 的 `allowed_tools` 里 → 它弹一个确认框,routine 里没人点 → **永久挂死**(实测:pr-sweep routine 整夜卡在"请允许 Workflow"上)。所以 routine 里**只用 allowed_tools 内、不弹确认的工具**(`Bash`/`Read`/`Write`/`Edit`/`Glob`/`Grep`/`Skill`),per-PR review 由本 session **逐个 inline 做**(读 diff + 核验 + 判 verdict)。**Step 1.5 轮次感知**已把每轮 PR 压到"真正变了的几个",串行完全够、还更省。 - **交互式(人在场 / 显式 opt-in)→ 可用 Workflow 扇出**加速:`parallel(PRS.map(pr => () => agent(prReviewPrompt(pr), {model:'sonnet', schema: VERDICT_SCHEMA})))`,主控 Opus 综合,可 resume。 - **铁律:任何无人值守运行,绝不调用会弹确认 / 等待用户 / 需 opt-in 的工具(Workflow、AskUserQuestion、EnterPlanMode,以及任何不在 `allowed_tools` 里的工具)——会卡死整条 routine。** 拿不准某工具会不会弹确认 → 当它会,改用 inline / `gh` / `Skill`。需要人拍板 → 问题(选项 + 推荐)作为 comment 挂 `needs-human-confirm` 落到对应 PR/issue,继续下一项。repo hook(`.claude/hooks/deny-interactive-unattended.py`)在无人值守 session 硬 deny 这三个工具兜底——被 deny 就按本条走,不要重试。 - review **read-only**:只分析、只产出 verdict + comment 草稿,**不发 comment、不合、不关**。所有 outward 写在 Step 4–5 统一做(限速可控、决策集中)。 ## Step 4 — 去重关闭(dedup-close):同 issue 重复对,留一个、关其余 **这是 sweep 相对单 PR 引擎的核心增量,也是当前最高频的清理动作。** 一个同-issue 簇里有 ≥2 个开放 PR 时: 1. **选保留方(keeper):** 用 pr-review 的留谁判据——更完整 diff > 更正确(对照权威源)> 有测试 > 更新 base > 先到。综合用 Opus 拍板,带证据。 1.5. **second opinion（关错 PR 不可逆——作者会收到关闭通知，值得多花一轮验证；#1055 方向五 / #1208）:** 定 keeper 前,再扇出**一个独立全新 context** 的 agent（`Agent` 工具,`general-purpose`),给它同一簇 PR 的摘要(diff 概要 + 判据表,不带主 session 的结论),要求它按同一判据独立选 keeper,返回结构化结果 `{keep: , reason: "<一句话>"}`(自然语言对比不可靠,见 #1208 评估——只比较 `keep` 的 PR 号,不比较 `reason` 措辞)。 - **两个 `keep` 一致** → 按本判据继续走步骤 2-4。 - **不一致** → **不去重关闭这一簇本轮**,在簇内每个 PR 上打 `pr-sweep:awaiting-direction`,comment 列出两个 agent 的选择 + 理由,等人拍板选哪个当 keeper。 - **仅对 dedup-close 的 keeper 选择触发**——其余高风险决策(security 标红、verification gate 语义)按现行的保守路径处理,不加 second-opinion,不拖慢日常 sweep 速度(评估结论见 #1208:security 已是 comment-only 足够保守,verification gate 场景在 issue-sweep/pr-sweep 里不存在)。 2. **矛盾必查权威源:** 簇内两 PR **断言冲突**(如同一处 license,一个 `BUSL-1.1` 一个 `BSL-1.1`)→ 先查 repo 权威源(`LICENSE` / 既有 canonical 文档)定哪个对,**正确的那个才可能当 keeper**;若两个都错,两个都不合,comment 指正。 3. **关冗余方(twin):** 对每个非-keeper: ```bash gh pr comment --body-file # 说明:与 # 重复(同 issue #N),保留 # 因 <判据+证据>;本 PR 关闭 gh pr close --comment "superseded by #" # 或先 comment 再 close ``` comment 顶部带完整身份行（整行由 ` --header "PR Review" --skill pr-sweep` 生成，不能用日期、占位符或手拼代替、也别再手写死 `Claude Code()`——engine/model 由脚本按 `ARC_AGENT_ENGINE`/`ARC_AGENT_MODEL` 自动带出；行尾追加读取/运行范围）。 正文一句话定责 + 指向 keeper。 4. **keeper 上留一条**:注明"已关闭重复 #twin,本 PR 为保留方",便于人追溯。 > **关闭是可逆的**(可 reopen),且这里有明确证据 + 双向回链 → 属"自动做"。但**别误关**:只有坐实"同 issue、同改动面、确为冗余/被取代"才关;拿不准就两个都留 `COMMENT`,把冲突摆出来等人。**簇内任一 PR 带 `agent:hold`(人类保留)→ 不参与去重关闭**(hold 冻结终态动作,close 属终态:它既不被当 twin 关掉,也不被拿来当 keeper 去关别人——它自己的去留人还没拍板;冲突事实照常写进 verdict comment 供人参考)。 ## Step 5 — 合并闸(`--merge` 时):分风险档自动合,高风险升级给人 **门控 = profile `gate_mode`(arc = `scripts`:PR 上无 CI,`pre-merge` 脚本即门控;`ci`/`both` 叠加 `gh pr checks` 绿),也不无脑合。** 每个 `MERGE`/`COMMENT`-可合 verdict 过这道闸: **通用前置(全档都要):** - **★ Verification 闸(强约束,真正的 merge 门控,不可跳过)**:每一次 merge 尝试都先运行 ` --comment `，再立即运行 ``。前者必须在本次 尝试中取得当前 `{HEAD SHA, scenario=pre-merge, resolved base}` 事实；shared broker 只会 对完全相同的身份复用，main/base 前进即强制重测。**不得**因已有 report、同一 HEAD、报告时间新 或手写 SHA marker 而跳过此调用。随后 merge gate 才确认 PR comment 的 sha 与当前 PR HEAD 匹配且 result=PASS 或 result=NA: ```bash --comment # --cs-head is the 40-char PR/CS head, must be current HEAD. --cs-head <40-char-sha> ``` 两者都 exit 0 → 可合;任一 exit 1 → 打印原因并止步:没有 comment / SHA 过期(push 后未重验)/ result=FAIL / resolved base 已推进。简单错误自己修后从 `` 重走;复杂错误把失败 诊断 + 完整日志贴 comment 升级给人。 **这是取代 CI 的合并门控**——pr-review 只判定不 merge,故门控落在这里。 **`` 还会要求 profile `additional_merge_gates` 列出的每道门都通过**(arc: `e2e-gate`)——当 diff 命中**可起的后端面**时还要求 `e2e-gate` sticky comment(SHA==HEAD 且 PASS/NA);它自己跑 `scope.ts` 独立判后端命中,纯文档/UI/前端/测试 PR 自动记 `e2e-gate`=N/A、不阻挡。exit 1 的新增原因:后端面命中却无 `e2e-gate` comment / `e2e-gate` result=FAIL / `e2e-gate` SHA 过期。`additional_merge_gates` 为空的仓库没有这层,只看 verification 闸。且 - **★ Review 闸(与 verification 闸同级,独立于 `mergeable_state` 的判读)**: merge 前**独立重新**取一次 `pulls//reviews`(或 MCP `pull_request_read(method="get_reviews")`), 按 reviewer 取每人**最新一条** review 的 `state`。**只认人类 reviewer**(`user.type != "Bot"`; 排除 `chatgpt-codex-connector[bot]` 等 bot-review connector——它们走下方「Codex / bot-review short-wait」条款 + [`codex-review-backlog`](../codex-review-backlog/SKILL.md),**不是**这道人类 `CHANGES_REQUESTED` 硬闸)。任一**人类** reviewer 的最新 state 为 `CHANGES_REQUESTED` 且未被同一人后续的 `APPROVED` 覆盖 → **硬止,不自动合**——即使 Step 3 verification 全绿、无论 GitHub 的 `mergeable_state` 显示什么(该字段不透明,不能拿它反推 有没有 `CHANGES_REQUESTED`,也不能反过来假设它没报异常就等于没有,只认这次独立 fetch 的结果)。 命中时按标准升级路径处理(comment 里贴出该 review 的 `state`+`body`,通常打 `pr-sweep:awaiting-direction`:reviewer 提出的是要不要按其要求改范围的方向问题,不是可以 自决的机械修复)。**这道闸独立于 Step 0/pr-review 是否已查过三面**——两处都要有,任一处漏了 另一处仍能拦住,不互相依赖。且 - **★ Codex / bot-review short-wait(推进优先,不长时间挂起):** 契约与 [`epic-conductor` §6](../epic-conductor/SKILL.md) **同一份**(Codex **和** Cursor Bugbot, 以及任何 inline connector)。本 org 的 bot 在 open/ready/push 后通常**数分钟内**给 inline findings,或只留一个 **👍** 表示无意见。规则: - **👍 / 无 inline finding** → 不挡 merge(不算人类 review 闸)。 - **有 P1 / High inline finding 且 agent 尚未 fix 或 in-thread REJECT-reply** → 当可执行活:打/保持 `pr-sweep:needs-fix`,在 PR 分支修或 **in-thread** 回绝,再重跑 `pre-merge` 与适用 sticky; **不要**因"等 bot 再评一次"挂数小时。新 top-level comment 不算 addressed。 - **全量 actionable thread 回执:** 每条要求改动、澄清或取舍的 inline review（人或 bot，任意 severity） 都须在**同一 thread** 留下结论，才可 merge：fix 回复当前完整 SHA、改动和验证；REJECT 回复理由；仅 P2/Medium/Low 可 defer 并给 tracking issue / owner / 重新处理条件。P1/High 只能 fixed 或 REJECT，不能 defer 后合入。P2/Medium/Low 可以不作为风险阻断，但缺回执仍须保持 `pr-sweep:needs-fix`，不得把顶层 verdict、verification sticky 或「已 push」当作已回应。每次 merge 前枚举当前所有 actionable thread；时间戳仅用于增量抓取，任何早于某次 fix/reply 但仍无结论的 thread 依然未处理，不能被之后回复别的 thread 的 commit 掩盖。 - **push 修完后**最多 **short-wait ≤10min** 看 re-review/👍;超时无新 P1 → 按其余闸合。 - **合入后才到的 late Codex** → 不回滚本轮 merge 决策;交给 [`codex-review-backlog`](../codex-review-backlog/SKILL.md)。 - 与 [`epic-conductor` §6](../epic-conductor/SKILL.md) 同契约(epic PR 由 conductor 执行; 本 skill 对非 `epic-managed` PR 执行同一 short-wait 语义)。且 - **PR 不带 `agent:hold`**(人类保留;hold 期间 review/响应照常但**合并一律冻结**——这里是合并前的硬闸,带 hold 一律不合,即使风险档是 🟢、即使 verdict 是 MERGE。verdict 写成 `MERGE (held)` 等人摘 label);且 - **★ UI 证据闸(与后端数据面闸对称,由 `` 焊死,issue #3010)**:diff 命中 profile **UI Face Paths** → merge 前必须有 **对当前 PR HEAD**、**已发布(publicly、无凭据可读)** 的 `` / `ui-verify` 截图证据——由 `` 自动强制(它跑 `.claude/skills/ui-verify/scripts/scope.ts` 判命中,不靠自觉;检查目标是一条 ` ``` 字段： - `ver`：schema 版本，当前 `1` - `pr`：对应 PR 编号（数字） - `gate`：决策闸门名称，取受控词表：`needsReview` / `disposition`。 **★ 标错 gate 会让去重静默失效**——下一轮查的是 `gate:"verdict"`（[pr-review](../pr-review/SKILL.md) 文末）， 一条 verdict comment 若标成 `needsReview`（实盘见过），那次 verdict 就查不到， 下一轮当作「没 verdict」走首轮全量流程、再发一条。**判据只有一句：这条 comment 承载的是不是 「本 PR 该怎么处置」的结论**——是 → `gate:"verdict"`（由 pr-review 发）；只是 sweep 自己的 分流/打标记录 → `gate:"disposition"`。拿不准就按 `verdict` 标（宁可多去重，不可漏去重）。 - `sha`：本判定针对的 PR HEAD（40 位 commit oid）——跨 runner 新鲜度判定的机器键（Step 1.5 …(truncated)