@geekbeer/minion 3.28.1 → 3.29.4

package/docs/api-reference.md

@@ -1056,17 +1056,291 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 - OK なら新バージョン行を `dag_workflow_versions` に追加し、`current_version_id` を更新、ドラフトをクリア
 - NG なら 400 で `{ error, details: [...] }` を返却
 
+### ノード/エッジ操作エンドポイント (PMロール限定)
+
+**graph 全文を JSON で書く代わりに、ノード・エッジを1つずつ操作する**ためのAPI。各操作は自動でドラフトに保存され、レスポンスに `validation` フィールド（`validateDagGraph` によるフル検証結果）を含む。これにより、1操作ごとにバリデーションフィードバックを受け取れる。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/minion/dag-workflows/:id/nodes` | ノードを追加（エッジ自動生成対応） |
+| PATCH | `/api/minion/dag-workflows/:id/nodes/:nodeId` | ノードのプロパティを更新 |
+| DELETE | `/api/minion/dag-workflows/:id/nodes/:nodeId` | ノードを削除（自動再接続対応） |
+| POST | `/api/minion/dag-workflows/:id/edges` | エッジを追加 |
+| PATCH | `/api/minion/dag-workflows/:id/edges/:edgeId` | エッジの kind / condition_label / contract を更新 |
+| DELETE | `/api/minion/dag-workflows/:id/edges/:edgeId` | エッジを削除 |
+| GET | `/api/minion/dag-workflows/:id/contracts` | 全contractsを取得 |
+| PUT | `/api/minion/dag-workflows/:id/contracts` | 全contractsを上書き |
+| POST | `/api/minion/dag-workflows/:id/contracts` | 個別contractを追加/更新 |
+| DELETE | `/api/minion/dag-workflows/:id/contracts` | 個別contractを削除 |
+| POST | `/api/minion/dag-workflows/:id/validate` | ドラフトをフル検証（公開せず） |
+
+#### POST `/api/minion/dag-workflows/:id/nodes` — ノード追加
+
+```json
+{
+  "type": "skill",
+  "label": "Fetch Data",
+  "after": "start",
+  "before": "end",
+  "skill_id": "<skill-uuid>",
+  "skill_version_id": "<version-uuid>",
+  "assigned_role": "engineer"
+}
+```
+
+- `type` (必須): `start` | `end` | `skill` | `review` | `fan_out` | `join` | `conditional` | `transform`
+- `id` (任意): 省略時は `<type>_1`, `<type>_2`, ... で自動採番
+- `label` (任意): 省略時は `New <type>`
+- `after` (任意): このノードの後ろに挿入。`after` → 新ノード へのエッジを自動生成
+- `before` (任意): このノードの前に挿入。新ノード → `before` へのエッジを自動生成
+- `after` と `before` を**両方指定**すると、既存の `after → before` エッジを削除して `after → 新ノード → before` に差し替え
+
+**ノードタイプ別の必須フィールド（publish 時検証）:**
+
+| type | 必須フィールド | 備考 |
+|------|---------------|------|
+| `start` / `end` | なし | |
+| `skill` | `skill_id`, `skill_version_id`, `assigned_role` | |
+| `review` | `review: { reviewer_type, criteria, revision_target }` | `revision` エッジと `approved` エッジが**自動生成**される |
+| `fan_out` | `fan_out_source`, `template` | `template` は sub-graph `{ nodes, edges }` |
+| `join` | `join_mode`, `aggregation` | |
+| `conditional` | `condition_type`, `branches` or `default_branch` | |
+| `transform` | `transform_instruction`, `assigned_role` | |
+
+**review ノード追加の例:**
+```json
+{
+  "type": "review",
+  "label": "Quality Check",
+  "after": "skill_1",
+  "before": "end",
+  "review": {
+    "reviewer_type": "human",
+    "criteria": "成果物の品質を確認",
+    "revision_target": "skill_1"
+  }
+}
+```
+→ `skill_1 → end` のエッジが削除され、以下が自動生成:
+- `skill_1 → review_1` (normal)
+- `review_1 → end` (approved)
+- `review_1 → skill_1` (revision)
+
+#### PATCH `/api/minion/dag-workflows/:id/nodes/:nodeId` — ノード更新
+
+```json
+{
+  "label": "Updated Label",
+  "skill_version_id": "<new-version-uuid>",
+  "position": { "x": 200, "y": 100 }
+}
+```
+
+- 指定したフィールドのみ上書き（未指定フィールドは変更しない）
+- `position` でノードのエディタ上の座標を更新可能
+- review ノードの `revision_target` を変更すると、revision エッジが自動で張り替えられる
+- fan_out ノードの `template` フィールドを上書きすることで、テンプレート sub-graph を更新可能（下記「fan_out テンプレートの編集」参照）
+
+#### DELETE `/api/minion/dag-workflows/:id/nodes/:nodeId` — ノード削除
+
+- start / end ノードは削除不可 (400)
+- 削除されたノードに接続されていたエッジも全て削除される
+- **自動再接続**: 削除ノードに incoming 1本 + outgoing 1本のエッジがあった場合、それらを直結する新エッジを自動生成
+
+レスポンス `extra` フィールド:
+```json
+{
+  "removed_node": "skill_2",
+  "removed_edges": ["edge_3", "edge_4"],
+  "reconnected_edge": { "id": "edge_5", "source": "skill_1", "target": "end" }
+}
+```
+
+#### POST `/api/minion/dag-workflows/:id/edges` — エッジ追加
+
+```json
+{
+  "source": "skill_1",
+  "target": "skill_2",
+  "kind": "normal",
+  "condition_label": "success"
+}
+```
+
+- `source`, `target` (必須): 既存ノードのID
+- `kind` (任意): `normal` (default) | `approved` | `revision`
+- `condition_label` (任意): conditional ノードの分岐ラベル
+- `contract` (任意): `graph.contracts` 内の型名への参照
+- `id` (任意): 省略時は `edge_1`, `edge_2`, ... で自動採番
+
+#### PATCH `/api/minion/dag-workflows/:id/edges/:edgeId` — エッジ更新
+
+```json
+{
+  "kind": "approved",
+  "condition_label": "success",
+  "contract": "prototype"
+}
+```
+
+- `kind` (任意): `normal` | `approved` | `revision`
+- `condition_label` (任意): 分岐ラベル。`null` を渡すとクリア
+- `contract` (任意): contracts 内の型名。`null` を渡すとクリア
+- 指定したフィールドのみ上書き（未指定フィールドは変更しない）
+
+#### DELETE `/api/minion/dag-workflows/:id/edges/:edgeId` — エッジ削除
+
+- エッジIDを指定して削除
+
+#### Contracts API
+
+エッジを流れるデータの型を定義するための API。contracts は `graph.contracts` に保存される。
+
+**Contract のスキーマ:**
+
+```typescript
+{
+  description: string          // contract の説明
+  fields: [{
+    key: string                // フィールド名
+    type: "string" | "number" | "boolean" | "url" | "array" | "object"  // フィールド型
+    description: string        // フィールドの説明
+    required?: boolean         // 必須フラグ (省略時 false)
+  }]
+}
+```
+
+**注意:**
+- エッジに設定する `contract` は `graph.contracts` に存在する名前でなければならない（存在しない名前を指定すると 400 エラー）
+- contract を削除すると、参照しているエッジの `contract` フィールドが自動でクリアされる（DELETE / PUT 共通）
+- `validate` エンドポイントはダングリング参照（存在しない contract への参照）をエラーとして報告する
+
+##### GET `/api/minion/dag-workflows/:id/contracts` — 全contracts取得
+
+レスポンス: `{ "contracts": { "name": { "description": "...", "fields": [...] }, ... } }`
+
+##### PUT `/api/minion/dag-workflows/:id/contracts` — 全contracts上書き
+
+```json
+{
+  "contracts": {
+    "prototype": {
+      "description": "プロトタイプ成果物",
+      "fields": [
+        { "key": "git_url", "type": "url", "description": "リポジトリURL", "required": true },
+        { "key": "preview_url", "type": "url", "description": "プレビューURL" }
+      ]
+    }
+  }
+}
+```
+
+##### POST `/api/minion/dag-workflows/:id/contracts` — 個別contract追加/更新
+
+```json
+{
+  "name": "prototype",
+  "contract": {
+    "description": "プロトタイプ成果物",
+    "fields": [
+      { "key": "git_url", "type": "url", "description": "リポジトリURL", "required": true }
+    ]
+  }
+}
+```
+
+##### DELETE `/api/minion/dag-workflows/:id/contracts` — 個別contract削除
+
+```json
+{ "name": "prototype" }
+```
+
+参照しているエッジの `contract` フィールドも自動でクリアされる。レスポンスの `cleared_edges` にクリアされたエッジIDの一覧が含まれる。
+
+#### POST `/api/minion/dag-workflows/:id/validate` — ドラフト検証
+
+body なし。現在のドラフトを `validateDagGraph` でフル検証し結果を返す。**公開はしない**。
+
+```json
+{
+  "valid": false,
+  "errors": ["Skill node \"skill_1\" must have a skill selected"],
+  "graph_errors": [],
+  "node_errors": {
+    "skill_1": ["Skill node \"skill_1\" must have a skill selected"]
+  }
+}
+```
+
+#### 全操作共通のレスポンス形式
+
+ノード/エッジ操作のレスポンスにはワークフロー全体 + `validation` フィールドが含まれる:
+
+```json
+{
+  "id": "...",
+  "draft_graph": { "nodes": [...], "edges": [...] },
+  "...",
+  "validation": {
+    "valid": false,
+    "errors": ["..."],
+    "node_errors": { "node_id": ["..."] }
+  },
+  "added_node": { "id": "skill_1", "type": "skill", "..." }
+}
+```
+
+`validation.valid` が `true` になれば `hq publish dag-workflow <id>` で公開可能。
+
+#### fan_out テンプレートの編集
+
+fan_out ノードの `template`（sub-graph）にノードやエッジを追加するには、PATCH でテンプレート全体を上書きする:
+
+```bash
+# 1. 現在のドラフトを取得して fan_out ノードの template を確認
+hq fetch dag-workflow <wf-id> | jq '.draft_graph.nodes[] | select(.id == "fan_out_1") | .template'
+
+# 2. template を編集して PATCH
+cat > /tmp/u.json <<'EOF'
+{
+  "template": {
+    "nodes": [
+      { "id": "t_skill", "type": "skill", "label": "Process Item",
+        "skill_id": "<uuid>", "skill_version_id": "<uuid>", "assigned_role": "engineer" }
+    ],
+    "edges": []
+  }
+}
+EOF
+hq dag update-node <wf-id> fan_out_1 /tmp/u.json
+```
+
+テンプレート内部のノード/エッジを個別操作するAPIは現在ない。テンプレートは `template` フィールドの全体上書きで更新すること。テンプレートは start/end ノードを持たない sub-graph であり、バリデーション時に再帰的に検証される。
+
+> **⚠️ 重要: テンプレート内に `start` / `end` ノードを配置してはいけない。**
+> テンプレートのエントリポイントとエグジットポイントは、エッジ構造から自動検出される（incoming edge がないノード = エントリ、outgoing edge がないノード = エグジット）。`start` / `end` はトップレベル DAG 専用のノードタイプであり、テンプレート内に含めるとバリデーションエラーになる。テンプレート内では `skill`, `conditional`, `transform`, `review` 等の実行ノードのみ使用すること。
+
 ### ミニオン CLI ラッパー
 
 以下の `hq` サブコマンドが上記エンドポイントを呼び出す。いずれもリクエスト送信前にローカルで JSON 構文検証を行う。
 
 ```bash
