OmX 验证与排序提示契约实战：证据驱动的验证循环、依赖顺序执行与停止条件

本指南围绕 OmX（oh-my-codex）提示体系中的核心片段 core-verification-and-sequencing.md 展开，它定义了所有 Agent 提示表面（根级 AGENTS 编排、Executor/Planner/Verifier 角色提示）共用的「验证循环 + 执行排序」行为契约。读完本文，你将掌握如何把一条模糊的完成声明拆成可验证的声明与成功标准，如何为编码任务选择最小且新鲜的验证手段，如何用顺序执行与局部覆盖避免依赖任务提前启动，以及如何在证据充分后及时停止、避免为措辞或非必要证据空转。

这个片段在 OmX 提示体系中的位置

OmX 的提示行为受 prompt-guidance-contract.md 约束——一份面向贡献者的「行为提示契约」，其目的是把根级编排（templates/AGENTS.md）、规范角色提示（prompts/*.md）、工作流技能（skills/*/SKILL.md）与生成的 Codex 配置（src/config/generator.ts）对齐到统一的提示指导原则。契约定义了 5 个核心行为模式：

1. 结果优先、以成功标准为先导的提示；
2. 简洁的协作风格与多步任务 preamble；
3. 对清晰、低风险、可逆下一步的自动跟进（AUTO-CONTINUE）；
4. 局部任务更新覆盖，保留此前不冲突的指令；
5. 证据预算、验证与显式停止规则。

本文的主角 core-verification-and-sequencing.md 正是第 5 个模式的共享片段，同时补充了「依赖任务顺序执行」与「局部覆盖」两条执行排序规则。它位于 docs/prompt-guidance-fragments/ 目录——该目录还包含 core-operating-principles.md（通用操作原则）、executor-constraints.md、planner-constraints.md、verifier-constraints.md 等按角色拆分的约束片段。

关键点：这些片段不是孤立文档，而是通过 HTML 注释标记（marker）注入到实际运行的提示表面中的。片段原文与目标表面之间由回归测试保证逐字同步（详见后文「从片段到运行时表面的同步机制」）。

验证循环：声明 → 最小验证 → 读输出 → 带证据汇报

片段第一条给出了 OmX 验证循环的完整形态：

Verification loop: define the claim and success criteria, run the smallest validation that can prove it, read the output, then report with evidence. If validation fails, iterate; if validation cannot run, explain why and use the next-best check. Keep evidence summaries concise but sufficient.

拆解为四个必须依次完成的动作：

步骤	动作	反例
1	定义声明与成功标准（define the claim and success criteria）	直接开跑，声称"应该没问题了"
2	运行能证明它的最小验证（run the smallest validation that can prove it）	跑全套无关测试、抓无关工具输出
3	完整读取输出（read the output）	只看到绿色对勾就跳过，不看失败详情
4	带证据汇报（report with evidence）	用"实现了""修好了"这类无证据措辞收尾

循环的控制流同样明确：验证失败就迭代；验证无法运行时，不能假装通过——必须解释原因并采用「次优检查」（next-best check）。证据摘要要求「简洁但充分」（concise but sufficient），这同时约束了汇报的长度与密度。

在角色提示中，这条循环被具体化为可执行的 5 步流程。prompts/verifier.md 的 <execution_loop> 与之逐条对应：

1. 陈述必须被证明的声明与验收标准；
2. 检查相关实现、diff、产物与既有证据；
3. 运行或复核能直接证明每个标准的最小检查，并读取完整结果；
4. 调和冲突证据、识别缺口与风险，只在得到 grounded 结论时停止；
5. 若证明不可得，指出缺失的证明源与已获得的最强有界证据。

Verifier 的输出契约把「带证据汇报」结构化成了固定四段：Verdict（PASS / FAIL / PARTIAL）、Evidence（每条证据注明证明或证伪了哪条标准）、Gaps（缺失或不完整的证明）、Risks（剩余不确定性）。这意味着验证循环的产出不是一句话结论，而是「声明 → 证据 → 缺口」的完整链，每一条都可追溯到具体命令或产物。

顺序执行与前置校验：依赖任务必须串行

片段第二条是一条硬性的执行排序规则：

Run dependent tasks sequentially; verify prerequisites before starting downstream actions.

有依赖关系的任务必须顺序执行，且启动下游动作之前必须先验证前置条件。这避免了并行/提前启动导致的竞态与返工——例如下游任务依赖上游产出的文件、状态或合并结果时，未验证前置就启动下游会直接消费脏数据。

这条规则在 src/hooks/prompt-guidance-contract.ts 的根模板契约中以正则形式固化：do not skip prerequisites|task is grounded and verified，即 AGENTS 表面必须包含「不得跳过前置条件 / 任务须已 grounded 并验证」的表述，否则契约测试失败。

