omh-ralph

OMH Ralph — 検証済みの実行（v2）

OMH プラグインが必要です。 このリポジトリの plugins/omh/ を ~/.hermes/plugins/omh/ にインストールしてください。

使用する場合

• omh-ralplan または手動で作成した計画があり、検証済みの実行が必要な場合
• ユーザーが「ralph」「止めないで」「完了するまで」「必ず完了して」「続けて」と指示した場合
• 「完了したように見える」だけでなく、証拠に裏付けられた完了を確実に検証する必要がある場合
• 各タスクを個別に検証する必要がある、複数ステップの実装の場合

使用しない場合

• 計画や仕様がない場合（まず omh-deep-interview や omh-ralplan を使用してください）
• 単純な単一ファイルの変更の場合（そのまま直接実行してください）
• ユーザーが検証を明示的に省略したい場合

アーキテクチャ：呼び出しごとにタスクは1つ

Ralph を呼び出すたびに、作業単位を1つ実行して終了します。呼び出し元は次のタスクのために再度呼び出します。これにより、コンテキストウィンドウの枯渇を防ぎ、各呼び出しがクリーンなチェックポイントになります。

Invocation N:  read state → pick task → execute → verify → update state → EXIT
Invocation N+1: read state → pick next task → execute → verify → update state → EXIT
...
Final invocation: all tasks pass → architect review → mark complete → EXIT

手順

ステップ0：インスタンスを解決してロックを取得する

Ralph と autopilot は、共有の .omh/plans/ 計画を変更します。同じ計画に対して2つのセッションが Ralph を実行すると、ralph-tasks の状態をめぐって競合し、非決定的な結果が生じる可能性があります。インスタンスごとの状態とアドバイザリロックを使用して、計画の同時実行を安全にします。

1. 計画パスから instance_id を解決します。
   • 既定の計画ソース：.omh/plans/ralplan-*.md または .omh/plans/ralph-plan.md。
   • instance_id = basename(plan_path) without ".md"（エンジンがスラッグ化します）。
   • 計画がまだない場合（ステップ2で選択する場合）は、instance_id="default" を使用します。
2. 状態を読み書きする前に ロックを取得します。

   lock = omh_state(action="lock", mode="ralph",
                    lock_key="{instance_id}",
                    session_id="{HERMES_SESSION_ID or uuid}",
                    holder_note="ralph executing {plan_path}")
   

   • acquired=true：続行します。
   • acquired=false：held_by（pid + session_id + started_at）をユーザーに伝えます。次の選択肢を提示します：待機する／保持者をキャンセルする （omh_state(action="cancel", mode="ralph", instance_id="{instance_id}") を実行し、 次回の呼び出し時に、停止した保持者のロックが古いPIDの検出によって 自動的に解放されます）／別の計画を選ぶ。
3. この呼び出し内で後続の omh_state を呼び出すたびに、ralph モードと ralph-tasks モードの両方で instance_id を渡します。
4. すべての終了時点（成功、ブロック、キャンセル、最大反復回数、例外）で ロックを解放します。

   omh_state(action="unlock", mode="ralph",
             lock_key="{instance_id}",
             session_id="{HERMES_SESSION_ID or uuid}")
   

   エラー時にもロック解除されるよう、手順の本体をラップしてください。

シングルトンへのフォールバック（レガシー）。 呼び出し元が instance_id を省略すると、 エンジンはレガシーの .omh/state/ralph-state.json に書き込み、 ロックをスキップします。計画を一度に1つだけ扱う構成の場合にのみ使用してください。

ステップ1：状態を読む

state = omh_state(action="read", mode="ralph", instance_id="{instance_id}")

• state.exists=false：新規開始です。ステップ2（計画のゲート）に進みます。
• state.data.active=true：再開します。ステップ3に進みます。
• state.data.phase="complete"：完了を報告します。ユーザーに新規開始するか尋ねます。
• state.data.phase="blocked"：阻害要因を報告します。問題が解決したか尋ねます。
• state.data.active=false、phase="cancelled"：キャンセルを報告します。再開を提案します。