+# 全文操作 (従来)
 hq list dag-workflows [project_id]           # GET  /api/minion/dag-workflows(?project_id=...)
 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
+
+# ノード/エッジ操作 (推奨)
+hq dag add-node <wf-id> <body.json>              # POST   .../nodes
+hq dag update-node <wf-id> <node-id> <body.json> # PATCH  .../nodes/:nodeId
+hq dag remove-node <wf-id> <node-id>             # DELETE .../nodes/:nodeId
+hq dag add-edge <wf-id> <body.json>              # POST   .../edges
+hq dag update-edge <wf-id> <edge-id> <body.json> # PATCH  .../edges/:edgeId
+hq dag remove-edge <wf-id> <edge-id>             # DELETE .../edges/:edgeId
+hq dag validate <wf-id>                          # POST   .../validate
 ```
 
 ### DAG Read Endpoints (チャットコンテキスト用)

package/docs/task-guides.md

@@ -258,11 +258,123 @@ hq put dag-workflow <dag-workflow-id> /tmp/dag-update.json
 hq publish dag-workflow <dag-workflow-id>
 ```
 
+#### 5. ノード/エッジ操作 API（推奨）
+
+graph 全文を JSON で書く代わりに、ノード・エッジを1つずつ操作するAPIが利用可能。**各操作のレスポンスにバリデーション結果が含まれる**ため、1ステップごとにエラーを確認・修正できる。
+
+```bash
+# 1. 空の DAG を作成
+cat > /tmp/dag-create.json <<'EOF'
+{
+  "project_id": "<project-uuid>",
+  "name": "my-dag"
+}
+EOF
+hq create dag-workflow /tmp/dag-create.json
+# → id を控える
+
+# 2. start/end ノードを追加
+echo '{ "type": "start", "label": "Start" }' > /tmp/n.json
+hq dag add-node <wf-id> /tmp/n.json
+
+echo '{ "type": "end", "label": "End" }' > /tmp/n.json
+hq dag add-node <wf-id> /tmp/n.json
+
+# 3. start → end をつなぐエッジ
+echo '{ "source": "start_1", "target": "end_1" }' > /tmp/e.json
+hq dag add-edge <wf-id> /tmp/e.json
+
+# 4. skill ノードを start と end の間に挿入
+#    after + before を指定すると、既存エッジを自動で差し替える
+cat > /tmp/n.json <<'EOF'
+{
+  "type": "skill",
+  "label": "Fetch Data",
+  "after": "start_1",
+  "before": "end_1",
+  "skill_id": "<skill-uuid>",
+  "skill_version_id": "<version-uuid>",
+  "assigned_role": "engineer"
+}
+EOF
+hq dag add-node <wf-id> /tmp/n.json
+# → start_1 → end_1 エッジが削除され、start_1 → skill_1 → end_1 に差し替え
+
+# 5. review ノードを追加（approved + revision エッジが自動生成）
+cat > /tmp/n.json <<'EOF'
+{
+  "type": "review",
+  "label": "Quality Check",
+  "after": "skill_1",
+  "before": "end_1",
+  "review": {
+    "reviewer_type": "human",
+    "criteria": "成果物の品質を確認",
+    "revision_target": "skill_1"
+  }
+}
+EOF
+hq dag add-node <wf-id> /tmp/n.json
+# → skill_1 → review_1 (normal), review_1 → end_1 (approved), review_1 → skill_1 (revision)
+
+# 6. バリデーション確認（公開せずにチェック）
+hq dag validate <wf-id>
+# → { "valid": true, "errors": [], ... } なら公開可能
+
+# 7. 公開
+hq publish dag-workflow <wf-id>
+```
+
+**ノード更新・削除:**
+
+```bash
+# ノードのプロパティを更新
+echo '{ "label": "Updated Name", "skill_version_id": "<new-uuid>" }' > /tmp/u.json
+hq dag update-node <wf-id> skill_1 /tmp/u.json
+
+# ノード削除（自動再接続あり）
+hq dag remove-node <wf-id> skill_2
+
+# エッジの kind や condition_label を更新
+echo '{ "kind": "approved" }' > /tmp/eu.json
+hq dag update-edge <wf-id> edge_3 /tmp/eu.json
+
+# エッジ削除
+hq dag remove-edge <wf-id> edge_3
+```
+
+**fan_out テンプレート編集:**
+
+> **⚠️ テンプレート内に `start` / `end` ノードを入れないこと。** テンプレートのエントリ/エグジットはエッジ構造から自動検出される。`start` / `end` はトップレベル DAG 専用であり、テンプレート内に含めるとバリデーションエラーになる。`skill`, `conditional`, `transform`, `review` 等の実行ノードのみ使用すること。
+
+```bash
+# fan_out ノードの template を PATCH で上書き
+# ※ start/end ノードは不要。実行ノードのみ配置する
+cat > /tmp/t.json <<'EOF'
+{
+  "template": {
+    "nodes": [
+      { "id": "t_skill", "type": "skill", "label": "Process Item",
+        "skill_id": "<uuid>", "skill_version_id": "<uuid>", "assigned_role": "engineer" }
+    ],
+    "edges": []
+  }
+}
+EOF
+hq dag update-node <wf-id> fan_out_1 /tmp/t.json
+```
+
+**Tips:**
+- `hq dag add-node` で review ノードを追加すると、`approved` エッジと `revision` エッジが自動生成される。手動でエッジを張る必要なし
+- 各操作のレスポンスの `validation.valid` が `true` かどうかで、いつでも公開可能かを判断できる
+- 複雑なグラフでも1ノードずつ積み上げれば、途中でバリデーションエラーの原因を特定しやすい
+
 #### 権限と注意事項
 
