@geekbeer/minion 3.17.0 → 3.22.0

package/docs/api-reference.md

@@ -240,6 +240,42 @@ Changes via the config API take effect immediately (no restart required).
 
 Allowed keys: `LLM_COMMAND`, `REFLECTION_TIME`
 
+### LLM Plugins (opt-in)
+
+プラグイン方式の LLM 設定。`primary` を設定すると有効化される。未設定の場合は従来の `LLM_COMMAND` 経路で動作する。設定は `~/minion/llm/config.json` にファイルとして保存される (env var に依存しないため quote 破損バグの影響を受けない)。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/llm/plugins` | List available plugins with capabilities & auth status |
+| GET | `/api/llm/config` | Get current primary/enabled selection |
+| PUT | `/api/llm/config` | Update primary/enabled. Body: `{primary?, enabled?}` |
+
+**GET /api/llm/plugins response**:
+```json
+{
+  "success": true,
+  "plugins": [
+    {
+      "name": "claude",
+      "displayName": "Claude Code",
+      "capabilities": {
+        "toolUse": true,
+        "streaming": true,
+        "vision": true,
+        "imageGeneration": false,
+        "sessionResume": true
+      },
+      "authenticated": true,
+      "builtin": true,
+      "enabled": true,
+      "primary": true
+    }
+  ]
+}
+```
+
+**PUT /api/llm/config** body: `{ "primary": "claude", "enabled": ["claude", "gemini", "codex"] }`
+
 ### Permissions
 
 CLIツール（Claude Code, Gemini CLI, Codex CLI）のパーミッション管理。
@@ -853,6 +889,409 @@ POST `/api/minion/execution` body:
 }
 ```
 
