merge-readiness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<Purpose> Merge Readiness is a post-task explainability gate. After implementation, tests, QA, and review evidence exist, it generates a human-readable explanation of the change, then asks the human targeted questions to verify they can explain why the change exists, what changed, what tradeoffs were made, what risks were considered, and how the team should understand it. </Purpose>

<Use_When>

A task, PR, or change set is functionally complete and needs a final human-understanding check before merge readiness
Tests, QA, code review, security review, or other verification has already run, or missing evidence must be explicitly recorded
The user wants AI to explain the change and then quiz the human on whether they can explain it
You need a durable session audit record showing why the team can trust and understand the change before asking for merge approval </Use_When>

<Do_Not_Use_When>

Requirements are still unclear before implementation; use
```
/deep-interview
```
The implementation is not done; use
```
/ralph
```
,
```
/team
```
, or
```
/autopilot
```
Tests or QA have not run and the user expects this command to replace them
The user wants code review findings; use
```
/review
```
or the relevant review workflow </Do_Not_Use_When>

<Why_This_Exists> Real delivery is not only code that works. Teams need to understand why a change exists, what changed, what was deliberately not done, which risks were considered, and what future maintainers should believe about the change. This workflow makes that understanding explicit before merge approval is requested. Passing this gate never means the change is approved or merged; it only means a human can explain it. </Why_This_Exists>

<Depth_Profiles>

Quick (
--quick
): small/local changes; correctness threshold
```
>= 0.70
```
; max 3 MCQs; required dimensions: why / change / risk
Standard (
--standard
, default): normal feature/bugfix; correctness threshold
```
>= 0.80
```
; max 5 MCQs; required dimensions: why / change / tradeoff / risk / team
Deep (
--deep
): high-risk, architectural, security, or cross-module changes; correctness threshold
```
>= 0.90
```
; max 8 MCQs (redundancy across all five dimensions)

If no flag is provided, use Standard. Thresholds and round counts are canonical in

src/hooks/merge-readiness/mcq.ts

and must stay in sync with this file. </Depth_Profiles>

<Execution_Policy>

This is a post-task command. Do not implement code inside this mode.
Gather repository and artifact evidence before asking the human for facts that can be discovered locally.
Generate the explanation doc + MCQs in one AI step, then present MCQs one-per-round.
The runtime (TS hook code) is the backbone: it owns validation, authoritative session state, objective MCQ scoring, and report rendering. The AI owns content generation + MCQ presentation via AskUserQuestion.
Present each MCQ one-per-round via AskUserQuestion (deep-interview style). Record each selection via the runtime so it is scored objectively.
Ask about explainability, not implementation trivia.
Never ask the human to memorize line numbers, variable names, private helper names, or incidental implementation details.
Score is the objective correctness rate (correct answers / answered), not a keyword heuristic.
If the correctness rate is below threshold after all required MCQs are answered, mark result
```
paused
```
and do not claim merge readiness.
If key evidence is missing (no diff/change signal), mark result
```
blocked
```
.
Passing this gate does not approve merge, replace tests, replace review, replace security review, accept risk, or bypass maintainer approval.
Persist state for resume safety under
```
.omc/state/merge-readiness-state.json
```
(session-scoped under
```
.omc/state/sessions/<sessionId>/
```
). Do not write this file directly.
v1 is advisory: the gate logic (
```
checkMergeReadiness
```
) is not wired to the Stop hook, so an active gate does not block the session. It does not perform or approve a Git merge. </Execution_Policy>

<Steps>

<Purpose> 合并就绪检查是一个任务完成后的可解释性关卡。在完成实现、测试、QA和审查后，它会生成一份人类可读的变更解释，随后向相关人员提出针对性问题，验证他们能否解释该变更存在的原因、变更内容、做出的权衡、考虑到的风险，以及团队应如何理解该变更。 </Purpose>

