omh-ralph-driver

OMH Ralph Driver — 検証済み実行のためのオーケストレーター向けプレイブック

ループをディスパッチするオーケストレーターは、omh-ralph と併せてこのスキルを読み込んでください。omh-ralph は、ロールが指定された ワーカー（executor / verifier / architect）が読み込みます。各タスクの delegate_task 呼び出し内で守る鉄則を扱います。このスキルでは、ディスパッチャーである あなた の役割、つまりプランの構成、イテレーションの進め方、並列バッチ処理、エビデンスの収集、検証担当者へのディスパッチ、ストライクへの対処、コミットの衛生管理、最終的なアーキテクトゲートを扱います。

2 つのスキルは、対象読者も役割も異なります。統合しないでください。ワーカーのコンテキストは貴重です。ディスパッチャー向けプレイブックをすべてのサブエージェントに持ち込むべきではありません。

このスキルは omh-ralplan-driver（設計ループである ralplan のディスパッチャー向けプレイブック）に対応する、ralph 側のスキルです。両者の関係は一貫しています。それぞれの手法には、ワーカー側のスキル（delegate_task 内で使用）とドライバー側のスキル（ディスパッチ間にオーケストレーターが使用）があります。

ralph を使う場合と、コードを直接書く場合

次の場合は ralph を使ってください。

• 5 つ以上の、個別に受け入れ可能なタスクを含むプランがある場合（omh-ralplan または手作業で作成）。
• 所要時間よりも検証による品質向上が重要で、次のタスクで成果物を利用する前に、各タスクの出力をエビデンスに基づいて評価する必要がある場合。
• 多数の作業単位にわたって、すっきりとしたチェックポイントを設けたい場合（コンテキストの肥大化を防ぐため）。
• 一部のタスクが独立していて、並列バッチで実行できる場合。

次の場合は ralph を使わないでください。

• 作業が単一ステップ、または直接書くのが自明な場合。
• まだプランがない場合。ralph を呼び出す前に omh-ralplan を実行してください（目標が明白な場合は、先に omh-deep-interview を実行してください）。
• ユーザーが検証を省略したい場合（まれです。通常は、作業が直接行えるほど小さいことを意味します）。

ralph 実行の流れ

iter 1: pick eligible tasks → dispatch executors (parallel where safe)
        → gather evidence → dispatch verifiers (parallel) → mark passes/fails
        → update state → release lock → exit

iter 2: re-invoke. Read state. Pick next batch. Same cycle.

...

iter N: all tasks pass → Step 7 final architect review → mark complete.

イテレーション間におけるオーケストレーターの仕事は、適切なバッチを選び、各実行担当者に適切なコンテキストを渡し、適切なエビデンスを収集し、検証担当者の判定を解釈して、再試行するか次へ進むかを決めることです。

5 ステップのプレイブック

1. プランを読み、ralph に適した形式か確認する

ralph のプランは、次の内容を含む番号付きタスクの一覧です。

• 明確なタイトル。
• 事前のコンテキストがない実行担当者でも実装できる、十分に簡潔な説明。
• テスト可能な受け入れ条件。「実装が完了している」のような一般的な条件は、ralph のプランニングゲートで却下されます。
• 依存関係（先に完了しておく必要がある他のタスク）。
• 変更対象ファイル（並列バッチの計画で使用します。ステップ 3 を参照してください）。

プランが omh-ralplan から作成された場合、それは設計向けの形式であり、ralph 向けではありません。まず stance の「MV slice」セクションを確認してください。ralph のタスク形式に変換する必要がある場合があります。適切なタスク構造で .omh/plans/ralph-plan.md（特定の ralplan インスタンスから派生する場合は .omh/plans/ralplan-<slug>.md）を作成してください。

最初からすべてのタスクを同じ深さで記述しておく必要はありません。実行中にプランを拡張できます。ralph のプランニングゲートは初回の呼び出し時点で記載されている内容を解析します。実行中に見つかった新しいタスクは、state 内の discovered: true フラグを使って追加します。

2. イテレーションごとに適切なバッチを選ぶ

各 ralph イテレーションでは、1 つの作業単位を実行します。「作業単位」は次のいずれかです。