-- 書き込み（create / put / publish）は **PMロールのみ**。Engineer / accountant では 403 が返る。読み取り（fetch）は全メンバー可。
-- ドラフト保存は軽量（構造チェックのみ）。インクリメンタルに graph を組み立てていくのに適している。
-- セマンティックエラーは publish 時にまとめて検出されるため、途中保存と最終公開を使い分けること。
+- 書き込み（create / put / publish / dag 操作）は **PMロールのみ**。Engineer / accountant では 403 が返る。読み取り（fetch）は全メンバー可。
+- ノード/エッジ操作は各ステップでドラフトに自動保存され、バリデーション結果がレスポンスに含まれる。
+- `hq dag validate` で公開前にフル検証できる。publish 時の想定外エラーを防止できる。
+- 全文 JSON 操作（`hq put dag-workflow`）も引き続き利用可能だが、**ノード/エッジ操作APIの方が推奨**。
 
 ### 実行フロー（ランタイム側、参考）
 

package/linux/bin/hq

@@ -28,6 +28,13 @@
 #   hq create dag-workflow <body.json>    - Create a DAG workflow (PM only). Body: {project_id, name, graph?, ...}
 #   hq put dag-workflow <id> <body.json>  - Update DAG workflow draft (PM only). Body: {graph?, content?, ...}
 #   hq publish dag-workflow <id>          - Publish the draft as a new version (PM only, validated)
