merge-readiness

Merge Readiness 是一个任务后的可解释性门禁。在实现、测试、QA 和评审证据齐备后，它会生成一份人类可读的变更说明，然后向人类提出有针对性的问题，以验证他们能够解释该变更为何存在、改动了什么、做了哪些取舍、考虑了哪些风险，以及团队应如何理解它。

<Use_When>

• 一个任务、PR 或变更集在功能上已完成，需要在合并就绪前进行最终的人类理解检查
• 测试、QA、代码评审、安全评审或其他验证已经运行，或者缺失的证据必须被明确记录
• 用户希望 AI 解释该变更，然后考查人类是否能够解释它
• 你需要一份持久化的会话审计记录，证明团队在请求合并批准之前为什么可以信任并理解该变更 </Use_When>

<Do_Not_Use_When>

• 实现之前需求仍不明确；使用 /deep-interview
• 实现尚未完成；使用 /ralph、/team 或 /autopilot
• 测试或 QA 尚未运行，而用户期望此命令替代它们
• 用户想要代码评审发现；使用 /review 或相关评审工作流 </Do_Not_Use_When>

<Why_This_Exists> 真正的交付不仅仅是能工作的代码。团队需要理解一个变更为何存在、改动了什么、有意未做什么、考虑了哪些风险，以及未来的维护者应如何看待该变更。此工作流在请求合并批准之前让这种理解变得明确。通过此门禁绝不意味着该变更已被批准或合并；它只意味着有人能够解释它。 </Why_This_Exists>

<Depth_Profiles>

• Quick (--quick)：小型/局部变更；正确率阈值 >= 0.70；最多 3 道 MCQ；必需维度：why / change / risk
• Standard (--standard，默认)：常规功能/缺陷修复；正确率阈值 >= 0.80；最多 5 道 MCQ；必需维度：why / change / tradeoff / risk / team
• Deep (--deep)：高风险、架构、安全或跨模块变更；正确率阈值 >= 0.90；最多 8 道 MCQ（覆盖全部五个维度的冗余）

如果未提供标志，使用 Standard。阈值和轮次数量以 src/hooks/merge-readiness/mcq.ts 为准，并且必须与此文件保持同步。 </Depth_Profiles>

<Execution_Policy>

• 这是一个任务后命令。不要在此模式内实现代码。
• 在向人类询问可在本地发现的事实之前，先收集仓库和产物证据。
• 在一次 AI 步骤中生成说明文档 + MCQ，然后每轮呈现一道 MCQ。
• 运行时（TS hook 代码）是主干：它负责验证、权威会话状态、客观 MCQ 评分和报告渲染。AI 负责内容生成 + 通过 AskUserQuestion 呈现 MCQ。
• 通过 AskUserQuestion 每轮呈现一道 MCQ（deep-interview 风格）。通过运行时记录每次选择，以便被客观评分。
• 询问可解释性，而不是实现细节琐事。
• 绝不要让人类记住行号、变量名、私有辅助函数名或附带的实现细节。
• 分数是客观正确率（正确答案数 / 已回答数），而非关键词启发式。
• 如果在所有必需 MCQ 都已回答后正确率仍低于阈值，将结果标记为 paused 并且不要声称合并就绪。
• 如果关键证据缺失（没有 diff/变更信号），将结果标记为 blocked。
• 通过此门禁不会批准合并、替代测试、替代评审、替代安全评审、接受风险或绕过维护者批准。
• 为恢复安全，将状态持久化到 .omc/state/merge-readiness-state.json（会话范围内位于 .omc/state/sessions/<sessionId>/）。不要直接写入此文件。
• v1 是建议性的：门禁逻辑（checkMergeReadiness）未接入 Stop hook，因此激活的门禁不会阻止会话。它不执行或批准 Git 合并。 </Execution_Policy>

阶段 0：证据收集

1. 解析 {{ARGUMENTS}}、深度配置文件、来源模式（--from-diff|--from-artifacts），并生成任务 slug。不支持 --from-pr；此工作流仅使用本地证据。
2. 收集可用证据（运行时根据文件名启发式规则检测工件；绝不会解析文件内容）：
   • 本地 Git 差异和提交范围
   • 变更文件
   • 测试／QA／验证工件（文件名匹配 test|spec|qa|verify|validation）
   • 审查／风险／安全／就绪状态／判定工件（文件名匹配 review|risk|security|readiness|verdict）
   • .omc/plans/、.omc/specs/、.omc/interviews/、.omc/artifacts/、.omc/logs/，以及相关模式状态工件（.omc/state/ 下记录实际运行的规范 {mode}-state.json 文件）
3. 明确记录缺失的证据。不能用出色的说明掩盖证据缺失。

阶段 1：初始化

调用 merge_readiness_start 工具并提供变更摘要，以初始化状态（运行时会解析 --quick／--deep 配置文件（未指定任何标志时默认为 --standard；它不是已解析的标记））。状态结构：

{
  "active": true,
  "current_phase": "merge-readiness",
  "phase": "content",
  "profile": "standard",
  "threshold": 0.80,
  "max_rounds": 5,
  "required_dimensions": ["why", "change", "tradeoff", "risk", "team"],
  "questions": [],
  "answers": [],
  "awaiting_content": true,
  "readiness_score": 0,
  "result": "pending"
}

在 AI 通过 merge_readiness_set_content 提交生成的文档和多项选择题之前，awaiting_content 始终为 true。

阶段 2：生成说明文档和多项选择题（AI 内容步骤）

根据实际差异和证据（而非模板）生成：

