claw-code 2.0 的 PR 与 Issue 收口门禁:证据驱动的合并、拒绝与延迟决策

本文基于 docs/pr-issue-resolution-gate.md 展开,讲解 Claw Code 2.0 发布前如何对全部开放 PR 和 Issue 做"收口"(reconciliation):如何抓取非破坏性快照、用 anti-slop 分类体系做分诊、以 JSON 台账记录每个 PR 的 merge/reject/defer 决策,以及最终证据清单与明确非目标。读完本文,你可以照搬这套门禁流程,为自己的多 Agent/多人协作仓库建立可审计的 PR 与 Issue 清理机制。

门禁的来源:一条明确的 Ultragoal 要求

Claw Code 2.0 的 Ultragoal(仓库长期目标执行流)在执行过程中追加了一条显式要求:

all PRs should be merged and all issues should be resolved if resolvable and correct.

即:凡是正确且可解决的 PR 应当合并,凡是可解决且正确的 Issue 应当被修复或显式关联到已合并的修复。这条要求被固化为 docs/pr-issue-resolution-gate.md 中的最终门禁(Gate)。它的定位不是"合并一切",而是"对一切给出有证据的处置":每个开放条目要么被合并/修复,要么被记录理由地拒绝/延迟/关闭。这一门禁在 docs/g012-final-release-readiness-report.md 中被列为 G011 生态/运维/UX 流的完成证据之一,并在 docs/g006-task-policy-board-verification-map.md 中明确"开放 PR/Issue 的协调显式推迟到 G011/G012 处理"。

门禁的完成标准(Scope)

在 Claw Code 2.0 Ultragoal 可以被标记为完成之前,必须满足以下 7 条标准(完整继承自原文档 Scope 一节):

1. 最终门禁快照(final-gate snapshot)中每一个开放的 GitHub PR 都必须被分诊(triage)。
2. 正确、与 Claw Code 2.0 方向兼容、且通过必需验证的 PR 必须被合并。
3. 陈旧的、错误的、重复的、不安全的、垃圾的、或超出 Claw Code 范围的 PR 不得合并,并且每一条都必须记录理由(recorded rationale)。
4. 最终门禁快照中每一个开放的 GitHub Issue 都必须被分诊。
5. 可解决且正确的 Issue 必须被修复,或显式链接到一个已合并的修复。
6. 垃圾、重复、错误、不可执行(externally blocked)、或不属于 Claw Code 工作的 Issue,在仓库策略允许时,必须被关闭,或带理由地打标签/评论。
7. 最终完成审计必须使用一份全新的 GitHub 快照,而不能只依赖规划阶段(planning)的快照。

第 7 条是关键:它承认了"快照会过期"这一现实——任何基于旧快照的"全部清理完毕"声明都不成立,必须用新鲜数据重新核对增量(delta)。

现场快照:如何抓取、如何解读

原文档记录了一次在 G011 W3 执行期间完成的非破坏性(non-destructive)快照,可作为抓取与解读范式的参考:

抓取命令(两条,分别针对 PR 与 Issue):

gh pr list --state open --limit 1000 --json number,title,state,updatedAt,url
gh issue list --state open --limit 1000 --json number,title,state,updatedAt,url,labels

快照要点(原文档记录的事实数据):

• 抓取时间:2026-05-15T02:39:41Z,发生在 Ultragoal 运行期间。
• 观测数量:51 条开放 PR 记录,1000 条开放 Issue 记录(来自 GitHub CLI 的 list 调用)。
• 快照中最新的开放 PR 为 #3040,标题 fix: recognize OPENAI_API_KEY as valid auth for OpenAI-compatible endpoints,更新于 2026-05-14T11:35:23Z。
• 快照中最新的开放 Issue 为 #3039,标题 How to install skills?,更新于 2026-05-14T08:14:36Z。
• limit 注意事项:Issue 快照打到了 --limit 1000 的上限,因此最终门禁必须把 Issue 数量视为"至少 1000",除非捕获了更高上限的导出或分页台账(paginated ledger)。

原文档还有一句重要的定性:

These command outputs are evidence inputs, not final proof. The final gate must refresh them and compare deltas before any completion claim.

即:这些命令输出只是证据输入,不是最终证明。任何"完成"声明之前,都必须刷新快照并对比差异。这是整个门禁方法论的核心纪律:快照是可过期的,结论必须绑定到新鲜快照之上。