+#   hq dag add-node <wf-id> <body.json>  - Add a node to DAG draft. Body: {type, label?, after?, before?, ...}
+#   hq dag update-node <wf-id> <node-id> <body.json> - Update a node. Body: {label?, skill_version_id?, ...}
+#   hq dag remove-node <wf-id> <node-id> - Remove a node (auto-reconnects if possible)
+#   hq dag add-edge <wf-id> <body.json>  - Add an edge. Body: {source, target, kind?, condition_label?}
+#   hq dag update-edge <wf-id> <edge-id> <body.json> - Update edge kind/condition_label
+#   hq dag remove-edge <wf-id> <edge-id> - Remove an edge
+#   hq dag validate <wf-id>              - Validate draft without publishing
 
 set -euo pipefail
 
@@ -96,7 +103,7 @@ fetch_resource() {
   fi
 }
 
-# Send a JSON request body from a file. Method is POST or PUT.
+# Send a JSON request body from a file. Method is POST, PUT, or PATCH.
 send_json_request() {
   local method="$1"
   local url="$2"
@@ -163,6 +170,15 @@ print_usage() {
   echo "  hq create dag-workflow <body.json>    - Create a DAG workflow (PM only)" >&2
   echo "  hq put dag-workflow <id> <body.json>  - Update DAG workflow draft (PM only)" >&2
   echo "  hq publish dag-workflow <id>          - Publish the draft as a new version (PM only)" >&2
+  echo "" >&2
+  echo "  DAG node/edge operations (PM only, each returns validation warnings):" >&2
+  echo "  hq dag add-node <wf-id> <body.json>              - Add a node to DAG draft" >&2
+  echo "  hq dag update-node <wf-id> <node-id> <body.json> - Update a node's properties" >&2
+  echo "  hq dag remove-node <wf-id> <node-id>             - Remove a node" >&2
+  echo "  hq dag add-edge <wf-id> <body.json>              - Add an edge" >&2
+  echo "  hq dag update-edge <wf-id> <edge-id> <body.json> - Update edge kind/label" >&2
+  echo "  hq dag remove-edge <wf-id> <edge-id>             - Remove an edge" >&2
+  echo "  hq dag validate <wf-id>                          - Validate draft (no publish)" >&2
 }
 
 # Main command dispatch
@@ -454,6 +470,112 @@ print(json.dumps(d))
     esac
     ;;
 
+  dag)
+    action="${2:-}"
+    case "$action" in
+      add-node)
+        wf_id="${3:-}"
+        body_file="${4:-}"
+        if [ -z "$wf_id" ] || [ -z "$body_file" ]; then
+          echo "Usage: hq dag add-node <wf-id> <body.json>" >&2
+          echo "  body.json: { type, label?, after?, before?, skill_id?, skill_version_id?, assigned_role?, review?, ... }" >&2
+          exit 1
+        fi
+        validate_json_file "$body_file"
+        send_json_request POST "$BASE_URL/dag-workflows/$wf_id/nodes" "$body_file"
+        ;;
+      update-node)
+        wf_id="${3:-}"
+        node_id="${4:-}"
+        body_file="${5:-}"
+        if [ -z "$wf_id" ] || [ -z "$node_id" ] || [ -z "$body_file" ]; then
+          echo "Usage: hq dag update-node <wf-id> <node-id> <body.json>" >&2
+          echo "  body.json: { label?, skill_version_id?, assigned_role?, review?, ... }" >&2
+          exit 1
+        fi
+        validate_json_file "$body_file"
+        send_json_request PATCH "$BASE_URL/dag-workflows/$wf_id/nodes/$node_id" "$body_file"
+        ;;
+      remove-node)
+        wf_id="${3:-}"
+        node_id="${4:-}"
+        if [ -z "$wf_id" ] || [ -z "$node_id" ]; then
+          echo "Usage: hq dag remove-node <wf-id> <node-id>" >&2
+          exit 1
+        fi
+        # DELETE with no body
+        response=$(curl -s -w "\n%{http_code}" -X DELETE \
+          -H "Authorization: Bearer $API_TOKEN" \
+          "$BASE_URL/dag-workflows/$wf_id/nodes/$node_id")
+        http_code=$(echo "$response" | tail -1)
+        body=$(echo "$response" | sed '$d')
+        if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+          echo "$body" | format_json
+        else
+          echo "Error: HQ API returned HTTP $http_code" >&2
+          echo "$body" >&2
+          exit 1
+        fi
+        ;;
+      add-edge)
+        wf_id="${3:-}"
+        body_file="${4:-}"
+        if [ -z "$wf_id" ] || [ -z "$body_file" ]; then
+          echo "Usage: hq dag add-edge <wf-id> <body.json>" >&2
+          echo "  body.json: { source, target, kind?, condition_label? }" >&2
+          exit 1
+        fi
+        validate_json_file "$body_file"
+        send_json_request POST "$BASE_URL/dag-workflows/$wf_id/edges" "$body_file"
+        ;;
+      update-edge)
+        wf_id="${3:-}"
+        edge_id="${4:-}"
+        body_file="${5:-}"
+        if [ -z "$wf_id" ] || [ -z "$edge_id" ] || [ -z "$body_file" ]; then
+          echo "Usage: hq dag update-edge <wf-id> <edge-id> <body.json>" >&2
+          echo "  body.json: { kind?, condition_label? }" >&2
+          exit 1
+        fi
+        validate_json_file "$body_file"
+        send_json_request PATCH "$BASE_URL/dag-workflows/$wf_id/edges/$edge_id" "$body_file"
+        ;;
+      remove-edge)
+        wf_id="${3:-}"
+        edge_id="${4:-}"
+        if [ -z "$wf_id" ] || [ -z "$edge_id" ]; then
+          echo "Usage: hq dag remove-edge <wf-id> <edge-id>" >&2
+          exit 1
+        fi
+        response=$(curl -s -w "\n%{http_code}" -X DELETE \
+          -H "Authorization: Bearer $API_TOKEN" \
+          "$BASE_URL/dag-workflows/$wf_id/edges/$edge_id")
+        http_code=$(echo "$response" | tail -1)
+        body=$(echo "$response" | sed '$d')
+        if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+          echo "$body" | format_json
+        else
+          echo "Error: HQ API returned HTTP $http_code" >&2
+          echo "$body" >&2
+          exit 1
+        fi
+        ;;
+      validate)
+        wf_id="${3:-}"
+        if [ -z "$wf_id" ]; then
+          echo "Usage: hq dag validate <wf-id>" >&2
+          exit 1
+        fi
+        send_empty_post "$BASE_URL/dag-workflows/$wf_id/validate"
+        ;;
+      *)
+        echo "Unknown dag action: $action" >&2
+        echo "Usage: hq dag {add-node|update-node|remove-node|add-edge|remove-edge|validate} ..." >&2
+        exit 1
+        ;;
+    esac
+    ;;
+
   *)
     print_usage
     exit 1

