kenaz 0.0.0-stage → 0.3.2

package/core/.system/formation/TOOLS_REFERENCE.md

@@ -0,0 +1,1145 @@
+# Formation 工具鏈完整參考
+
+**版本**: v2.0
+**最後更新**: 2026-02-20
+
+本文檔詳細說明 `.formation/tools/` 下所有模組的函數簽名、參數、呼叫關係與設計意圖。
+
+---
+
+## 目錄
+
+1. [系統架構總覽](#系統架構總覽)
+2. [headless.js — Dispatch 入口](#headlessjs--dispatch-入口)
+3. [prompt.js — Prompt 組裝 + Principles 注入](#promptjs--prompt-組裝--principles-注入)
+4. [runner.js — Subagent 執行](#runnerjs--subagent-執行)
+5. [logger.js — Log 管理](#loggerjs--log-管理)
+6. [utils.js — 工具函數](#utilsjs--工具函數)
+7. [loader.js — 任務載入三層 Fallback](#loaderjs--任務載入三層-fallback)
+8. [呼叫關係圖](#呼叫關係圖)
+9. [關鍵流程範例](#關鍵流程範例)
+
+---
+
+## 系統架構總覽
+
+Formation 工具鏈採用**分層架構**，各模組職責清晰：
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ L5: headless.js — 陣型編排層（5 種陣型的執行邏輯）        │
+│     launch() → launchUnit/Solo/Squad/Legion/Legacy        │
+└────────────────────┬─────────────────────────────────────┘
+                     ↓
+┌──────────────────────────────────────────────────────────┐
+│ L4: runner.js — 進程啟動層（統一的 claude 進程管理）      │
+│     runSingle / runHeadless / runLegionLead / runParallel │
+└────────────────────┬─────────────────────────────────────┘
+                     ↓
+┌──────────────────────────────────────────────────────────┐
+│ L3: prompt.js — Prompt 組裝層（針對不同陣型組裝 prompt）  │
+│     buildPrompt → Unit/Solo/Squad/Legion/Legacy builders  │
+└────────────────────┬─────────────────────────────────────┘
+                     ↓
+┌──────────────────────────────────────────────────────────┐
+│ L2: loader.js — 資料載入層（skill YAML + 任務三層查詢）  │
+│     loadSkill / loadTask                                  │
+└────────────────────┬─────────────────────────────────────┘
+                     ↓
+┌──────────────────────────────────────────────────────────┐
+│ L1: logger.js + utils.js — 基礎設施層                     │
+│     createLogWriter / formatEntry / generateSessionId     │
+└──────────────────────────────────────────────────────────┘
+```
+
+**設計原則**：
+- **單一職責**：每個模組只負責一件事（編排 / 進程 / prompt / 載入 / 日誌）
+- **依賴單向**：L5 依賴 L4，L4 依賴 L3，依此類推，無循環依賴
+- **可測試性**：每層可獨立測試，dry-run 可在 prompt 層停下
+
+---
+
+## headless.js — Dispatch 入口
+
+**職責**：根據 `--formation` 參數分發到 5 種陣型的執行邏輯
+
+### 主入口
+
+#### `launch(options)`
+
+陣型編排的總調度器。
+
+**參數**：
+```js
+{
+  formation: 'unit' | 'solo' | 'squad' | 'legion' | 'legacy',
+  skill: string,          // 技能名稱（YAML 檔名，不含 .yaml）
+  task: string | null,    // TASK_ID 或任務描述（null 則自動尋找）
+  dryRun: boolean,        // true=只印 prompt，不啟動進程
+  mode: string | null     // 分析模式（squad 用），如 'optimization', 'innovation'
+}
+```
+
+**回傳**：
+- `unit/solo`: `ChildProcess`（單一進程）
+- `squad`: `ChildProcess[]`（並行進程陣列）
+- `legion`: `ChildProcess`（lead 進程）
+- `legacy`: `null`（scheduler loop 在 legacy-scheduler.js）
+
+**流程**：
+1. 若 `task` 為空且非 legacy → 呼叫 `findNextTask()` 自動選擇任務
+2. 載入 skill YAML (`loadSkill`) 和任務資料 (`loadTask`)
+3. 組裝 prompt (`buildPrompt`)
+4. 若 `dryRun=true` → 印出 prompt，結束
+5. 分發到對應陣型的 launcher 函數
+
+---
+
+### 陣型 Launchers
+
+#### `launchUnit(opts)`
+
+**單一 agent 直接執行**（最簡單的模式）
+
+**參數**：
+```js
+{
+  rawPrompt: string,     // 組裝好的 prompt
+  skill: string,
+  sessionId: string
+}
+```
+
+**行為**：
+- 呼叫 `runHeadless({ prompt: HEADLESS_PREFIX + rawPrompt, ... })`
+- 輸出壓縮、原始 stdout 直通
+
+---
+
+#### `launchSolo(opts)`
+
+**單一 agent 多視角分析**（agent 自主切換視角）
+
+**參數** / **行為**：與 `launchUnit` 相同，差異在 prompt 結構（含 perspectives）
+
+---
+
+#### `launchSquad(opts)`
+
+**多 agent 並行 + 辯論 + 整合**（複雜度最高的陣型）
+
+**參數**：
+```js
+{
+  rawPrompt: Array<{ memberId, prompt, skill }>, // 成員 prompt 陣列
+  skill: string,
+  sessionId: string,
+  skillDef: object  // 完整的 skill YAML（含 debate/merge 設定）
+}
+```
+
+**執行流程**：
+1. **Round 1**：並行啟動所有成員 (`runHeadless` × N)，各自獨立分析
+2. 等待所有成員完成 (`waitAll`)
+3. 若啟用 debate → **Round 2**：每個成員讀取其他人的報告，寫反駁
+4. **Synthesis**：整合者讀取所有報告，產出最終報告
+
+**關鍵函數**：
+- `waitAll(children)`: 等待所有進程完成，回傳 `Promise<{ memberId, exitCode, logPath }[]>`
+- `printResults(label, results, total)`: 格式化輸出進程執行結果
+- `hasSuccess(results)`: 檢查是否有至少一個成功
+- `squadSynthesis(opts)`: 啟動整合 agent
+
+---
+
+#### `launchLegion(opts)`
+
+**Agent Teams 啟動**（使用 Claude Code 官方 teammate 功能）
+
+**參數**：
+```js
+{
+  rawPrompt: {        // buildLegionPrompts 的輸出
+    teamName: string,
+    teamDesc: string,
+    lead: { prompt },
+    members: [{ name, agentType, prompt }]
+  },
+  skill: string,
+  sessionId: string
+}
+```
+
+**行為**：
+- 用 `buildLegionLeadPrompt(legionConfig)` 組裝 lead prompt
+- 呼叫 `runLegionLead({ prompt, ... })` 啟動 lead agent
+- Lead agent 用 `Task` 工具 spawn teammates（進程內並行）
+
+---
+
+#### `launchLegacy(opts)`
+
+**連續排程器**（Rust SingleAgentScheduler 對等實作）
+
+**參數**：
+```js
+{
+  skillDef: object  // legacy skill YAML（含 config 設定）
+}
+```
+
+**行為**：
+- 從 `skillDef.config` 提取參數（initial_delay_secs, interval_minutes 等）
+- 呼叫 `legacy-scheduler.js` 的 `start(overrides)`
+- 回傳 `null`（scheduler loop 不是 child process）
+
+---
+
+### 自動任務選擇
+
+#### `findNextTask()`
+
+從 `.collaboration/tasks/backlog/` 中找出最高優先級的任務。
+
+**回傳**：
+```js
+{
+  id: 'TASK_XXX',
+  title: string,
+  priority: number  // 0=P0, 1=P1, 2=P2, 3=P3
+} | null
+```
+
+**排序規則**：
+1. 優先級排序（P0 > P1 > P2 > P3）
+2. 同優先級按 ID 數字排序（TASK_150 > TASK_151）
+3. 跳過有未完成依賴的任務（檢查 dependencies 是否都在 done/）
+
+---
+
+### Dry Run
+
+#### `printDryRun(formation, rawPrompt, skillDef, skill)`
+
+列印 prompt 但不執行，用於偵錯。
+
+**行為**：
+- `legion`: 印 lead prompt
+- `squad`: 印 R1 所有成員 prompt + R2 debate prompts + synthesis prompt
+- 其他: 直接印 `HEADLESS_PREFIX + rawPrompt`
+
+---
+
+## prompt.js — Prompt 組裝 + Principles 注入
+
+**職責**：根據 skill YAML 和陣型，組裝出符合格式的 prompt
+
+### 主入口
+
+#### `buildPrompt(skillDef, taskInput, taskData, options)`
+
+根據陣型分發到對應的 prompt builder。
+
+**參數**：
+```js
+skillDef: object,        // loadSkill 回傳的 YAML 解析結果
+taskInput: string,       // TASK_ID 或任務描述
+taskData: string | null, // loadTask 回傳的 YAML 文本（或 null）
+options: {
+  analysisMode?: string  // 'optimization' | 'innovation'（squad 用）
+}
+```
+
+**回傳**：
+- `unit/solo/legacy`: `string`（單一 prompt）
+- `squad`: `Array<{ memberId, prompt, skill }>`
+- `legion`: `{ teamName, teamDesc, lead, members }`
+
+---
+
+### 陣型 Builders
+
+#### `buildUnitPrompt(skillDef, taskInput, taskData)`
+
+組裝單一 agent 的 prompt（最簡單結構）
+
+**Prompt 結構**：
+```
+## Role
+{role.identity}
+Priority: {role.priority}
+
+## Behavior
+- {behavior[0]}
+- {behavior[1]}
+...
+
+## Task
+{taskInput 或 taskData}
+
+## Workflow
+### {workflow[0].step}
+...
+
+## Expected Output
+Primary: {output.primary}
+Secondary: {output.secondary}
+```
+
+---
+
+#### `buildSoloPrompt(skillDef, taskInput, taskData)`
+
+在 unit 基礎上加入**可用視角 (perspectives)** 和**分析原則 (analysis_principles)**
+
+**額外區塊**：
+```
+## Analysis Principles
+### {principle.name}
+{principle.description}
+
+## Available Perspectives
+### {perspective.name}
+- 關注：{perspective.lens}
+- 何時切換：{perspective.trigger}
+```
+
+---
+
+#### `buildSquadPrompts(skillDef, taskInput, taskData, options)`
+
+為每個成員分別組裝 prompt（**最複雜的 builder**）
+
+**成員 Prompt 結構**：
+```
+## Role
+{member.role}
+
+## Analysis Mode: {analysisMode}
+{modeConfig.description}
+**你在此模式下的立場調整**:
+{member.mode_behavior[analysisMode]}
+
+## Principles (絕對遵守)
+{skillDef.principles.focus}
+**禁止 (違反即失敗)**:
+- ❌ {forbidden[0]}
+...
+**必須遵守**:
+- ✅ {required[0]}
+...
+
+## Identity
+你是 Squad 的成員 **{member.name}** (id: {member.id})。
+你與其他成員並行工作，各自獨立，不能互相通訊。
+完成你負責的部分後回報結果，Lead 會負責整合。
+
+## Scope (你只能碰這些檔案)
+Include:
+  - {scope.include[0]}
+  - ...
+Exclude:
+  - {scope.exclude[0]}
+  - ...
+
+## Shared Context (所有成員共享的約定)
+{skillDef.shared_context.description}
+### {key}
+{value}
+
+## Behavior
+- {skillDef.behavior[0]}
+- {member.behavior[0]}
+...
+
+## Task
+{taskInput 或 taskData}
+
+## Workflow
+{member.workflow 或 skillDef.collaboration.workflow}
+
+## Expected Output
+{member.output 或 skillDef.output}
+```
+
+**關鍵函數**：
+- `buildSharedContextBlock(skillDef)`: 組裝 shared_context 區塊（成員共用的約定）
+
+---
+
+#### `buildLegionPrompts(skillDef, taskInput, taskData)`
+
+組裝 team lead 和每個成員的 prompt。
+
+**回傳結構**：
+```js
+{
+  teamName: string,     // 團隊名稱（自動轉 kebab-case）
+  teamDesc: string,     // 團隊描述
+  lead: {
+    prompt: string      // Lead agent 的 prompt
+  },
+  members: [
+    {
+      name: string,         // 成員名稱
+      agentType: string,    // 'general-purpose' 等
+      prompt: string        // 成員的 prompt
+    }
+  ]
+}
+```
+
+**Lead Prompt 結構**：
+```
+## Role
+你是 {teamName} 的 Team Lead。
+{role.identity}
+
+## Team Members
+- **{member.name}**: {member.role}
+
+## Communication Rules
+### Principles
+- {comm.principles[0]}
+...
+### Patterns
+- **{pattern.name}**: {pattern.who} — {pattern.content}
+...
+### Broadcast Policy
+{comm.broadcast_policy}
+
+## Task
+{taskInput}
+
+## Lifecycle
+### {phase}
+{description}
+Lead actions:
+- {lead_actions[0]}
+Exit criteria:
+- {exit_criteria[0]}
+
+## Expected Output
+...
+```
+
+**Member Prompt**：
+- 優先使用 `skillDef.member_prompts[member.id]`（如 forge 的 designer/implementer）
+- 否則自動生成（Role + Responsibilities + Skills + Scope + Team Context）
+
+---
+
+#### `buildLegacyPrompt(skillDef)`
+
+回傳 scheduler 配置摘要（供 dry-run 顯示）
+
+---
+
+### Squad 專用：Synthesis 與 Debate
+
+#### `buildSquadSynthesisPrompt(skillDef, reportDir)`
+
+組裝整合 agent 的 prompt，讀取所有成員報告並整合。
+
+**Prompt 結構**：
+```
+## Role
+你是 Squad Synthesis Agent（整合者）。
+你不偏袒任何一方。
+
+## Principles (整合時也必須遵守)
+{skillDef.principles.focus}
+**禁止**: {forbidden}
+**必須遵守**: {required}
+
+## Merge Strategy: {merge.strategy}
+{merge.description}
+
+## Merge Steps (按順序執行)
+### Step: {step.step}
+{step.action}
+**Partial Failure Handling**: {step.on_partial_failure}
+
+## Reports Location
+所有成員報告位於 `.formation/reports/{reportDir}/` 目錄。
+**執行步驟**:
+1. 用 Glob 工具掃描 `.formation/reports/{reportDir}/*.md`
+2. 排除 synthesis.md
+3. 用 Read 工具逐一讀取每份報告
+4. 按照上述 Merge Steps 逐步整合
+
+## Squad Members（供參考）
+- **{member.name}** ({member.id}): {roleFirstLine}
+
+## Output
+將整合報告寫入 `.formation/reports/{reportDir}/synthesis.md`
+```
+
+---
+
+#### `buildSquadDebatePrompts(skillDef, reportDir)`
+
+組裝 Round 2 交叉辯論的 prompts（每個成員讀其他人的報告）
+
+**回傳**：`Array<{ memberId, prompt, skill }>`（格式與 buildSquadPrompts 相同）
+
+**Prompt 結構**：
+```
+## Role
+你是 **{member.name}**，這是你的第二輪分析（辯論回合）。
+
+## 你的立場（簡要提醒）
+{roleFirstLine}
+
+## Debate Instructions
+{member.debate_instructions}
+
+## Debate Rules
+- {debate.rules[0]}
+...
+
+## Reports to Read
+- **{other.name}**: `.formation/reports/{reportDir}/{other.id}.md`
+
+用 Read 工具讀取上述報告，然後寫出你的回應。
+
+## Output
+將反駁報告寫入 `.formation/reports/{reportDir}/{member.id}-r2.md`
+```
+
+---
+
+### Legion 專用
+
+#### `buildLegionLeadPrompt(config)`
+
+組裝 Legion lead 的完整 headless prompt（複製 Sunny teammate 成功模式）
+
+**結構**：
+```
+{LEGION_SYSTEM_PREFIX}
+Create an agent team with {members.length} teammates:
+1. "{name}" - {desc}
+2. ...
+
+Task: {taskMatch}
+
+{LEGION_AUTO_EXECUTE}
+```
+
+**常數定義**：
+- `LEGION_SYSTEM_PREFIX`: 定義 Team Lead 的角色與責任
+- `LEGION_AUTO_EXECUTE`: 強制執行規則（立即建 teammates，進入 polling loop，等所有人完成）
+
+---
+
+### 共用片段
+
+#### `appendBehavior(lines, skillDef)`
+
+將 `skillDef.behavior` 陣列附加到 lines。
+
+#### `appendTask(lines, taskInput, taskData)`
+
+組裝 Task 區塊：
+- 若有 taskData → 用 ` ``` ` 包起來顯示
+- 否則直接顯示 taskInput
+
+#### `appendWorkflow(lines, skillDef)`
+
+組裝 Workflow 區塊（從 `skillDef.collaboration.workflow`）
+
+#### `appendOutput(lines, skillDef)`
+
+組裝 Output 區塊（`primary` + `secondary`）
+
+---
+
+### Headless 常數
+
+#### `HEADLESS_PREFIX`
+
+強制規則：
+1. 直接執行，不要提問
+2. 不要讀取 CLAUDE.md
+3. 完成後輸出結構化結果
+4. 遇到無法執行的問題，輸出錯誤描述後結束
+5. **禁止執行任何 git 操作**（Git 由 Formation Lead 統一管理）
+
+---
+
+## runner.js — Subagent 執行
+
+**職責**：統一的 `claude` 進程啟動與輸出收集
+
+### 內部：進程管理
+
+#### `spawnClaude(opts)`
+
+所有 `run*` 函數的底層實作。
+
+**參數**：
+```js
+{
+  prompt: string,                 // 完整 prompt（已包含 HEADLESS_PREFIX）
+  formation: string,              // 陣型名稱（用於 log 目錄）
+  skill: string,                  // 技能名稱
+  sessionId: string,              // session ID
+  memberId?: string,              // 成員 ID（squad/legion 用）
+  silent?: boolean,               // 不輸出到 console
+  outputPath?: string,            // 自訂 log 路徑
+  cleanPrompt?: boolean,          // true=壓縮 prompt（移除換行、多餘空格）
+  allowedTools?: string,          // 允許的工具清單（逗號分隔）
+  extraArgs?: string[],           // 額外的 claude CLI 參數
+  pipeRaw?: boolean,              // true=原始 stdout 直通，false=格式化輸出
+  onLog?: (formatted: string) => void  // 自訂 log handler
+}
+```
+
+**回傳**：`ChildProcess`（附加 `_formation` 屬性）
+
+**流程**：
+1. 建立 log writer (`createLogWriter`)
+2. 啟動 `claude.cmd -p - --dangerously-skip-permissions --output-format stream-json ...`
+3. 將 prompt 透過 stdin 傳入
+4. 呼叫 `collectOutput(child, log, opts)` 收集輸出
+5. 附加 `_formation` 屬性到 child process
+
+**`_formation` 屬性**：
+```js
+{
+  logPath: string,    // log 檔案路徑
+  memberId: string,   // 成員 ID
+  log: object         // log writer 實例
+}
+```
+
+---
+
+#### `collectOutput(child, log, opts)`
+
+收集 `claude` 進程的 stdout/stderr，寫入 log。
+
+**參數**：
+```js
+child: ChildProcess,
+log: LogWriter,
+opts: {
+  silent?: boolean,       // 不輸出到 console
+  memberId?: string,      // 成員 ID（顯示用）
+  pipeRaw?: boolean,      // true=直通，false=格式化
+  onLog?: (line) => void  // 自訂 handler
+}
+```
+
+**行為**：
+1. 監聽 `stdout.data` 事件，解析 stream-json 格式
+2. 用 `formatEntry(entry)` 格式化每條 entry
+3. 寫入 log 檔案
+4. 若 `!silent && !pipeRaw` → 輸出到 console
+5. 偵測到 `type: 'result'` → emit `formation:done` 並延遲 kill（Windows fix）
+6. 監聽 `close/exit/formation:done` → 呼叫 `log.writeFooter(code)`
+
+**Windows 特殊處理**：
+- `claude.cmd` 有時進程不 exit，偵測到 `result` 就 emit 完成信號並延遲 kill
+
+---
+
+### 公開 API
+
+#### `runSingle(opts)`
+
+啟動單一 claude subagent（**格式化輸出**）
+
+**用途**：dispatch.js 用（一般模式）
+
+---
+
+#### `runHeadless(opts)`
+
+無頭模式：**壓縮 prompt + 原始 stdout 直通**
+
+**用途**：Unit / Solo / Squad 成員
+
+---
+
+#### `runLegionLead(opts)`
+
+Agent Teams 模式：啟用 `--teammate-mode in-process` + `Task` 工具
+
+**預設參數覆蓋**：
+```js
+{
+  cleanPrompt: true,
+  pipeRaw: true,
+  allowedTools: 'Bash,Read,Edit,Write,Glob,Grep,Task',
+  extraArgs: ['--teammate-mode', 'in-process']
+}
+```
+
+---
+
+#### `runParallel(opts)`
+
+並行啟動多個 claude subagent（**dispatch 用**）
+
+**參數**：
+```js
+{
+  members: Array<{ memberId, prompt, skill }>,
+  formation: string,
+  sessionId: string
+}
+```
+
+**回傳**：`Promise<Array<{ memberId, exitCode, logPath }>>`
+
+**行為**：
+1. 用 `runSingle` 並行啟動所有成員
+2. 用 `Promise.all` 等待所有進程完成
+3. 輸出執行結果摘要
+
+---
+
+## logger.js — Log 管理
+
+**職責**：Claude subagent 的 stream-json 格式化與 log 寫入
+
+### Log Writer
+
+#### `createLogWriter(opts)`
+
+建立 log writer 實例。
+
+**參數**：
+```js
+{
+  formation: string,   // 陣型（決定 log 目錄）
+  skill: string,       // 技能名稱
+  sessionId: string,   // session ID
+  outputPath?: string, // 自訂輸出路徑
+  memberId?: string    // Squad 成員 ID
+}
+```
+
+**回傳**：
+```js
+{
+  stream: WriteStream,      // fs.createWriteStream 實例
+  path: string,             // log 檔案絕對路徑
+  writeHeader: () => void,  // 寫入 header（formation, skill, session, 時間）
+  writeFooter: (code) => void  // 寫入 footer（finished, exit code）
+}
+```
+
+**Log 目錄結構**：
+```
+.formation/logs/{formation}/{skill}_{memberId?}_{sessionId}.log
+```
+
+---
+
+### Entry 格式化
+
+#### `formatEntry(entry)`
+
+格式化 stream-json 的一條 entry。
+
+**參數**：
+```js
+entry: {
+  type: 'system' | 'assistant' | 'user' | 'result',
+  subtype?: string,
+  message?: { content: [...] },
+  ...
+}
+```
+
+**回傳**：`string | null`（格式化後的文本，或 null 表示跳過）
+
+**支援的 entry types**：
+
+1. **system**：
+   - `init`: `[SYSTEM][INIT] model=... cwd=...`
+   - `hook_started`: `[SYSTEM][HOOK] {hook_name} started`
+   - `hook_response`: `[SYSTEM][HOOK] {hook_name} OK/FAILED`
+
+2. **assistant**（agent 輸出 + 工具呼叫）：
+   - `text` block → 移除 markdown 格式，分行輸出 `[Agent] ...`
+   - `tool_use` block → `[Agent][{tool}] {detail}`
+
+3. **user**（tool results、teammate 訊息）：
+   - `tool_use_result.status === 'teammate_spawned'` → `[SYSTEM][Spawned] ...`
+   - `message.content` 包含 "Message from" → `[Teammate:{name}] | ...`
+
+4. **result**（session 結束摘要）：
+   - `[RESULT] {subtype}`
+   - `Duration: {duration_ms/1000}s`
+   - `Cost: ${total_cost_usd}`
+   - `Turns: {num_turns}`
+   - 摘要前 10 行
+
+---
+
+#### `formatToolUse(ts, block)`
+
+格式化 tool_use block。
+
+**工具清單**：
+- `Bash`: 顯示 `description` 或 `command` 前 60 字元
+- `Read/Write/Edit`: 顯示 `file_path`
+- `Glob/Grep`: 顯示 `pattern`
+- `TeamCreate`: 顯示 `team_name`
+- `Task`: 顯示 `name` 和 `subagent_type`
+- `SendMessage`: 顯示 `recipient` 和 `type`，並附加完整訊息內容
+
+**格式**：
+```
+[HH:MM:SS][Agent][{tool}] {detail}
+    | {message line 1}
+    | {message line 2}
+    | ...
+```
+
+---
+
+#### `formatUser(ts, entry)`
+
+格式化 user events（tool results、teammate 訊息）
+
+**格式**：
+```
+[HH:MM:SS][SYSTEM][Spawned] Teammate "{name}" model=...
+[HH:MM:SS][Teammate:{name}]
+    | {message line 1}
+    | {message line 2}
+    | ...
+```
+
+---
+
+#### `formatResult(ts, entry)`
+
+格式化 session 結束摘要。
+
+**格式**：
+```
+[HH:MM:SS][RESULT] {subtype}
+  Duration: {seconds}s
+  Cost: ${usd}
+  Turns: {num_turns}
+  {result line 1}
+  {result line 2}
+  ...
+```
+
+---
+
+## utils.js — 工具函數
+
+**職責**：路徑常數、Session ID 生成、Git Bash 偵測、環境變數設定
+
+### 路徑常數
+
+```js
+ROOT                // D:\repo\side\ava\KenazAI
+FORMATION_DIR       // {ROOT}/.formation
+COLLABORATION_API   // {ROOT}/.collaboration/core/task-api.js
+LOG_DIR             // {ROOT}/.formation/logs
+```
+
+---
+
+### Session ID
+
+#### `generateSessionId()`
+
+生成唯一的 session ID。
+
+**格式**：`YYYYMMDD-HHMMSS-{4 位隨機 hex}`
+
+**範例**：`20260220-123045-a3f9`
+
+---
+
+### Git Bash 偵測
+
+#### `detectGitBash()`
+
+Windows 專用：自動偵測 Git Bash 路徑。
+
+**回傳**：`string | null`（bash.exe 的絕對路徑）
+
+**偵測順序**：
+1. 從 `where git` 找到 git.exe 路徑
+2. 往上找包含 `bin/bash.exe` 的 Git 根目錄
+3. Fallback 到固定路徑清單：
+   - `C:\Program Files\Git\bin\bash.exe`
+   - `C:\Program Files (x86)\Git\bin\bash.exe`
+   - `D:\Program Files\Git\bin\bash.exe`
+
+---
+
+### 環境變數
+
+#### `getClaudeEnv()`
+
+建立 claude 進程的環境變數。
+
+**回傳**：`object`（繼承 `process.env` 並修改）
+
+**變更**：
+1. 設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`（啟用 agent teams）
+2. 刪除 `CLAUDECODE`（避免 nested session 錯誤）
+3. Windows: 設定 `CLAUDE_CODE_GIT_BASH_PATH`（若未設定）
+
+---
+
+## loader.js — 任務載入三層 Fallback
+
+**職責**：載入 skill YAML + 任務資料（支援新舊兩套任務系統）
+
+### Skill 載入
+
+#### `loadSkill(formation, skill)`
+
+載入 skill YAML 定義。
+
+**參數**：
+```js
+formation: string,  // 陣型名稱（決定子目錄）
+skill: string       // 技能名稱（YAML 檔名，不含 .yaml）
+```
+
+**回傳**：`object`（YAML 解析結果）
+
+**路徑**：`.formation/{formation}/{skill}.yaml`
+
+**錯誤處理**：檔案不存在 → `console.error` + `process.exit(1)`
+
+---
+
+#### `listSkills(formation)`
+
+列出某個陣型下所有可用的 skill。
+
+**回傳**：`string[]`（skill 名稱列表，不含 .yaml）
+
+---
+
+### 任務載入（三層 Fallback）
+
+#### `loadTask(taskId)`
+
+載入任務資料，支援新舊兩套任務系統。
+
+**參數**：
+```js
+taskId: string  // TASK_XXX 格式（若不符合或為 null 則回傳 null）
+```
+
+**回傳**：`string | null`（YAML 或 JSON 文本）
+
+**查詢順序**：
+
+1. **新系統** (`.collaboration/tasks/`)
+   - 呼叫 `node .collaboration/core/task-api.js get {taskId}`
+   - 目錄結構：`{status}/{taskId}_{git_user}.yaml`（status = backlog/active/done/blocked）
+
+2. **舊系統 YAML** (`dev/pipeline/completed/` + `tasks/`)
+   - 掃描兩個目錄，找到以 `{taskId}` 開頭且 `.yaml` 結尾的檔案
+   - 讀取並回傳檔案內容
+
+3. **舊系統 JSON** (`dev/pipeline/TASK_QUEUE.json`)
+   - 解析 JSON 檔案
+   - 從 `tasks` 陣列找到 `id === taskId` 的任務
+   - 用 `yaml.dump` 轉為 YAML 格式回傳
+
+**錯誤處理**：
+- 所有層都失敗 → `console.warn` + 回傳 `null`（不中斷執行）
+
+---
+
+### 實作細節
+
+#### `loadTaskFromCollaboration(taskId)`
+
+新系統載入邏輯。
+
+**實作**：
+```js
+const result = execSync(
+  `node "${COLLABORATION_API}" get ${taskId}`,
+  { encoding: 'utf8', cwd: ROOT, timeout: 10000 }
+);
+```
+
+**錯誤處理**：捕捉 exception 並回傳 `null`
+
+---
+
+#### `loadTaskFromLegacyYaml(taskId)`
+
+舊系統 YAML 檔載入。
+
+**實作**：
+```js
+const dirs = ['completed', 'tasks'];
+for (const dir of dirs) {
+  const files = fs.readdirSync(dirPath);
+  const match = files.find(f => f.startsWith(taskId) && f.endsWith('.yaml'));
+  if (match) return fs.readFileSync(...);
+}
+```
+
+---
+
+#### `loadTaskFromLegacyQueue(taskId)`
+
+舊系統 JSON 索引載入。
+
+**實作**：
+```js
+const queue = JSON.parse(fs.readFileSync(LEGACY_TASK_QUEUE, 'utf8'));
+const task = queue.tasks.find(t => t.id === taskId);
+if (task) return yaml.dump(task, { lineWidth: -1 });
+```
+
+---
+
+## 呼叫關係圖
+
+```
+CLI (node .formation/tools/headless.js --formation=squad --skill=blitz)
+  ↓
+headless.js:launch()
+  ↓
+  ├─→ loader.js:loadSkill(formation, skill)        → 載入 YAML
+  ├─→ loader.js:loadTask(taskId)                   → 三層 fallback 載入任務
+  ├─→ prompt.js:buildPrompt(skillDef, taskInput)   → 組裝 prompt
+  ↓
+  ├── formation='squad' → headless.js:launchSquad()
+  │     ↓
+  │     ├─→ runner.js:runHeadless() × N (Round 1)
+  │     │     ↓
+  │     │     ├─→ runner.js:spawnClaude()
+  │     │     │     ↓
+  │     │     │     ├─→ logger.js:createLogWriter()
+  │     │     │     ├─→ utils.js:getClaudeEnv()
+  │     │     │     └─→ runner.js:collectOutput()
+  │     │     │           ↓
+  │     │     │           └─→ logger.js:formatEntry() → log 寫入
+  │     │     └─→ waitAll() → 等待所有進程完成
+  │     ↓
+  │     ├─→ prompt.js:buildSquadDebatePrompts() (Round 2)
+  │     ├─→ runner.js:runHeadless() × N (Round 2)
+  │     └─→ headless.js:squadSynthesis()
+  │           ↓
+  │           └─→ prompt.js:buildSquadSynthesisPrompt()
+  │                 ↓
+  │                 └─→ runner.js:runHeadless()
+  │
+  ├── formation='legion' → headless.js:launchLegion()
+  │     ↓
+  │     ├─→ prompt.js:buildLegionLeadPrompt()
+  │     └─→ runner.js:runLegionLead()
+  │           ↓
+  │           └─→ runner.js:spawnClaude(extraArgs: ['--teammate-mode', ...])
+  │
+  ├── formation='unit' → headless.js:launchUnit()
+  │     ↓
+  │     └─→ runner.js:runHeadless()
+  │
+  ├── formation='solo' → headless.js:launchSolo()
+  │     ↓
+  │     └─→ runner.js:runHeadless()
+  │
+  └── formation='legacy' → headless.js:launchLegacy()
+        ↓
+        └─→ legacy-scheduler.js:start()
+```
+
+---
+
+## 關鍵流程範例
+
+### 範例 1：Unit 執行流程
+
+**命令**：
+```bash
+node .formation/tools/headless.js --skill=do --task="修正按鈕顏色"
+```
+
+**流程**：
+1. `headless.launch()` 解析參數：`formation='unit', skill='do', task='修正按鈕顏色'`
+2. `loader.loadSkill('unit', 'do')` → 讀取 `.formation/unit/do.yaml`
+3. `prompt.buildPrompt()` → 呼叫 `buildUnitPrompt()` 組裝 prompt
+4. `headless.launchUnit()` → 呼叫 `runner.runHeadless()`
+5. `runner.spawnClaude()` 啟動 `claude.cmd -p - ...`
+6. `collectOutput()` 收集輸出，`formatEntry()` 格式化每條 entry
+7. 寫入 `.formation/logs/unit/do_{sessionId}.log`
+
+---
+
+### 範例 2：Squad 執行流程（含 Debate）
+
+**命令**：
+```bash
+node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_201
+```
+
+**流程**：
+1. `headless.launch()` 解析參數：`formation='squad', skill='blitz', task='TASK_201'`
+2. `loader.loadTask('TASK_201')` → 三層 fallback 載入任務 YAML
+3. `prompt.buildSquadPrompts()` → 回傳 `[{ memberId, prompt, skill }, ...]`
+4. `headless.launchSquad()`:
+   - **Round 1**：`runHeadless()` × N，並行啟動所有成員
+   - `waitAll()` 等待所有進程完成
+   - 若 `skillDef.debate.enabled=true`:
+     - **Round 2**：`buildSquadDebatePrompts()` 組裝辯論 prompts
+     - `runHeadless()` × N，成員互相讀取報告
+   - **Synthesis**：`buildSquadSynthesisPrompt()` + `runHeadless()`
+5. 每個成員的輸出分別寫入：
+   - R1: `.formation/logs/squad/{member.id}_{sessionId}.log`
+   - R2: `.formation/logs/squad/{member.id}-r2_{sessionId}.log`
+   - Synthesis: `.formation/logs/squad/{skill}-synthesis_{sessionId}.log`
+
+---
+
+### 範例 3：Legion 執行流程
+
+**命令**：
+```bash
+node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_202
+```
+
+**流程**：
+1. `prompt.buildLegionPrompts()` → 回傳 `{ teamName, lead, members }`
+2. `prompt.buildLegionLeadPrompt()` → 組裝 lead prompt（含 `LEGION_AUTO_EXECUTE`）
+3. `runner.runLegionLead()` → 啟動 lead agent（`--teammate-mode in-process`）
+4. Lead agent 用 `Task` 工具 spawn teammates（進程內並行）
+5. Lead agent 進入 polling loop（`sleep 5` + check messages）
+6. 等待所有 teammates 回報 → 整合結果 → 結束
+
+---
+
+## 總結
+
+Formation 工具鏈設計遵循以下核心原則：
+
+1. **分層架構**：L1 基礎設施 → L2 載入 → L3 prompt → L4 進程 → L5 編排
+2. **單一職責**：每個模組只做一件事，介面清晰
+3. **可測試性**：dry-run 可在 prompt 層停下，不啟動進程
+4. **統一進程管理**：所有陣型的 subagent 啟動都經過 `runner.js`
+5. **統一日誌格式**：所有 log 都經過 `logger.js` 格式化
+6. **雙系統相容**：任務載入支援新舊兩套系統（三層 fallback）
+
+**擴展建議**：
+- 新增陣型：在 `.formation/{formation}/` 建立 YAML，在 `headless.js` 新增 launcher
+- 新增工具支援：在 `logger.js:formatToolUse()` 新增格式化規則
+- 調整 prompt 結構：修改 `prompt.js` 對應的 builder 函數
+
+**維護要點**：
+- 修改 prompt 結構時，同步更新 `.formation/{formation}/` 下的 YAML 範例
+- 新增環境變數時，在 `utils.js:getClaudeEnv()` 統一設定
+- 修改 log 格式時，確保與 Sunny 的 `format-output.js` 保持一致