<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
）：小型/局部变更；正确率阈值
```
>= 0.70
```
；最多3道MCQs；必填维度：原因/变更/风险
标准模式（
--standard
，默认）：常规功能/ bug修复；正确率阈值
```
>= 0.80
```
；最多5道MCQs；必填维度：原因/变更/权衡/风险/团队
深度模式（
--deep
）：高风险、架构级、安全或跨模块变更；正确率阈值
```
>= 0.90
```
；最多8道MCQs（覆盖所有五个维度的冗余题目）

如果未提供标志，默认使用标准模式。阈值和轮次数量在

src/hooks/merge-readiness/mcq.ts

中是标准值，必须与此文件保持同步。 </Depth_Profiles>

<Execution_Policy>

这是一个任务完成后的命令。请勿在此模式内实现代码。
在向人工询问可本地获取的信息前，先收集仓库和工件证据。
一步生成解释文档+MCQs，然后逐轮展示MCQs。
运行时（TS hook代码）是核心：它负责验证、权威会话状态、客观MCQs评分和报告渲染。AI负责通过AskUserQuestion生成内容和展示MCQs。
通过AskUserQuestion逐轮展示每个MCQ（深度访谈风格）。通过运行时记录每个选项，以便进行客观评分。
询问可解释性相关问题，而非实现细节琐事。
绝不要要求人工记住行号、变量名、私有辅助函数名或附带的实现细节。
分数为客观正确率（正确答案数/已答题数），而非基于关键词的启发式评分。
如果完成所有必填MCQs后正确率低于阈值，标记结果为
```
paused
```
，且不得声称已具备合并就绪条件。
如果关键证据缺失（无差异/变更信号），标记结果为
```
blocked
```
。
通过此关卡并不代表批准合并、替代测试、替代审查、替代安全审查、接受风险或绕过维护者批准。
在
```
.omc/state/merge-readiness-state.json
```
下持久化状态以支持安全恢复（会话范围在
```
.omc/state/sessions/<sessionId>/
```
下）。请勿直接写入此文件。
v1版本为建议性：关卡逻辑（
```
checkMergeReadiness
```
）未与Stop hook关联，因此活跃关卡不会阻止会话。它不会执行或批准Git合并。 </Execution_Policy>

<Steps>

Phase 0: Evidence Intake

Phase 0: 证据收集

Parse
```
{{ARGUMENTS}}
```
, depth profile, source mode (
```
--from-diff|--from-artifacts
```
), and derive a task slug.
```
--from-pr
```
is unsupported; this workflow uses local evidence only.
Collect available evidence (the runtime detects artifacts by FILENAME heuristics; file CONTENTS are never parsed):
- Local Git diff and commit range
- Changed files
- Test/QA/verification artifacts (filenames matching
```
test|spec|qa|verify|validation
```
  )
- Review/risk/security/readiness/verdict artifacts (filenames matching
```
review|risk|security|readiness|verdict
```
  )
- ```
.omc/plans/
```
  ,
```
.omc/specs/
```
  ,
```
.omc/interviews/
```
  ,
```
.omc/artifacts/
```
  ,
```
.omc/logs/
```
  , and relevant mode state artifacts (canonical
```
{mode}-state.json
```
  files under
```
.omc/state/
```
  that record a real run)
Record missing evidence explicitly. Missing evidence is not hidden by a good explanation.

