@geekbeer/minion 3.34.0 → 3.36.0

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

@@ -255,6 +255,7 @@ async function executeTransformNode(node) {
     assigned_role,
     input_data,
     transform_instruction,
+    input_contracts,
     output_contracts,
   } = node
 
@@ -290,7 +291,12 @@ async function executeTransformNode(node) {
 
     // 2. Create ephemeral skill from transform_instruction.
     // Write to every active plugin's skill dir so any Primary can find it.
-    const skillContent = buildTransformSkillContent(transform_instruction, input_data, output_contracts)
+    const skillContent = buildTransformSkillContent(
+      transform_instruction,
+      input_data,
+      input_contracts,
+      output_contracts,
+    )
     for (const dir of ephemeralSkillDirs) {
       await fs.mkdir(dir, { recursive: true })
       await fs.writeFile(path.join(dir, 'SKILL.md'), skillContent, 'utf-8')
@@ -357,51 +363,88 @@ async function executeTransformNode(node) {
 
 /**
  * Build SKILL.md content for a transform node's ephemeral skill.
+ *
+ * Transform is contract-driven: the Output Contract is the authoritative
+ * target shape, enforced by HQ's runtime validator on node-complete.
+ * `instruction` is an optional hint layered on top for cases where the
+ * contract alone doesn't convey the intent (unit conversion, filter
+ * criteria, renaming conventions, etc.).
  */
-function buildTransformSkillContent(instruction, inputData, outputContracts) {
+function buildTransformSkillContent(instruction, inputData, inputContracts, outputContracts) {
   const lines = [
     '---',
     'name: dag-transform',
     'description: DAG Transform Node',
     '---',
     '',
-    'You are a data transformation step in a DAG workflow.',
+    'You are a data transformation step in a DAG workflow. Your job is to',
+    'reshape the Input Data into an object that conforms **exactly** to the',
+    'Output Contract. HQ will reject the result if any required field is',
+    'missing or has the wrong type.',
     '',
     '## Input Data',
     '```json',
     JSON.stringify(inputData, null, 2),
     '```',
-    '',
-    '## Transform Instruction',
-    instruction,
   ]
 
+  if (inputContracts && inputContracts.length > 0) {
+    lines.push('', '## Input Contract')
+    lines.push('The Input Data above conforms to:')
+    for (const ic of inputContracts) {
+      lines.push(`### ${ic.contract_name}`)
+      lines.push(ic.contract.description || '')
+      appendContractTable(lines, ic.contract.fields || [])
+    }
+  }
+
   if (outputContracts && outputContracts.length > 0) {
-    lines.push('', '## Output Contract')
-    lines.push('Your output MUST conform to the following contract(s):')
+    lines.push('', '## Output Contract (REQUIRED)')
+    lines.push(
+      'Produce a JSON object matching this contract. Every required field',
+      'must be present with the declared type. Extra fields are discarded.',
+    )
     for (const oc of outputContracts) {
       lines.push(`### ${oc.contract_name}`)
       lines.push(oc.contract.description || '')
-      lines.push('| Field | Type | Required | Description |')
-      lines.push('|-------|------|----------|-------------|')
-      for (const f of oc.contract.fields || []) {
-        const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
-        lines.push(`| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |`)
-      }
+      appendContractTable(lines, oc.contract.fields || [])
     }
+  } else {
+    lines.push(
+      '',
+      '## Output Contract',
+      '⚠️ No output contract was declared on the outgoing edge. This transform',
+      'node is misconfigured and should not have reached execution. Return',
+      'the input data unchanged and fail loudly.',
+    )
+  }
+
+  if (instruction && instruction.trim()) {
+    lines.push('', '## Hint (optional)')
+    lines.push(instruction.trim())
   }
 
   lines.push(
     '',
     '## Task',
-    'Apply the transform instruction to the input data above.',
-    'Output the result as a JSON object in an "## Output Data" section with a json code block.',
+    '1. Read Input Data and the Output Contract carefully.',
+    '2. Construct a JSON object satisfying the Output Contract.',
+    '3. Output it under a "## Output Data" section with a json code block.',
     'Do NOT output anything other than the Output Data section.',
   )
 
   return lines.join('\n')
 }
 
+function appendContractTable(lines, fields) {
+  lines.push('| Field | Type | Required | Description |')
+  lines.push('|-------|------|----------|-------------|')
+  for (const f of fields) {
+    const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
+    lines.push(`| ${f.name} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |`)
+  }
+}
+
 /**
  * Resolve skill_version_id to skill name via HQ API.
  */

package/docs/api-reference.md

@@ -1110,7 +1110,7 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 | `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` | |
+| `transform` | `assigned_role`, incoming edge 1 本 + outgoing edge 1 本 (両方 `contract` 必須) | `transform_instruction` は optional hint。I/O 型は edge の contract から自動導出される |
 
 **review ノード追加の例:**
 ```json
@@ -1207,7 +1207,7 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 {
   description: string          // contract の説明
   fields: [{
-    key: string                // フィールド名
+    name: string               // フィールド名（※ "key" ではない）
     type: "string" | "number" | "boolean" | "url" | "array" | "object"  // フィールド型
     description: string        // フィールドの説明
     required?: boolean         // 必須フラグ (省略時 false)
@@ -1216,6 +1216,8 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 }
 ```
 
+**⚠️ 重要: 各 field には必ず `name` プロパティを使用すること（`key` ではない）**。他のスキーマ言語（JSON Schema、OpenAPI 等）の慣習に引きずられて `key` と書かないように注意。構造バリデーションで弾かれる（400エラー）。
+
 **注意:**
 - エッジに設定する `contract` は `graph.contracts` に存在する名前でなければならない（存在しない名前を指定すると 400 エラー）
 - **エッジが参照できる Contract は 1 つのみ**。`edge.contract` に配列を渡すことは不可（400エラー）。複数の型構造を束ねたい場合は、それらを束ねた複合Contractを1つ定義してから参照すること
@@ -1232,16 +1234,16 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
     "Article": {
       "description": "個別の記事",
       "fields": [
-        { "key": "title", "type": "string", "required": true, "description": "タイトル" },
-        { "key": "url", "type": "url", "description": "記事URL" }
+        { "name": "title", "type": "string", "required": true, "description": "タイトル" },
+        { "name": "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": "件数" }
+        { "name": "articles", "type": "array", "items": "Article", "required": true, "description": "記事リスト" },
+        { "name": "collected_at", "type": "string", "required": true, "description": "収集日時" },
+        { "name": "count", "type": "number", "required": true, "description": "件数" }
       ]
     }
   },
@@ -1265,8 +1267,8 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
     "prototype": {
       "description": "プロトタイプ成果物",
       "fields": [
-        { "key": "git_url", "type": "url", "description": "リポジトリURL", "required": true },
-        { "key": "preview_url", "type": "url", "description": "プレビューURL" }
+        { "name": "git_url", "type": "url", "description": "リポジトリURL", "required": true },
+        { "name": "preview_url", "type": "url", "description": "プレビューURL" }
       ]
     }
   }
@@ -1281,7 +1283,7 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
   "contract": {
     "description": "プロトタイプ成果物",
     "fields": [
-      { "key": "git_url", "type": "url", "description": "リポジトリURL", "required": true }
+      { "name": "git_url", "type": "url", "description": "リポジトリURL", "required": true }
     ]
   }
 }
@@ -1528,6 +1530,7 @@ Body:
 - `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` がこの抽出を行う）
+- **Contract runtime validation**: 報告時に outgoing edge の `contract` で `output_data` が検証される。違反があれば HQ はノードを `failed` に書き換え、`contract_violations` カラムに構造化済み違反を保存し、`output_summary` に詳細を追記する。スキル・transform 共通。contract が貼られていない edge の先については検証スキップ
 
 Response:
 ```json
@@ -1589,7 +1592,7 @@ DAG ワークフローの graph は以下の構造で保存される（`dag_work
 | `start` | エントリポイント | ❌ (内部) |
 | `end` | 終端 | ❌ (内部) |
 | `skill` | スキル実行。`skill_version_id` と `assigned_role` が必須 | ✅ |
-| `transform` | LLM によるデータ変換。`transform_instruction` が必須 | ✅ |
+| `transform` | contract 同士のブリッジ。I/O 型は incoming/outgoing edge の `contract` から自動導出、出力は HQ が contract validate。`transform_instruction` は optional hint | ✅ |
 | `review` | レビューゲート。`approved` / `revision_requested` で分岐 | ❌ (内部) |
 | `fan_out` | 配列入力をテンプレートsub-graphに展開して並列実行。子が全て settle すると自ノードが completed に遷移 | ❌ (内部) |
 | `join` | N本の上流エッジを待ち合わせる汎用バリア。fan_out とは独立 | ❌ (内部) |

package/docs/task-guides.md

@@ -455,17 +455,64 @@ fan_out_source = ".items"
 
 ミニオンから見ると、fan-out 内の skill/transform ノードも通常どおり `pending-nodes` に返ってくる（`scope_path` が空でない点だけが違い）。
 
-### Transform ノード
+### Transform ノード（contract 駆動）
 
-Transform ノードは LLM を使って input_data を output_data に変換する軽量ノード。`transform_instruction` に自然言語で変換指示を書く。ミニオン側では `transform_instruction` を本文とする一時的なスキルを組み立てて実行する。
+Transform ノードは **contract 同士のブリッジ** となる軽量ノード。入出力の shape は **incoming/outgoing edge に貼った contract から自動導出** され、LLM はその Output Contract に適合する JSON を生成する。HQ は `node-complete` 報告時に output を contract で検証し、違反ならノードを failed にする。
 
+**静的バリデーション要件:**
+
+- incoming edge がちょうど 1 本で、**必ず contract を持つ**
+- outgoing edge がちょうど 1 本で、**必ず contract を持つ**
+- `transform_instruction` は **optional**（contract だけで意図が明確なら空欄で OK）
+- `assigned_role` は必須
+
+**典型用途: 「スキルの Markdown レポート出力 → 下流 contract の shape に整形」**
+
+```
+incoming edge contract: compe-search-result (items: array<compe-item>, total_count, search_criteria)
+outgoing edge contract: selected-items (items: array<compe-item>)
+
+transform_instruction (optional): "上位5件のみを items に残してください"
+input_data (upstream skill output): { "_raw": "# 検索レポート\n..." }
+↓ (LLM は Output Contract を見てプロンプト通りに整形)
+output_data: { "items": [ {...}, {...}, {...}, {...}, {...} ] }
+↓ HQ が contract で検証、OK なら cascade 続行
 ```
-transform_instruction: "items 配列から title が 'Item B' のエントリを除外し、残りを返してください"
+
+**典型用途: 配列フィルタ**
+
+```
+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" }] }
 ```
 
+### DAG 構築時のノード選定フロー
+
+スキルは汎用的で再利用可能な資産であり、ワークフロー固有の contract に合わせて SKILL.md を改修することは原則行わない。代わりに以下のフローで判断する:
+
+1. スキルノードの outgoing edge に contract を貼る
+2. そのスキルが contract に沿った `## Output Data` JSON ブロックを出力できるか確認
+   - **Yes**: そのまま接続。runtime validation が成功すれば cascade 続行
+   - **No**: スキルと下流ノードの間に **transform ノードを挟む**。 transform の outgoing edge に下流向け contract を貼り、incoming edge はスキルからの「実質 `_raw` だけ」の契約にする（あるいは contract を定義しない中間エッジとして置く構成）
+3. fan_out ノードの前では特に注意: incoming edge contract の `fan_out_source` が指すフィールドが `type='array'` で宣言されている必要がある（そうでなければ validator がエラーを出す）
+
+### 契約違反時の挙動
+
+`node-complete` で outgoing edge の contract に `output_data` が適合しない場合:
+
+- ノードは `status='failed'`, `outcome='failure'` として記録される
+- `contract_violations` カラムに違反詳細（path / expected / actual / message）が JSON で保存される
+- `output_summary` の末尾にも人間可読な違反メッセージが追記される
+- 下流の join / fan-out は `on_failure` policy に従って進む（`ignore` / `collect` / `fail_all`）
+
+**よくある違反:**
+
+- skill が `## Output Data` セクションを出力しなかった → `{ _raw: "..." }` フォールバックとなり、required field がすべて未定義で failed
+- skill 出力の型が contract と違う（`string` が required だが `number` が返った等）
+- transform の出力 JSON が broken（JSON.parse 失敗→`_raw` → 同じく required 欠落）
+
 ### Review ノードとリビジョン
 
 Review ノードはレビューゲート。`review_status=review_pending` で下流カスケードが停止する。レビュアーが:

package/linux/routes/chat.js

@@ -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}                  # 公開`,
-            `Contract編集時の重要な規則: edge.contract は単一Contract名（string）のみ、配列不可。List<X> は type:"array" + items:"X" で表現。詳細は ~/.minion/docs/api-reference.md の「Contracts API」参照。`,
+            `Contract編集時の重要な規則: edge.contract は単一Contract名（string）のみ、配列不可。List<X> は type:"array" + items:"X" で表現。**contract.fields[] の各要素は { "name": "...", "type": "...", ... } の形式で、"key" ではなく "name" を使うこと**（JSON Schema等の慣習に引きずられないように）。詳細は ~/.minion/docs/api-reference.md の「Contracts API」参照。`,
+            `Contract はランタイムで強制される型: node-complete 時に outgoing edge の contract で output_data が検証され、違反はノード failed 扱い。transform は contract 同士のブリッジ（I/O 型は edge の contract から自動導出、transform_instruction は optional hint）。スキルが contract に沿った ## Output Data を出せない場合はスキルと下流の間に transform を挟んで整形すること。`,
             `graph JSON 全文PUTは非推奨: hq put dag-workflow ${context.dagWorkflowId} <body.json>`,
             `新規作成は: hq create dag-workflow <body.json>`,
             `プロジェクト内の DAG ワークフロー一覧: hq list dag-workflows ${context.projectId}`,