キャンセルシグナルを確認します。

cancel = omh_state(action="cancel_check", mode="ralph", instance_id="{instance_id}")

cancel.cancelled=true の場合：phase="cancelled" に設定し、状態を書き込んで終了します。

古さを確認します。state.stale=true の場合はユーザーに警告し、続行するか新規開始するかを提案します。

state.data.iteration をインクリメントします。iteration > max_iterations（既定値は100）の場合： phase="blocked" を書き込み、「最大反復回数に到達しました」と報告して終了します。

ステップ 2：計画ゲート

Ralph は計画なしで実行してはなりません。以下の順にソースを確認します。

1. omh_state(action="check", mode="ralph-tasks", instance_id="{instance_id}") → exists=true — すでに解析済みのため、ステップ 3 に進みます
2. .omh/plans/ralplan-*.md — ralph-tasks の状態に解析します：omh_state(action="write", mode="ralph-tasks", instance_id="{instance_id}", data={...})
3. .omh/plans/ralph-plan.md — ralph-tasks の状態に解析します
4. 見つからない場合 → ユーザーに伝えます：「計画が見つかりません。まず omh-ralplan を実行してください。」

計画の解析ルール：

• 番号付きのタスクから、タイトル、説明、受け入れ基準を抽出します
• 「実装が完了している」などの一般的な基準は却下します。テスト可能である必要があります
• 原子性を徹底します。複数の要素を含むタスクは別々のエントリーに分割します
• 依存関係の順序に従って優先度を割り当てます（依存関係のないタスクを先にします）
• すべてのタスクを passes: false に設定します

初期状態を書き込みます：

omh_state(action="write", mode="ralph", instance_id="{instance_id}", data={
  "active": true, "phase": "execute", "iteration": 0,
  "session_id": "<uuid>", "max_iterations": 100,
  "task_prompt": "<original user request>",
  "current_task_id": null,
  "started_at": "<ISO 8601 timestamp>",
  "project_path": "<absolute path to project root>",
  "files_modified": [],
  "error_history": [],
  "completed_task_learnings": []
})

ステップ 3：次のタスクを選択

タスクリストを読み取ります：

tasks = omh_state(action="read", mode="ralph-tasks", instance_id="{instance_id}")

1. すべてのタスクが passes: true の場合 → ステップ 7（最終レビュー）に進みます
2. 実行可能なタスクを見つけます：passes=false かつすべての依存関係が満たされているタスク
3. 実行可能なタスクがなく、未完了のタスクが残っている場合 → 依存関係のデッドロックです → phase="blocked" を設定し、状態を書き込み、終了します
4. 実行可能なタスクの中から、優先度（番号の小さい順）で選択します

並列実行： 互いに独立した実行可能なタスクが 2～3 個ある場合（共有するファイル範囲がなく、相互に依存関係がない場合）、1 回の delegate_task 呼び出しにまとめます。

ステップ 4：実行

実行サブエージェントに委任します：

delegate_task(
    goal="[omh-role:executor] Implement this task:\n\n{task.title}\n{task.description}\n\nAcceptance Criteria:\n{task.acceptance_criteria}",
    context="Project Context:\n{tech stack, conventions, relevant paths}\n\nPrevious Feedback (if retry):\n{task.verifier_verdict}\n\nLearnings from prior tasks:\n{state.data.completed_task_learnings}"
)

ゴール内の [omh-role:executor] マーカーにより、OMH プラグインが実行ロールのプロンプトをサブエージェントのシステムプロンプトに自動的に挿入するため、インラインで追加する必要はありません。 （プラグインなしの場合の代替手段：マーカーを omh_state(action="load_role", role="executor") に置き換え、返されたプロンプトテキストをコンテキストに渡します。）

実行サブエージェントの応答を解析します：COMPLETE → ステップ 5、PARTIAL → ステップ 5、BLOCKED → ブロッカーを記録し、必要に応じて見つかったタスクを追加し、状態を更新して終了します。

ステップ 5：検証

パート A：証拠を収集