+### Pending Revisions (PM のみ)
+
+レビューで `revision_requested` になったステップを検知する。ミニオンの `revision-watcher` デーモンが30秒ごとにポーリングし、LLM で差し戻し先ステップを判断した上で `/api/minion/revision-reset` を呼び出す。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/pending-revisions` | `revision_requested` 状態のステップ一覧（PMのプロジェクトのみ） |
+| POST | `/api/minion/revision-reset` | 差し戻し対象ステップを `pending` に戻す |
+
+GET Response:
+```json
+{
+  "revisions": [
+    {
+      "execution_id": "uuid",
+      "workflow_name": "daily-check",
+      "revision_step_index": 2,
+      "review_comment": "string (レビュアーのフィードバック)",
+      "pipeline": [
+        {
+          "step_index": 0,
+          "skill_version_id": "uuid",
+          "skill_name": "string|null",
+          "assigned_role": "pm|engineer|accountant"
+        }
+      ]
+    }
+  ]
+}
+```
+
+POST `/api/minion/revision-reset` body:
+```json
+{
+  "execution_id": "uuid",
+  "target_step_index": 0,
+  "revision_step_index": 2,
+  "revision_feedback": "string (省略可、target step の review_comment に保存)"
+}
+```
+
+- `target_step_index` は差し戻し先（やり直し起点）のインデックス
+- `revision_step_index` は差し戻しを要求されたレビューステップのインデックス（`target_step_index <= revision_step_index`）
+- target から revision までのステップが `pending` に戻り、`revision_feedback` が再実行時のコンテキストとして注入される
+
+Response:
+```json
+{
+  "success": true,
+  "reset_count": 3,
+  "target_step_index": 0,
+  "revision_step_index": 2
+}
+```
+
+---
+
+## DAG Workflows (HQ, ノード/エッジ方式)
+
+DAG ワークフローは従来の線形パイプラインを拡張した有向非巡回グラフ方式のワークフローです。HQダッシュボードの DAG エディタで作成・編集できるほか、ミニオンAPI経由でも JSON ベースで編集可能（PMロールのみ）。ミニオンはプルベースのポーリングで pending ノードを検出・実行します。
+
+### 編集エンドポイント (PMロール限定)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/minion/dag-workflows` | 新規 DAG ワークフローを作成（ドラフトとして保存） |
+| PUT | `/api/minion/dag-workflows/:id` | ドラフト graph / メタデータを更新 |
+| POST | `/api/minion/dag-workflows/:id/publish` | ドラフトをバリデーションし新バージョンとして公開 |
+
+いずれも Bearer 認証 + プロジェクトメンバーシップが `role='pm'` のミニオンに限定。非PMは 403。PUT / POST はドラフト保存時にセマンティックバリデーションを行わない（`graph` が object で `nodes` / `edges` 配列を持つことの構造チェックのみ）。パブリッシュ時には `validateDagGraph` によるフル検証（ノードID重複・エッジの参照整合性・サイクル検出・必須フィールド等）が走る。
+
+**推奨ワークフロー**: create → put で graph を整える → publish、または既存ワークフローに対して put → publish。
+
+POST `/api/minion/dag-workflows` body:
+```json
+{
+  "project_id": "uuid",
+  "name": "my-dag",
+  "graph": { "nodes": [], "edges": [] },
+  "content": "Markdown description (optional)",
+  "change_summary": "initial draft (optional)"
+}
+```
+
+- `name` は `/^[a-z0-9-]+$/`
+- `graph` は省略可。省略時はドラフト無しで作成される
+- レスポンスは作成された DAG ワークフロー全体（`current_version_id` は null のまま、ドラフトに保存）
+
+PUT `/api/minion/dag-workflows/:id` body（全フィールド optional、省略したものは変更しない）:
+```json
+{
+  "graph": { "nodes": [...], "edges": [...] },
+  "content": "...",
+  "change_summary": "Updated fan-out branch",
+  "name": "renamed-dag",
+  "is_active": true,
+  "maturity": "preview|stable|..."
+}
+```
+
+- `graph` を渡すと draft_graph が上書きされる（構造チェックのみ、セマンティックチェック無し）
+- `content` / `change_summary` は `graph` と併せて draft スロットに保存される
+
+POST `/api/minion/dag-workflows/:id/publish` (body なし):
+- 現在の draft_graph を `validateDagGraph` でフル検証
+- OK なら新バージョン行を `dag_workflow_versions` に追加し、`current_version_id` を更新、ドラフトをクリア
+- NG なら 400 で `{ error, details: [...] }` を返却
+
+### ミニオン CLI ラッパー
+
+以下の `hq` サブコマンドが上記エンドポイントを呼び出す。いずれもリクエスト送信前にローカルで JSON 構文検証を行う。
+
+```bash
+hq create dag-workflow <body.json>           # POST /api/minion/dag-workflows
+hq put dag-workflow <id> <body.json>         # PUT  /api/minion/dag-workflows/:id
+hq publish dag-workflow <id>                 # POST /api/minion/dag-workflows/:id/publish
+hq fetch dag-workflow <id>                   # GET  /api/minion/dag-workflows/:id
+hq fetch dag-execution <id>                  # GET  /api/minion/dag-executions/:id
+```
+
+### DAG Read Endpoints (チャットコンテキスト用)
+
+ユーザーがHQダッシュボードでDAGエディタ/実行詳細を閲覧中にチャットした場合、チャットコンテキストに `context.type = 'dag-workflow'` または `'dag-execution'` が注入される。以下の `hq` CLI コマンドで詳細を取得できる（内部的に `/api/minion/dag-workflows/:id` / `/api/minion/dag-executions/:id` を叩く）。
+
+| コマンド | 対応エンドポイント | 用途 |
+|---------|-------------------|------|
+| `hq fetch dag-workflow <id>` | GET `/api/minion/dag-workflows/:id` | DAG ワークフロー定義（published graph + draft）取得 |
+| `hq fetch dag-execution <id>` | GET `/api/minion/dag-executions/:id` | DAG 実行詳細（graph_snapshot + node_executions）取得 |
+
+いずれもミニオンのプロジェクトメンバーシップでスコープされる。ミニオンが参加していないプロジェクトのDAGは 404。
+
+GET `/api/minion/dag-workflows/:id` Response:
+```json
+{
+  "id": "uuid",
+  "project_id": "uuid",
+  "name": "my-dag",
+  "is_active": true,
+  "maturity": "draft|stable|...",
+  "current_version_id": "uuid",
+  "draft_graph": { "nodes": [...], "edges": [...] } ,
+  "draft_content": "markdown|null",
+  "draft_change_summary": "string|null",
+  "draft_updated_at": "ISO|null",
+  "current_version": {
+    "id": "uuid",
+    "version": 3,
+    "graph": { "nodes": [...], "edges": [...] },
+    "content": "markdown",
+    "change_summary": "string",
+    "created_at": "ISO"
+  },
+  "my_role": "pm|engineer|accountant|null"
+}
+```
+
+GET `/api/minion/dag-executions/:id` Response:
+```json
+{
+  "id": "uuid",
+  "dag_workflow_id": "uuid",
+  "dag_workflow_name": "my-dag",
+  "dag_workflow_version_id": "uuid",
+  "dag_workflow_version": 3,
+  "project_id": "uuid",
+  "status": "pending|running|completed|failed",
+  "graph_snapshot": { "nodes": [...], "edges": [...] },
+  "started_at": "ISO|null",
+  "completed_at": "ISO|null",
+  "created_at": "ISO",
+  "node_executions": [
+    {
+      "id": "uuid",
+      "node_id": "n2",
+      "scope_path": "",
+      "status": "pending|waiting|running|completed|failed|skipped",
+      "outcome": "success|failure|null",
+      "input_data": {},
+      "output_data": {},
+      "output_summary": "string|null",
+      "requires_review": false,
+      "review_status": "review_pending|approved|rejected|revision_requested|null",
+      "revision_count": 0,
+      "started_at": "ISO|null",
+      "completed_at": "ISO|null"
+    }
+  ]
+}
+```
+
+### DAG Runtime Endpoints (ミニオン向け)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/dag/minion/pending-nodes` | 自分が実行すべき pending ノード一覧（ロール一致・依存解決済み） |
+| POST | `/api/dag/minion/claim-node` | ノードを楽観ロックで取得（排他実行） |
+| POST | `/api/dag/minion/node-complete` | ノード完了を報告し、下流ノードへカスケード |
+
+ミニオンの `dag-step-poller` デーモンが30秒ごとに `pending-nodes` を叩き、最大2並列で claim → skill/transform 実行 → node-complete の流れを回す。`skill`・`transform` 以外のノード（start/end/review/fan_out/join/conditional）はHQ内部のカスケードエンジンが処理するため、ミニオンには返されない。
+
+#### GET /api/dag/minion/pending-nodes
+
+Response:
+```json
+{
+  "nodes": [
+    {
+      "node_execution_id": "uuid",
+      "execution_id": "uuid",
+      "dag_workflow_name": "my-dag",
+      "node_id": "node-abc",
+      "scope_path": "",
+      "node_type": "skill",
+      "skill_version_id": "uuid|null",
+      "skill_name": "skill-1|null",
+      "assigned_role": "pm|engineer|accountant",
+      "input_data": { "...": "..." },
+      "revision_feedback": "string|null",
+      "transform_instruction": "string|null"
+    }
+  ]
+}
+```
+
+返却条件:
+- `assigned_role` がミニオンのプロジェクトロールと一致
+- ノードの `status` が `pending`
+- `node_type` が `skill` または `transform`
+- スコープ内の全依存ノードが `completed`（`requires_review` の場合は `approved` も必要）
+
+`scope_path` は fan-out 内のインスタンスを示す（ルートは空文字列、1段のfan-outでは `fan_out_A:0`、ネストでは `fan_out_A:2/fan_out_B:1`）。依存解決は同じ scope_path 内で閉じる。
+
+#### POST /api/dag/minion/claim-node
+
+Body:
+```json
+{ "node_execution_id": "uuid" }
+```
+
+Response (成功 / 201):
+```json
+{ "success": true, "node_execution_id": "uuid" }
+```
+
+Response (競合 / 409): 他ミニオンが既に claim 済み、または状態が pending でない場合。
+```json
+{ "error": "Node already claimed or not pending" }
+```
+
+409 を受け取った場合は `pending-nodes` を取り直して次のノードに進むこと。
+
+#### POST /api/dag/minion/node-complete
+
+Body:
+```json
+{
+  "node_execution_id": "uuid",
+  "status": "completed|failed",
+  "output_data": { "...": "..." },
+  "output_summary": "string (省略可、レポート/サマリー)"
+}
+```
+
+- `status: completed` で `requires_review` なノードはサーバ側で `review_status=review_pending` になりカスケードは停止（レビュー承認まで下流は生成されない）
+- `status: failed` でもカスケードは走る（fan-out join が `on_failure=ignore|collect` で集約できるため）
+- `output_data` は下流ノードの `input_data` に伝播する。**スキル実行時はスキル本文の「## Output Data」セクションの JSON コードブロックを抽出して `output_data` に載せる規約**（ミニオンの `dag-node-executor` がこの抽出を行う）
+
+Response:
+```json
+{ "success": true }
+```
+
+レビュー待ち状態の場合:
+```json
+{ "success": true, "review_pending": true }
+```
+
+### DAG Graph Structure
+
+DAG ワークフローの graph は以下の構造で保存される（`dag_workflow_versions.graph` / `dag_executions.graph_snapshot`）:
+
+```json
+{
+  "nodes": [
+    { "id": "n1", "type": "start", "label": "Start", "position": { "x": 0, "y": 0 } },
+    {
+      "id": "n2",
+      "type": "skill",
+      "label": "Fetch data",
+      "skill_version_id": "uuid",
+      "assigned_role": "engineer"
+    },
+    {
+      "id": "n3",
+      "type": "fan_out",
+      "label": "Per item",
+      "fan_out_source": ".items",
+      "template": { "nodes": [ ... ], "edges": [ ... ] },
+      "join_node": "n4",
+      "max_concurrency": 3
+    },
+    {
+      "id": "n4",
+      "type": "join",
+      "label": "Collect",
+      "fan_out_node": "n3",
+      "join_mode": "all",
+      "on_failure": "collect"
+    },
+    { "id": "n5", "type": "end", "label": "End" }
+  ],
+  "edges": [
+    { "id": "e1", "source": "n1", "target": "n2", "kind": "normal" },
+    { "id": "e2", "source": "n2", "target": "n3" },
+    { "id": "e3", "source": "n3", "target": "n4" },
+    { "id": "e4", "source": "n4", "target": "n5" }
+  ]
+}
+```
+
+#### Node Types
+
+| `type` | 役割 | ミニオン実行 |
+|--------|------|---------------|
+| `start` | エントリポイント | ❌ (内部) |
+| `end` | 終端 | ❌ (内部) |
+| `skill` | スキル実行。`skill_version_id` と `assigned_role` が必須 | ✅ |
+| `transform` | LLM によるデータ変換。`transform_instruction` が必須 | ✅ |
+| `review` | レビューゲート。`approved` / `revision_requested` で分岐 | ❌ (内部) |
+| `fan_out` | 配列入力をテンプレートsub-graphに展開して並列実行 | ❌ (内部) |
+| `join` | fan_out の結果を集約 | ❌ (内部) |
+| `conditional` | 条件分岐（`llm` / `regex` / `jq`） | ❌ (内部) |
+
+#### DagNode 主要フィールド
+
+| Field | Type | 説明 |
+|-------|------|------|
+| `id` | string | グラフ内ユニークなノードID |
+| `type` | DagNodeType | 上記ノード種別 |
+| `label` | string | 表示名 |
+| `skill_version_id` | string? | skill ノードで使用するスキルバージョンUUID |
+| `assigned_role` | `pm`\|`engineer`\|`accountant` | 実行ロール |
+| `fan_out_source` | string? | fan_out: 入力から配列を取り出すドット記法（例 `.items`） |
+| `template` | DagGraph? | fan_out: 各要素ごとに展開するsub-graph |
+| `join_node` | string? | fan_out: 対応する join ノードID |
+| `max_concurrency` | number? | fan_out: 並列インスタンス上限 |
+| `fan_out_node` | string? | join: 対応する fan_out ノードID |
+| `join_mode` | `all`\|`any`\|`majority` | join: 完了判定 |
+| `on_failure` | `fail_all`\|`ignore`\|`collect` | join: 失敗時の挙動 |
+| `condition_type` | `llm`\|`regex`\|`jq` | conditional: 条件評価方式 |
+| `condition_expression` | string | conditional: 条件式 |
+| `branches` | Record<string,string> | conditional: 条件出力→遷移先ノードID |
+| `default_branch` | string? | conditional: マッチしなかった場合の遷移先 |
+| `transform_instruction` | string | transform: LLMへの変換指示 |
+| `review` | object | review: レビュー設定 |
+
+#### DagEdge
+
+| Field | Type | 説明 |
+|-------|------|------|
+| `id` | string | エッジID |
+| `source` | string | 起点ノードID |
+| `target` | string | 終点ノードID |
+| `kind` | `normal`\|`approved`\|`revision` | `normal`=通常、`approved`=review承認時、`revision`=review差し戻し時（サイクル検出では無視される） |
+| `condition_label` | string? | 表示ラベル |
+
+### DAG Execution API (読み取り)
+
+| Method | Endpoint | Auth | 用途 |
+|--------|----------|------|------|
+| GET | `/api/dag/executions/:execId` | セッション | 実行詳細 (graph_snapshot + node_executions) 取得。UI用、ミニオンは通常使わない |
+
+Response:
+```json
+{
+  "id": "uuid",
+  "dag_workflow_id": "uuid",
+  "dag_workflow_name": "my-dag",
+  "dag_workflow_version_id": "uuid",
+  "status": "pending|running|completed|failed",
+  "graph_snapshot": { "nodes": [...], "edges": [...] },
+  "started_at": "ISO",
+  "completed_at": "ISO|null",
+  "node_executions": [
+    {
+      "id": "uuid",
+      "node_id": "n2",
+      "scope_path": "",
+      "status": "pending|waiting|running|completed|failed|skipped",
+      "outcome": "success|failure|null",
+      "input_data": {},
+      "output_data": {},
+      "output_summary": "string|null",
+      "requires_review": false,
+      "review_status": "review_pending|approved|rejected|revision_requested|null",
+      "revision_count": 0,
+      "started_at": "ISO|null",
+      "completed_at": "ISO|null"
+    }
+  ]
+}
+```
+
 ### Issue Reporting (GitHub Issue 起票)
 
 | Method | Endpoint | Description |