Anti-slop 分诊:九种分类与配套模板

门禁执行前,原文档要求先使用 docs/anti-slop-triage.md 加仓库模板,再对现场快照采取行动。分诊分类体系共 9 种:

actionable-bug、actionable-docs、actionable-feature、duplicate、spam-or-promotion、generated-slop-or-hallucinated、unsafe-or-security-sensitive、not-reproducible-yet、externally-blocked。

分类体系的判定标准与证据要求

docs/anti-slop-triage.md 为每种分类规定了"何时使用""必需证据"和"安全动作"三列,这是分类能落地的关键——不允许只贴标签而不附证据。摘选其中几种的典型规则:

分类	何时使用	必需证据	安全动作
actionable-bug	报告包含可复现的产品故障	复现步骤、失败测试、脱敏日志,或对应的 roadmap 项	修复、指派,或链接到已有修复
duplicate	已有 Issue/PR 覆盖同一用户可见结果	链接规范(canonical)的 Issue/PR,并记录值得保留的额外证据	交叉链接;仅按维护者/Owner 策略关闭
generated-slop-or-hallucinated	改动面过大、机械生成、无法评审,或引用了不存在的 API/文件	Diff/路径示例、缺失符号、不可验证的断言	要求窄化复现,或带理由拒绝/延迟
unsafe-or-security-sensitive	涉及密钥、漏洞细节或危险操作指引	脱敏摘要与安全策略链接	转入私有/安全通道,不扩散公开细节
not-reproducible-yet	声称可能成立但证据不足以行动	缺少命令、环境、期望/实际行为或版本	索取复现细节;不做推测性修复
externally-blocked	依赖上游服务、凭据、策略或不可获得的 Owner 审批	阻塞依赖与 Owner/门禁	带具体解除条件的延迟

完整的九类表格见 docs/anti-slop-triage.md。该文档同时给出两个问答清单:

• PR 评审门禁要求每个 PR 分诊记录回答 5 个问题:是否为合并候选/要求修改候选/重复/不安全/超出范围/生成垃圾?支撑该分类的确切证据是什么?运行或刻意跳过了哪些测试/文档检查?它解决哪个 Issue、roadmap 行或用户问题?如果现在不该合并,最小的非破坏性下一步是什么?
• Issue 收件门禁要求回答 4 个问题:Issue 是正确、重复、垃圾、无效、外部阻塞还是暂不可复现?若正确且可解决,哪条修复路径或已合并提交能解决它?若当前不可解决,什么证据会改变分类?是否存在密钥、私有数据或安全细节需要走私有通道?

模板文件:把分诊固化进提交入口

门禁引用的两个模板文件在当前仓库中都实际存在:

1. Issue 分诊表单 .github/ISSUE_TEMPLATE/anti_slop_triage.yml

从文件结构看,它由四部分构成:

• 元数据:表单名 Anti-slop triage,标题前缀固定为 triage: ,默认打标签 needs-triage(anti_slop_triage.yml)。
• classification 下拉框:强制选择 9 种 anti-slop 分类之一,且 required 为 true(anti_slop_triage.yml)。
• evidence 与 safe_next_action 两个必填文本域:前者要求链接支持该分类的 PR、Issue、命令输出、文档页、复现或策略;后者要求声明下一步非破坏性动作,如果提议关闭或合并,必须指明所需的 Owner/门禁(anti_slop_triage.yml)。
• guardrails 勾选项(全部 required):未作为分诊报告的一部分去关闭/合并/变更远端状态;推荐动作前已检查重复项;涉及凭据、安全或私有数据时避免公开复现细节并转入私有/安全通道(anti_slop_triage.yml)。

2. PR 模板 .github/PULL_REQUEST_TEMPLATE.md

该模板把门禁要求直接写进每个 PR 的默认骨架,包含四个区块:

• Anti-slop triage 区块:要求填写分类(merge 候选之外的可选值含 actionable-fix、docs-only、duplicate、generated-slop、unsafe、out-of-scope、needs-maintainer-decision)、证据、非破坏性评审结果(merge candidate / request changes / close-defer with rationale / needs owner gate)。
• Verification 区块:三个勾选项——目标测试/文档检查已运行或缺口已被显式记录;git diff --check 通过;不包含真实密钥、令牌、私有日志或无关的生成性改动。
• Resolution gate 区块:若 PR 解决某个 Issue,必须链接 Issue 编号与修复证据;若不应合并,拒绝/延迟理由必须"有证据支撑且不依赖感觉"(does not rely on vibes);并且勾选确认"没有从自动化泳道未经 Owner 批准就合并/关闭远端 PR 或 Issue"(PULL_REQUEST_TEMPLATE.md)。