evidence = omh_gather_evidence(commands=[
    "{project build command}",
    "{project test command}",
    "{project lint command}"
])

プロジェクトで実際に使用されているビルド／テスト／lint コマンドを使います。ツールは出力をキャプチャし、タイムアウトを適用して、{results, all_pass, summary} を返します。

パート B：検証担当に委任

delegate_task(
    goal="[omh-role:verifier] Verify whether this task's acceptance criteria are met:\n\n{task.title}\n{task.acceptance_criteria}\n\nExecutor Report:\n{task.executor_report}",
    context="Evidence:\n{evidence.results}"
)

検証担当の応答を解析します：

• APPROVE / PASS：task.passes = true に設定します。学習内容に {task_id, summary, files_changed, gotchas} を追加します。.omh/logs/ralph-progress.md に追記します。
• REQUEST_CHANGES / FAIL：task.verifier_verdict を記録します。3 回の失敗ルール（ステップ 6）を確認します。

ステップ 6：エラー処理

3 回失敗時のサーキットブレーカー： エラーフィンガープリント {task_id, category, error_key} を作成します。task.error_fingerprints に追加します。同じ category + error_key を共有するフィンガープリントが 3 つある場合、タスクをブロック済みにし、エラーを記録して、次回の呼び出しで次の実行可能なタスクに進みます。残りのタスクがすべてブロックされている場合は、phase="blocked" を書き込み、報告して終了します。

キャンセルの検出（ユーザーが「stop」、「cancel」、「abort」と言った場合）：

omh_state(action="cancel", mode="ralph", instance_id="{instance_id}", reason="user request")

その後、状態の phase="cancelled" を書き込み、再開手順を示して終了します。

ステップ 7：最終レビュー

すべてのタスクが passes: true になったら：

evidence = omh_gather_evidence(commands=["{build command}", "{test command}"])

delegate_task(
    goal="[omh-role:architect] Review the complete implementation for architectural soundness.\n\nOriginal Plan:\n{source plan text}\n\nTasks Completed:\n{summary of all tasks + learnings}",
    context="Evidence:\n{evidence.results}\n\nFiles Changed Across All Tasks:\n{aggregate file list}"
)

• APPROVE：{active: false, phase: "complete"} を書き込み、状態ファイルを消去し、進捗ログは保持します。
• REQUEST_CHANGES：discovered: true を付けて新しいタスクを追加し、phase="execute" に設定します。

ステップ 8：状態を更新して終了

各アクションの後に：

omh_state(action="write", mode="ralph", instance_id="{instance_id}", data={...updated state...})

正常に終了します。呼び出し元は次の反復のために再度呼び出します。

注意事項

• 計画ゲートを決してスキップしないでください。 計画がなければ実行しません。
• 検証者による証拠がない限り、実行者の主張を決して信用しないでください。 検証者は omh_gather_evidence の出力を確認する必要があります。
• 検証者への委任中に証拠を収集しないでください。 委任する前に証拠を収集してください。
• 検証者とアーキテクトを混同しないでください。 担当業務、プロンプト、フェーズがそれぞれ異なります。
• 3回までのルールを守ってください。 同じエラーが3回発生したら、根本的な問題を明らかにしてください。
• 学びを次に生かしてください。 すべての実行者への委任に completed_task_learnings を含めてください。
• [omh-role:NAME] マーカーを使用してください — OMH プラグインがサブエージェントのセッションにロールプロンプトを自動で挿入します。ロールプロンプトのテキストを手動で直接記述しないでください。利用可能なロール：executor、verifier、architect、planner、critic、analyst、security-reviewer、code-reviewer、test-engineer、debugger。プラグインがない場合の代替手段：omh_state(action="load_role", role="NAME") を実行し、返されたプロンプトをコンテキストとして渡します。

Sentinel の規約

ほかのスキルは ralph のステータスを検出します：

• omh_state(action="check", mode="ralph", instance_id="{instance_id}") → {exists, active, phase, stale}
• phase="complete" → ralph は正常に完了しました
• phase="blocked" → ralph には介入が必要です