解析
```
{{ARGUMENTS}}
```
、深度配置文件、源模式（
```
--from-diff|--from-artifacts
```
），并生成任务标识。
```
--from-pr
```
暂不支持；此工作流仅使用本地证据。
收集可用证据（运行时通过文件名启发式检测工件；绝不解析文件内容）：
- 本地Git diff和提交范围
- 已变更文件
- 测试/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
```
  文件，记录真实运行情况）
明确记录缺失的证据。缺失的证据不会被优质解释掩盖。

Phase 1: Initialize

Phase 1: 初始化

Call the

merge_readiness_start

tool with the change summary to seed state (the runtime parses the

--quick

--deep

profile (

--standard

is the default when neither flag is present; it is not a parsed token)). State shape:

json

{
  "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"
}

awaiting_content

is true until the AI submits the generated doc + MCQs via

merge_readiness_set_content

调用

merge_readiness_start

工具，传入变更摘要以初始化状态（运行时解析

--quick

--deep

配置文件（未提供任一标志时默认使用

--standard

；它不是一个可解析的令牌））。状态结构：

json

{
  "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"
}

awaiting_content

为true，直到AI通过

merge_readiness_set_content

提交生成的文档+MCQs。

Phase 2: Generate Explanation Doc + MCQs (AI content step)

Phase 2: 生成解释文档+MCQs（AI内容生成步骤）

Generate, from the actual diff + evidence (not templates):

A 5-section narrative: Why, What Changed, Tradeoffs, Risks Considered, Team Understanding.
A set of MCQs (one correct option each, with
```
correctOptionId
```
+ optional
```
rationale
```
):
- Up to the profile max rounds (quick 3 / standard 5 / deep 8)
- Distributed across the required dimensions
- Testing understanding of THIS change, not implementation trivia

Submit them with

merge_readiness_set_content

(requires an active gate from

merge_readiness_start

; it errors if no gate is active). Do not write the state JSON or invoke internal runtime functions. Invalid content is rejected with recoverable validation errors. The validated content is persisted in the authoritative session state.

Use

merge_readiness_report

to render the five sections, evidence, quiz progress, readiness, and merge boundary directly from state. It is read-only and does not create a file. Correct answers and rationales remain hidden until the attempt is complete; cancellation or override reveals only answered questions.

The Merge Boundary must say: "Passing means the human can explain the change. It does not approve merge, replace tests, replace review, or accept risk."

基于实际diff+证据（而非模板）生成：

包含5个部分的叙述：原因、变更内容、权衡、考虑到的风险、团队理解。
一组MCQs（每题一个正确选项，包含
```
correctOptionId
```
+ 可选的
```
rationale
```
）：
- 不超过配置文件的最大轮次（快速模式3/标准模式5/深度模式8）
- 覆盖所有必填维度
- 测试对本次变更的理解，而非实现细节琐事

通过

merge_readiness_set_content

提交（需要来自

merge_readiness_start

的活跃关卡；若无活跃关卡则报错）。请勿写入状态JSON或调用内部运行时函数。无效内容会被拒绝并返回可恢复的验证错误。验证后的内容会被持久化到权威会话状态中。

使用

merge_readiness_report

直接从状态渲染五个部分、证据、测试进度、就绪状态和合并边界。它是只读的，不会创建文件。正确答案和理由在尝试完成前保持隐藏；取消或覆盖仅会显示已回答的问题。

合并边界必须说明：“通过意味着人工能够解释该变更。它不代表批准合并、替代测试、替代审查或接受风险。”

Maintainer Override Authority

维护者覆盖权限

/merge-readiness --override <reason>

is accepted only when the MCP server launcher injects an authenticated principal in

OMC_MERGE_READINESS_AUTHENTICATED_PRINCIPAL

and includes that exact principal in the comma-separated

OMC_MERGE_READINESS_MAINTAINERS

allowlist. The caller-provided

session_id

selects the state record only; it is never override authority and is not recorded as

override_owner

仅当MCP服务器启动器在

OMC_MERGE_READINESS_AUTHENTICATED_PRINCIPAL

中注入已认证主体，且该主体包含在逗号分隔的

OMC_MERGE_READINESS_MAINTAINERS

允许列表中时，才接受

/merge-readiness --override <reason>

。调用者提供的

session_id

仅用于选择状态记录；它不具备覆盖权限，也不会被记录为

override_owner

。

Phase 3: Human Quiz Loop (MCQ, one-per-round, deep-interview style)

Phase 3: 人工测试循环（MCQs，逐轮进行，深度访谈风格）

Present each MCQ one-per-round via AskUserQuestion with the option ids/text as choices, then record the human’s selection with the

merge_readiness_record_answer

tool (questionId + optionId). The runtime scores it objectively and either advances to the next question or finalizes the gate (pass / paused / blocked).

Cover these dimensions before passing (quick = why/change/risk only):

why - why this change was worth doing
change - what behavior, workflow, interface, or maintenance model changed
tradeoff - what was chosen, deferred, or rejected and why
risk - which risks were considered and what remains risky
team - how the team should understand and maintain this change

Forbidden question types:

Function-name trivia
Line-number trivia
Variable-name recall
Private helper memorization
Any question whose answer does not help a reviewer explain the change

通过AskUserQuestion逐轮展示每个MCQ，将选项ID/文本作为选择项，然后使用

merge_readiness_record_answer

工具记录人工的选择（questionId + optionId）。运行时会进行客观评分，要么进入下一题，要么最终确定关卡结果（通过/暂停/阻塞）。

通过前需覆盖以下维度（快速模式仅需原因/变更/风险）：

why - 该变更值得实施的原因
change - 行为、工作流、接口或维护模型发生了哪些变更
tradeoff - 选择、推迟或拒绝了什么，以及原因
risk - 考虑到了哪些风险，哪些仍存在风险
team - 团队应如何理解和维护该变更

禁止的问题类型：

函数名称琐事
行号琐事
变量名称回忆
私有辅助函数记忆
任何答案无助于审查者解释变更的问题

Phase 4: Score Readiness (runtime-owned, objective)

Phase 4: 就绪状态评分（运行时负责，客观评分）

The runtime computes:

```
readiness_score
```
= correctness rate = (correct answers) / (answered answers), in [0, 1]
Per-dimension coverage = whether every required dimension has at least one answered MCQ

Gate results:

```
pass
```
: all required MCQs answered AND correctness rate >= threshold AND required dimensions covered
```
paused
```
: all required MCQs answered but correctness rate below threshold (or required dimension uncovered)
```
blocked
```
: missing minimal evidence (no diff/change signal)

Thresholds: quick

0.70

/ standard

0.80

/ deep

0.90

运行时计算：

```
readiness_score
```
= 正确率 =（正确答案数）/（已答题数），范围[0, 1]
维度覆盖情况 = 是否每个必填维度至少有一个已回答的MCQ

关卡结果：

```
pass
```
：所有必填MCQs已回答且正确率 >= 阈值且覆盖所有必填维度
```
paused
```
：所有必填MCQs已回答但正确率低于阈值（或未覆盖必填维度）
```
blocked
```
：缺失最小必要证据（无差异/变更信号）

阈值：快速模式

0.70

/ 标准模式

0.80

/ 深度模式

0.90

。

Phase 5: Crystallize Result

Phase 5: 固化结果

Persist these fields in the terminal session state and inspect them with

merge_readiness_report

Final readiness score
Dimension breakdown
Human answers
AI assessment
Result
Blocking or paused gap
Next step

将以下字段持久化到终端会话状态，并可通过

merge_readiness_report

查看：

最终就绪分数
维度细分
人工答案
AI评估
结果
阻塞或暂停的差距
下一步操作

Phase 6: Handoff

Phase 6: 交接

pass

State that the change may proceed to human merge approval.
Do not merge.

paused

State which explanation dimension is missing.
Recommend rereading or revising the report and rerunning
```
/merge-readiness
```
.

blocked

State which evidence must be produced before rerunning.

</Steps>

<Tool_Usage>

Use repository search and local artifacts for evidence intake before asking the human for context.
Use structured user questioning when available.
Use
```
merge_readiness_start
```
to initialize the gate,
```
merge_readiness_set_content
```
to submit the report + MCQs,
```
merge_readiness_record_answer
```
to record each selection, and
```
merge_readiness_report
```
to render the current audit record. Use state read/status/clear only for
```
.omc/state/merge-readiness-state.json
```
; never use generic state write to submit quiz content.
```
state_clear
```
routes merge-readiness through cancellation and preserves terminal state; pass the current session_id to avoid cancelling concurrent quizzes. </Tool_Usage>

<Escalation_And_Stop_Conditions>

User says stop/cancel/abort -> persist terminal
```
cancelled
```
state and stop.
Missing diff or change evidence ->
```
blocked
```
.
Human cannot explain a required dimension ->
```
paused
```
.
Readiness threshold reached and mandatory gates satisfied ->
```
pass
```
. </Escalation_And_Stop_Conditions>

<Final_Checklist>

Evidence intake completed
Missing evidence recorded
Explanation doc (5 sections) + MCQs submitted via merge_readiness_set_content
MCQs presented one-per-round via AskUserQuestion
Each answer correlated from marked AskUserQuestion output (objective scoring)
Questions avoided implementation trivia
Correctness rate calculated by the runtime
Result is
```
pass
```
,
```
paused
```
,
```
blocked
```
,
```
overridden
```
, or
```
cancelled
```
Merge Boundary is explicit
No direct implementation or merge performed </Final_Checklist>

如果结果为

pass

：

说明变更可进入人工合并批准环节。
请勿执行合并操作。

如果结果为

paused

：

说明缺失哪个解释维度。
建议重新阅读或修订报告，然后重新运行
```
/merge-readiness
```
。

如果结果为

blocked

：

说明重新运行前必须提供哪些证据。

</Steps>

<Tool_Usage>

在向人工询问上下文信息前，先使用仓库搜索和本地工件进行证据收集。
尽可能使用结构化用户提问。
使用
```
merge_readiness_start
```
初始化关卡，使用
```
merge_readiness_set_content
```
提交报告+MCQs，使用
```
merge_readiness_record_answer
```
记录每个选择，使用
```
merge_readiness_report
```
渲染当前审计记录。仅对
```
.omc/state/merge-readiness-state.json
```
使用状态读取/状态/清除操作；绝不要使用通用状态写入来提交测试内容。
```
state_clear
```
通过取消操作处理合并就绪状态并保留终端状态；传入当前session_id以避免取消并发测试。 </Tool_Usage>

<Escalation_And_Stop_Conditions>

用户说stop/cancel/abort -> 持久化终端
```
cancelled
```
状态并停止。
缺失diff或变更证据 ->
```
blocked
```
。
人工无法解释必填维度 ->
```
paused
```
。
达到就绪阈值且满足强制关卡要求 ->
```
pass
```
。 </Escalation_And_Stop_Conditions>

<Final_Checklist>

证据收集完成
缺失证据已记录
解释文档（5个部分）+ MCQs已通过merge_readiness_set_content提交
MCQs已通过AskUserQuestion逐轮展示
每个答案与标记的AskUserQuestion输出关联（客观评分）
问题未涉及实现细节琐事
运行时已计算正确率
结果为
```
pass
```
、
```
paused
```
、
```
blocked
```
、
```
overridden
```
或
```
cancelled
```
合并边界已明确说明
未执行直接实现或合并操作 </Final_Checklist>

Recommended Delivery Pipeline

Autopilot Bridge

Autopilot桥接

Autopilot may call this workflow after QA/validation when configured:

jsonc

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

autopilot.understandingGate

is a deprecated compatibility alias for

autopilot.mergeReadiness

. </Advanced>

Task: {{ARGUMENTS}}

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

jsonc

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

autopilot.understandingGate

是

autopilot.mergeReadiness

的已弃用兼容别名。 </Advanced>

Task: {{ARGUMENTS}}

merge-readiness

Original

Translation

Phase 0: Evidence Intake

Phase 0: 证据收集

Phase 1: Initialize

Phase 1: 初始化

Phase 2: Generate Explanation Doc + MCQs (AI content step)

Phase 2: 生成解释文档+MCQs（AI内容生成步骤）

Maintainer Override Authority

维护者覆盖权限

Phase 3: Human Quiz Loop (MCQ, one-per-round, deep-interview style)

Phase 3: 人工测试循环（MCQs，逐轮进行，深度访谈风格）

Phase 4: Score Readiness (runtime-owned, objective)

Phase 4: 就绪状态评分（运行时负责，客观评分）

Phase 5: Crystallize Result

Phase 5: 固化结果

Phase 6: Handoff

Phase 6: 交接

Recommended Delivery Pipeline

推荐交付流水线

Autopilot Bridge

Autopilot桥接