package/linux/routine-runner.js

@@ -128,10 +128,22 @@ async function executeRoutineSession(routine, executionId, skillNames) {
       throw new Error('No LLM configured. Set a Primary plugin via /api/llm/config or LLM_COMMAND in minion.env')
     }
 
-    // Create tmux session with the LLM command.
-    // PATH, HOME, DISPLAY, and minion secrets are already set in
-    // process.env at server startup, so child processes inherit them automatically.
-    // Per-execution identifiers are passed via -e flags for the session environment.
+    // Create the tmux session as an empty shell first, then configure
+    // remain-on-exit, then inject the command via send-keys. This avoids
+    // the race where a fast-failing LLM command tears down the session
+    // before set-option can run (see workflow-runner.js for the full
+    // explanation — the same fix applies here).
+    //
+    // Per-execution identifiers are passed via -e flags so the session
+    // shell inherits them; send-keys runs inside that shell.
+    const execScript = path.join(os.tmpdir(), `minion-routine-exec-${sessionName}.sh`)
+    await fs.writeFile(
+      execScript,
+      `#!/bin/bash\n${llmCommand}\necho $? > ${exitCodeFile}\n`,
+      'utf-8',
+    )
+    await execAsync(`chmod +x "${execScript}"`)
+
     const tmuxCommand = [
       'tmux new-session -d',
       `-s "${sessionName}"`,
@@ -139,7 +151,6 @@ async function executeRoutineSession(routine, executionId, skillNames) {
       `-e "MINION_EXECUTION_ID=${executionId}"`,
       `-e "MINION_ROUTINE_ID=${routine.id}"`,
       `-e "MINION_ROUTINE_NAME=${routine.name.replace(/"/g, '\\"')}"`,
-      `"${llmCommand}; echo $? > ${exitCodeFile}"`,
     ].join(' ')
 
     await execAsync(tmuxCommand, { cwd: homeDir })
@@ -155,6 +166,12 @@ async function executeRoutineSession(routine, executionId, skillNames) {
       console.error(`[RoutineRunner] Failed to set up pipe-pane: ${err.message}`)
     }
 
+    // Now that remain-on-exit and pipe-pane are in place, inject the
+    // actual command.
+    await execAsync(
+      `tmux send-keys -t "${sessionName}" "bash ${execScript}" Enter`,
+    )
+
     console.log(`[RoutineRunner] Started tmux session: ${sessionName}`)
 
     // Wait for session to complete (poll for exit code file)

package/linux/workflow-runner.js

@@ -107,19 +107,19 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of ic.contract.fields || []) {
         const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
-        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        contractContext += `| ${f.name} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'
   }
   if (options.dagOutputContracts && options.dagOutputContracts.length > 0) {
-    contractContext += '## Output Contract\nYour output MUST conform to the following contract(s). Include all required fields in your execution report.\n'
+    contractContext += '## Output Contract (REQUIRED)\nEnd your execution report with a "## Output Data" section containing a single `json` code block whose content conforms **exactly** to the contract(s) below. HQ validates this JSON on completion; any missing required field or type mismatch fails the node.\n\nIf the skill\'s natural output does not match this shape, add a transform node upstream instead of reshaping inside the skill.\n\n'
     for (const oc of options.dagOutputContracts) {
       contractContext += `### ${oc.contract_name}\n${oc.contract.description || ''}\n`
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of oc.contract.fields || []) {
         const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
-        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        contractContext += `| ${f.name} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'
@@ -178,17 +178,34 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       throw new Error('No LLM configured. Set a Primary plugin via /api/llm/config or LLM_COMMAND in minion.env')
     }
 
-    // Create tmux session with the LLM command.
+    // Create the tmux session as an empty shell first, then configure it,
+    // then inject the command via send-keys.
+    //
+    // Why two steps instead of `tmux new-session -d <cmd>`: if the LLM
+    // command exits very quickly (auth failure, missing binary, etc.) the
+    // session dies before we can call `set-option remain-on-exit on`, and
+    // the subsequent set-option/pipe-pane calls fail with "no such
+    // window". DAG transform nodes exposed this race because ephemeral
+    // skills start immediately and some failure modes (invalid prompt,
+    // missing LLM config) return instantly.
+    //
+    // Writing the invocation to a script file also insulates the command
+    // from shell-escaping edge cases when send-keys types it into the
+    // session.
+    const execScript = path.join(os.tmpdir(), `minion-workflow-exec-${sessionName}.sh`)
+    await fs.writeFile(
+      execScript,
+      `#!/bin/bash\n${llmCommand}\necho $? > ${exitCodeFile}\n`,
+      'utf-8',
+    )
+    await execAsync(`chmod +x "${execScript}"`)
+
     // PATH, HOME, DISPLAY, and minion secrets are already set in
     // process.env at server startup, so child processes inherit them automatically.
