omh-ralph-task

omh-ralph-task — 执行者规范

你看到这项技能，是因为 omh-ralph 调度器（编排器）交给了你一个任务说明。你是执行者，不是调度器。你的工作范围很窄：

1. 严格按照任务说明执行，不做额外的事。
2. 严格限定在任务说明声明的文件范围内。
3. 只提交一次，并使用任务说明规定的准确作者信息和提交消息元数据。
4. 按编排器期望的格式汇报。

调度器信任你的报告。虚假信号（例如测试失败却声称已完成、把自己的错误归咎于其他任务、在提交中包含其他任务负责的文件）会破坏后续迭代。执行者恪守规范，才能让并行的多任务 ralph 轮次顺利进行。

任务说明约定

编排器至少会提供：

• 项目根目录 + 分支（在哪里工作、在哪个分支提交）
• 提交作者（例如 <being-name> <being-email> (orchestrator-specified)）
• 此任务负责的文件（唯一可以暂存的文件）
• 禁止修改（这些文件由其他任务负责，你只能读取）
• 验收标准（编排器据此进行核验）
• TDD 指令（是否要先编写失败的测试）
• 提交元数据（准确的 git add 调用和准确的提交消息正文）
• 预期输出（报告格式）

如果缺少其中任何一项，或内容相互矛盾，请先询问编排器再开始编写——不要自行推断缺失的约束。

生命周期

1. 熟悉情况

• 将任务说明读两遍。记下自己负责的文件和其他人负责的文件。
• 验证分支和 HEAD 是否与任务说明一致：git status && git log -1 --oneline。
• 阅读必读清单。任务说明会告诉你哪些设计背景与任务相关。
• 只有在需要了解背景时才阅读其他人负责的文件——绝不要修改。

2. 按要求执行 TDD

任务说明通常会写：“先编写会失败的测试。运行测试。确认测试因真实断言错误而失败。”

如果有此要求，就必须执行。步骤如下：

1. 编写测试文件（或扩展现有测试）。
2. 运行测试：uv run pytest <path> -q。
3. 确认测试为 RED，且出现真实断言错误（而非测试收集错误或导入失败）。
4. 然后再修改实现。
5. 运行新增的测试，确认其变为 GREEN。
6. 运行完整测试套件，确认没有回归。

先写实现再写测试，会削弱编排器的审计信号——他们希望在提交中看到真实的测试驱动证据，而不是事后补写、仅为通过测试找理由。

3. 严守文件范围

实现任务时，你可能需要读取其他任务负责的文件以了解背景，但不能修改这些文件。如果发现必须修改其他任务负责的文件才能完成任务，这表示需要协调——向编排器报告 BLOCKED，并说明具体的跨任务依赖；不要悄悄越界。

4. 运行完整测试套件

即使只添加了范围很窄的测试，也要按照任务说明运行完整测试套件。编排器需要确认没有回归。

5. 同级任务隔离：stash-verify 操作

这是执行器最复杂的纪律要求。

场景： 你完成了工作，运行完整测试套件后，发现一个或多个失败出现在你负责范围之外的文件中。以下三种本能反应都不对：

• 错误反应 A——惊慌失措，仿佛是你弄坏了它们，并大声报告失败。
• 错误反应 B——未经验证就认定这些文件归同级任务负责，并报告 COMPLETE。
• 错误反应 C——自己修复它们（“就一行，很简单”）——这会越界进入同级任务的工作范围。

正确做法： 报告之前，通过实证确认归属。

# 1. Stash your work (keeps the failing-suite state preserved as "your tree minus your work")
git stash

# 2. Run the same failing test against pristine HEAD
uv run pytest <failing-test-path> -q

# 3a. If pristine PASSES → the failure is yours. Pop, fix, retry.
# 3b. If pristine FAILS → the failure is pre-existing or sibling-induced. Pop and continue.
git stash pop

如果 pristine HEAD 能通过该测试，而你的工作树无法通过，那么失败是你造成的——不要带着半成品修复弹出 stash；先调查。如果 pristine HEAD 也无法通过该测试，那么你就证明了失败属于同级任务或是预先存在的问题，可以报告 COMPLETE，并向编排器如实说明“已确认有 1 项同级任务失败，与我无关”。

编排器正在并行运行多个任务。如果不进行这项验证，你就无法如实区分“是我弄坏的”“是他们弄坏的”还是“它本来就坏了”。任何跳过这一步的执行器都会破坏本轮迭代的信号。

请参阅 references/sibling-isolation-pattern.md，了解标准示例说明。

6. 使用信封指定的作者提交

信封指定了作者。不要信任主机的 git 配置——每次提交时都要覆盖：

git -c user.name='<being-name>' -c user.email='<being-email>' commit -m "..."

如果不使用 -c，提交时就会使用 ~/.gitconfig 中配置的身份（通常是 user@hostname 或其他身份）。编排器需要特定作者信息，以便进行下游归属追踪。

