omh-ralph-task

omh-ralph-task — エグゼキューターの規律

このスキルが表示されているのは、omh-ralph のディスパッチャー（オーケストレーター）からタスクの指示一式が渡されたためです。あなたはエグゼキューターであり、ディスパッチャーではありません。担当範囲は限定されています。

1. 指示一式に指定されたタスクだけを、正確に実行します。それ以上は行いません。
2. 指示一式で定められたファイルの範囲を守ります。
3. 指示一式で指定された作成者とメッセージのメタデータを正確に用いて、1 回だけコミットします。
4. オーケストレーターが期待する形式で報告します。

ディスパッチャーはあなたの報告を信頼します。誤った報告（テストが失敗したのに COMPLETE と主張する、変更を兄弟タスクのせいにする、兄弟タスクが所有するファイルをコミットに含めるなど）は、イテレーションの残りを損ないます。エグゼキューター側で規律を守ることが、並行する複数タスクの ralph ラウンドを実行可能にします。

タスク指示一式の契約

オーケストレーターは、最低限、次の情報を提供します。

• プロジェクトのルートとブランチ（作業場所と、コミット先のブランチ）
• コミット作成者（例：<being-name> <being-email> (orchestrator-specified)）
• このタスクが所有するファイル（ステージできる唯一のファイル）
• 変更禁止のファイル（兄弟タスクが所有するため、読み取り専用）
• 受け入れ基準（オーケストレーターが検証する基準）
• TDD の指示（先に失敗するテストを書くかどうか）
• コミットのメタデータ（正確な git add の実行内容と、正確なコミットメッセージ本文）
• 期待される出力（報告の形式）

これらの情報に不足や矛盾がある場合は、作業を始める前にオーケストレーターに確認してください。不足している制約を推測で補ってはいけません。

ライフサイクル

1. 状況を把握する

• 指示一式を 2 回読みます。自分が所有するファイルと、他者が所有するファイルの両方を確認します。
• ブランチと 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 の手順

これは、実行者が守るべき規律の中でも特に難しいものです。

**シナリオ：**作業を終えて全テストスイートを実行したところ、担当範囲外のファイルで1つ以上の失敗が発生しました。反射的に取ってしまいがちな次の3つの対応は、いずれも誤りです。

• 誤った対応 A — パニックになり、自分が壊したかのように大げさに失敗を報告する。
• 誤った対応 B — 確認せずに兄弟タスクの担当だと決めつけ、COMPLETE と報告する。
• 誤った対応 C — 自分で修正する（「1行だけだから簡単」）。兄弟タスクの領域に踏み込みます。

**正しい対応：**報告する前に、実証的に担当範囲を確認します。

# 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

クリーンな HEAD ではテストが通り、作業ツリーでは失敗する場合、その失敗はあなたのものです。中途半端な修正のまま stash を戻してはいけません。原因を調査してください。クリーンな HEAD でもテストが失敗する場合、その失敗が兄弟タスクによるものか、以前から存在していたものだと確認できています。そのうえで、「自分のものではない兄弟タスクの失敗を1件確認した」と正直に添えて、COMPLETE と報告できます。

オーケストレーターは複数のタスクを並行して実行しています。この確認をしない限り、「自分が壊した」「他の人が壊した」「もともと壊れていた」を正直に区別できません。この手順を省略する実行者は、全員がイテレーションの判断材料を損ないます。

説明付きの標準例については、references/sibling-isolation-pattern.md を参照してください。

6. エンベロープで指定された作成者でコミットする

作成者はエンベロープで指定されています。ホストの git 設定を信用せず、コミットごとに上書きしてください。

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

-c を付けないと、~/.gitconfig に設定された作成者（多くの場合は user@hostname か、別の ID）でコミットされます。オーケストレーターは、後続の帰属処理のために特定の作成者を想定しています。

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 を付けないと、ホストのデフォルト ID でコミットされます。作成者が間違っているコミットを拒否し、タスクを再割り当てするオーケストレーターもあります。

