graph

Graph Skill

宣言的な JSON ディスクリプターから、決定論的なオーケストレーショングラフを実行します。 ランタイムは src/graph/* の封印済みディスクリプター契約と純粋スケジューラー契約を使用し、 独立した OS プロセス（omc graph run）を介して実行するため、クラッシュ後の復旧 （実行中に強制終了し、再実行してジャーナルから再開）が実際に機能します。

使用方法

/oh-my-claudecode:graph <descriptor.json>
/oh-my-claudecode:graph "build then test then ask me before deploy"   (author the descriptor first)

実行には常に CLI サブコマンドを使用します。

omc graph run <descriptor.json> [--runs-root <dir>]

非対話型グラフの場合は Bash ツールから実行します。進行状況の行は [run]、[node]、[ok]、[fail]、[join]、[done] としてストリーミングされます。

使用する場合

• 依存関係（DAG）が明示された、再現可能な複数ステップのパイプライン
• 中断後も継続する必要がある作業：強制終了／再起動後、ジャーナルから再開します
• 監査可能な実行：OCC ジャーナルとプロジェクションスナップショットが .omc/graph-runs/<run_id>/ に保存されます

使用しない場合：探索的な単発作業（会話または /team を使用してください）。 実行中に適応的な再計画が必要な作業（グラフは決定論的です）。

ワークフロー

1. ディスクリプターが提供された場合 -> 手順 3 に進みます。

2. パイプラインの説明がある場合 -> ディスクリプター JSON を作成します（以下のスキーマを参照）。プロジェクトの隣に保存し （.omc/graphs/<name>.json を推奨）、実行前にユーザーに提示します。run_id は論理パイプラインごとに一意である必要があります。 同じ run_id で再実行すると、再開され、最初からは実行されません。

3. 承認ノード：ディスクリプターに "kind": "human-approval" ノードが含まれている場合、Bash ツールから実行してはいけません（そこでは標準入力が対話型ではなく、 EOF は拒否としてフェイルクローズします）。代わりに、ユーザーに対話的に実行するよう伝えます。

   ! omc graph run <file>
   

   ! 接頭辞を付けると、このセッション内で標準入力をライブ状態にして実行されるため、y/n で応答できます。

4. 実行して進行状況を伝えます。終了コード（規定値）： 0 成功 | 1 終端失敗 | 19 別の書き込みプロセスがこの実行を所有中（ビジー） 20 ジャーナルの破損／改ざん（フェイルクローズ） | 21 再開時のディスクリプターの不一致 | 70 ランタイムクラッシュ（未分類のエラー）

5. 再開：クラッシュ後に同じコマンドを再実行すると、コミット済みの遷移を再生して続行します。 完了済みのノードは再実行されません。

ディスクリプタースキーマ（最小構成）

{ "descriptor_version": 1, "run_id": "unique-pipeline-id", "revision_id": "rev-1", "goal": "one line", "nodes": [ { "id": "n1", "kind": "command", "title": "...", "timeout_ms": 60000, "max_attempts": 2, "effect_policy": { "policy": "side_effect_free" }, "command": "npm test" }, { "id": "a1", "kind": "agent", "title": "...", "timeout_ms": 300000, "max_attempts": 1, "effect_policy": { "policy": "side_effect_free" }, "instructions": "..." }, { "id": "gate", "kind": "human-approval", "title": "...", "prompt": "続行しますか？" } ], "edges": [ { "id": "e1", "kind": "fixed", "from": "n1", "to": "a1" } ], "entry_node_ids": ["n1"], "concurrency_limit": 2, "terminal_verification_node_id": "a1" }

エッジの種類：fixed | conditional | fan_out/join ペア | back_edge（max_traversals による回数制限付きの再試行）。正式な Zod スキーマは src/graph/schema.ts を参照してください。 また、組み込みエグゼキューターが現在実際に実行する内容については、上記の「機能の境界」セクションをお読みください。

機能境界とセマンティクス（作成前にお読みください）

• エッジのサポート：組み込みのコマンド／エージェント実行器は、fixed エッジと fan_out／join の組み合わせに対応しています。conditional と back_edge のルートは、ランタイムおよびスケジューラーの契約で完全にサポートされていますが、結果に route を出力するカスタムの NodeExecutor が必要です。組み込みの実行器はルートを出力しないため、これらに依存するグラフは推測で処理されず、route_required で即座に失敗します。
• クラッシュ復旧の保証は、コマンドノードについては少なくとも 1 回の実行です。外部への副作用が発生してからジャーナルに追記されるまでの間にクラッシュすると、再開時にそのノードが再実行されます。idempotent コマンドでは、解決されたキーがコマンドの開始前に GRAPH_IDEMPOTENCY_KEY としてコマンドから利用でき、下流の重複排除用にも記録されます。組み込みの実行器は reconcile を拒否します。照合には、実際の外部照合権限を持つカスタム実行器が必要です。外部への副作用に対する厳密に 1 回の実行は、v1 の対象範囲外です。
• コマンドの信頼境界：コマンドノードは、現在の作業ディレクトリでプロセス権限を持つ任意のシェル行です。自身が記述した、または信頼できる実行記述子のみを実行してください。コマンドの子プロセスには、ホストのシークレットすべてではなく、許可リストにある環境変数（PATH、HOME/USERPROFILE、TEMP/TMP、ロケール／タイムゾーン、USER ID、GRAPH_*、および任意の冪等性キー）が渡されます。コマンドはファイルシステム／プロセスのサンドボックスで隔離されません。
• エージェントの権限境界：組み込みのエージェントノードは明示的に読み取り専用です。現在の作業ディレクトリで、追加ディレクトリへのアクセスなしで実行され、利用できるのは Read、Glob、Grep のみです。permissionMode: dontAsk が設定され、セッションの永続化は無効で、プロバイダー固有の環境変数許可リストが適用されます。エージェントのタイムアウト時には処理が中断され、SDK クエリも割り込み終了します。変更や外部への副作用が必要なエージェントには、カスタム実行器を使用してください。.omc/graph-runs/<run_id>/descriptor.json は実行可能なコンテンツとして扱ってください。