原文档还特别规定了一条自动化边界:

Automation lanes may recommend labels, comments, defer/close rationales, or merge candidates, but must not merge or close remote PRs/issues without maintainer-owned approval.

即自动化泳道可以推荐标签、评论、延迟/关闭理由或合并候选,但不得在没有维护者批准的情况下合并或关闭远端 PR/Issue。docs/anti-slop-triage.md 中的表述与之呼应:自动化泳道只能产出台账行、添加本地文档/模板,并向 Owner 拥有的最终门禁报告推荐动作。

G012 最终 PR 对账:JSON 台账是怎么长出来的

门禁要求的"每 PR 一行台账"在仓库中有一份真实样例:docs/pr-triage-g012-final-gate.json。这是 G012 最终门禁执行期间,worker-3 抓取的新鲜 PR 台账,可直接作为台账 schema 的参考实现。

台账元数据(文件头部,pr-triage-g012-final-gate.json):

• schema_version: "1.0"
• captured_at: 2026-05-15T02:58:00Z(G012 最终门禁执行期间)
• captured_by: g012-final-gate-ultra-e61d2271/worker-3
• source_commands: 记录了两条真实命令——
  1. gh pr list --state open --limit 100 --json number,title,headRefName,baseRefName,author,updatedAt,isDraft,mergeable,reviewDecision,statusCheckRollup,url(列表级)
  2. gh pr view <number> --json number,title,additions,deletions,changedFiles,files,commits,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup,url(逐 PR 的文件与合并状态证据)
• policy: 一句话安全策略——只合并正确、安全、无冲突、且带证据可解决的 PR;延迟不安全、不正确、冲突、未验证或高风险的 PR。

台账汇总(summary 字段) 给出的分布数字与原文档一致:

{
  "open_pr_count": 51,
  "merged_by_worker_3": 0,
  "deferred_not_merged": 51,
  "conflicting_or_dirty": 32,
  "mergeable_but_unstable_or_unverified": 19,
  "docs_only_candidate_review": 2,
  "safe_merge_candidates_with_fresh_ci": 0
}

这组数字本身就是一篇完整的"为什么 0 合并"的论证:51 个开放 PR 中,32 个处于 CONFLICTING/DIRTY 状态(需要先 rebase 或人工协调),其余 19 个虽被 GitHub 报告为 MERGEABLE,但合并状态为 UNSTABLE 且活快照中没有新鲜的 check-rollup 证据——两者都不满足"正确、安全、无冲突、可验证"的合并条件,因此带新鲜 CI 的安全合并候选数为 0,worker-3 的实际合并数为 0,全部 51 个被 defer_not_merged。

逐 PR 行的字段设计以 #3040 为例(pr-triage-g012-final-gate.json):

{
  "number": 3040,
  "title": "fix: recognize OPENAI_API_KEY as valid auth for OpenAI-compatible endpoints",
  "mergeable": "MERGEABLE",
  "mergeStateStatus": "UNSTABLE",
  "reviewDecision": "",
  "checks": [],
  "changedFiles": 1,
  "additions": 11,
  "deletions": 10,
  "files": ["rust/crates/rusty-claude-cli/src/main.rs"],
  "files_truncated": false,
  "decision": "defer_not_merged",
  "decision_reason": "GitHub reports mergeable but UNSTABLE with no fresh CI/check rollup in the live PR snapshot; requires maintainer review and verification before merge.",
  "merged_by_worker_3": false
}

