@geekbeer/minion 3.32.0 → 3.34.0

package/core/lib/dag-step-poller.js

@@ -385,7 +385,8 @@ function buildTransformSkillContent(instruction, inputData, outputContracts) {
       lines.push('| Field | Type | Required | Description |')
       lines.push('|-------|------|----------|-------------|')
       for (const f of oc.contract.fields || []) {
-        lines.push(`| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |`)
+        const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
+        lines.push(`| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |`)
       }
     }
   }

package/docs/api-reference.md

@@ -1048,8 +1048,13 @@ PUT `/api/minion/dag-workflows/:id` body（全フィールド optional、省略
 }
 ```
 
-- `graph` を渡すと draft_graph が上書きされる（構造チェックのみ、セマンティックチェック無し）
+- `graph` を渡すと draft_graph が上書きされる（構造チェック + structural validation: contract参照の型整合性チェックは実行、ノード完全性チェックは `publish` 時のみ）
 - `content` / `change_summary` は `graph` と併せて draft スロットに保存される
+- **推奨**: graph 全文PUTは**原則使用しない**。代わりに個別APIの `/nodes` `/edges` `/contracts` を使ってインクリメンタルに編集すること。全文PUTは型の取り違え（例: `edge.contract` に配列を渡す）が発生しやすく、バリデーションエラーで400が返る
+- 具体的な制約:
+  - `edge.contract` は**単一の**Contract名（string）。配列は不可
+  - `contract.fields[].items` は Contract名（string）で、`graph.contracts` 内に存在するものを参照
+  - 不整合があると `{ "error": "...", "details": [...] }` の形式で400エラー
 
 POST `/api/minion/dag-workflows/:id/publish` (body なし):
 - 現在の draft_graph を `validateDagGraph` でフル検証
@@ -1206,15 +1211,48 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
     type: "string" | "number" | "boolean" | "url" | "array" | "object"  // フィールド型
     description: string        // フィールドの説明
     required?: boolean         // 必須フラグ (省略時 false)
+    items?: string             // type='array' 時のみ。要素の型を表す別Contract名
   }]
 }
 ```
 
 **注意:**
 - エッジに設定する `contract` は `graph.contracts` に存在する名前でなければならない（存在しない名前を指定すると 400 エラー）
+- **エッジが参照できる Contract は 1 つのみ**。`edge.contract` に配列を渡すことは不可（400エラー）。複数の型構造を束ねたい場合は、それらを束ねた複合Contractを1つ定義してから参照すること
 - contract を削除すると、参照しているエッジの `contract` フィールドが自動でクリアされる（DELETE / PUT 共通）
 - `validate` エンドポイントはダングリング参照（存在しない contract への参照）をエラーとして報告する
 
+**Contract内で List<別Contract> を表現する方法 (items):**
+
+`type: 'array'` のフィールドに `items` プロパティを設定すると、配列要素の型を別Contractで記述できる。`items` の値は `graph.contracts` 内のContract名。
+
+```json
+{
+  "contracts": {
+    "Article": {
+      "description": "個別の記事",
+      "fields": [
+        { "key": "title", "type": "string", "required": true, "description": "タイトル" },
+        { "key": "url", "type": "url", "description": "記事URL" }
+      ]
+    },
+    "NewsCollection": {
+      "description": "収集されたニュース全体",
+      "fields": [
+        { "key": "articles", "type": "array", "items": "Article", "required": true, "description": "記事リスト" },
+        { "key": "collected_at", "type": "string", "required": true, "description": "収集日時" },
+        { "key": "count", "type": "number", "required": true, "description": "件数" }
+      ]
+    }
+  },
+  "edges": [
+    { "id": "edge_1", "source": "a", "target": "b", "contract": "NewsCollection" }
+  ]
+}
+```
+
+この構造で「エッジは単一Contract (`NewsCollection`) を参照し、その内部で `articles` フィールドが `Article[]` 型」という意味になる。
+
 ##### GET `/api/minion/dag-workflows/:id/contracts` — 全contracts取得
 
 レスポンス: `{ "contracts": { "name": { "description": "...", "fields": [...] }, ... } }`

package/linux/routes/chat.js

@@ -433,7 +433,7 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
             `  hq fetch dag-workflow ${context.dagWorkflowId}`,
             `プロジェクトコンテキスト:`,
             `  hq fetch project-context ${context.projectId}`,