场景化的佐证在角色提示的 <scenario_handling> 中：prompts/executor.md 明确要求——当用户说 make a PR targeting dev 时，只在本地结果已验证之后才准备下游 PR 路径；当用户说 merge to dev if CI green 时，必须先验证确切的 CI 条件再合并，且「不能把用户的请求本身当作证明」。这正是「验证前置条件后再执行下游动作」在真实工作流中的体现：合并是下游动作，CI 绿是前置条件，二者之间的校验不可省略。

局部任务更新：作用域覆盖而非全局重写

片段第三条定义了任务更新（task update）的处理边界：

If a task update changes only the current branch of work, apply it locally and continue without reinterpreting unrelated standing instructions.

当一条新指令只影响当前工作分支时，把它当作**局部覆盖（local override）**应用，然后继续——但不得顺带重新解释无关的常驻指令（standing instructions，如安全边界、输出契约、角色身份）。这避免了「用户改了个小需求 → Agent 顺手推翻了其他既有约定」的连锁漂移。

同一语义贯穿整个片段家族：

• executor-constraints.md："Treat newer user instructions as local overrides for the active task while preserving unrelated acceptance criteria"（保留无关验收标准）；
• planner-constraints.md："local overrides for the active planning branch"（只作用于当前规划分支）；
• verifier-constraints.md 与 prompts/verifier.md 的 <verification_loop>："当新指令只改变验证目标或报告形态时，局部应用它，同时保留无关验收标准与「每条声明到证据/显式证明缺口」的可追溯性"；
• core-operating-principles.md 补充了同线程新证据规则：用户给出新的日志、堆栈或测试输出时，把它当作当前事实源，据此重新评估旧假设，除非用户重申，否则不要锚定旧证据。

契约测试同样为此设防：src/hooks/prompt-guidance-contract.ts 要求 AGENTS 表面匹配 local overrides?.*non-conflicting instructions。

编码工作的验证阶梯：targeted tests → typecheck/lint/build/smoke

片段第三条的后半部分定义了编码任务专属的验证路径：

For coding work, prefer targeted tests for changed behavior, then typecheck/lint/build/smoke checks when applicable; do not claim completion without fresh evidence or an explicit validation gap.

关键约束是新鲜证据（fresh evidence）：声称完成必须有刚跑出来的验证结果，而不是"上次跑过"或"应该能过"。验证手段按优先级递减：

1. 针对变更行为的定向测试（targeted tests）——优先，最小且直接；
2. 适用的 typecheck / lint / build / smoke 检查——作为第二层；
3. 若完整验证成本过高，用最小 smoke test；
4. 若验证确实无法运行，必须给出显式原因与次优检查（explicit validation gap）。

这条阶梯在 prompts/executor.md 中有最具体的落地形态。它的 <execution_loop> 第 4 步要求"运行针对变更行为的定向检查，然后检查输出并审查 diff"，第 5 步要求"移除临时/调试改动，持续到验证通过或留下精确的 blocker"。其 <output_contract> 的 ## Verification 小节强制按三类命令汇报证据：

## Verification
- Diagnostics or checks: `[command]` → `[result]`
- Tests: `[command]` → `[result]`
- Build/typecheck when applicable: `[command]` → `[result]`

每条都是「命令 → 结果」的成对结构，与"带证据汇报"的要求完全一致。prompt-guidance-contract.md 的「Evidence budgets, validation, and explicit stop rules」一节进一步概括了同一原则：编码提示应要求具体的验证手段，包括针对变更行为的定向测试、适用的 typecheck/lint/build 检查、完整验证太贵时的最小 smoke test，以及验证无法运行时的显式原因与次优检查。

证据预算与停止条件：不要为措辞或非必要证据空转

片段第四条是验证循环的停止规则：

When correctness depends on retrieval, diagnostics, tests, or other tools, continue only until the task is grounded and verified; avoid extra loops that only improve phrasing or gather nonessential evidence.

工具使用应当有明确的证据预算：只有当正确性依赖于检索、诊断、测试或其他工具时才继续使用工具，一旦任务 grounded 并验证完成就停止。两条典型的空转要避免：

• 只为改善措辞（improve phrasing）而反复改写——这不是验证，是自我消耗；
• 收集非必要证据（nonessential evidence）——与声明无关的工具输出、重复的检索、冗余的确认。

core-operating-principles.md 把这一原则扩展为两条可操作规则：

Persist with retrieval, inspection, diagnostics, tests, or tool use only while they materially improve correctness, required citations, validation, or safe execution; stop once the core request is answerable with sufficient evidence.

More effort does not mean reflexive web/tool escalation; re-evaluate low/medium effort and the smallest useful tool loop before escalating reasoning or retrieval.

即：只有工具能实质提升正确性、引证、验证或安全执行时才继续；「更努力」不等于「反射式升级到联网/更多工具」——在升级推理或检索前，先重新评估是否可以用最小工具循环解决。

Verifier 侧同样强调「收集真正重要的证明，而非无关工具输出」（见 verifier-constraints.md 与 src/hooks/prompt-guidance-contract.ts 中的 proof that matters|tool churn 正则），并且"持续检查直到 verdict grounded，或必需的证明源不可用"。