package/linux/routes/chat.js

@@ -403,9 +403,15 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
             `  hq fetch dag-workflow ${context.dagWorkflowId}`,
             `プロジェクトコンテキスト:`,
             `  hq fetch project-context ${context.projectId}`,
-            `PMロールの場合、graph JSON を直接編集できます:`,
-            `  hq put dag-workflow ${context.dagWorkflowId} <body.json>   # ドラフト更新 (構造チェックのみ)`,
-            `  hq publish dag-workflow ${context.dagWorkflowId}           # ドラフトを新バージョンとして公開 (フル検証)`,
+            `PMロールの場合、ノード/エッジ操作APIでインクリメンタルに編集できます（推奨）:`,
+            `  hq dag add-node ${context.dagWorkflowId} <body.json>              # ノード追加`,
+            `  hq dag update-node ${context.dagWorkflowId} <node-id> <body.json> # ノード更新`,
+            `  hq dag remove-node ${context.dagWorkflowId} <node-id>             # ノード削除`,
+            `  hq dag add-edge ${context.dagWorkflowId} <body.json>              # エッジ追加`,
+            `  hq dag remove-edge ${context.dagWorkflowId} <edge-id>             # エッジ削除`,
+            `  hq dag validate ${context.dagWorkflowId}                          # ドラフト検証（公開せず）`,
+            `  hq publish dag-workflow ${context.dagWorkflowId}                  # 公開`,
+            `graph JSON 全文操作も可能: hq put dag-workflow ${context.dagWorkflowId} <body.json>`,
             `新規作成は: hq create dag-workflow <body.json>`,
             `プロジェクト内の DAG ワークフロー一覧: hq list dag-workflows ${context.projectId}`,
             `DAG の構造（nodes/edges/node types/scope_path 等）や実行フローの詳細は ~/.minion/docs/api-reference.md の「DAG Workflows」セクション、および ~/.minion/docs/task-guides.md の「DAG ワークフロー」セクションを参照してください。`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.28.1",