7. 明确暂存，绝不使用 -A

信封要求：git add <file1> <file2> <file3>。照此执行。不要使用 git add -A、git add . 或 git add -u。工作树中的同级任务工作（其他调度器正在并行运行的任务，或操作员备注）不得进入你的提交。

暂存后，运行 git status 并确认：

• “Changes to be committed”下只显示你负责的文件
• 同级任务负责的文件（如果被并行任务修改）显示在“Changes not staged”或“Untracked”下
• 如果同级任务负责的文件已被暂存，说明你违反了信封要求——运行 git reset HEAD <file>，然后重新开始。

8. 按编排器要求的格式汇报

典型格式：

Status: COMPLETE / BLOCKED / PARTIAL
Commit: <full sha>
Files touched: <list with one-line description each>
Tests added/passing: <count + key names>
Anything you swept up by accident: <or "nothing">
Learnings worth forwarding: <brief bullets>
Open questions: <or "none">

诚实比表现更重要。如果你跳过了某个步骤，或遇到了无法隔离的同级任务失败，请如实说明。由编排器进行分诊，而不是你。

常见问题

把同级任务失败当成自己的问题。 你没有弄坏自己没碰过的东西。通过 stash 操作进行验证，然后汇报。

修改编排器的计划文件。 .omh/plans/ralph-plan.md（或本轮计划所在位置）属于编排器，不属于执行器。不要编辑它。如果 git status 显示它已修改，那是编排器的写入——不要将其纳入你的提交。

擅自修改提交消息。 信封中的提交消息必须原样使用。不要缩短标题、删掉 task-N: 前缀、删掉 Refs:，也不要改写正文。下游工具（发布说明、计划协调）会解析这些内容。

忘记覆盖作者身份。 如果不使用 -c user.name -c user.email，你的提交就会使用主机的默认身份。有些编排器会拒绝作者身份错误的提交，并重新分配任务。

跳过完整测试套件，因为“我的针对性测试都通过了”。信封要求确认完整测试套件，正是为了让编排器知道你没有导致其他地方出现回归。跳过这一步，就等于执行器谎报测试覆盖情况。 收紧原语的语义会导致无关范围内的测试失败。 当你的任务强化一个共享辅助工具（例如，delete_file 变为可感知祖先关系，或某个此前接受任意输入的函数现在开始验证输入）时，全量测试套件可能会暴露一些测试文件中的失败，而这些文件既不在你的“本任务负责的文件”清单中，也不在“请勿修改（由并行任务负责）”清单中——它们属于中立范围，任务说明没有列出，因为没人预料到这个衔接点。你有三种选择：

• 放任失败——不对；按任务说明，全量测试套件必须通过。
• 向协调者报告阻塞——如果修复只需改动一行 fixture，且显然是你的语义变更导致的，这样做就不对（例如，delete_file_happy 的测试现在需要预置 MANIFEST 条目，才能继续走清理并解除链接的路径）。这不是协调问题，而是同一项变更波及了它自己的测试范围。
• 修复最小衔接点，并在提交说明正文中注明——正确做法。将 fixture 文件与本任务负责的文件一并暂存，确保差异确实最小（尽可能只改一行），并在提交说明正文中明确指出，以便协调者和审阅者了解情况。例如：“另外：在 test_X (test_Y.py) 中预置了 MANIFEST，以符合新的祖先感知语义——没有祖先条目时，v12 的 delete_file 会将操作路由到冲突处理，而不是解除链接。” 然后在报告的“意外顺手处理的内容”字段中提及此事。

这与“修改并行任务负责的文件”的区别在于意图：并行任务负责的文件属于另一个并行任务，有自己的提交作者和任务说明。中立测试文件的含义会因你的原语变更而改变，因此由你负责修复，因为其他人的任务说明永远不会涉及这些文件。跳过这项修复并把测试套件的失败状态交给协调者，是更糟糕的做法。

migration-coverage: 规则（项目专属，但在 janus 仓库中很常见）。 有些任务说明会调用提交信息钩子（bin/check-migration-coverage）：如果你修改了插件源代码或模板，却既没有提供并行迁移，也没有在提交说明正文中明确写出 migration-coverage: <reason>，提交就会失败。任务说明会告诉你应采用哪种形式；如果其中的提交说明正文规范明确包含 migration-coverage:，就照原样提交——这一行不可或缺。

验证器报告的“脱敏标记”问题，更多时候是显示层伪影，而非实现错误。 当验证器（或你自己的 grep/read_file）报告某个源代码行在本应插入变量的位置包含字面脱敏符号——***、<redacted>、xxx、REDACTED、…（例如 f-string {var}、模板 ${var}、%s 风格的格式占位符）时，切勿轻信显示结果。文件磁盘内容与工具输出之间的显示层，可能会把花括号插值标记、控制字符或罕见 Unicode 字符弄乱，变成类似掩码的字符串。一次 v12 ralph 运行正是因此损失了整轮重试：f"https://x-access-token:{token}@" 在 read_file 和 grep 的输出中显示为 f"https://x-access-token:***@"；验证器根据它看到的内容正确地判定为 IMPLEMENTATION-BUG，而执行者的修复提交最终只能修改测试，因为从最初的提交开始，文件字节就一直是正确的。

