merge-ready

可合并就绪

在将 PR 标记为可供审查或合并之前，使用此技能作为最后一道关卡。

此技能负责协调现有项目工作流。它不会取代：

• qa-team：用于编写和执行外部用户视角的场景
• quality-audit：用于迭代执行 SEEK → VALIDATE → FIX 审查
• default-workflow：用于处理在将 PR 准备到可合并状态时发现的实质性问题

使用 pr-description-template.md 更新 PR 描述，并提供所需证据。

必须达成的结果

只有满足以下所有条件，PR 才可合并：

1. qa-team 场景已编写或更新，已通过 gadugi-test validate 验证，并且已通过 gadugi-test run 实际运行。
2. 如果改动影响 API、配置、部署、命令行行为或其他外部接口，则已更新面向用户的文档。
3. quality-audit 至少完成了 3 轮 SEEK → VALIDATE → FIX 循环；如果仍有严重或高优先级问题，则继续执行超过 3 轮，并以一轮干净的最终循环结束。
4. 所有 GitHub Actions 检查均通过，且失败数为 0。
5. PR 描述包含证明条件 1–4 和 6 已满足的具体证据。
6. 差异中不包含无关改动。

如果缺少任何一项条件，PR 就尚未达到可合并状态。

不可妥协的防护要求

• 不要将“场景 YAML 文件已存在”视为满足要求。场景必须经过验证并且实际运行。
• 不要在未检查改动涉及的接口前，就声称文档与改动无关。
• 不要接受少于 3 轮 quality-audit 循环。
• 不要接受最终循环不干净的 quality-audit 结果。
• 不要接受待处理或失败的 CI 检查。
• 不要在 PR 描述本身尚未更新并包含证据时，将 PR 标记为可合并。
• 不要默默忽略缺少环境访问权限、缺少 PR 访问权限或缺少测试工具等阻塞问题。请明确报告。

工作流

1. 确认 PR 背景

如果提供了 $ARGUMENTS，则从中识别目标 PR；否则使用当前分支对应的 PR。

收集以下信息：

• PR 编号、URL、标题和当前 PR 描述
• 已更改文件和当前差异范围
• 改动是否涉及外部接口或面向用户的功能
• 当前 CI 状态

可用命令：

gh pr view "$PR" --json number,url,title,body
gh pr diff "$PR" --name-only
gh pr checks "$PR"
git diff --name-only origin/main...HEAD

如果尚无 PR，仍可准备证据，但在 PR 创建且 CI 状态可用之前，最终判定必须保持为受阻状态。

2. 使用 qa-team 满足 QA 条件

调用 qa-team，并确保其从外部用户的视角覆盖已更改的行为。

必需交付物：

• 场景文件路径
• gadugi-test validate 成功的证明
• gadugi-test run 成功的证明
• 运行所用的目标环境（本地或已部署）
• 证据位置或执行输出摘要

最低限度的命令：

gadugi-test validate path/to/scenario.yaml
gadugi-test run path/to/scenario.yaml

如果运行场景所需的环境不存在，请停止并报告阻塞问题。不要将其降级为“仅定义场景”。

3. 满足文档条件

检查已更改的文件，并判断 PR 是否更改了任何面向用户的接口：

• API
• 配置
• 部署或运维流程
• 命令行或 TUI 行为
• 用户可见的工作流

如果是，请更新相应文档，并在 PR 描述中添加这些文档的链接。

如果不是，请列出检查过的改动接口，并说明每项为何仅涉及内部实现。例如：“已审查的改动接口：rust_runner.py、smart-orchestrator.yaml——二者都是内部编排基础设施，不影响命令行、API 或配置。”

4. 满足质量审计标准

调用 quality-audit，并要求完成完整的迭代循环：

• 至少 3 个周期
• 每个周期都按 SEEK → VALIDATE（多 Agent 共识）→ FIX 执行
• 如果仍有严重或高危问题，超过 3 个周期继续执行
• 最后一个周期必须干净：严重或高危问题为 0，且不存在会造成正确性或安全风险的中危问题

审计过程中发现的所有问题都必须通过 default-workflow 修复。如果审计发现需要修改代码或文档的问题，切换到 default-workflow 进行修复，完成后再返回此技能并恢复验证。

在 PR 描述中记录：

• 周期数
• 每个周期确认的问题
• 已应用的修复
• 收敛情况摘要
• 明确说明最后一个周期已通过：严重或高危问题为 0，且不存在会造成正确性或安全风险的中危问题

5. 满足 CI 标准

检查 PR 的所有 GitHub Actions 状态。

规则：

• 所有检查都必须通过（条件工作流中跳过的检查可以接受，但必须列出）
• 仅重新运行明显不稳定的任务
• 继续之前必须修复真实故障
• 只有故障数为 0 才算通过
• 如果 CI 处于待处理、失败、已取消或不可用状态，则 PR 尚未达到可合并状态
• 在 PR 描述中按名称列出所有跳过的检查及跳过原因

实用命令：

gh pr checks "$PR"
gh run list --branch "$(git branch --show-current)"

如果 CI 处于待处理、失败、已取消或不可用状态，则 PR 尚未达到可合并状态。

6. 确保范围符合要求

检查差异，并确认 PR 仅聚焦于预期变更。如果存在无关变更，将其报告为阻碍项，不要将 PR 标记为可合并。

7. 更新 PR 描述

**只有在完成步骤 2–6 并收集好证据后，才能执行此步骤。**不要使用占位内容或预期证据更新 PR 描述。

使用 pr-description-template.md，并将每个占位内容替换为实际证据。措辞应简洁，但证据必须具体到足以让审查者无需猜测即可验证工作成果。

如果 PR 描述中已有有用的章节，请将证据合并到现有结构中，而不是重复添加标题。

8. 给出二元结论

以以下其中一种结果结尾：

• MERGE_READY：所有标准均已通过，且 PR 描述已更新
• NOT_MERGE_READY：仍有一个或多个阻碍项

使用以下格式：

Verdict: MERGE_READY | NOT_MERGE_READY

Criteria:

- QA-team: pass | fail
- Docs: pass | fail | not-applicable
- Quality-audit: pass | fail
- CI: pass | fail
- Scope: pass | fail
- PR description evidence: pass | fail

Blockers:

- <concrete missing item or `none`>

何时停止并移交阻碍项

出现以下任一情况时，停止并报告 NOT_MERGE_READY：

• 不存在可运行所需 gadugi 场景的环境
• 无法访问 PR 或 CI 状态
• quality-audit 尚未收敛到干净的最后一个周期
• 需要修改文档，但尚未完成
• 差异中包含无关变更

不要用承诺或待办事项代替证据。