配套的还有一条措辞纪律——绝对语言规则（见 prompt-guidance-contract.md）：MUST、NEVER、ALWAYS、only 等绝对措辞只用于真正的不变量（安全/安全边界、副作用约束、必填输出字段、工作流状态迁移、团队/ralph 门禁、产品契约）；而对于"是否再搜索一次、是否澄清、是否继续迭代"这类判断型决策，应该用决策规则与停止条件而非绝对措辞。验证循环中"何时停止"正是典型的判断型决策，所以它被写成"grounded 即停"的规则，而不是"必须永远跑下去"或"跑一次就够"。

从片段到运行时表面的同步机制

理解该片段的价值，还要知道它在仓库中如何被强制同步。片段以 HTML 注释标记注入 AGENTS 表面，标记区间为 <!-- OMX:GUIDANCE:VERIFYSEQ:START --> 与 <!-- OMX:GUIDANCE:VERIFYSEQ:END -->（见 templates/AGENTS.md 第 148–155 行附近）。回归测试 src/hooks/tests/prompt-guidance-fragments.test.ts 的机制很直接：

• 读取 docs/prompt-guidance-fragments/core-verification-and-sequencing.md（连同 operating 与 specialist-routing 两个片段）并 .trim()；
• 遍历 listTrackedAgentSurfaces() 得到的所有受管表面；
• 用 assert.equal 做逐字节字符串相等断言：表面中 VERIFYSEQ:START 与 VERIFYSEQ:END 之间的内容必须与片段文件完全一致。

也就是说，任何一处表面（AGENTS 模板、生成的配置）如果与片段漂移哪怕一个字符，测试就会失败。同样的同步机制也覆盖 Executor、Planner、Verifier 的角色约束片段（EXECUTOR:CONSTRAINTS、PLANNER:CONSTRAINTS、VERIFIER:CONSTRAINTS 等标记），并分别断言 prompts/executor.md、prompts/planner.md、prompts/verifier.md。

行为层面的契约则由 src/hooks/prompt-guidance-contract.ts 以正则清单维护。与本文主题直接相关的根模板模式包括：

正则模式	强制的行为
do not skip prerequisites|task is grounded and verified	前置校验与 grounded 门槛
coding work.*targeted tests|targeted tests for changed behavior	编码工作的定向测试优先
validation.*cannot run|validation gap	验证不可运行时的显式缺口声明
local overrides?.*non-conflicting instructions	局部覆盖语义

角色级契约进一步细分：Executor 必须匹配 task is grounded and verified，Planner 必须匹配 plan is grounded\|requirements.*affected resources.*validation commands.*failure behavior（验证命令与失败行为入计划），Verifier 必须匹配 claim.*success criteria.*validation evidence.*gaps.*stop condition 与 proof that matters|tool churn。

如何验证与演进这套契约

若你作为贡献者修改了本片段或任何提示表面，prompt-guidance-contract.md 给出了最小验证命令集。构建并运行提示契约相关测试：

npm run build
node --test \
  dist/hooks/__tests__/prompt-guidance-contract.test.js \
  dist/hooks/__tests__/prompt-guidance-wave-two.test.js \
  dist/hooks/__tests__/prompt-guidance-scenarios.test.js \
  dist/hooks/__tests__/prompt-guidance-catalog.test.js \
  dist/hooks/__tests__/skill-guidance-contract.test.js \
  dist/hooks/__tests__/prompt-guidance-fragments.test.js \
  dist/hooks/__tests__/explicit-terminal-stop-docs-contract.test.js

其中 prompt-guidance-fragments.test.js 正是守护本片段与受管表面逐字同步的关键用例；若改动了片段内容，必须同步刷新所有注入表面后重跑，否则断言失败。涉及更广的提示/技能变更时，契约文档建议直接跑全量 npm test。

修改提示文本时还需对照 prompt-guidance-contract.md 的贡献者清单：保留五个核心行为（结果优先、简洁协作/preamble、低风险跟进、局部覆盖、证据验证/停止规则）、保持角色措辞与行为语义对齐、行为变化时同步更新 continue / make a PR / merge if CI green 等场景示例及其测试、绝对语言只用于真正不变量，并同步更新回归覆盖。

小结

core-verification-and-sequencing.md 虽短，却是 OmX 提示行为契约中承上启下的枢纽：它把「验证」从一句"记得测试"升级为声明—成功标准—最小验证—读输出—带证据汇报的闭环，把「执行」约束为前置校验后的串行推进，把「更新」限定为局部覆盖，并把「停止」定义为 grounded 且证据充分即停。这些规则经由 marker 注入与回归测试固化进 AGENTS 模板，再在 Executor/Planner/Verifier 角色提示中细化为可执行的循环步骤与输出契约——从「证据预算」到「PASS/FAIL/PARTIAL + Evidence/Gaps/Risks 四段式裁决」，整条链路都可以在当前仓库中逐层追查验证。