• 1 つのタスク（次に実行可能なタスクが単独の場合、またはほかの実行可能なタスクと変更対象ファイルが重複する場合）
• 2～4 個のタスクのバッチ（互いに独立したタスクが実行可能で、変更対象が重複しない場合）

実行可能条件 = passes: false であり、すべての依存関係が満たされていること。

変更対象の重複なし = タスクが同じファイルを変更しないこと。計画にある「変更／作成するファイル」の一覧を確認してください。2 つの実行可能なタスクがどちらも bin/janus-new-being を変更する場合、並列実行しても安全ではありません。一方のタスクがその変更を担当します。一方が migrations/lib.py を、もう一方が bin/_lineage.py を変更する場合は、並列実行しても安全です。

例外ケース — インポートの共有。 ファイルが重複していなくても、タスク A が作成するヘルパーをタスク B がインポートする場合は、タスク A を先に完了させる必要があることがあります。計画の作成時に依存関係として明記してください。見落とした場合は、B の実行担当者がタスクの途中で依存関係を指摘します。

適切なバッチサイズ。 2～4 個のタスクです。1 つのバッチに 5 個以上のタスクを含めると、オーケストレーターが実行担当者の報告を解析し、検証担当者への割り当てを行う際に、使用中のコンテキストウィンドウへ過度な負荷がかかります。

3. 十分なコンテキストを付けて実行担当者に割り当てる

各実行担当者には、新しいサブエージェントを割り当てます。サブエージェントには、以前のイテレーション、会話、タスクの記憶が一切ありません。必要な情報をすべて、割り当て時のコンテキストに含めてください。

実行担当者に渡すコンテキストには、次の内容を含める必要があります。

• プロジェクトのルートとブランチ。 相対パスではなく、絶対パスを指定します。
• 以前の状態。 以前のイテレーションで完了したタスク、現在存在するファイル、インポート可能なヘルパーやライブラリを説明します。
• 以前のタスクから得た知見で、今回のタスクに関連するもの。実行担当者が守るべき注意点、命名規則、アーキテクチャ上の選択を引き継ぎます。
• タスクそのもの。 タイトル、説明、受け入れ基準をすべて含めます。
• 必読資料。 正式な設計資料、以前のタスクの成果物、パターンの参考にする類似タスクの絶対パスを指定します。
• TDD の指示。 まず失敗するテストを書いて実行し、失敗を確認してから実装し、成功を確認したうえで、全テストを実行してコミットします。すべての実行担当者への割り当てに、必ず明記してください。
• コミットのメタデータ。 作成者の識別情報、コミットメッセージの形式、ブランチを指定します。
• 変更禁止の対象。 並列バッチでは特に重要です。詳しくは以下の P3 を参照してください。

goal には [omh-role:executor] マーカーを使用してください。OMH プラグインは pre_llm_call フックを介して、実行担当者の役割プロンプトを自動的に挿入します。役割の文面を手動でインライン化しないでください。

TDD の指示、同じバッチ内のタスクを考慮した変更禁止のルール、コミットのメタデータ、各種の失敗区分に応じた再試行のバリエーションを含む、実行担当者の goal フィールド用の完全なテンプレートは references/executor-goal-template.md にあります。変数を調整し、構成は維持してください。

4. 検証担当者に割り当てる前に omh_gather_evidence で証拠を収集する

すべての実行担当者が作業を完了したら、omh_gather_evidence を使って、プロジェクトで実際に使用しているテスト、ビルド、lint のコマンドを実行します。検証担当者が評価できる、構造化された {results, all_pass, summary} オブジェクトが生成されます。

重要： 検証担当者は自分で証拠を収集しません。オーケストレーターの段階で証拠を収集し、検証担当者が確認する前に、実行担当者の申告が実際の結果と一致しているかを検証します。

許可リストに関する注意点。 omh_gather_evidence は、トークン接頭辞の許可リスト（~/.hermes/plugins/omh/config.yaml → evidence_tool.allowlist_prefixes）を適用します。uv run --with pytest --with pyyaml -m pytest のような一般的なプロジェクトのテストコマンドは、--with が接頭辞に含まれるため、uv run pytest には一致しません。次のいずれかを行ってください。