可以看到,台账行同时保留了客观证据(mergeable、mergeStateStatus、checks、files、additions/deletions)与主观决策(decision、decision_reason、merged_by_worker_3),且 decision_reason 必须引用具体的状态字段(如 UNSTABLE、CONFLICTING/DIRTY),而不是空泛理由。对于大型 PR,文件列表会被截断并以 files_truncated: true 标记(如 #3016 的 LSP 集成 PR),避免台账无限膨胀。

原文档还点名了两个 docs-only 候选评审 PR:#3021(Document TweetClaw skill install example)与 #2824(docs: personal assistant roadmap),两者保持 deferred,等待内容/事实来源(source-of-truth)评审与新鲜验证可用后再定。

最终证据清单与非目标

最终报告必须包含的证据

原文档 "Required final evidence" 一节规定了最终报告的五个必备项,完整继承如下:

• 新鲜的 gh pr list --state open 与 gh issue list --state open 快照。
• 一份 PR 台账,每 PR 一行:merge / reject / defer 决策、理由、验证情况、commit/merge 引用。
• 一份 Issue 台账,每 Issue 一行:fixed / duplicate / spam / invalid / deferred-with-rationale / externally-blocked 分类、理由、以及链接的证据。
• 验证"不存在正确且可合并的 PR 被无理由地留在未合并状态"。
• 验证"不存在可解决且正确的 Issue 被无理由地留在开放状态"。

注意最后两条是否定式验证:门禁不仅要求"做了什么",还要求证明"没有遗漏该做的事"。这正是"all PRs should be merged and all issues should be resolved if resolvable and correct"这条原始要求的可审计化形式。

非目标(Non-goals)

原文明确划界:

This gate does not require merging unsafe, unverified, incompatible, spam, or incorrect contributions. It requires explicit evidence-backed triage and action for everything that is correct and resolvable.

即门禁不要求合并不安全、未验证、不兼容、垃圾或错误的贡献;它只要求对所有"正确且可解决"的事项做出有证据的分诊与处置。这条非目标防止门禁被误读为"合并数量指标"——G012 台账中 51 个 PR 全部 deferred、0 合并,在策略上是完全合规的结果,因为没有任何一个 PR 同时满足"正确、安全、无冲突、带新鲜证据"。

门禁在跨泳道验证中的位置

从 docs/g011-ecosystem-ops-ux-verification-map.md 的跨泳道验收矩阵可以看到,"Issue/PR ops gate" 行的验收方式是:运行 python3 .github/scripts/check_release_readiness.py 与 git diff --check(仅当 .omx/cc2/board.md 变化时才可选运行 python3 scripts/validate_cc2_board.py),并且约束写明"Worker 泳道不得合并/关闭远端 PR 或 Issue;最终对账仍由 leader 拥有"(final reconciliation remains leader-owned)。

与之配套的是 docs/roadmap-pr-goals.md 中为 roadmap PR 单独制定的合并策略:只合并仍与 Claw Code 2.0 相关、非 draft、指向 main、且在新鲜合并性刷新后无冲突的 PR;优先 squash 合并;纯文档 PR 在检查/冲突干净且确属 roadmap 缺口时允许合并;陈旧、被已落地工作覆盖、或不符合产品方向的 PR 不得强行合并,而是记录理由并把仍然正确的需求映射进 G011/G012。该文档还把开放 roadmap PR 分成三档:历史检查全绿的首轮合并候选、需要本地验证或 CI 刷新的 PR、以及合并前需产品契合度(product-fit)评审的 PR(如 #2824)。

小结:一套可复制的收口方法论

把 docs/pr-issue-resolution-gate.md 与配套工件串起来,得到一套完整的"发布前 PR/Issue 收口"流水线:

1. 快照:gh pr list / gh issue list 带 --limit 与 --json 字段抓取,记录时间戳,并警惕 limit 截断(见 G012 报告中对 Issue 数量"至少 1000"的表述);
2. 分诊:用 9 种 anti-slop 分类 + 必需证据列,配合 anti_slop_triage.yml 与 PULL_REQUEST_TEMPLATE.md 固化进提交入口;
3. 对账:为每个 PR/Issue 产出带 decision + decision_reason 的台账行,理由必须引用客观状态字段;
4. 验证:新鲜快照 + 否定式双验证(无遗漏可合并 PR、无遗漏可解决 Issue);
5. 边界:自动化泳道只建议不执行,合并/关闭权保留给 Owner/leader。

这套门禁在 claw-code 仓库中的价值,是把"社区贡献清理"这种容易依赖主观判断的工作,转化为一份可复查、可对比增量、可跨泳道交接的证据链。对于任何需要定期清理 PR/Issue 积压的仓库,上述五步都可以直接参照 docs/pr-issue-resolution-gate.md、docs/anti-slop-triage.md 和 docs/pr-triage-g012-final-gate.json 落地。