+  "version": "3.29.4",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/win/bin/hq.ps1

@@ -22,6 +22,13 @@
     .\hq.ps1 create dag-workflow <body.json>
     .\hq.ps1 put dag-workflow <id> <body.json>
     .\hq.ps1 publish dag-workflow <id>
+    .\hq.ps1 dag add-node <wf-id> <body.json>
+    .\hq.ps1 dag update-node <wf-id> <node-id> <body.json>
+    .\hq.ps1 dag remove-node <wf-id> <node-id>
+    .\hq.ps1 dag add-edge <wf-id> <body.json>
+    .\hq.ps1 dag update-edge <wf-id> <edge-id> <body.json>
+    .\hq.ps1 dag remove-edge <wf-id> <edge-id>
+    .\hq.ps1 dag validate <wf-id>
 #>
 
 param(
@@ -35,7 +42,10 @@ param(
     [string]$Arg2,
 
     [Parameter(Position = 3)]
-    [string]$Arg3
+    [string]$Arg3,
+
+    [Parameter(Position = 4)]
+    [string]$Arg4
 )
 
 $ErrorActionPreference = 'Stop'
@@ -133,6 +143,15 @@ function Show-Usage {
     Write-Host "  hq create dag-workflow <body.json>    - Create a DAG workflow (PM only)"
     Write-Host "  hq put dag-workflow <id> <body.json>  - Update DAG workflow draft (PM only)"
     Write-Host "  hq publish dag-workflow <id>          - Publish the draft as a new version (PM only)"
+    Write-Host ""
+    Write-Host "  DAG node/edge operations (PM only, each returns validation warnings):"
+    Write-Host "  hq dag add-node <wf-id> <body.json>              - Add a node to DAG draft"
+    Write-Host "  hq dag update-node <wf-id> <node-id> <body.json> - Update a node's properties"
+    Write-Host "  hq dag remove-node <wf-id> <node-id>             - Remove a node"
+    Write-Host "  hq dag add-edge <wf-id> <body.json>              - Add an edge"
+    Write-Host "  hq dag update-edge <wf-id> <edge-id> <body.json> - Update edge kind/label"
+    Write-Host "  hq dag remove-edge <wf-id> <edge-id>             - Remove an edge"
+    Write-Host "  hq dag validate <wf-id>                          - Validate draft (no publish)"
 }
 
 switch ($Command) {
@@ -251,6 +270,105 @@ switch ($Command) {
         }
     }
 
+    'dag' {
+        $Action = $Arg1
+        switch ($Action) {
+            'add-node' {
+                $WfId = $Arg2
+                $BodyFile = $Arg3
+                if (-not $WfId -or -not $BodyFile) {
+                    Write-Error "Usage: hq dag add-node <wf-id> <body.json>"
+                    exit 1
+                }
+                Assert-ValidJsonFile -Path $BodyFile
+                Send-JsonRequest -Method 'Post' -Url "$BaseUrl/dag-workflows/$WfId/nodes" -Path $BodyFile
+            }
+            'update-node' {
+                $WfId = $Arg2
+                $NodeId = $Arg3
+                $BodyFile = $Arg4
+                if (-not $WfId -or -not $NodeId -or -not $BodyFile) {
+                    Write-Error "Usage: hq dag update-node <wf-id> <node-id> <body.json>"
+                    exit 1
+                }
+                Assert-ValidJsonFile -Path $BodyFile
+                Send-JsonRequest -Method 'Patch' -Url "$BaseUrl/dag-workflows/$WfId/nodes/$NodeId" -Path $BodyFile
+            }
+            'remove-node' {
+                $WfId = $Arg2
+                $NodeId = $Arg3
+                if (-not $WfId -or -not $NodeId) {
+                    Write-Error "Usage: hq dag remove-node <wf-id> <node-id>"
+                    exit 1
+                }
+                try {
+                    $response = Invoke-RestMethod -Uri "$BaseUrl/dag-workflows/$WfId/nodes/$NodeId" `
+                        -Headers $Headers -Method Delete -ErrorAction Stop
+                    $response | ConvertTo-Json -Depth 20
+                }
+                catch {
+                    $statusCode = $_.Exception.Response.StatusCode.value__
+                    Write-Error "Error: HQ API returned HTTP $statusCode"
+                    Write-Error $_.ErrorDetails.Message
+                    exit 1
+                }
+            }
+            'add-edge' {
+                $WfId = $Arg2
+                $BodyFile = $Arg3
+                if (-not $WfId -or -not $BodyFile) {
+                    Write-Error "Usage: hq dag add-edge <wf-id> <body.json>"
+                    exit 1
+                }
+                Assert-ValidJsonFile -Path $BodyFile
+                Send-JsonRequest -Method 'Post' -Url "$BaseUrl/dag-workflows/$WfId/edges" -Path $BodyFile
+            }
+            'update-edge' {
+                $WfId = $Arg2
+                $EdgeId = $Arg3
+                $BodyFile = $Arg4
+                if (-not $WfId -or -not $EdgeId -or -not $BodyFile) {
+                    Write-Error "Usage: hq dag update-edge <wf-id> <edge-id> <body.json>"
+                    exit 1
+                }
+                Assert-ValidJsonFile -Path $BodyFile
+                Send-JsonRequest -Method 'Patch' -Url "$BaseUrl/dag-workflows/$WfId/edges/$EdgeId" -Path $BodyFile
+            }
+            'remove-edge' {
+                $WfId = $Arg2
+                $EdgeId = $Arg3
+                if (-not $WfId -or -not $EdgeId) {
+                    Write-Error "Usage: hq dag remove-edge <wf-id> <edge-id>"
+                    exit 1
+                }
+                try {
+                    $response = Invoke-RestMethod -Uri "$BaseUrl/dag-workflows/$WfId/edges/$EdgeId" `
+                        -Headers $Headers -Method Delete -ErrorAction Stop
+                    $response | ConvertTo-Json -Depth 20
+                }
+                catch {
+                    $statusCode = $_.Exception.Response.StatusCode.value__
+                    Write-Error "Error: HQ API returned HTTP $statusCode"
+                    Write-Error $_.ErrorDetails.Message
+                    exit 1
+                }
+            }
+            'validate' {
+                $WfId = $Arg2
+                if (-not $WfId) {
+                    Write-Error "Usage: hq dag validate <wf-id>"
+                    exit 1
+                }
+                Send-EmptyPost -Url "$BaseUrl/dag-workflows/$WfId/validate"
+            }
+            default {
+                Write-Error "Unknown dag action: $Action"
+                Write-Error "Usage: hq dag {add-node|update-node|remove-node|add-edge|remove-edge|validate} ..."
+                exit 1
+            }
+        }
+    }
+
     default {
         Show-Usage
         exit 1

package/win/routes/chat.js

@@ -464,9 +464,15 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
             `  hq fetch dag-workflow ${context.dagWorkflowId}`,
             `プロジェクトコンテキスト:`,
             `  hq fetch project-context ${context.projectId}`,
-            `PMロールの場合、graph JSON を直接編集できます:`,
-            `  hq put dag-workflow ${context.dagWorkflowId} <body.json>   # ドラフト更新 (構造チェックのみ)`,
-            `  hq publish dag-workflow ${context.dagWorkflowId}           # ドラフトを新バージョンとして公開 (フル検証)`,
+            `PMロールの場合、ノード/エッジ操作APIでインクリメンタルに編集できます（推奨）:`,
+            `  hq dag add-node ${context.dagWorkflowId} <body.json>              # ノード追加`,
+            `  hq dag update-node ${context.dagWorkflowId} <node-id> <body.json> # ノード更新`,
+            `  hq dag remove-node ${context.dagWorkflowId} <node-id>             # ノード削除`,
+            `  hq dag add-edge ${context.dagWorkflowId} <body.json>              # エッジ追加`,
+            `  hq dag remove-edge ${context.dagWorkflowId} <edge-id>             # エッジ削除`,
+            `  hq dag validate ${context.dagWorkflowId}                          # ドラフト検証（公開せず）`,
+            `  hq publish dag-workflow ${context.dagWorkflowId}                  # 公開`,
+            `graph JSON 全文操作も可能: hq put dag-workflow ${context.dagWorkflowId} <body.json>`,
             `新規作成は: hq create dag-workflow <body.json>`,
             `プロジェクト内の DAG ワークフロー一覧: hq list dag-workflows ${context.projectId}`,
             `DAG の構造（nodes/edges/node types/scope_path 等）や実行フローの詳細は ~/.minion/docs/api-reference.md の「DAG Workflows」セクション、および ~/.minion/docs/task-guides.md の「DAG ワークフロー」セクションを参照してください。`,