• 一致する接頭辞を使用します：uv run pytest <args>（推奨。--with pytest が不要になるよう、pytest をプロジェクトの開発用依存関係として維持します）。
• OMH 設定にカスタム接頭辞を追加します。
• プロジェクト内のスクリプトでラップします。

gather_evidence がコマンドを拒否した場合、exit_code: -1, output: "Command not in allowlist" が表示されます。検証担当者に割り当てる前に、コマンドを組み直してください。

5. 検証担当を並列でディスパッチする（タスクごとにバッチ化）

完了した各タスクについて、次の内容を含む検証担当サブエージェントをディスパッチします。

• [omh-role:verifier] マーカー（検証担当の役割プロンプトを自動で挿入します）。
• タスクの受け入れ基準（実行担当の解釈ではなく、仕様に照らして評価してもらうためのものです）。
• エビデンスの完全な出力（検証担当は、言い換えられた成功の主張ではなく、実際のテスト結果を確認する必要があります）。
• 調査対象のファイルパス。
• 「テストに合格する」こと以外の、重要な確認事項（例：「不一致フラグのチェックがファイルシステムへの書き込みより前に行われることを確認してください。そうでない場合、一部のフラグのみを指定した呼び出しによって状態が破損します」）。

検証担当は、delegate_task(tasks=[...]) を使ったバッチ処理で並列に実行します。これにより、Round 2 の ralplan レビュアーと同じように、経過時間を短縮できます。

検証担当は、次のいずれかを返します。

• APPROVE / PASS — タスクの passes フラグが true になります。
• REQUEST_CHANGES / FAIL — 判定を記録し、そのフィードバックを添えて実行担当に再試行させます。ストライクを記録します（下記 P5 を参照）。

検証担当の goal フィールド用の完全なテンプレート（受け入れ基準を逐語的に記載するルール、エビデンスを貼り付ける形式、同時作業する担当者間の境界チェック、ストライクの分類、判定例を含む）は references/verifier-goal-template.md にあります。

落とし穴（P1–P10）

これらは、ralph ディスパッチャーが陥りがちな失敗パターンです。相互参照用に番号を付けており、欠番は今後の追加用に確保されています。

P1 — プランは設計書ではなく、ralph 形式にする必要があります

omh-ralplan は設計書である stance.md を生成します。ralph に必要なのは、テスト可能な受け入れ基準を備えたタスクリストです。

ralph に stance を直接渡すと、プランニングゲートは弱い解析しか できず、タスクらしく見える番号付きセクションを抽出するだけに なるか、処理を拒否します。まず stance の MV スライスを、適切な ralph プランに変換してください。

変換は機械的に行えます。

• Stance の MV スライス項目 → ralph タスク（項目ごとに 1 タスク）。
• Stance のテスト可能性 → タスクの受け入れ基準（stance に記載がある場合はそのまま使用）。
• Stance の「depends on」に関する説明 → タスクの dependencies: フィールド。
• Stance のファイルパス → タスクの files: リスト（並列バッチ計画用）。

ralph プランは .omh/plans/ralph-plan.md または .omh/plans/ralplan-<slug>.md として作成します。ralph のプランニングゲートは どちらのファイルも検出します。

変換例（2026-04-27 の janus 実行より）。 stance の 「MV slice plan」セクションには、NOW（約 3.5 時間、次回の provision 前に lineage を取得）／NEXT（+72 時間、update ツール）／DEFERRED（後続リリース）に 分けた 13 個の作業項目が記載されていました。ralph プランでは各項目を次の形式の タスクにしました。

### Task 4 — bin/janus-new-being: version stamp + seed-history snapshot

**Files to modify:**
- `bin/janus-new-being`

**Files to create:**
- `bin/tests/test_janus_new_being_lineage.py`

**Description:**
Patch `bin/janus-new-being` provisioning logic to write lineage data
per the stance's NOW slice item 2. After successful provisioning,
write `<profile>/.janus/version`, snapshot rendered template + plugin
tree to `<profile>/.janus/seed-history/v1/` via post-write disk-read,
compute MANIFEST with content hashes per file...