-            `PMロールの場合、ノード/エッジ操作APIでインクリメンタルに編集できます（推奨）:`,
+            `PMロールの場合、ノード/エッジ操作APIでインクリメンタルに編集してください（**強く推奨**、全文PUTは型取り違えが起きやすいためエラーになりがち）:`,
             `  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>             # ノード削除`,
@@ -441,7 +441,8 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
             `  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>`,
+            `Contract編集時の重要な規則: edge.contract は単一Contract名（string）のみ、配列不可。List<X> は type:"array" + items:"X" で表現。詳細は ~/.minion/docs/api-reference.md の「Contracts API」参照。`,
+            `graph JSON 全文PUTは非推奨: 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/linux/workflow-runner.js

@@ -106,7 +106,8 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       contractContext += `### ${ic.contract_name}\n${ic.contract.description || ''}\n`
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of ic.contract.fields || []) {
-        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
+        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'
@@ -117,7 +118,8 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       contractContext += `### ${oc.contract_name}\n${oc.contract.description || ''}\n`
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of oc.contract.fields || []) {
-        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
+        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'

package/package.json

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

package/rules/core.md

@@ -28,6 +28,10 @@ Minion
 
 - **Workflow**: プロジェクトスコープ。線形パイプライン形式のバージョン管理ワークフロー。ミニオンAPIで push/fetch 可能。
 - **DAG Workflow**: プロジェクトスコープ。ノード/エッジで依存関係を表現する新方式。fan-out / join / conditional / transform / review をサポート。作成・編集はHQダッシュボードのみ、ミニオンは `dag-step-poller` で自動実行。詳細は `~/.minion/docs/api-reference.md` の「DAG Workflows」と `~/.minion/docs/task-guides.md` の「DAG ワークフロー」を参照。
+  - **PMロールで編集する場合の重要な規則**:
+    - ノード/エッジ/contract の追加・更新は**個別API** (`/nodes` `/edges` `/contracts`) を使うこと。`PUT /dag-workflows/:id` による graph 全文PUTは型の取り違えが起きやすく、バリデーションエラーで 400 が返る
+    - `edge.contract` は**単一のContract名（string）**のみ。配列は不可。複数の型構造を束ねたい場合は、それらを内包する複合Contractを1つ定義する
+    - Contract内で `List<別Contract>` を表現するには `type: 'array'` + `items: "別Contract名"` を使う（詳細は `~/.minion/docs/api-reference.md` の「Contracts API」を参照）
 - **Routine**: ミニオンスコープ。ミニオンローカルの定期タスク。
 - **Workspace**: ミニオンは複数のワークスペースに所属でき、スキルやプロジェクトはワークスペース単位でスコープされる。チャットセッションもワークスペース別に分離される。所属ワークスペースはハートビートで自動同期され、`hq list workspaces` で確認できる。
 - ミニオンは複数プロジェクトに `pm`、`engineer`、`accountant` として参加できる。

package/win/routes/chat.js

@@ -494,7 +494,7 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
             `  hq fetch dag-workflow ${context.dagWorkflowId}`,
             `プロジェクトコンテキスト:`,
             `  hq fetch project-context ${context.projectId}`,
-            `PMロールの場合、ノード/エッジ操作APIでインクリメンタルに編集できます（推奨）:`,
+            `PMロールの場合、ノード/エッジ操作APIでインクリメンタルに編集してください（**強く推奨**、全文PUTは型取り違えが起きやすいためエラーになりがち）:`,
             `  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>             # ノード削除`,
@@ -502,7 +502,8 @@ async function buildContextPrefix(message, context, sessionId, workspaceId) {
             `  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>`,
+            `Contract編集時の重要な規則: edge.contract は単一Contract名（string）のみ、配列不可。List<X> は type:"array" + items:"X" で表現。詳細は ~/.minion/docs/api-reference.md の「Contracts API」参照。`,
+            `graph JSON 全文PUTは非推奨: 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/win/workflow-runner.js

@@ -113,7 +113,8 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       contractContext += `### ${ic.contract_name}\n${ic.contract.description || ''}\n`
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of ic.contract.fields || []) {
-        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
+        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'
@@ -124,7 +125,8 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       contractContext += `### ${oc.contract_name}\n${oc.contract.description || ''}\n`
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of oc.contract.fields || []) {
-        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
+        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'