kenaz 0.3.18 → 0.3.20

package/core/.system/formation/README.md

@@ -1,1094 +0,0 @@
-# Formation System - 多陣型調度系統
-
-> **[RETIRED 2026-10, TASK_2401/2402/2403]** 本文描述已退役的 headless / legacy-scheduler Formation，僅留作歷史參考。現行路徑：`node .formation/tools/dispatch.js --skill=do --task=TASK_XXX --dispatch-mode=subagent`（見 `.formation/README.md`）。
-
-> **專案位置**: `.formation/`
-> **系統類型**: Multi-Agent 協作陣型系統
-> **適用場景**: 根據任務規模動態選擇最佳 Agent 部署策略
-
----
-
-## 📋 系統概述
-
-Formation 系統是 Kenaz AI 的 **Agent 部署陣型系統**，根據任務規模和協作需求，提供 **5 種不同的 Agent 調度陣型**，從最輕量的單人執行到最重火力的即時團隊協作。
-
-### 核心理念
-
-**「合適的陣型 = 最佳的效率與成本平衡」**
-
-不同任務需要不同的協作模式：
-- 簡單任務不需要團隊，浪費資源
-- 複雜任務單人做不完，拆不好反而更慢
-- 高耦合任務需要即時溝通，延遲會產生返工
-
-Formation 提供漸進式的陣型選擇，從「一人做一事」到「團隊即時協作」。
-
----
-
-## 🔥 陣型一覽
-
-```
-Unit  →  Solo  →  Squad  →  Legion  →  Legacy
- 1×1      1×N      N×1      Team       自動化
-最輕量    最靈活    真並行    最重火力    排程器
-```
-
-| 陣型 | 人數 | 溝通 | 成本 | 適用場景 |
-|------|------|------|------|---------|
-| **Unit** | 1 Agent, 1 Task | 無 | 最低 | 明確單一任務、Bug 修復 |
-| **Solo** | 1 Agent, N 視角 | 自主切換 | 低 | 策略分析、多角度審視 |
-| **Squad** | N Agents, 1 Task | 無（靠 context） | 中 | 並行子任務、批量修改 |
-| **Legion** | N Agents, 即時通訊 | SendMessage | 高 | 順序依賴、回饋循環 |
-| **Legacy** | 排程器自動調度 | 無 | 最低 | 自動化連續開發 |
-
----
-
-## 📁 目錄結構
-
-```
-.formation/
-├── README.md                     # 陣型選擇指南（本文件）
-├── lead.yaml                     # Formation Lead 定義（陣型選擇器）
-│
-├── tools/                        # ⭐ 核心工具模組
-│   ├── headless.js               # 無頭啟動器（推薦，所有陣型）
-│   ├── dispatch.js               # CLI 入口（互動式）
-│   ├── loader.js                 # YAML/Task 載入（三層 fallback）
-│   ├── prompt.js                 # Prompt 組裝（unit/solo/squad/legion）
-│   ├── runner.js                 # Claude 進程管理（單進程 + 並行）
-│   ├── logger.js                 # 日誌格式化
-│   ├── utils.js                  # 工具函數
-│   ├── run-round2.js             # Round 2 調度器（測試用）
-│   └── legacy-scheduler.js       # Legacy 排程器實作
-│
-├── logs/                         # ⭐ 執行日誌（按陣型分目錄）
-│   ├── unit/
-│   ├── solo/
-│   ├── squad/
-│   ├── legion/
-│   └── legacy/
-│
-├── briefs/                       # 任務簡報
-├── reports/                      # 執行報告
-│
-├── unit/                         # Unit 陣型定義
-│   ├── do.yaml                   # 執行者（做事）
-│   ├── think.yaml                # 分析者（思考）
-│   └── plan.yaml                 # 規劃者（計畫）
-│
-├── solo/                         # Solo 陣型定義（多視角）
-│   ├── strategy.yaml             # 策略分析（6 視角）
-│   └── diagnosis.yaml            # 問題診斷（4 視角）
-│
-├── squad/                        # Squad 陣型定義（並行協作）
-│   ├── blitz.yaml                # 通用並行拆分
-│   ├── sweep.yaml                # 同規則多範圍掃蕩
-│   └── strategy-tribunal.yaml    # 策略法庭（多視角辯論）
-│
-├── legion/                       # Legion 陣型定義（即時團隊）
-│   ├── forge.yaml                # 順序流水線（設計→打造→淬煉）
-│   └── hive.yaml                 # 網狀即時協調（全連接）
-│
-└── legacy/                       # Legacy 陣型定義（排程器）
-    ├── scheduler.yaml            # 排程器配置
-    ├── frontend.yaml             # 前端團隊
-    ├── backend.yaml              # 後端團隊
-    ├── designer.yaml             # 設計團隊
-    ├── qa.yaml                   # 測試團隊
-    ├── sre.yaml                  # 運維團隊
-    └── pm.yaml                   # 產品團隊
-```
-
----
-
-## 🎯 5 種陣型詳解
-
-### 1. Unit（單兵作戰）
-
-**1 Agent, 1 Task** — 最小部署單位。
-
-**機制**：
-- 使用 `Task` 工具，單次 subagent 調用
-- 不切換角色、不協作，純粹的「去做這件事」
-
-**成本**：最低
-
-**適用場景**：
-- ✅ 明確的單一任務
-- ✅ Bug 修復
-- ✅ 檔案修改
-- ✅ 腳本執行
-- ✅ 明確的 TASK_ID 任務
-
-**可用 Skills**：
-- `do`: 重心在「做」，交付可用成果
-- `think`: 重心在「思考」，深度分析
-- `plan`: 重心在「計畫」，規劃步驟
-
-**範例**：
-```bash
-# 修正按鈕顏色
-node .formation/tools/headless.js --skill=do --task="修正按鈕顏色為藍色"
-
-# 執行特定任務
-node .formation/tools/headless.js --skill=do --task=TASK_172
-```
-
----
-
-### 2. Solo（單人多視角）
-
-**1 Agent, N Perspectives** — 單人多視角自主切換。
-
-**機制**：
-- 派出一個 subagent，同時裝備多個專業視角
-- Agent 根據分析過程中的需要，**自主決定何時切換到哪個視角**
-- 不是輪流發言，是一個人用不同鏡頭看同一件事
-
-**成本**：低（單次 subagent 調用）
-
-**適用場景**：
-- ✅ 策略分析
-- ✅ 程式碼審查
-- ✅ 方案評估
-- ✅ 設計決策
-- ✅ 問題診斷
-
-**可用 Skills**：
-
-#### solo/strategy.yaml（策略分析 — 6 視角）
-
-**視角集**：
-1. **產品策略師** - 用戶需求、功能優先級、產品方向、競品分析
-2. **技術架構師** - 技術可行性、架構設計、技術選型、效能評估
-3. **UX 策略師** - 用戶體驗、交互模式、易用性、設計原則
-4. **商業分析師** - 價值評估、複雜度成本、技術債權衡、系統 ROI
-5. **創新專家** - 新技術探索、突破性方案、趨勢分析
-6. **風險分析師** - 風險識別、影響評估、緩解策略、應急計劃
-
-**核心原則**：
-- **獨立驗證**：不照抄輸入結論，自己讀源碼驗證
-- **深度優先**：每個視角要有具體證據（源碼行號、實際數據）
-- **不相關就跳過**：6 個視角不需要全部用到
-
-**範例流程**：
-```
-問題：評估快取方案
-→ [技術架構師] 分析架構影響，發現成本問題
-→ [產品策略師] 評估 ROI
-→ [風險分析師] 識別安全疑慮
-→ 綜合判斷，產出結論
-（視角切換由 agent 自主決定，非固定順序）
-```
-
-#### solo/diagnosis.yaml（問題診斷 — 4 視角）
-
-**視角集**：
-1. **表層診斷** - 錯誤訊息分析、日誌檢查
-2. **深層分析** - 源碼追蹤、資料流檢查
-3. **根因探索** - 為什麼會發生、系統性問題
-4. **解決方案** - 修復方案、預防措施
-
-**範例**：
-```bash
-# 策略分析（深度模式）
-node .formation/tools/headless.js \
-  --formation=solo \
-  --skill=strategy \
-  --task="評估 Redis vs Memcached 快取方案" \
-  --depth=deep
-
-# 問題診斷
-node .formation/tools/headless.js \
-  --formation=solo \
-  --skill=diagnosis \
-  --task="分析登入失敗問題"
-```
-
----
-
-### 3. Squad（多人並行）
-
-**N Agents, 1 Task** — 多 Agent 並行協作。
-
-**機制**：
-- 同時派出多個 subagent，各自負責任務的不同部分
-- 並行執行後由 Lead 整合成果
-- **成員之間不能互相通訊**（那是 Legion 的事）
-- 各自獨立完成後由 Lead 整合
-
-**成本**：中等（隨 Agent 數量線性增長）
-
-**核心約束**：
-- ✅ 成員之間**不通訊**，只靠 `shared_context`（啟動前定義的共享約定）協調
-- ✅ 每個成員的 `scope_paths` 不得重疊（避免檔案衝突）
-- ❌ 如果子任務之間有依賴關係，不適合用 Squad
-
-**適用場景**：
-- ✅ 並行子任務開發
-- ✅ 跨模組批量修改
-- ✅ 多區域同步掃蕩
-- ❌ 子任務有順序依賴 → 用 Legion
-
-**可用 Skills**：
-
-#### squad/blitz.yaml（通用並行拆分）
-
-**機制**：一個大任務拆成 N 個獨立子任務，每個成員拿到不同的子任務描述和檔案範圍。
-
-**與 sweep 的差別**：
-- blitz: 「同一個目標拆成 N 件**不同的事**」
-- sweep: 「同一個規則套 N 個**不同的地方**」
-
-**拆分原則**：
-- 每個子任務必須能獨立完成，不依賴其他子任務的產出
-- 每個成員的 `scope_paths` 不得重疊
-- 如果拆出來的子任務之間有「A 做完才能做 B」的關係，不要用 Squad
-
-**範例**：
-```
-範例 1：並行拆分
-├── [part_1] → 實作模組 A 的功能
-├── [part_2] → 實作模組 B 的功能
-└── [part_3] → 實作模組 C 的功能
-→ Lead 整合驗證，統一提交
-```
-
-#### squad/sweep.yaml（同規則掃蕩）
-
-**機制**：同一個規則套用到 N 個不同範圍。
-
-**範例**：
-```
-範例 2：同規則掃蕩
-├── [zone_1] → 重構 cmd_modules/ 下的模組
-├── [zone_2] → 重構 components/ 下的元件
-└── [zone_3] → 重構 lib/ 下的工具函數
-→ Lead 驗證一致性，統一提交
-```
-
-**啟動方式**：
-```bash
-# Blitz: 並行拆分
-node .formation/tools/headless.js \
-  --formation=squad \
-  --skill=blitz \
-  --task=TASK_201 \
-  --max_members=3
-
-# Sweep: 同規則掃蕩
-node .formation/tools/headless.js \
-  --formation=squad \
-  --skill=sweep \
-  --task="重構所有 API 模組使用 async/await"
-```
-
----
-
-### 4. Legion（即時團隊）
-
-**Native Team** — 即時溝通的完整團隊。
-
-**機制**：
-- 使用 Claude Code 原生的 `TeamCreate` 機制，建立持久化團隊
-- 成員之間可互相通訊（`SendMessage`）、即時協調
-- Legion 的核心價值不是「更多人」，而是「**即時溝通**」
-
-**成本**：最高（持久化 context + 通訊開銷）
-
-**核心價值**（Squad 做不到的事）：
-- ✅ 即時通知「我改了 X，你要更新」
-- ✅ 回饋循環（review → fix → re-review）
-- ✅ 順序依賴（A 做完 B 才開始）
-- ✅ 動態調整（做到一半改方向）
-
-**適用場景**：
-- ✅ 有順序依賴、回饋循環、或高度耦合的複雜任務
-- ✅ 需要跨成員協調介面契約
-- ✅ 需要多輪審查與修正
-- ❌ 子任務獨立無溝通需求 → 用 Squad 更便宜
-
-**可用 Skills**：
-
-#### legion/forge.yaml（鍛造 — 順序流水線）
-
-**拓撲**：`Designer → Implementer(s) → Reviewer`（帶回饋循環）
-
-**角色**：
-1. **Designer**（1 人）- 設計藍圖（介面契約、架構設計、遷移計劃）
-2. **Implementer**（1-3 人）- 按藍圖執行，遇到問題即時回報 Designer
-3. **Reviewer**（1 人）- 驗收每個 Implementer 的產出，不通過則打回修正
-
-**階段**：
-```
-Phase 1: Design   → Designer 產出藍圖
-Phase 2: Build    → Implementer(s) 按藍圖執行，Reviewer 同步就位
-Phase 3: Temper   → 全面驗證、修正、淬煉品質
-Phase 4: Teardown → 收集成果、關閉團隊
-```
-
-**溝通觸發**：
-- **藍圖發布**：Designer → All（Implementers + Reviewer）
-- **問題回報**：Implementer → Designer
-- **跨邊界通知**：Implementer → Implementer
-- **完成通知**：Implementer → Reviewer
-- **審查結果**：Reviewer → Implementer（通過 / 需修正）
-- **全部通過**：Reviewer → Team Lead
-
-**範例**：
-```
-需求：重構 API 模組架構
-→ Designer 設計新架構，產出介面契約
-→ Implementer_1 重構模組 A
-→ Implementer_2 重構模組 B
-→ Reviewer 逐一審查，發現問題打回修正
-→ 全部通過，整合提交
-```
-
-#### legion/hive.yaml（蜂巢 — 網狀協調）
-
-**拓撲**：全連接（所有成員彼此互聯）
-
-**機制**：
-- Worker A ←→ Worker B
-- 所有人即時互聯，任何變更即時同步
-
-**適用**：工作高度耦合、需要全員即時同步的場景
-
-**啟動方式**：
-```bash
-# Forge: 順序流水線
-node .formation/tools/headless.js \
-  --formation=legion \
-  --skill=forge \
-  --task=TASK_202
-
-# Hive: 網狀協調
-node .formation/tools/headless.js \
-  --formation=legion \
-  --skill=hive \
-  --task="多模組聯動重構"
-
-# Dry run（只看 prompt，不啟動）
-node .formation/tools/headless.js \
-  --formation=legion \
-  --skill=forge \
-  --task=TASK_202 \
-  --dry-run
-```
-
----
-
-### 5. Legacy（自動化排程器）
-
-**Scheduler = Formation Lead** — 連續調度排程器。
-
-#### 核心理念
-
-**Scheduler 升級為 Formation Lead**：
-- 不再只是「呼叫 CLI 的腳本」，而是真正的 **Formation Lead**
-- 負責 **任務調度 + post-complete（archive + git）+ Lead-only 任務處理**
-- 所有任務透過 Formation Legacy Skill 調度（不使用 `/dev` 或 `/product-review` CLI）
-- subagent 禁止執行 git 操作（Rule 5），由 Lead 統一管理
-
-#### 機制
-
-**雙重任務類型**：
-1. **一般任務**（role ≠ lead）：派給 Formation Legacy Skill 的 subagent 執行
-2. **Lead-only 任務**（role: lead）：Scheduler 自己處理（如 archive、git branch/merge）
-
-**完整流程**：
-```
-1. Scheduler 掃描待辦任務（新舊系統合併）
-   ↓
-2a. 一般任務（role ≠ lead）
-   → 調度 Formation Legacy Skill subagent
-   → subagent 完成任務移動（task-api.js complete）
-   → Scheduler 執行 post-complete（archive + git）
-
-2b. Lead-only 任務（role: lead）
-   → Scheduler 自己執行（post-complete.js）
-   → Scheduler 標記任務完成（task-api.js complete）
-   ↓
-3. 失敗 → 重置為 pending，繼續迴圈
-```
-
-**持續迴圈**：
-- 無待辦時進入 **idle check 模式**（預設 20s 輪詢）
-- 支援 **self-enhancement 模式**：無待辦時使用 review skill 分析專案
-
-**成本**：最低（自動化執行，無人工介入）
-
-**適用場景**：
-- ✅ 自動化連續開發
-- ✅ 夜間批量任務處理
-- ✅ Self-enhancement 迭代模式
-- ❌ 需要即時決策 → 用其他陣型
-
-#### 關鍵工具
-
-##### post-complete.js（Archive + Git）
-
-**任務完成後的自動化處理**：
-1. **Archive 檢查**（雙系統）：
-   - 新系統：`.collaboration/tasks/done/ → archived/`（超過 N 個）
-   - 舊系統：`dev/pipeline/completed/ → dev/pipeline/archived/`
-   - 預設保留 10 個最新任務，其餘移到 archived/
-
-2. **Git 分支管理**：
-   ```
-   task/task_xxx → user_branch → (手動) main
-   ```
-   - 建立 task branch（如 `task/task_205`）
-   - Stage + commit 所有變更（Co-Authored-By: Claude）
-   - Merge 到用戶分支（Git user name，如 `{git_user}`）
-   - 用戶手動 merge 到 main
-
-3. **Windows 安全處理**：
-   - `gitAddSafe()`：移除保留檔名（nul, con, prn, aux, com1-9, lpt1-9）
-   - SQLite journal 重試機制（暫存檔可能在 git add 時消失）
-
-**使用方式**：
-```bash
-# CLI 手動呼叫
-node .formation/tools/post-complete.js --task=TASK_205
-
-# Scheduler 自動呼叫（via postComplete() 函數）
-# （在 legacy-scheduler.js 的 runDevAgent 中）
-```
-
-##### HEADLESS_PREFIX（Rule 5：禁止 git 操作）
-
-**subagent 的行為規則**（prompt.js 注入）：
-```
-[HEADLESS MODE]
-你已被 Formation Lead 指派任務。規則：
-1. 直接執行，不要提問。需求已經確認過了。
-2. 不要讀取 CLAUDE.md — 這是 Formation 系統。
-3. 完成後輸出結構化結果。
-4. 遇到無法執行的問題,輸出錯誤描述後結束。
-5. 禁止執行任何 git 操作（commit、branch、merge、push）。Git 由 Formation Lead 統一管理。
-```
-
-**Rule 5 的重要性**：
-- ❌ 如果 subagent 執行 git commit → 可能與 Scheduler 的 post-complete 衝突
-- ✅ subagent 只負責「完成任務內容」（檔案修改、程式碼實作）
-- ✅ Scheduler 統一處理 git（避免混亂的 commit 歷史）
-
-#### 配置
-
-**對應 `legacy/scheduler.yaml`**：
-```yaml
-config:
-  initial_delay_secs: 30        # 首次執行前等待
-  interval_minutes: 20          # 執行間隔
-  idle_check_secs: 20           # 無任務時輪詢間隔（新增！）
-  early_finish_delay_secs: 30   # 提前完成時等待
-  dev_timeout_minutes: 60       # 任務超時
-  review_timeout_minutes: 30    # review skill 超時
-  enable_self_enhancement: false # 啟用自我增強
-
-formation_dispatch:
-  role_skill_map:
-    developer: developer
-    frontend: frontend
-    backend: backend
-    designer: designer
-    qa: qa
-    sre: sre
-    pm: pm
-    lead: lead                  # Lead-only 任務（Scheduler 自己處理）
-  default_skill: developer
-  review_skill: review
-
-post_complete:
-  keep: 10                      # archive 保留數量
-  git_flow: "task/task_xxx → user_branch → (手動) main"
-```
-
-**狀態機**：
-```
-stopped → waiting → running_dev → paused → completed
-                        ↓           ↑
-                   running_review ──┘
-                        ↓
-                     idle / error
-```
-
-**Idle Check 機制**（新增！）：
-- 無待辦任務時，每 `idle_check_secs` 秒（預設 20s）重新檢查
-- 避免 self-enhancement 模式頻繁執行 review（cost 最佳化）
-- 新任務出現時立即執行（手動使用 task-api.js 建立）
-
-#### 啟動方式
-
-```bash
-# 透過 headless.js（整合模式）
-node .formation/tools/headless.js \
-  --formation=legacy \
-  --skill=scheduler \
-  --task="連續開發所有待辦任務"
-
-# 透過專用排程器（推薦）
-node .formation/tools/legacy-scheduler.js
-
-# 啟用 self-enhancement
-node .formation/tools/legacy-scheduler.js --self-enhancement
-
-# 調整配置
-node .formation/tools/legacy-scheduler.js \
-  --initial-delay=0 \
-  --interval=10 \
-  --idle-check=30 \
-  --dev-timeout=120
-
-# Dry run（只檢查任務狀態）
-node .formation/tools/legacy-scheduler.js --dry-run
-```
-
-#### Lead-only 任務範例
-
-**任務定義**（`TASK_XXX.yaml`）：
-```yaml
-id: TASK_999
-title: "Archive 舊任務到 .memory/"
-role: lead                # ← 關鍵：role: lead
-status: pending
-priority: P2
-dependencies: []
-scope_paths: [".collaboration/tasks/done/"]
-requirements:
-  - "將 done/ 中超過 20 個的舊任務移到 archived/"
-acceptance_criteria:
-  - "done/ 目錄保留最新 10 個任務"
-commit_message: "[TASK_999] Archive 舊任務"
-```
-
-**執行流程**：
-```javascript
-// legacy-scheduler.js 的 runDevAgent 函數
-if (task.agentType === 'lead') {
-  // Lead-only 任務：Scheduler 自己處理
-  postComplete({ taskId: task.taskId, message: task.commitMessage });
-  execSync(`node .collaboration/core/task-api.js complete ${task.taskId}`);
-} else {
-  // 一般任務：派給 subagent
-  runWithFormation(task, skillName, config, logger);
-}
-```
-
----
-
-## 🛠️ 核心工具模組
-
-### 1. headless.js（無頭啟動器）⭐
-
-**用途**：統一的無頭啟動器，支援所有陣型。
-
-**特性**：
-- Subagent 不問問題，直接執行
-- 支援 dry-run 模式（只看 prompt，不啟動）
-- 自動載入任務定義（支援三層 fallback）
-- 自動記錄日誌到 `.formation/logs/{formation}/`
-
-**使用方式**：
-```bash
-# Unit
-node .formation/tools/headless.js --skill=do --task=TASK_172
-
-# Solo
-node .formation/tools/headless.js --formation=solo --skill=strategy --task=TASK_172
-
-# Squad
-node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_173
-
-# Legion
-node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_174
-
-# Legacy
-node .formation/tools/headless.js --formation=legacy --skill=scheduler --task="持續開發"
-
-# Dry run（只看 prompt，不啟動）
-node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_174 --dry-run
-```
-
-### 2. dispatch.js（互動式 CLI）
-
-**用途**：互動式 CLI 入口，支援動態參數輸入。
-
-**使用方式**：
-```bash
-node .formation/tools/dispatch.js --skill=do --task=TASK_172
-```
-
-### 3. loader.js（任務載入器）⭐
-
-**用途**：從三個來源載入任務定義（三層 fallback）。
-
-**Fallback 順序**：
-1. **新系統** - `.collaboration/tasks/{status}/TASK_XXX.yaml`（優先，目錄即狀態）
-2. **舊系統 YAML** - `dev/pipeline/completed/TASK_XXX_*.yaml`（降級，已完成任務）
-3. **舊系統 JSON** - `dev/pipeline/TASK_QUEUE.json` 內的 tasks 陣列（最終降級，活躍任務）
-
-**載入邏輯**（v3.1 新版本）：
-```javascript
-const { loadTask } = require('./.formation/tools/loader');
-
-// 自動嘗試三層 fallback
-const taskData = loadTask('TASK_172');
-
-// 內部實作：
-function loadTask(taskId) {
-  // Layer 1: 新系統 - .collaboration/tasks/
-  const collaborationPath = findTaskInCollaboration(taskId);
-  if (collaborationPath) {
-    return parseYAML(fs.readFileSync(collaborationPath, 'utf8'));
-  }
-
-  // Layer 2: 舊系統 YAML - dev/pipeline/completed/
-  const legacyYamlPath = findTaskInLegacy(taskId);
-  if (legacyYamlPath) {
-    return parseYAML(fs.readFileSync(legacyYamlPath, 'utf8'));
-  }
-
-  // Layer 3: 舊系統 JSON - dev/pipeline/TASK_QUEUE.json
-  const taskQueue = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
-  const task = taskQueue.tasks.find(t => t.id === taskId);
-  if (task) {
-    return task; // 已是 JS 物件，無需解析
-  }
-
-  throw new Error(`Task not found: ${taskId}`);
-}
-```
-
-**遷移策略**：
-- **現階段**（2026-02-18）：三層 fallback 同時運作，確保相容性
-- **未來階段 1**（2026 Q2 計劃）：新系統功能補齊（路徑鎖定、依賴解析增強）
-- **未來階段 2**（2026 Q3 計劃）：排程器遷移到新系統，舊系統標記為 Legacy
-- **未來階段 3**（2026 Q4 計劃）：封存舊系統，移除 Layer 2/3 fallback
-
-**優點**：
-- ✅ 向後相容（可讀取歷史任務）
-- ✅ 零停機遷移（新舊並存）
-- ✅ 自動優先新系統（鼓勵使用新系統）
-
-### 4. prompt.js（Prompt 組裝器）
-
-**用途**：根據陣型組裝對應的 Prompt。
-
-**支援陣型**：
-- `unit`: 單一 Agent prompt
-- `solo`: 單一 Agent + 多視角 prompt
-- `squad`: N 個 Agent prompts（並行）
-- `legion`: Team Lead prompt + Member prompts（團隊配置）
-
-**關鍵函數**：
-```javascript
-const { buildPrompt } = require('./.formation/tools/prompt');
-
-// Unit / Solo
-const prompt = buildPrompt(skillDef, taskInput, taskData);
-
-// Squad（回傳陣列）
-const prompts = buildPrompt(skillDef, taskInput, taskData);
-// prompts = [
-//   { memberId: 'part_1', prompt: '...', skill: 'do' },
-//   { memberId: 'part_2', prompt: '...', skill: 'do' }
-// ]
-
-// Legion（回傳配置）
-const legionConfig = buildPrompt(skillDef, taskInput, taskData);
-// legionConfig = {
-//   teamName: 'forge-team',
-//   teamDesc: '...',
-//   lead: { prompt: '...' },
-//   members: [{ name: 'designer', prompt: '...', agentType: '...' }]
-// }
-```
-
-### 5. runner.js（進程管理器）
-
-**用途**：啟動 Claude 進程（單進程 + 並行）。
-
-**關鍵函數**：
-```javascript
-const { runSingle, runParallel } = require('./.formation/tools/runner');
-
-// 單進程
-const result = await runSingle({ prompt, sessionId, output });
-
-// 並行進程
-const results = await runParallel([
-  { prompt: prompt1, sessionId: 'part_1' },
-  { prompt: prompt2, sessionId: 'part_2' }
-]);
-```
-
-### 6. logger.js（日誌格式化）
-
-**用途**：統一的日誌格式化與寫入。
-
-**日誌路徑**：`.formation/logs/{formation}/{timestamp}_{skill}_{sessionId}.log`
-
-### 7. utils.js（工具函數）
-
-**用途**：常用工具函數。
-
-**關鍵函數**：
-- `generateSessionId()`: 產生唯一 session ID
-- `parseCliArgs()`: 解析 CLI 參數
-- `findProjectRoot()`: 尋找專案根目錄
-
-### 8. post-complete.js（Formation Lead 專用）⭐
-
-**用途**：任務完成後的自動化處理（Archive + Git）。
-
-**完整流程**：
-```
-任務完成（subagent 已執行 task-api.js complete）
-   ↓
-┌─────────────────────────────────────────┐
-│ Formation Lead 執行 post-complete.js   │
-└─────────────────────────────────────────┘
-   ↓
-┌─ Step 1: Archive 檢查（雙系統）─────────┐
-│ 新系統：.collaboration/tasks/done/       │
-│   → 超過 keep 個 → 移到 archived/       │
-│ 舊系統：dev/pipeline/completed/          │
-│   → 超過 keep 個 → 移到 archived/       │
-│ （預設 keep=10）                         │
-└─────────────────────────────────────────┘
-   ↓
-┌─ Step 2: Git 分支管理 ──────────────────┐
-│ 1. 建立 task/task_xxx branch            │
-│ 2. gitAddSafe()                         │
-│    - 移除 Windows 保留檔名              │
-│    - SQLite journal 重試機制            │
-│ 3. git commit（Co-Authored-By: Claude） │
-│ 4. 切換/建立用戶分支（git user name）  │
-│ 5. git merge task/task_xxx → user_branch│
-│ 6. 留在 user_branch（用戶手動 merge main）│
-└─────────────────────────────────────────┘
-   ↓
-完成！
-```
-
-**CLI 使用方式**：
-```bash
-# 完整流程（archive + git）
-node .formation/tools/post-complete.js --task=TASK_205
-
-# 調整保留數量
-node .formation/tools/post-complete.js --task=TASK_205 --keep=15
-
-# 只做 archive（跳過 git）
-node .formation/tools/post-complete.js --skip-git
-
-# 只做 git（跳過 archive）
-node .formation/tools/post-complete.js --task=TASK_205 --skip-archive
-
-# Dry run（模擬執行）
-node .formation/tools/post-complete.js --task=TASK_205 --dry-run
-
-# 自訂 commit message
-node .formation/tools/post-complete.js --task=TASK_205 --message "[TASK_205] Custom message"
-```
-
-**JavaScript API**：
-```javascript
-const { postComplete } = require('./.formation/tools/post-complete');
-
-// 由 legacy-scheduler.js 自動呼叫
-postComplete({ taskId: 'TASK_205' });
-
-// 自訂參數
-postComplete({
-  taskId: 'TASK_205',
-  keep: 15,
-  skipArchive: false,
-  skipGit: false,
-  message: '[TASK_205] Custom commit message'
-});
-```
-
-**gitAddSafe() 處理**：
-1. **Windows 保留檔名清理**：
-   - 掃描專案根目錄，移除保留檔名（nul, con, prn, aux, com1-9, lpt1-9）
-   - 這些檔案通常是意外產生的空檔，會導致 git add 失敗
-
-2. **SQLite journal 重試機制**：
-   - Chromadb 暫存檔（如 `chroma.sqlite3-journal`）可能在 git add 時消失
-   - 最多重試 3 次，每次間隔 500ms
-   - 防止 `fatal: pathspec 'xxx-journal' did not match any files`
-
-**輸出範例**：
-```
-⚔️  Post-Complete: TASK_205
-   Keep: 10 | Archive: true | Git: true | DryRun: false
-
-── Archive Check ──
-   ✅ [新系統] done: 8/10 — no archive needed
-   📦 [舊系統] Archived 5 tasks (15 → 10):
-      → TASK_134_api_refactor.yaml
-      → TASK_135_ui_update.yaml
-      ...
-
-── Git Branch & Merge ──
-   ✅ Committed on task/task_205
-   ✅ Merged task/task_205 → {git_user}
-   📌 Now on branch: {git_user}
-   👉 Review changes, then: git checkout main && git merge {git_user}
-
-── Summary ──
-   Archive [新]: 0 archived, 8 kept
-   Archive [舊]: 5 archived, 10 kept
-   Git: branch=task/task_205 committed=true merged=true
-   👉 On branch: {git_user} — merge to main when ready
-```
-
----
-
-## 📊 選擇決策樹
-
-```
-問自己這些問題，找到最合適的陣型：
-
-1. 任務簡單、目標明確？
-   ✅ Yes → Unit
-
-2. 需要多角度分析？
-   ✅ Yes → Solo
-
-3. 需要同時做多件事？
-   ✅ Yes → 檢查是否有依賴
-      - 無依賴 → Squad
-      - 有依賴 → Legion (forge)
-
-4. 有順序依賴或回饋循環？
-   ✅ Yes → Legion (forge)
-
-5. 工作高度耦合、需即時協調？
-   ✅ Yes → Legion (hive)
-
-6. 需要自動化連續執行？
-   ✅ Yes → Legacy (scheduler)
-```
-
-### 選擇指南表格
-
-| 問自己 | 答案 | 陣型 |
-|--------|------|------|
-| 任務簡單、目標明確？ | Yes | **Unit** |
-| 需要多角度分析？ | Yes | **Solo** |
-| 需要同時做多件事？ | Yes | **Squad** |
-| 有順序依賴或回饋循環？ | Yes | **Legion** (forge) |
-| 工作高度耦合、需即時協調？ | Yes | **Legion** (hive) |
-| 需要自動化連續執行？ | Yes | **Legacy** (scheduler) |
-
----
-
-## 🎓 最佳實踐
-
-### 1. 陣型選擇原則
-
-**從小到大**：
-- 預設用 Unit，除非有明確理由升級
-- 需要多角度 → Solo
-- 需要並行 → Squad
-- 需要溝通 → Legion
-
-**避免過度設計**：
-- 不要為了用 Legion 而用 Legion
-- Squad 成員不要超過 4 個（成本和整合複雜度失控）
-- Legion 團隊規模：Designer(1) + Implementer(1-3) + Reviewer(1)，最多 5 人
-
-### 2. Squad 拆分品質
-
-**好的拆分**：
-```yaml
-# ✅ 乾淨的拆分
-├── part_1: scope_paths: ["src/api/auth/"]
-├── part_2: scope_paths: ["src/api/user/"]
-└── part_3: scope_paths: ["src/api/admin/"]
-→ 無依賴、無重疊、可並行
-```
-
-**壞的拆分**：
-```yaml
-# ❌ 有依賴關係
-├── part_1: "設計 API 介面"  # 必須先做
-└── part_2: "實作 API"       # 依賴 part_1
-→ 應該用 Legion (forge)
-
-# ❌ 路徑重疊
-├── part_1: scope_paths: ["src/"]
-└── part_2: scope_paths: ["src/api/"]  # 包含在 part_1 中
-→ 會產生檔案衝突
-```
-
-### 3. Legion 溝通準則
-
-**只在必要時通訊**：
-- ✅ 藍圖有破壞性變更 → broadcast
-- ✅ 發現藍圖問題 → SendMessage 給 Designer
-- ✅ 跨邊界變更 → SendMessage 給其他 Implementer
-- ❌ 定期打招呼 → 浪費 token
-
-**Broadcast vs SendMessage**：
-| 場景 | 使用 |
-|------|------|
-| 藍圖破壞性變更 | `broadcast`（所有人都要知道） |
-| Team Lead 調整分工 | `broadcast` |
-| 回報問題給 Designer | `SendMessage` |
-| 跨邊界通知 | `SendMessage` |
-| 審查結果 | `SendMessage` |
-
-### 4. Legacy 排程器配置
-
-**推薦配置**：
-```yaml
-config:
-  initial_delay_secs: 30        # 給系統初始化時間
-  interval_minutes: 20          # 20 分鐘足夠完成大多數任務
-  dev_timeout_minutes: 60       # 1 小時超時保護
-  enable_self_enhancement: false # 預設關閉，手動啟用
-```
-
-**Self-Enhancement 模式**：
-- 無待辦時自動執行 product review
-- 產生新任務後繼續執行
-- 設定 `max_enhancement_cycles` 防止無限迭代（推薦 3 次）
-
----
-
-## 🔗 相關文檔
-
-| 文檔 | 路徑 | 說明 |
-|------|------|------|
-| **Formation 系統概述** | `.formation/README.md` | 陣型選擇指南 |
-| **任務載入器原理** | `.formation/tools/loader.js` | 三層 fallback 實作 |
-| **Prompt 組裝邏輯** | `.formation/tools/prompt.js` | 各陣型 prompt 生成 |
-| **新任務系統** | `.system/collaboration/README.md` | Collaboration 系統文檔 |
-| **舊任務系統** | `.system/pipeline/README.md` | Pipeline 系統文檔 |
-| **Lead Agent 流程** | `CLAUDE.md` | 12 步開發流程 |
-
----
-
-## ❓ 常見問題
-
-### Q1: Unit vs Solo 如何選擇？
-
-**A**: 看任務性質。
-
-- **Unit**：任務明確，直接執行即可（如「修正按鈕顏色」）
-- **Solo**：需要分析判斷，多角度審視（如「評估快取方案」）
-
-**判斷標準**：
-- 任務描述是「做 X」→ Unit
-- 任務描述是「分析 / 評估 / 選擇 X」→ Solo
-
-### Q2: Squad vs Legion 如何選擇？
-
-**A**: 看子任務之間是否需要溝通。
-
-- **Squad**：子任務獨立，無溝通需求（省錢）
-- **Legion**：子任務有依賴、需要回饋循環（功能強）
-
-**判斷標準**：
-- 子任務之間能否用 `shared_context` 協調？
-  - ✅ Yes → Squad
-  - ❌ No（需要即時通訊）→ Legion
-
-### Q3: Formation 與任務系統的關係？
-
-**A**: Formation 是 Agent 調度系統，支援兩套任務管理系統（新舊並存）。
-
-**任務系統對照**：
-
-| 特性 | 新系統（Collaboration） | 舊系統（Pipeline） | Formation 支援 |
-|------|------------------------|-------------------|---------------|
-| 路徑 | `.collaboration/tasks/` | `dev/pipeline/` | ✅ 三層 fallback |
-| 格式 | 目錄 + YAML | JSON + YAML | ✅ 自動轉換 |
-| 狀態 | 目錄即狀態 | JSON 索引 | ✅ 統一介面 |
-| 適用 | 手動協作 | 排程器 | ✅ 兩者皆可 |
-| 載入順序 | Layer 1（優先） | Layer 2/3（降級） | ✅ 向後相容 |
-
-**協作流程**：
-```
-1. 任務從任務系統載入（TASK_172）
-   ├─ 優先嘗試新系統（.collaboration/tasks/）
-   ├─ 降級舊系統 YAML（dev/pipeline/completed/）
-   └─ 最終降級舊系統 JSON（dev/pipeline/TASK_QUEUE.json）
-
-2. Formation Lead 分析任務規模，選擇陣型
-   ├─ 簡單任務 → Unit
-   ├─ 多視角分析 → Solo
-   ├─ 並行子任務 → Squad
-   ├─ 順序依賴 → Legion
-   └─ 自動化連續執行 → Legacy
-
-3. Formation 調度對應陣型的 Agent 執行
-
-4. 完成後更新任務系統狀態
-   ├─ 新系統：移動 YAML 到 done/ 目錄
-   └─ 舊系統：更新 TASK_QUEUE.json 的 status 欄位
-```
-
-**未來計劃**：
-- **2026 Q2**：新系統功能補齊（路徑鎖定、依賴解析）
-- **2026 Q3**：Legacy 排程器遷移到新系統
-- **2026 Q4**：移除舊系統 fallback，Formation 只讀取新系統
-
-### Q4: 如何測試陣型配置？
-
-**A**: 使用 `--dry-run` 模式。
-
-```bash
-# 只看 prompt，不啟動
-node .formation/tools/headless.js \
-  --formation=legion \
-  --skill=forge \
-  --task=TASK_174 \
-  --dry-run
-```
-
-輸出會顯示：
-- Lead prompt
-- 各成員的 prompt
-- 團隊配置（Legion）
-
-確認 prompt 正確後再移除 `--dry-run` 執行。
-
-### Q5: 如何除錯 Formation 執行失敗？
-
-**A**: 檢查日誌。
-
-```bash
-# 查看最新日誌
-ls -lt .formation/logs/{formation}/ | head -5
-
-# 讀取日誌
-cat .formation/logs/{formation}/{timestamp}_{skill}_{sessionId}.log
-```
-
-**常見問題**：
-- **找不到任務**：檢查 `loader.js` 的三層 fallback 是否正確
-- **Prompt 錯誤**：使用 `--dry-run` 檢查 prompt 內容
-- **進程超時**：調整 `runner.js` 的超時配置
-
----
-
-## 📈 未來規劃
-
-- [ ] **動態陣型切換**：執行中根據負載動態調整陣型
-- [ ] **陣型效能分析**：記錄各陣型的成本與效率統計
-- [ ] **自動陣型推薦**：根據任務特徵自動推薦最佳陣型
-- [ ] **分散式 Squad**：支援跨機器並行執行
-
----
-
-**版本**: 1.0.0
-**最後更新**: 2026-02-18
-**維護者**: Developer Team
-**相關任務**: TASK_192