-    const tmuxCommand = [
-      'tmux new-session -d',
-      `-s "${sessionName}"`,
-      '-x 200 -y 50',
-      `"${llmCommand}; echo $? > ${exitCodeFile}"`,
-    ].join(' ')
-
-    await execAsync(tmuxCommand, { cwd: homeDir })
+    await execAsync(
+      `tmux new-session -d -s "${sessionName}" -x 200 -y 50`,
+      { cwd: homeDir },
+    )
 
     // Keep session alive after command completes (for debugging via terminal mirror)
     await execAsync(`tmux set-option -t "${sessionName}" remain-on-exit on`)
@@ -203,6 +220,13 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       // Continue execution even if pipe-pane fails
     }
 
+    // Now that remain-on-exit and pipe-pane are in place, inject the
+    // actual command. A fast-failing command will still be captured in the
+    // log and the exit code file will be written.
+    await execAsync(
+      `tmux send-keys -t "${sessionName}" "bash ${execScript}" Enter`,
+    )
+
     console.log(`[WorkflowRunner] Started tmux session: ${sessionName}`)
 
     // Wait for session to complete (poll for exit code file)

package/package.json

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

package/rules/core.md

@@ -32,6 +32,9 @@ Minion
     - ノード/エッジ/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」を参照）
+    - **Contract はランタイムで強制される型定義**。`node-complete` 報告時に outgoing edge の contract で `output_data` が検証され、違反はノード `failed` 扱い。スキルが contract に沿った `## Output Data` を出せない場合は **transform ノードをスキルと下流の間に挟んで整形**すること。スキル側の SKILL.md を各ワークフロー専用に改修するのは原則 NG（スキルは汎用資産）
+    - **transform ノードの I/O 型は edge の contract から自動導出**。incoming edge と outgoing edge にそれぞれ contract を必ず貼ること。`transform_instruction` は contract だけで意図が伝わらない場合の補足ヒント（任意）
+    - **fan_out の incoming edge に contract を貼る場合**、`fan_out_source` が指すフィールドが contract 内に `type='array'` として宣言されている必要がある（静的検証で弾かれる）
 - **Routine**: ミニオンスコープ。ミニオンローカルの定期タスク。
 - **Workspace**: ミニオンは複数のワークスペースに所属でき、スキルやプロジェクトはワークスペース単位でスコープされる。チャットセッションもワークスペース別に分離される。所属ワークスペースはハートビートで自動同期され、`hq list workspaces` で確認できる。
 - ミニオンは複数プロジェクトに `pm`、`engineer`、`accountant` として参加できる。

