kenaz 0.3.17 → 0.3.19

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

@@ -1,1145 +0,0 @@
-# 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` 保持一致