**Acceptance criteria (verbatim from stance test affordance):**

    def test_provision_writes_v1_lineage(tmp_path):
        profile = tmp_path / "alice-janus"
        # ... provision invocation ...
        assert (profile / ".janus" / "version").read_text().strip() == "v1"
        seed = profile / ".janus" / "seed-history" / "v1"
        assert (seed / "SOUL.md").exists()
        ...

**Dependencies:** none (Task 5 extends, but doesn't conflict)

この変換を成功させた手順は次のとおりです。

1. 受け入れ基準は stance からそのまま転記します。 stance に test_provision_writes_v1_lineage_and_gh_config が合格すると 記載されている場合、ralph プランにもそのテスト名をそのまま使います。 これにより、実行担当者は stance が指定したテストを書き、検証担当者は 言い換えによるずれを生じさせず、stance 自体の契約に基づいて評価できます。

2. 変更対象ファイルを明示します。 各タスクの files: には、作成・変更する ファイルを正確に列挙します。これにより、後で並列バッチ計画（P2）が可能になります。 オーケストレーターは説明文から対象ファイルを推測し直さずに、リストを読み取り、 変更対象が重複しないか確認できます。

3. 依存関係は説明文だけでなく、共通する具体的な成果物から推定します。 stance には MANIFEST の形式は Task 4 で作成すると記載されており、 Task 8（hash_equals_ancestor を含む lib.py）はその形式を読み取る必要があります。 そのため Task 8 の dependencies: [task-4] は、「Task 8 は Task 4 の後に 実行する必要がある」という文章ではなく、共通するファイル形式から推定しました。

4. NOW／NEXT／DEFERRED を優先順位に反映します。 NOW スライスのタスクには すべて priority: 1 または priority: 2 を割り当てます（後続の並列バッチを 開始させるタスクには priority 2 を割り当てます）。NEXT には 3～5 を割り当てます。 DEFERRED の項目は今回の実行範囲に含まれないため、ralph タスクとしては記載しません。

5. 各タスクのテスト可能性に関するセクションを、pytest の完全な関数シグネチャに 展開します。 stance にテスト名と簡単な内容しか記載されていない場合でも、 ralph タスクには関数名と動作を正確に記載します。そうすれば、実行担当者が それらを推測し直す必要はありません。

この変換自体が、後工程を支える重要なステップです。 ここを雑に済ませると、 その後のオーケストレーションがどれほど規律正しくても、実行結果は雑になります。 ralph プランは、実行担当者が実装し、検証担当者が評価する契約そのものです。 曖昧なプランでは、ループの成果も曖昧になります。

タスクが 10 個以上あるプランでは、変換に 30～60 分を見込んでください。 出力されたファイルは ralph のプランニングゲートが解析するものであり、実行中に stance を直接参照することはもうありません。

P2 — ディスパッチ前に、並列実行可能なバッチを特定します

各イテレーションの開始時に、対象となるすべてのタスク （passes: false かつ依存関係が満たされているタスク）を確認します。 各タスクのペアについて、変更対象が重複しないかをチェックします。並列実行可能な タスク群を決め、一括した delegate_task でディスパッチします。

1 つのタスクをディスパッチした後で、ほかのタスクも並列実行できたか検討するのでは、 そのイテレーションで短縮できたはずの時間を失います。判断する適切なタイミングは、 すでに状態を読み取っているイテレーションの開始時です。

適切なバッチサイズは 2～4 です。依存関係が密接な場合は 2、独立したタスクが複数 積み重なっている場合は 4 にします。5 つ以上にすると、実行担当者の報告と並列の 検証ディスパッチによって、オーケストレーター自身のコンテキストが過負荷になります。

P3 — 並列ディスパッチのコンテキストでは「共有ファイルを変更しない」と明示する必要があります

並列の実行担当者をディスパッチする際は、共有ファイルごとに担当するタスクを1つだけにします。他の実行担当者はインポート（読み取り専用）できますが、変更してはいけません。

各実行担当者のディスパッチコンテキストに、次の指示を明示してください。

このタスク中にmigrations/lib.pyを変更してはいけません。この変更の担当はTask Xです。必要なものをインポートしてください。関数がまだ存在しない場合は、Task Xが想定するシグネチャに一致するインライン実装で代用し、両方のコミットが取り込まれたときに問題なく収束するようにしてください。

この指示がないと、並列の実行担当者が共有ファイルを取り合い、競合するコミットを作成します。指示があれば、境界を守り、自分の作業だけをコミットします。

各実行担当者には、コミット前に兄弟タスクのファイルをステージング解除するよう指示してください。そうしないと、git add -Aで他のタスクの未コミット作業まで取り込まれてしまいます。P9を参照してください。

P4 — 各実行担当者のディスパッチに、前のイテレーションの学びを組み込む

各イテレーションでは、気づき（注意点、命名規則、うまくいったパターン、うまくいかなかったパターン）が得られます。次のイテレーションの実行担当者は、これらを組み込まない限り把握できません。

ralphの状態のcompleted_task_learningsフィールドにイテレーションごとの学びのリストを保持し、以降の各実行担当者のディスパッチコンテキストに、関連するものを含めてください。

次のような内容を引き継ぐと役立ちます。

• 「TEST-INFRA：一時ディレクトリ名にhash(content) & 0xffffは絶対に使わないでください。ランダム性と小さな剰余の組み合わせにより、衝突のリスクがあります。」
• 「追跡対象ファイルを削除するときは、Gitの履歴を保持するためにrm -rfではなくgit rm -rを使ってください。」
• 「bin/janus-new-beingはuvのシバンを使い、.pyサフィックスは付けません。新しいbin/*スクリプトも同じパターンに従ってください。」
• 「bin/_lineage.pyのclassify()関数が提供するのは分類基準（パスプレフィックスのパターンとClass-Bの完全一致セット）であり、列挙ではありません。分類体系を重複して作らず、再利用してください。」

これらはディスパッチコンテキストを通じて簡潔に引き継がれます。omh-ralphの状態にあるcompleted_task_learningsが正式な保存先です。

P5 — 実行担当者のストライクをカテゴリ別に区別する

検証担当者がREQUEST_CHANGESを返す原因は、次のいずれかです。

1. テストインフラ — テスト自体に不具合があります（例：hash() & 0xffffによるパスの衝突、フィクスチャの競合、テストランナーの設定問題）。実装は正しい可能性があり、修正が必要なのはテストだけです。

2. 仕様の読み違い — 実行担当者が受け入れ基準で求められたものとは異なるものを実装しました。実装の修正が必要です。

3. 実装バグ — 実行担当者は正しいものを実装しましたが、実際の不具合があります（ロジックエラー、見落としたエッジケース、セキュリティ上の問題）。

この3つのカテゴリでは、それぞれ必要な修正が異なります。テストインフラの再試行では、テストファイルだけを変更します。仕様の読み違いによる再試行では、仕様が実際に求めていることを強調した新しいコンテキストが必要です。実装バグによる再試行では、失敗したケースを明示する必要があります。

状態を更新するときは、エラーフィンガープリントにストライクのカテゴリをタグ付けしてください。

"error_fingerprints": [
    {"category": "test-infra", "error_key": "hash-collision-in-tmpdir-naming", "round": 1},
    ...
]

（omh-ralphのステップ6に従う）3ストライクのサーキットブレーカーは、同じ(category, error_key)が3回繰り返されると作動します。カテゴリでタグ付けすることで、テストインフラのストライクが実際のバグを見落とさせる（またはその逆の）事態を防げます。

P6 — 検証担当者は実行担当者の主張ではなく、実際の証拠を確認する必要があります

検証担当者をディスパッチする前に、必ずomh_gather_evidenceを実行してください。証拠の出力を検証担当者のディスパッチコンテキストに含めてください。

証拠収集を省略すると、検証担当者は実行担当者の報告（「ステータス：完了、テスト5件が成功、コミットX」）だけを読み、評価の基準となる事実を得られません。実行担当者の報告が誤っていることもあります。実行担当者が実際に何かを見落とした場合もあれば、重要なアサーションが実行される前にパスの衝突でクラッシュしたため、テストが成功したように見えた場合もあります（このスキルの実例を参照）。

オーケストレーターが証拠を実行するパターンによって、ralphの検証の信頼性が確保されます。

P7 — 最終アーキテクトレビュー（ステップ 7）はマージゲートです

すべてのタスクが合格すると、ralph のステップ 7 でアーキテクトが呼び出され、元の計画／方針に照らして実装全体をレビューします。

アーキテクトは全体的な観点からレビューします。

• アーキテクチャへの忠実性（実装は設計を尊重していますか？）
• 原則との整合性（重要な原則は、文章に登場するだけでなく、仕組みの中で実際に機能していますか？）
• MV スライスの準備状況（ユーザーは今夜、実際に実行できますか？）
• アーキテクチャ上の継ぎ目（粗い部分はありますか、それとも明示的に先送りされていますか？）
• コミットの整理状況（マージするのに十分きれいな Git 履歴ですか？）
• テスト容易性の不足

これは、ユーザーに PR 対応済みのブランチを渡す前に、オーケストレーターが行う最終ゲートです。アーキテクトは次の判定を返せます。

• APPROVE — マージ可の承認です。
• APPROVE_WITH_PROVISO — マージ前に追加する、折りたたみ可能な小規模項目（通常、名前を付けた 1〜3 項目です）。
• REQUEST_CHANGES — リリースできない問題があり、新しいタスクが discovered: true で追加されます。

アーキテクトのレビューは、設計ディレクトリに <orchestrator>-architect-review.md として作成してください（オーケストレーター自身によるイテレーションレベルのレビューは <orchestrator>-review.md です。アーキテクトレビューは別の成果物です）。

アーキテクト最終レビューの goal フィールドに使う完全なテンプレート（差分範囲の確認、エンドツーエンドの MV スライストレース、原則の発動監査、コミット整理状況の確認、判定の調整ガイダンス、レビュー例（APPROVE_WITH_PROVISO と REQUEST_CHANGES）を含む）は、references/architect-final-review-template.md にあります。

P8 — アクションのたびに状態を更新し、終了時には必ずロックを解除します

omh-ralph のステップ 0／ステップ 8 に従い、.omh/state/ralph--<instance_id>.json と .omh/state/ralph-tasks--<instance_id>.json の状態ファイルで実行を追跡します。.omh/state/ralph--<instance_id>.lock のロックにより、同じ計画で複数のセッションが競合するのを防ぎます。

規律：

• イテレーション開始時（ステップ 0）にロックを取得します。
• すべての実行担当の完了後、すべての検証判定後、すべてのタスク遷移後に状態を更新します。
• すべての終了時点（成功、ブロック、キャンセル、最大イテレーション数到達、例外）でロックを解除します。エラー時にもロック解除が実行されるよう、イテレーション本体をラップしてください。

古いロックを残さないでください。ロックを保持しているプロセスが停止している場合、次回の ralph の呼び出しで held_by を通じてそれが通知されます。キャンセルして再試行するよう提案し、黙ってロックを奪わないでください。

P9 — 並列書き込み時のコミット整理

1 回のオーケストレーターターンで 3 人の実行担当が同じブランチに書き込むと、互いの状態の一部（コミット済みのもの）を確認できますが、未コミットの作業は確認できません。実行担当の 1 人がコミットのステージングに git add -A を使うと、まだ作業中の兄弟タスクのファイルまで取り込んでしまうことがあります。

並列実行担当をディスパッチする際の規律：

1. 各実行担当には git add -A ではなく、対象ファイルを明示して git add するよう指示します。ファイル名はタスクの files: フィールドと一致させます。

2. コミット前に git status を確認するよう各実行担当に指示します。兄弟タスクのファイルが存在し、未ステージングの場合は、それらを含めないでください。よくある兄弟ファイル：未追跡の init.py スタブ、未追跡のテストファイル、編集中の RELEASES.yaml。

3. 誤って取り込まれることがある点は受け入れます。 そうなっても復旧できます。インタラクティブリベースで過剰なコミットと欠けているコミットをまとめるか、後続の履歴注記コミットで境界を説明します。

4. イテレーションログに誤取り込みを記録します。 実行担当から「既存の未追跡ファイルを取り込んだ」と報告された場合、ステップ 7 でのアーキテクトによるコミット整理状況の確認に向けて、その旨を記録してください。

このパターンは苦い経験から学びました。ある実行では、git add -A によって task-11 のコミットに task-12 のコミット予定内容の約 60% が取り込まれました。テストはすべて成功し、成果物も正しくできていましたが、コミットの境界は曖昧でした。アーキテクトは、折りたたみ可能な但し書きとして指摘しました。

P10 — プラグイン／ツールの変更では、再開するか再起動するかが重要です

反復の間にユーザーがプラグインやツールセットを変更した場合 （ツールの追加、プラグインの有効化、config.yaml の変更など）、ツールは 現在のセッションでライブ登録されません。エージェントの 起動時に登録されます。

ユーザーが「設定を変更したので、新しいツールを今すぐ使えますか？」と言った場合：

• Resume ボタンをクリックするだけでなく、セッションを完全に再起動する必要があります （一部のチャット UI では、「Resume」後も同じエージェントプロセスが再利用されます）。
• 関数スキーマを確認して検証してください。新しいツールがなければ、 起動は行われていません。
• 最も速い確認方法は、OMH 関連のプラグインの場合は omh_state(action="check", ...) を実行することです。ツールが 「function not found」というエラーを返す場合、そのプラグインは読み込まれていません。

再起動後もツールが表示されない場合の、プラグインインストールの完全な診断手順については、 兄弟スキルの enabling-hermes-plugin-in-profile を参照してください。

状態管理のチートシート

# Step 0: check + lock
omh_state(action="cancel_check", mode="ralph", instance_id=instance_id)
lock = omh_state(action="lock", mode="ralph", lock_key=instance_id,
                  session_id=session_id, holder_note="...")

# Step 1: read state (or trigger planning gate)
state = omh_state(action="read", mode="ralph", instance_id=instance_id)
tasks = omh_state(action="read", mode="ralph-tasks", instance_id=instance_id)

# Step 2: planning gate (only on first invocation)
omh_state(action="write", mode="ralph-tasks", instance_id=instance_id, data={
    "tasks": [{"id": "task-1", "title": "...", "description": "...",
               "acceptance_criteria": "...", "priority": 1,
               "dependencies": [], "passes": False, "files": [...]}, ...]
})

# Step 3-5: per-iteration execution
# (delegate_task for executors, omh_gather_evidence, delegate_task for verifiers)

# Step 8: update state, exit
omh_state(action="write", mode="ralph", instance_id=instance_id, data={
    "active": True, "phase": "execute", "iteration": N, ...,
    "completed_task_learnings": [...]
})
omh_state(action="unlock", mode="ralph", lock_key=instance_id, session_id=session_id)

オーケストレーターの作業完了条件

• ralph-tasks の状態で、すべてのタスクが passes: true になっている。
• ステップ 7 の最終アーキテクトレビューが、プロバイゾを反映したうえで APPROVE または APPROVE_WITH_PROVISO になっている。
• <orchestrator>-architect-review.md が書き込まれている。
• .omh/logs/ralph-progress.md（またはドメインに相当するファイル）に、反復の経過、発生したストライク、重要な学びが記されている。
• 状態が phase: complete、active: false になっている。
• ロックが解除されている。
• ユーザーがブランチから PR を作成できる。

実例（2026-04-27、janus の移行）

13 タスクの計画、5 回の反復、ストライクは合計 1 回、最終結果は APPROVE_WITH_PROVISO です。

• 反復 1：独立した 3 タスク（RELEASES.yaml、AGENT.md のパッチ、janus-migration スキルの廃止）を並行して実施。すべて APPROVE。
• 反復 2：task-4 のみを実施（系譜の取得、ゲート 5／6／8）。ストライク 1 は test-infra のハッシュ衝突でした。再試行で APPROVE。
• 反復 3：3 タスクを並行して実施（gh-config、backfill-lineage、lib.py）。各タスクのディスパッチには「bin/_lineage.py は変更しないでください — 担当は Task X です」と記載。ストライクなしのラウンドでした。
• 反復 4：3 タスクを並行して実施（janus-migrate スキル、janus-update CLI、pytest ハーネス）。ストライクなし。
• 反復 5：3 タスクを並行して実施（boot-context のサーフェス、janus-contribute のスタブ、v2 の移行）。ストライクなし。コミット衛生に関する問題が 1 件ありました：task-11 が git add -A によって task-12 のファイルを取り込みました。テストは成功しましたが、アーキテクトレビューでの確認対象として指摘されました。
• ステップ 7：アーキテクトは APPROVE_WITH_PROVISO。折りたたみ可能な項目が 2 件（コミット衛生のためのリベースと、欠落している migrations/README.md）。

合計：実装コミット 14 件で、テスト数は 0 件から 132 件に増加しました。5 回中 4 回の並行反復でストライクがなかったのは、P3（「<共有ファイル> は変更しないでください」）＋P4（学びの転送エンコーディング）＋P6（オーケストレーターが証拠を実行）の規律があったためです。唯一のストライクは P5 の test-infra で発生しましたが、問題なく復旧しました。

独自の実行ログを管理する

新たな落とし穴や予想外のパターンが見つかった ralph の実行は、ログに残す価値があります。簡潔な表を作成してください。

日付	ドメイン	反復数	ストライク	予想外のこと	このスキルへのパッチ

このスキルをセッションログにしないでください。ログは別の場所（基盤、プロジェクトのメモ、Wiki など）に記録してください。将来のオーケストレーターに教える価値があるほど一般的な落とし穴がある場合にのみ、このスキルにパッチを適用してください。

関連するスキル

• omh-ralph — ワーカー側の規律です。各 delegate_task 内で読み込まれます。 オーケストレーターが内容を理解するために一度読む必要がありますが、ワーカーの コンテキストには読み込まれません（プラグインが役割プロンプトを自動挿入します）。
• omh-ralplan-driver — 設計ループのディスパッチャー用プレイブックです。 まだ計画がない場合は、ralph より先に使用してください。同じ形式の ドライバー側スキルですが、異なる手法（コンセンサス設計と検証済み実行）を扱います。
• omh-ralplan — ワーカー側の設計規律です。[omh-role:planner|architect|critic] マーカーを付けて、 delegate_task 内でのみ使用してください。
• enabling-hermes-plugin-in-profile — プラグインのインストール診断手順を扱う 関連スキルです。OMH ツールが関数スキーマに含まれておらず ralph の実行が ブロックされる場合に参照してください。
• subagent-driven-development — OMH プラグインを利用できない環境で、 計画を実行するためのよりシンプルな形式です。同じアーキテクチャパターンですが、 状態管理、役割の挿入、エビデンスツールはありません。

見落としてはならない内容

最も重要な要点は、オーケストレーターがエビデンスを収集し、検証者は収集しないことです。 検証者にタスクを割り当てる前に、必ず omh_gather_evidence を実行してください。 実際のテスト出力を検証者のコンテキストに含めてください。 これにより ralph の判定の信頼性が確保されます。そうしなければ、実行者の自己報告が 二重に重なることになります。

次に重要なのは、「共有ファイルを変更してはならない」という規律が、 並列バッチを 3 件で実行可能にすることです。 並列実行タスクを割り当てるたびに、 兄弟タスクが担当するファイルを明示してください。そうしないと、並列バッチで 共有ファイルをめぐる競合が発生し、あるタスクのコミットに別のタスクの作業が 取り込まれてしまいます。

3 つ目に、ストライクには分類があります。 テスト基盤の問題 ≠ 仕様の読み違い ≠ 実装のバグです。分類を付けてください。3 ストライクのサーキットブレーカーは、 同じタスクではなく、同じ分類に対して作動させる必要があります。分類を混同すると、 誤検知による停止が生じます（さらに悪い場合は、本物のバグがテスト基盤の問題に 見えてしまい、見逃されることもあります）。

4 つ目に、オーケストレーターが立つべき高度は「反復の間」であり、 個々のタスクの中ではありません。1 回の呼び出しにつき 1 タスクという絶対原則が あるのは、一定の高度を保ち、バッチの選定、学びの次段階への引き継ぎ、エビデンスの収集、 検証者へのタスク割り当て、再試行するか次へ進むかの判断を行うためです。 作業に入り込めば、実行者になってしまい、このループの価値はすべて失われます。