package/win/routes/chat.js

@@ -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}                  # 公開`,
-            `Contract編集時の重要な規則: edge.contract は単一Contract名（string）のみ、配列不可。List<X> は type:"array" + items:"X" で表現。詳細は ~/.minion/docs/api-reference.md の「Contracts API」参照。`,
+            `Contract編集時の重要な規則: edge.contract は単一Contract名（string）のみ、配列不可。List<X> は type:"array" + items:"X" で表現。**contract.fields[] の各要素は { "name": "...", "type": "...", ... } の形式で、"key" ではなく "name" を使うこと**（JSON Schema等の慣習に引きずられないように）。詳細は ~/.minion/docs/api-reference.md の「Contracts API」参照。`,
+            `Contract はランタイムで強制される型: node-complete 時に outgoing edge の contract で output_data が検証され、違反はノード failed 扱い。transform は contract 同士のブリッジ（I/O 型は edge の contract から自動導出、transform_instruction は optional hint）。スキルが contract に沿った ## Output Data を出せない場合はスキルと下流の間に transform を挟んで整形すること。`,
             `graph JSON 全文PUTは非推奨: hq put dag-workflow ${context.dagWorkflowId} <body.json>`,
             `新規作成は: hq create dag-workflow <body.json>`,
             `プロジェクト内の DAG ワークフロー一覧: hq list dag-workflows ${context.projectId}`,

package/win/workflow-runner.js

@@ -114,19 +114,19 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of ic.contract.fields || []) {
         const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
-        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        contractContext += `| ${f.name} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'
   }
   if (options.dagOutputContracts && options.dagOutputContracts.length > 0) {
-    contractContext += '## Output Contract\nYour output MUST conform to the following contract(s). Include all required fields in your execution report.\n'
+    contractContext += '## Output Contract (REQUIRED)\nEnd your execution report with a "## Output Data" section containing a single `json` code block whose content conforms **exactly** to the contract(s) below. HQ validates this JSON on completion; any missing required field or type mismatch fails the node.\n\nIf the skill\'s natural output does not match this shape, add a transform node upstream instead of reshaping inside the skill.\n\n'
     for (const oc of options.dagOutputContracts) {
       contractContext += `### ${oc.contract_name}\n${oc.contract.description || ''}\n`
       contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
       for (const f of oc.contract.fields || []) {
         const typeDisplay = f.type === 'array' && f.items ? `array<${f.items}>` : f.type
-        contractContext += `| ${f.key} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+        contractContext += `| ${f.name} | ${typeDisplay} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
       }
     }
     contractContext += '\n'