**「自分の範囲のテストは通る」からと、全テストスイートの実行を省略する。**オーケストレーターが遠く離れた箇所のリグレッションを起こしていないと確認できるよう、エンベロープでは全テストスイートの確認を求めています。この手順を省くのは、実行者がテスト範囲について虚偽の報告をすることと同じです。 プリミティブのセマンティクスを厳格化すると、中立領域のテストが失敗することがあります。 共有ヘルパーを強化するタスク（例：delete_file が祖先を考慮するようになる、以前は任意の入力を受け付けていた関数が検証を行うようになる）では、全テストスイートの実行時に、「このタスクの担当ファイル」リストにも「変更禁止（兄弟タスクの担当）」リストにも含まれていないテストファイルで失敗が見つかることがあります。これは中立領域であり、誰もその境界部分を想定していなかったため、エンベロープに列挙されていません。選択肢は3つあります。

• 壊れたままにする — 誤りです。エンベロープの要件では、全テストスイートが通る必要があります。
• オーケストレーターに対応不能として差し戻す — セマンティクスの変更が明らかな原因で、修正が1行のフィクスチャ更新で済む場合は誤りです（例：delete_file_happy のテストで、クリーンな unlink 経路を通し続けるには MANIFEST エントリーのシードが必要になる場合）。これは調整の問題ではなく、同じ変更が自身のテスト範囲にも波及しているだけです。
• 最小限の境界部分を修正し、コミット本文に記載する — 正解です。担当ファイルと一緒にフィクスチャファイルをステージし、差分は真に最小限（可能なら1行）に抑え、オーケストレーターやレビュアーが確認できるよう、コミット本文に明記します。例：「補足：新しい祖先考慮セマンティクスに合わせて、test_X（test_Y.py）に MANIFEST をシードしました。祖先エントリーがない場合、v12 の delete_file は unlink ではなく conflicts に振り分けるためです。」そのうえで、レポートの「誤って巻き込んで対応したもの」欄にも記載します。

「兄弟タスクの担当ファイルに手を入れる」場合との違いは、意図にあります。兄弟タスクの担当ファイルは、独自のコミット作成者と独自のエンベロープを持つ並行タスクに属します。一方、プリミティブの変更によって意味が変わる中立的なテストファイルは、他の誰のエンベロープにも決して含まれないため、自分で修正する対象です。この修正を省略し、テストスイートが失敗した状態でオーケストレーターに渡すことのほうが、より大きな失敗です。

migration-coverage: ルール（プロジェクト固有ですが、janus リポジトリでよく使われます）。 一部のエンベロープでは、プラグインのソースまたはテンプレートを変更したにもかかわらず、兄弟のマイグレーションを追加していない場合、またはコミット本文に明示的な migration-coverage: <reason> 行がない場合に、コミットを失敗させるコミットメッセージフック（bin/check-migration-coverage）が実行されます。どちらの形式を使うかはエンベロープに記載されています。仕様で指定されたコミット本文に migration-coverage: が含まれている場合は、そのまま含めてください。この行は必須です。

検証ツールによる「マスキングマーカー」の指摘は、実装のバグではなく表示レイヤーの問題であることがよくあります。 検証ツール（または独自の grep／read_file）が、ソースの特定行にリテラルのマスキング記号（***、<redacted>、xxx、REDACTED、…）が含まれていると報告し、その位置では明らかに変数の展開（f-string の {var}、テンプレートの ${var}、%s 形式のフォーマット）が行われるべき場合は、表示結果を信用しないでください。ディスク上のファイルとツールの出力との間にある表示レイヤーによって、中括弧による展開マーカー、制御文字、またはまれな Unicode 文字が、マスクに見える文字列に化けることがあります。v12 の ralph 実行では、まさにこれが原因で再試行が丸ごと1回分失われました。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 ヘルパーを使うと、バイトレベルのチェックを 1 回の実行で自動化できます。根拠としてマスク状の置換が挙げられている IMPLEMENTATION-BUG ストライクのリトライを開始する前に実行してください。