package/docs/task-guides.md

@@ -144,6 +144,226 @@ curl -s -X POST "http://localhost:8080/api/workflows/push/<name>" \
   -H "Authorization: Bearer $API_TOKEN"
 ```
 
+> **Note**: `/api/workflows/push|fetch` は線形パイプライン形式（`pipeline_skill_names`）の旧式ワークフロー専用です。DAGワークフロー（ノード/エッジ形式）はHQダッシュボードの DAG エディタで作成・編集します。次節を参照。
+
+---
+
+## DAG ワークフロー (ノード/エッジ形式)
+
+DAG ワークフローは有向非巡回グラフでスキル間の依存関係を表現する新方式のワークフローです。fan-out による並列展開、join による集約、conditional による分岐、transform による LLM データ変換、review によるゲーティングをサポートします。
+
+**HQダッシュボードの DAG エディタ（プロジェクト画面 → 「DAG (beta)」タブ）で GUI 編集**できるほか、**ミニオンからは JSON ベースで編集可能**（PMロールのみ）。ミニオンは実行ランタイムも担当し、`dag-step-poller` デーモンが pending ノードを自動で処理します。
+
+### ミニオンによる DAG ワークフロー編集 (PM のみ)
+
+ミニオンは `hq` CLI で DAG ワークフローの graph JSON を直接編集できる。
+
+#### 1. 新規作成
+
+```bash
+# body.json を用意
+cat > /tmp/dag-create.json <<'EOF'
+{
+  "project_id": "<project-uuid>",
+  "name": "my-dag",
+  "content": "Description of this DAG",
+  "change_summary": "initial draft",
+  "graph": {
+    "nodes": [
+      { "id": "start", "type": "start", "label": "Start", "position": { "x": 0, "y": 0 } },
+      { "id": "end",   "type": "end",   "label": "End",   "position": { "x": 300, "y": 0 } }
+    ],
+    "edges": [
+      { "id": "e1", "source": "start", "target": "end" }
+    ]
+  }
+}
+EOF
+
+# 作成（ドラフトとして保存される、まだ v1 にはならない）
+hq create dag-workflow /tmp/dag-create.json
+```
+
+- `name` は `/^[a-z0-9-]+$/`
+- `graph` は省略可。省略時は空で作成してから put で埋めていく
+- レスポンスの `id` を控えて後続の put / publish に使う
+
+#### 2. ドラフト更新
+
+```bash
+# body.json を用意（フィールドは全て optional）
+cat > /tmp/dag-update.json <<'EOF'
+{
+  "graph": {
+    "nodes": [
+      { "id": "start", "type": "start", "label": "Start" },
+      { "id": "fetch", "type": "skill", "label": "Fetch",
+        "skill_version_id": "<skill-version-uuid>", "assigned_role": "engineer" },
+      { "id": "end",   "type": "end", "label": "End" }
+    ],
+    "edges": [
+      { "id": "e1", "source": "start", "target": "fetch" },
+      { "id": "e2", "source": "fetch", "target": "end" }
+    ]
+  },
+  "content": "Description updated",
+  "change_summary": "add fetch skill node"
+}
+EOF
+
+hq put dag-workflow <dag-workflow-id> /tmp/dag-update.json
+```
+
+- ドラフト保存時はセマンティックバリデーション無し（構造チェックのみ）。未完成状態でも保存できる。
+- `hq` CLI は送信前にローカルで JSON 構文を検証する。壊れていれば API を叩かずに `Error: invalid JSON syntax in ...` で停止する。
+
+#### 3. 公開（バリデーション付き）
+
+```bash
+hq publish dag-workflow <dag-workflow-id>
+```
+
+- 現在のドラフトを `validateDagGraph` でフル検証（ノードID重複・エッジ参照整合性・サイクル・必須フィールド等）
+- OK なら新バージョンが `dag_workflow_versions` に追加され、`current_version_id` が更新される
+- NG なら 400 で `{ error, details: [...] }` が返る。エラー詳細を見てドラフトを修正し再試行する
+- 公開後、`dag-step-poller` による実行対象になる
+
+#### 4. 既存ワークフローの取得と編集のラウンドトリップ
+
+```bash
+# 現在の state をダウンロード
+hq fetch dag-workflow <dag-workflow-id> > /tmp/current.json
+
+# jq で graph 部分だけ抜き出して編集用ボディを作る
+jq '{ graph: (.draft_graph // .current_version.graph), content: (.draft_content // .current_version.content), change_summary: "…" }' \
+  /tmp/current.json > /tmp/dag-update.json
+
+# 編集（エディタや AI で graph を変更）
+# ...
+
+# 更新 → 公開
+hq put dag-workflow <dag-workflow-id> /tmp/dag-update.json
+hq publish dag-workflow <dag-workflow-id>
+```
+
+#### 権限と注意事項
+
+- 書き込み（create / put / publish）は **PMロールのみ**。Engineer / accountant では 403 が返る。読み取り（fetch）は全メンバー可。
+- ドラフト保存は軽量（構造チェックのみ）。インクリメンタルに graph を組み立てていくのに適している。
+- セマンティックエラーは publish 時にまとめて検出されるため、途中保存と最終公開を使い分けること。
+
+### 実行フロー（ランタイム側、参考）
+
+```
+HQ側:
+  ユーザーが DAG 実行を開始
+  → dag_executions レコード作成
+  → 初期ノード (start の下流) が status=pending で生成
+
+ミニオン側 (dag-step-poller, 30秒ごと):
+  1. GET /api/dag/minion/pending-nodes
+     → 自分のロールに一致し、依存が解決済みの pending ノードを取得
+  2. POST /api/dag/minion/claim-node
+     → 楽観ロックでノードを取得（409 の場合は他ミニオンが先に処理中）
+  3. スキル実行 (skill ノード) または変換実行 (transform ノード)
+  4. POST /api/dag/minion/node-complete
+     → output_data と output_summary を報告
+
+HQ側 (カスケードエンジン):
+  - completed → 下流ノードを pending で生成 (依存解決後)
+  - fan_out ノード → template を N 個展開、各インスタンスに scope_path 付与
+  - join ノード → fan-out 全インスタンス完了待機・集約
+  - conditional ノード → 条件評価で分岐先を決定
+  - review ノード → review_pending で停止、レビュー承認で再開
+```
+
+### スキルの output_data 出力規約
+
+DAGのスキルノードでは、下流ノードに構造化データを渡すため、スキル本文に「## Output Data」セクションを設けて JSON コードブロックで出力を記述すること。ミニオンの `dag-node-executor` がこのブロックを抽出して `output_data` に載せる。
+
+例（スキル実行結果の末尾）:
+
+````markdown
+## 実行サマリー
+
+検索結果を3件取得しました。
+
+## Output Data
+
+```json
+{
+  "items": [
+    { "id": "a1", "title": "Item A" },
+    { "id": "a2", "title": "Item B" },
+    { "id": "a3", "title": "Item C" }
+  ],
+  "count": 3
+}
+```
+````
+
+- 「## Output Data」セクションが無い、または JSON パースに失敗した場合は `{ _raw: "<出力全文>" }` にフォールバック
+- 失敗時 (`status: failed`) は `output_data` は空オブジェクト `{}` として扱われる
+
+### Fan-out / Join の動作
+
+fan-out ノードは入力から配列を取り出し、template sub-graph を配列要素数だけ並列展開する。
+
+```
+入力 input_data = { "items": [A, B, C] }
+fan_out_source = ".items"
+↓
+3 つのインスタンスを生成:
+  scope_path="<fan_out_id>:0", input=A, 対応する template nodes が pending で出現
+  scope_path="<fan_out_id>:1", input=B, ...
+  scope_path="<fan_out_id>:2", input=C, ...
+↓
+各インスタンスの template 実行完了後、対応する join ノードが集約
+  join_mode=all: 全成功で完了
+  join_mode=any: いずれか成功で完了
+  join_mode=majority: 過半数成功で完了
+  on_failure=collect: 失敗も含め結果を集める
+  on_failure=ignore: 失敗を除外
+  on_failure=fail_all: 1つでも失敗すれば join も失敗
+↓
+集約結果が join の output_data として下流に渡る
+```
+
+ミニオンから見ると、fan-out 内の skill/transform ノードも通常どおり `pending-nodes` に返ってくる（`scope_path` が空でない点だけが違い）。
+
+### Transform ノード
+
+Transform ノードは LLM を使って input_data を output_data に変換する軽量ノード。`transform_instruction` に自然言語で変換指示を書く。ミニオン側では `transform_instruction` を本文とする一時的なスキルを組み立てて実行する。
+
+```
+transform_instruction: "items 配列から title が 'Item B' のエントリを除外し、残りを返してください"
+input_data: { "items": [{ "title": "Item A" }, { "title": "Item B" }, { "title": "Item C" }] }
+↓ (LLM)
+output_data: { "items": [{ "title": "Item A" }, { "title": "Item C" }] }
+```
+
+### Review ノードとリビジョン
+
+Review ノードはレビューゲート。`review_status=review_pending` で下流カスケードが停止する。レビュアーが:
+- `approved` にすると `approved` 種別のエッジで下流に進む
+- `revision_requested` にすると `revision` 種別のエッジで差し戻し先に戻る
+
+レガシー線形パイプラインの差し戻しは `revision-watcher` デーモン + `/api/minion/pending-revisions` + `/api/minion/revision-reset` で処理される。DAGの差し戻しはサーバ側カスケードで自動処理。
+
+### デバッグ
+
+```bash
+# 自分が取得できる pending DAG ノードを確認
+curl -s "$HQ_URL/api/dag/minion/pending-nodes" \
+  -H "Authorization: Bearer $API_TOKEN" | jq
+
+# DAG 実行の詳細（UI用だがデバッグにも使える、セッション認証が必要なため通常はHQダッシュボード側から）
+# ミニオンから実行詳細を直接取得する手段は現時点では無い。pending-nodes で見える範囲で判断する
+
+# dag-step-poller のログを確認
+tail -f ~/.minion/logs/agent.log | grep '\[DAG'
+```
+
 ---
 
 ## プロジェクトコンテキストの操作