1. 一份包含 5 个部分的说明：原因、变更内容、权衡、已考虑的风险、团队理解。
2. 一组多项选择题（每题只有一个正确选项，包含 correctOptionId 和可选的 rationale）：
   • 最多达到配置文件规定的轮数（quick 为 3 轮／standard 为 5 轮／deep 为 8 轮）
   • 分布于所有必需维度
   • 测试对本次变更的理解，而非实现细节

使用 merge_readiness_set_content 提交（需要 merge_readiness_start 激活的门控；如果没有激活的门控，则会报错）。不要写入状态 JSON，也不要调用内部运行时函数。无效内容会被拒绝，并返回可恢复的验证错误。通过验证的内容会持久化到权威会话状态中。

使用 merge_readiness_report 直接从状态呈现五个部分、证据、测验进度、就绪状态和合并边界。此操作只读，不会创建文件。答题完成前，正确答案和解析会保持隐藏；取消或覆盖操作只会显示已回答的问题。

合并边界必须写明：“通过意味着人类能够解释这项变更。它不代表批准合并，也不能替代测试或审查，亦不代表接受风险。”

维护者覆盖权限

只有在 MCP 服务启动器将经过身份验证的主体注入 OMC_MERGE_READINESS_AUTHENTICATED_PRINCIPAL，且该主体与逗号分隔的 OMC_MERGE_READINESS_MAINTAINERS 允许列表中的某项完全一致时，才接受 /merge-readiness --override <reason>。调用方提供的 session_id 仅用于选择状态记录；它绝不是覆盖权限的依据，也不会被记录为 override_owner。

阶段 3：人工测验循环（单选题，每轮一题，深度访谈风格）

通过 AskUserQuestion 每轮呈现一道单选题，将选项 id/文本作为选项，然后用 merge_readiness_record_answer 工具记录人工的选择（questionId + optionId）。运行时对其进行客观评分，然后要么推进到下一题，要么对门禁做出最终判定（pass / paused / blocked）。

在通过之前，需覆盖以下维度（quick = 仅 why/change/risk）：

1. why - 为什么这项变更值得做
2. change - 哪些行为、工作流、接口或维护模型发生了变化
3. tradeoff - 选择了什么、推迟了什么或拒绝了什么，以及原因
4. risk - 考虑了哪些风险，以及哪些仍然存在风险
5. team - 团队应如何理解并维护这项变更

禁止的题型：

• 函数名冷知识
• 行号冷知识
• 变量名记忆
• 私有辅助函数记忆
• 任何其答案无助于评审者解释该变更的问题

阶段 4：评分就绪度（运行时负责，客观）

运行时计算：

• readiness_score = 正确率 = （正确回答数）/（已回答数），取值范围 [0, 1]
• 各维度覆盖率 = 每个必需维度是否至少有一道已作答的单选题

门禁结果：

• pass：所有必需单选题均已作答 且 正确率 >= 阈值 且 必需维度均已覆盖
• paused：所有必需单选题均已作答 但 正确率低于阈值（或必需维度未覆盖）
• blocked：缺少最小证据（无 diff/变更信号）

阈值：quick 0.70 / standard 0.80 / deep 0.90。

阶段 5：结晶结果

将以下字段持久化到终端会话状态中，并通过 merge_readiness_report 查看它们：

• 最终就绪度评分
• 维度细分
• 人工回答
• AI 评估
• 结果
• 阻塞或暂停的缺口
• 下一步

阶段 6：交接

如果 pass：

• 声明该变更可进入人工合并审批。
• 不要合并。

如果 paused：

• 声明缺少哪个解释维度。
• 建议重读或修订报告，并重新运行 /merge-readiness。

如果 blocked：

• 声明在重新运行之前必须产出哪些证据。

<Tool_Usage>

• 在向人工询问上下文之前，使用仓库搜索和本地产物进行证据采集。
• 在可用时使用结构化用户提问。
• 使用 merge_readiness_start 初始化门禁，使用 merge_readiness_set_content 提交报告 + 单选题，使用 merge_readiness_record_answer 记录每次选择，使用 merge_readiness_report 渲染当前审计记录。仅对 .omc/state/merge-readiness-state.json 使用状态读取/状态/清除；切勿使用通用状态写入来提交测验内容。state_clear 会将 merge-readiness 路由至取消流程并保留终端状态；传入当前 session_id 以避免取消并发的测验。 </Tool_Usage>

<Escalation_And_Stop_Conditions>

• 用户说停止/取消/中止 -> 持久化终端 cancelled 状态并停止。
• 缺少 diff 或变更证据 -> blocked。
• 人工无法解释某个必需维度 -> paused。
• 达到就绪度阈值且强制门禁满足 -> pass。 </Escalation_And_Stop_Conditions>

<Final_Checklist>

• 证据采集已完成
• 已记录缺失的证据
• 解释文档（5 个部分）+ 单选题已通过 merge_readiness_set_content 提交
• 单选题已通过 AskUserQuestion 每轮一题呈现
• 每个答案均从标记的 AskUserQuestion 输出中关联（客观评分）
• 问题避免了实现细节冷知识
• 正确率由运行时计算
• 结果为 pass、paused、blocked、overridden 或 cancelled
• 合并边界明确
• 未执行任何直接实现或合并 </Final_Checklist>

## 推荐的交付流水线

/deep-interview
  -> /omc-plan or /ralplan
  -> /ralph, /team, or /autopilot
  -> /ultraqa and review
  -> /merge-readiness
  -> human merge approval

Autopilot Bridge

在完成 QA/验证后，Autopilot 可在已配置的情况下调用此工作流：

{
  "autopilot": {
    "mergeReadiness": true
  }
}

autopilot.understandingGate 是 autopilot.mergeReadiness 的已弃用兼容别名。

Task: {{ARGUMENTS}}