この障害モードは ralph 以外にも当てはまります。あるエージェントがレンダリングされた出力を読んで別のエージェントのコードを検証するエージェントループは、すべてこの問題の影響を受けます。architect-final-review（docs/design/<rel>/forge-architect-review.md）でも、「redaction」または「stub-substitution」と分類された verifier-strike の指摘を正しい事実として扱う前に、バイトレベルで確認する必要があります。

v12 のインシデントを説明した内容については references/sibling-executor-preemption.md、ヘルパーについては scripts/verify-redaction-marker.sh を参照してください。

リトライ時の兄弟エグゼキューターによる先取り（同一レーン内、レーン間ではない）。 上記の異なるレーンにある兄弟タスクの場合とは別のケースです。同じタスクの strike-N リトライを開始すると、オーケストレーターが同じタスクのエンベロープに対して、すでに並行エグゼキューターを起動している場合があります。または、前のエグゼキューターが作業の一部を反映させていたものの、リトライ開始時点ではまだコミットされていない場合があります。診断方法：パッチツールの応答に、"<file> was modified by sibling subagent 'sa-X' but this agent never read it" のような _warning フィールドが含まれます。この警告は重大です。STOP して、さらにパッチを適用する前に状態を調整してください。具体的には、次のとおりです。

1. git diff <parent-sha> -- <file> を確認し、エンベロープで親として指定されたコミットと照合します。差分が空なら、修正はすでにツリーにあります（兄弟エグゼキューターがディスクに反映済みです）。この時点で、あなたの作業はテストのみとなり、コミット本文にもその旨を記載してください。
2. 何かがおかしいと感じた場合、ターミナルにレンダリングされた grep の出力を決定的な根拠として信頼しないでください。バイトレベルの確認（od -c、python3 -c "open(p,'rb').read()..."）に切り替えるか、git show HEAD:<file> で実際にディスク上にある内容を確認してください。
3. 作業中に兄弟エグゼキューターが同じ修正を実際にコミットしていた場合、オーケストレーターが調整します。「兄弟エグゼキューター 'sa-X' がこのリトライの開始前に実装差分を適用済みでした。私のコミットはテストのみです。出所情報はコミット本文に保持されています」と正直に記載して、COMPLETE と報告してください。

これによって防げる根本的な障害モードは、古いように見える grep の結果から修正が反映されていないと思い込み、何度もツールを呼び出して幻のバグを追い続けることです。説明付きの例については references/sibling-executor-preemption.md を参照してください。

テスト環境の PATH に hermes が必要な場合の --from-file エンドツーエンドテストの実行。 エグゼキューターが hermes のないプロファイルまたはコンテナーで実行されると、これらのテストは何も知らせずにスキップされます（典型的なパターン：@pytest.mark.skipif(not _hermes_available(), ...)）。スキップを成功と取り違えないでください。テストスイートのサマリーを必ず確認してください。

関連スキル

• omh-ralplan-driver — OMH の計画側（ディスパッチャーが実行する ralph プランの設計）。
• omh-ralph-driver — エンベロープを渡すオーケストレーション側。
• omh-triage-driver — トリアージ版。
• kanban-worker — Hermes Kanban のエグゼキューター規律。別のシステム（omh-ralph ではなく Kanban ディスパッチャー）ですが、ワーカー規律の形は似ています。ファイル範囲、構造化された引き継ぎ、リトライへの対応などです。
• github-pr-workflow — 一連の作業が PR に至る場合、通常はディスパッチャー（あなたではありません）が作成します。ディスパッチャーがまとめるコミットを提出してください。

関連項目

• references/sibling-isolation-pattern.md — 実際の反復作業から得られた、stash-verify の手順を説明する標準的な例。
• references/sibling-executor-preemption.md — strike-N リトライ時に同一レーン内の兄弟エグゼキューターが先取りする例と、ターミナルの grep 出力が誤解を招く場合のバイトレベルの検証手順。
• scripts/verify-redaction-marker.sh — 「literal redaction marker」ストライクに対する、バイトレベルのワンショット確認（表示レイヤー由来のアーティファクトによる誤検出を検出）。特定の行にあるマスク状の置換（***、<redacted> など）が根拠として挙げられている IMPLEMENTATION-BUG ストライクのリトライ前に実行してください。