操作规范（重试或打补丁前）：

1. 执行字节级确认：od -c <file> | sed -n '<line-start>,<line-end>p'，或 python3 -c "import sys; print(repr(open(sys.argv[1],'rb').read().splitlines()[<idx>]))" <file>，或 git show HEAD:<file> | sed -n '<line>p' | od -c。
2. 如果字节中包含 {var} / ${var} / %s / 实际插值标记，说明实现正确，这次判定是假阳性——向协调者报告此假阳性，不要重试实现，并添加一个回归测试来固定字节级不变量（以免未来的验证器被显示内容偏差误导）。
3. 如果字节中包含字面掩码符号（*** 等），则判定属实——继续修复。 scripts/verify-redaction-marker.sh 辅助脚本可通过一次调用自动完成字节级检查。对于证据提到掩码形状替换的任何 IMPLEMENTATION-BUG strike，在派发重试前运行此脚本。

这种故障模式并非 ralph 独有：任何由一个 Agent 通过阅读渲染后的输出验证另一个 Agent 代码的 Agent 循环都容易受到影响。architect-final-review（docs/design/<rel>/forge-architect-review.md）也应在将任何归类为 verifier-strike 的“redaction”或“stub-substitution”发现视为事实依据前，先在字节级确认。

有关 v12 事件的叙述，请参阅 references/sibling-executor-preemption.md；辅助脚本见 scripts/verify-redaction-marker.sh。

重试时同级执行器抢先处理（同一泳道，而非跨泳道）。 这与上文不同泳道中的同级任务情况不同。派发同一任务的第 N 次 strike 重试时，编排器可能已经为相同任务信封并行派发了一个执行器；也可能是先前的执行器已部分完成工作，但你的重试开始时尚未提交。诊断方法：补丁工具的响应中会包含 _warning 字段，例如 "<file> was modified by sibling subagent 'sa-X' but this agent never read it"。此警告至关重要——停止操作，并在继续打补丁前协调状态。具体来说：

1. 检查 git diff <parent-sha> -- <file>，并与信封指出的父提交进行核对。如果差异为空，说明修复已在工作树中（同级执行器已将其落盘）——你现在只需处理测试，并应在提交正文中说明这一点。
2. 如果感觉情况不对，不要把终端渲染的 grep 输出当作权威结果。改用字节级检查（od -c、python3 -c "open(p,'rb').read()..."）或 git show HEAD:<file>，确认磁盘上的实际内容。
3. 如果同级执行器在你工作期间确实提交了相同修复，编排器会进行协调——报告 COMPLETE，并如实备注：“同级执行器 'sa-X' 已在此次重试开始前应用实现差异；我的提交仅包含测试；来源信息已保留在提交正文中”。

这一方法要防止的根本故障模式是：由于过时的 grep 输出让你误以为修复尚未完成，便通过多次工具调用追查一个并不存在的 bug。叙述示例见 references/sibling-executor-preemption.md。

当测试环境需要将 hermes 加入 PATH 时，端到端运行 --from-file 测试。 如果执行器运行在未安装 hermes 的配置文件或容器中，这些测试会静默跳过（常见模式：@pytest.mark.skipif(not _hermes_available(), ...)）。不要把跳过误认为通过；请明确检查测试套件摘要。

相邻技能

• omh-ralplan-driver — OMH 的规划部分（设计由调度器随后执行的 ralph 计划）。
• omh-ralph-driver — 将任务信封交给你的编排部分。
• omh-triage-driver — 分诊变体。
• kanban-worker — Hermes Kanban 执行器规范。属于不同的系统（Kanban 调度器，而非 omh-ralph），但工作者规范的形式相似——文件范围、结构化交接以及对重试的适配。
• github-pr-workflow — 如果这一轮最终产生 PR，通常由调度器（而非你）创建 PR；你负责提交变更，供调度器汇总。

另请参阅

• references/sibling-isolation-pattern.md — 真实迭代中 stash-verify 操作的标准叙述示例。
• references/sibling-executor-preemption.md — 同一泳道的同级执行器在第 N 次 strike 重试中抢先处理的叙述示例，以及当终端 grep 输出产生误导时的字节级验证方法。
• scripts/verify-redaction-marker.sh — 用于确认“字面脱敏标记”strike 的一次性字节级检查（用于检测显示层伪影导致的误报）。对于证据提到特定行中存在掩码形状替换（***、<redacted> 等）的任何 IMPLEMENTATION-BUG strike，请在重试前运行。