kenaz 0.3.17 → 0.3.19

package/core/.system/sunny/knowledge/collaboration-api.md

@@ -1,925 +0,0 @@
-# Collaboration 任務系統 API 完整指南
-
-> **版本**: 3.3.0
-> **最後更新**: 2026-02-20
-> **維護**: Kenaz Team
-
-## 概述
-
-`.collaboration/core/` 提供了一套完整的任務管理 API，包含 3 個核心模組：
-
-| 模組 | 檔案 | 用途 |
-|------|------|------|
-| 主 API | `task-api.js` | 核心任務 CRUD 操作、狀態管理、CLI 介面 |
-| JSON 輸出 | `task-api-json.js` | 向後相容的 JSON 格式輸出（供 Dashboard 使用） |
-| 遷移工具 | `migrate-legacy.js` | 從舊系統（dev/pipeline/）遷移任務到新系統 |
-
-## 1. task-api.js — 核心任務 API
-
-### 1.1 基本資訊
-
-- **API 版本**: 3.3.0
-- **Node 模組**: ✅ 可用 `require()` 導入
-- **CLI 介面**: ✅ 可直接執行
-
-### 1.2 CLI 命令列表
-
-#### 列出任務 (list)
-
-```bash
-# 基本列表
-node .collaboration/core/task-api.js list
-
-# 按狀態篩選
-node .collaboration/core/task-api.js list --status pending
-node .collaboration/core/task-api.js list --status in_progress
-node .collaboration/core/task-api.js list --status completed
-
-# 按優先級篩選
-node .collaboration/core/task-api.js list --priority P0
-node .collaboration/core/task-api.js list --priority P1
-
-# 按角色篩選
-node .collaboration/core/task-api.js list --role developer
-node .collaboration/core/task-api.js list --role designer
-
-# 按嚴謹度篩選（v3.3 新增）
-node .collaboration/core/task-api.js list --rigor high    # 需要 team 執行
-node .collaboration/core/task-api.js list --rigor medium  # 可選 team 或單一 Agent
-node .collaboration/core/task-api.js list --rigor low     # 單一 Agent 即可
-
-# 按標籤篩選（v3.2 新增）
-node .collaboration/core/task-api.js list --tags doc
-node .collaboration/core/task-api.js list --tags code,fix  # 多標籤逗號分隔
-
-# 組合篩選
-node .collaboration/core/task-api.js list --status pending --priority P1 --role developer
-```
-
-**輸出格式**：
-```
-總任務數: 10
-Pending: 3 | In Progress: 2 | Completed: 5
-
-任務列表 (3 個):
-  [TASK_224] 系統文檔：.collaboration 任務系統基礎概念 (pending, P1, developer, rigor:medium, docs)
-  [TASK_225] 前端組件：Agent 任務卡片組件 (pending, P1, developer, rigor:medium, code)
-```
-
-#### 取得任務 (get)
-
-```bash
-# 取得單個任務的完整資訊（JSON 格式）
-node .collaboration/core/task-api.js get TASK_224
-```
-
-**輸出**：完整的 JSON 物件，包含所有欄位。
-
-#### 建立任務 (create)
-
-```bash
-# 最小參數（只有標題）
-node .collaboration/core/task-api.js create --title "實作登入功能"
-
-# 完整參數
-node .collaboration/core/task-api.js create \
-  --title "實作登入功能" \
-  --description "建立用戶登入頁面和 API" \
-  --priority P1 \
-  --role frontend \
-  --rigor high \
-  --complexity medium \
-  --tags code,doc \
-  --dependencies TASK_170,TASK_171 \
-  --scope-paths "dashboard/src/pages/Login.tsx,backend/api/auth.py" \
-  --estimated-hours 8 \
-  --branch feature/login \
-  --notes "使用 JWT 驗證" \
-  --feature-ids F-001,F-002 \
-  --keywords login,auth
-
-# 多值欄位（支援多次使用同一 flag）
-node .collaboration/core/task-api.js create \
-  --title "系統文檔" \
-  --requirements "建立 API 文檔" \
-  --requirements "更新 README" \
-  --acceptance-criteria "文檔包含所有 API" \
-  --acceptance-criteria "範例程式碼可執行" \
-  --technical-notes "使用 Markdown 格式" \
-  --technical-notes "包含範例程式碼"
-```
-
-**參數清單**：
-
-| 參數 | 必填 | 預設值 | 說明 |
-|------|------|--------|------|
-| `--title` | ✅ | - | 任務標題 |
-| `--description` | ❌ | "" | 任務描述 |
-| `--priority` | ❌ | P2 | 優先級 (P0/P1/P2/P3) |
-| `--role` | ❌ | developer | 角色 (designer/developer/frontend/pm/sre/team_developer/team_strategy) |
-| `--rigor` | ❌ | medium | 嚴謹度 (high/medium/low) |
-| `--complexity` | ❌ | medium | 複雜度 (simple/medium/complex) |
-| `--tags` | ❌ | [] | 標籤（逗號分隔）|
-| `--dependencies` | ❌ | [] | 依賴任務 ID（逗號分隔）|
-| `--scope-paths` | ❌ | [] | 修改範圍路徑（逗號分隔）|
-| `--estimated-hours` | ❌ | null | 預估工時（小時）|
-| `--branch` | ❌ | null | Git 分支名稱 |
-| `--notes` | ❌ | "" | 備註 |
-| `--feature-ids` | ❌ | [] | Feature ID（逗號分隔）|
-| `--keywords` | ❌ | [] | 關鍵字（逗號分隔）|
-| `--requirements` | ❌ | [] | 需求（可多次使用）|
-| `--acceptance-criteria` | ❌ | [] | 驗收標準（可多次使用）|
-| `--technical-notes` | ❌ | [] | 技術筆記（可多次使用）|
-
-**輸出**：
-```
-✅ 任務已建立: TASK_248
-Hash: 9a8b7c6d-1234-5678-90ab-cdef12345678
-標題: 實作登入功能
-優先級: P1
-角色: frontend
-嚴謹度: high
-複雜度: medium
-標籤: code, doc
-依賴: TASK_170, TASK_171
-範圍: dashboard/src/pages/Login.tsx, backend/api/auth.py
-預估工時: 8h
-分支: feature/login
-```
-
-#### 認領任務 (claim)
-
-```bash
-# 將任務從 backlog/ 移至 active/
-node .collaboration/core/task-api.js claim TASK_224
-```
-
-**效果**：
-- 更新 `assigned_to` 欄位（當前 Git 用戶）
-- 更新 `metadata.claimed_at` 和 `metadata.claimed_by`
-- 檔案從 `.collaboration/tasks/backlog/` 移至 `.collaboration/tasks/active/`
-
-#### 完成任務 (complete)
-
-```bash
-# 基本完成（不記錄工時）
-node .collaboration/core/task-api.js complete TASK_224
-
-# 記錄實際工時
-node .collaboration/core/task-api.js complete TASK_224 --actual-hours 6.5
-```
-
-**效果**：
-- 更新 `executed_by` 欄位（當前 Git 用戶）
-- 設置 `actual_hours`（如果提供）
-- 檔案從 `.collaboration/tasks/active/` 移至 `.collaboration/tasks/done/`
-
-#### 移動任務 (move)
-
-```bash
-# 基本移動（遵守狀態機規則）
-node .collaboration/core/task-api.js move TASK_224 blocked
-node .collaboration/core/task-api.js move TASK_224 cancel
-
-# 強制移動（跳過狀態機驗證）
-node .collaboration/core/task-api.js move TASK_224 done --force
-```
-
-**狀態機規則**：
-
-| 來源狀態 | 允許的目標狀態 |
-|---------|---------------|
-| `backlog` | active, cancel, blocked |
-| `active` | done, blocked, cancel, backlog |
-| `blocked` | active, backlog, cancel |
-| `done` | backlog（重新開啟）, archived |
-| `cancel` | backlog（重新開啟）|
-
-#### 搜尋任務 (search)
-
-```bash
-# 全文搜尋（搜尋 title, description, id, tags）
-node .collaboration/core/task-api.js search "登入"
-node .collaboration/core/task-api.js search "API"
-```
-
-**輸出**：
-```
-找到 2 個符合 "登入" 的任務:
-
-  [TASK_248] 實作登入功能 (pending, P1)
-  [TASK_249] 登入頁面 UI 設計 (pending, P2)
-```
-
-#### 統計資訊 (stats)
-
-```bash
-node .collaboration/core/task-api.js stats
-```
-
-**輸出**：
-```
-任務統計:
-
-按狀態:
-  pending: 3
-  in_progress: 2
-  completed: 5
-
-按優先級:
-  P0: 1
-  P1: 4
-  P2: 3
-  P3: 2
-
-按角色:
-  developer: 6
-  designer: 2
-  frontend: 2
-
-按標籤:
-  doc: 4
-  code: 5
-  fix: 1
-
-總計: 10 個任務
-```
-
-#### 封存任務 (archive)
-
-```bash
-# 預覽（不實際執行）
-node .collaboration/core/task-api.js archive --keep 10 --dry-run
-
-# 執行封存（保留最新 10 個 done 任務）
-node .collaboration/core/task-api.js archive --keep 10
-
-# 保留最新 20 個
-node .collaboration/core/task-api.js archive --keep 20
-```
-
-**效果**：
-- 將 `done/` 中最舊的任務移至 `archived/`
-- 保留最新 N 個任務在 `done/`
-
-### 1.3 JavaScript API
-
-#### 導入模組
-
-```javascript
-const { TaskAPI, CONFIG, parseYAML, toYAML } = require('./.collaboration/core/task-api.js');
-
-const api = new TaskAPI();
-// 或自訂任務目錄
-const customApi = new TaskAPI({ tasksDir: '/path/to/tasks' });
-```
-
-#### 核心方法
-
-##### getAllTasks()
-
-```javascript
-const result = await api.getAllTasks();
-
-// 返回格式
-{
-  version: "3.3.0",
-  tasks: [
-    {
-      id: "TASK_224",
-      hash: "ee9ddf4b-9746-4899-970a-da7c4d510681",
-      title: "系統文檔：.collaboration 任務系統基礎概念",
-      description: "...",
-      priority: "P1",
-      status: "pending",
-      role: "developer",
-      tags: ["docs", "collaboration"],
-      complexity: "medium",
-      rigor: "medium",
-      estimated_hours: null,
-      actual_hours: null,
-      branch: null,
-      dependencies: [],
-      scope_paths: [],
-      requirements: [],
-      acceptance_criteria: [],
-      technical_notes: [],
-      created_by: { name: "...", git_user: "...", timestamp: "..." },
-      executed_by: null,
-      feature_ids: [],
-      keywords: [],
-      _status_dir: "backlog",  // 內部欄位：實際目錄
-      _file_path: "D:\\repo\\...\\backlog\\TASK_224_{git_user}.yaml"  // 內部欄位：檔案路徑
-    }
-  ],
-  statistics: {
-    total: 10,
-    pending: 3,
-    in_progress: 2,
-    completed: 5,
-    blocked: 0,
-    cancelled: 0
-  },
-  metadata: {
-    last_updated: "2026-02-20T12:00:00.000Z",
-    directories: ["backlog", "active", "done"]
-  }
-}
-```
-
-##### getTask(taskId)
-
-```javascript
-const task = await api.getTask('TASK_224');
-
-if (task) {
-  console.log(task.title);
-  console.log(task.status);
-  console.log(task._file_path);  // 內部欄位
-} else {
-  console.log('任務不存在');
-}
-```
-
-##### createTask(taskData)
-
-```javascript
-const task = await api.createTask({
-  title: "實作登入功能",
-  description: "建立用戶登入頁面和 API",
-  priority: "P1",
-  role: "frontend",
-  rigor: "high",
-  complexity: "medium",
-  tags: ["code", "doc"],
-  dependencies: ["TASK_170", "TASK_171"],
-  scope_paths: ["dashboard/src/pages/Login.tsx", "backend/api/auth.py"],
-  requirements: ["建立登入表單", "實作 JWT 驗證"],
-  acceptance_criteria: ["登入表單正常顯示", "JWT 驗證正常運作"],
-  estimated_hours: 8,
-  branch: "feature/login",
-  notes: "使用 JWT 驗證",
-  feature_ids: ["F-001", "F-002"],
-  keywords: ["login", "auth"]
-});
-
-console.log(`任務已建立: ${task.id}`);
-console.log(`Hash: ${task.hash}`);
-console.log(`檔案位置: ${task._file_path}`);
-```
-
-**自動處理**：
-- 自動生成遞增的 `id`（如 TASK_248）
-- 自動生成唯一的 `hash`（UUID v4）
-- 自動記錄 `created_by`（當前 Git 用戶）
-- 自動設置 `status: "pending"`
-- 檔案自動儲存到 `.collaboration/tasks/backlog/TASK_XXX_<git_user>.yaml`
-
-##### updateTask(taskId, updates)
-
-```javascript
-const task = await api.updateTask('TASK_224', {
-  title: "新標題",
-  priority: "P0",
-  tags: ["urgent", "code"],
-  estimated_hours: 10
-});
-
-console.log(`任務已更新: ${task.id}`);
-```
-
-**注意**：
-- 如果 `updates.status` 與原狀態不同，會自動呼叫 `moveTask()`
-- 自動更新 `metadata.updated_at` 和 `metadata.updated_by`
-
-##### moveTask(taskId, newStatus, taskData?, options?)
-
-```javascript
-// 基本移動
-const task = await api.moveTask('TASK_224', 'active');
-
-// 移動並更新資料
-const task = await api.moveTask('TASK_224', 'active', {
-  ...existingTask,
-  estimated_hours: 10
-});
-
-// 強制移動（跳過狀態機驗證）
-const task = await api.moveTask('TASK_224', 'done', null, { skipValidation: true });
-```
-
-**效果**：
-- 檔案從來源目錄移至目標目錄
-- 更新 `status` 欄位
-- 原子性操作（先寫入新位置，確認成功後刪除舊檔案）
-
-##### deleteTask(taskId)
-
-```javascript
-const success = await api.deleteTask('TASK_224');
-
-if (success) {
-  console.log('任務已刪除');
-} else {
-  console.log('任務不存在');
-}
-```
-
-##### claimTask(taskId, assignee?)
-
-```javascript
-// 認領給當前用戶
-const task = await api.claimTask('TASK_224');
-
-// 認領給指定用戶
-const task = await api.claimTask('TASK_224', 'johndoe');
-```
-
-**效果**：
-- 移至 `active/` 目錄
-- 更新 `assigned_to` 欄位
-- 更新 `metadata.claimed_at` 和 `metadata.claimed_by`
-
-##### completeTask(taskId, options?)
-
-```javascript
-// 基本完成
-const task = await api.completeTask('TASK_224');
-
-// 記錄工時
-const task = await api.completeTask('TASK_224', { actual_hours: 6.5 });
-```
-
-**效果**：
-- 移至 `done/` 目錄
-- 更新 `executed_by` 欄位
-- 設置 `actual_hours`（如果提供）
-
-##### queryTasks(query)
-
-```javascript
-// 按狀態篩選
-const tasks = await api.queryTasks({ status: 'pending' });
-
-// 按優先級篩選
-const tasks = await api.queryTasks({ priority: 'P1' });
-
-// 按角色篩選
-const tasks = await api.queryTasks({ role: 'developer' });
-
-// 按嚴謹度篩選
-const tasks = await api.queryTasks({ rigor: 'high' });
-
-// 按標籤篩選（任一匹配）
-const tasks = await api.queryTasks({ tags: ['doc', 'code'] });
-
-// 全文搜尋
-const tasks = await api.queryTasks({ search: '登入' });
-
-// 組合查詢
-const tasks = await api.queryTasks({
-  status: 'pending',
-  priority: 'P1',
-  role: 'developer',
-  rigor: 'high',
-  tags: ['code'],
-  search: 'API'
-});
-```
-
-##### getStatistics()
-
-```javascript
-const stats = await api.getStatistics();
-
-console.log(`總任務數: ${stats.total}`);
-console.log(`按狀態:`, stats.byStatus);
-console.log(`按優先級:`, stats.byPriority);
-console.log(`按角色:`, stats.byRole);
-console.log(`按標籤:`, stats.byTags);
-```
-
-#### 輔助方法
-
-##### generateTaskID()
-
-```javascript
-const newId = await api.generateTaskID();
-console.log(newId);  // TASK_248
-```
-
-##### validateTaskID(id)
-
-```javascript
-const isValid = api.validateTaskID('TASK_248');  // true
-const isValid2 = api.validateTaskID('INVALID');  // false
-```
-
-##### validateTransition(fromStatus, toStatus)
-
-```javascript
-const result = api.validateTransition('backlog', 'active');
-if (result.valid) {
-  console.log('允許的狀態轉換');
-} else {
-  console.log(`不允許的轉換: ${result.reason}`);
-}
-```
-
-### 1.4 配置常數 (CONFIG)
-
-```javascript
-const { CONFIG } = require('./.collaboration/core/task-api.js');
-
-console.log(CONFIG.API_VERSION);       // "3.3.0"
-console.log(CONFIG.TASKS_DIR);         // 預設任務目錄
-console.log(CONFIG.VALID_ROLES);       // ['designer', 'developer', ...]
-console.log(CONFIG.COMMON_TAGS);       // ['doc', 'code', 'plan', ...]
-console.log(CONFIG.VALID_RIGOR);       // ['high', 'medium', 'low']
-console.log(CONFIG.STATUS_DIRS);       // ['backlog', 'active', 'done']
-console.log(CONFIG.STATUS_MAP);        // 舊狀態 → 新狀態映射
-console.log(CONFIG.REVERSE_STATUS_MAP); // 新狀態 → 舊狀態映射
-console.log(CONFIG.ALLOWED_TRANSITIONS); // 狀態機規則
-```
-
-### 1.5 YAML 工具函數
-
-```javascript
-const { parseYAML, toYAML } = require('./.collaboration/core/task-api.js');
-
-// 解析 YAML 字串
-const obj = parseYAML('id: TASK_224\ntitle: Test');
-
-// 物件轉 YAML
-const yamlStr = toYAML({ id: 'TASK_224', title: 'Test' });
-```
-
----
-
-## 2. task-api-json.js — JSON 輸出 Wrapper
-
-### 2.1 基本資訊
-
-- **用途**: 向後相容的 JSON 格式輸出（供 Tauri Dashboard 使用）
-- **輸出**: 純 JSON（stdout），錯誤輸出到 stderr
-
-### 2.2 CLI 用法
-
-```bash
-# 取得所有任務（JSON 格式）
-node .collaboration/core/task-api-json.js
-
-# 取得單個任務
-node .collaboration/core/task-api-json.js --task TASK_224
-```
-
-### 2.3 輸出格式
-
-與舊版 `TASK_QUEUE.json` 相容，並匹配 Rust Task struct：
-
-```json
-{
-  "version": "3.3.0",
-  "tasks": [
-    {
-      "id": "TASK_224",
-      "hash": "ee9ddf4b-9746-4899-970a-da7c4d510681",
-      "title": "系統文檔：.collaboration 任務系統基礎概念",
-      "description": "...",
-      "status": "pending",
-      "priority": "P1",
-      "agent_type": "developer",
-      "role": "developer",
-      "complexity": "medium",
-      "assigned_agent": null,
-      "estimated_hours": null,
-      "actual_hours": null,
-      "branch": null,
-      "tags": ["docs", "collaboration"],
-      "dependencies": [],
-      "scope_paths": [],
-      "requirements": ["建立完整的 API 文檔"],
-      "acceptance_criteria": ["文檔包含所有 API"],
-      "technical_notes": [],
-      "created_by": {
-        "name": "{os_user}",
-        "git_user": "{git_user}",
-        "timestamp": "2026-02-20T12:33:44.145Z"
-      },
-      "last_modified_by": null,
-      "executed_by": null,
-      "assigned_to": null,
-      "rigor": "medium",
-      "metadata": {
-        "claimed_at": null,
-        "claimed_by": null,
-        "created_at": null,
-        "created_by": null
-      },
-      "feature_ids": [],
-      "related_tasks": [],
-      "keywords": [],
-      "notes": "",
-      "_file_path": "D:\\repo\\...\\backlog\\TASK_224_{git_user}.yaml",
-      "_source": "collaboration"
-    }
-  ],
-  "statistics": { ... },
-  "metadata": { ... }
-}
-```
-
-### 2.4 關鍵轉換
-
-| 新系統欄位 | 舊系統欄位 | 轉換邏輯 |
-|-----------|-----------|---------|
-| `role` | `agent_type` | 優先 `role`，否則 `agent_type` |
-| `status` | `status` | 保持舊格式 (pending/in_progress/completed) |
-| `assigned_to` | `assigned_agent` | 從物件提取 `git_user` 或 `name` |
-| `requirements` / `acceptance_criteria` / `technical_notes` | 同名 | 確保是字串陣列 |
-
-### 2.5 JavaScript 使用
-
-```javascript
-const { execSync } = require('child_process');
-
-// 取得所有任務
-const json = execSync('node .collaboration/core/task-api-json.js', { encoding: 'utf8' });
-const data = JSON.parse(json);
-
-// 取得單個任務
-const json2 = execSync('node .collaboration/core/task-api-json.js --task TASK_224', { encoding: 'utf8' });
-const task = JSON.parse(json2);
-```
-
----
-
-## 3. migrate-legacy.js — 舊系統遷移工具
-
-### 3.1 基本資訊
-
-- **用途**: 將舊系統（dev/pipeline/）的任務遷移到新系統（.collaboration/tasks/archived/）
-- **來源**:
-  1. `dev/pipeline/completed/*.yaml` — 舊 YAML 檔
-  2. `dev/pipeline/tasks/*.yaml` — 待處理任務
-  3. `dev/pipeline/TASK_QUEUE.json` — JSON 索引
-- **目標**: `.collaboration/tasks/archived/TASK_XXX.yaml`
-
-### 3.2 CLI 用法
-
-```bash
-# 預覽模式（不實際寫入）
-node .collaboration/core/migrate-legacy.js
-
-# 執行遷移
-node .collaboration/core/migrate-legacy.js --execute
-```
-
-### 3.3 輸出範例
-
-```
-📋 Existing tasks in new system: 30
-🔍 Legacy tasks found: 50
-❌ Missing from new system: 20
-
-  📝 TASK_134 ← dev/pipeline/completed/TASK_134_legacy.yaml (dry-run)
-  📝 TASK_135 ← dev/pipeline/TASK_QUEUE.json (dry-run)
-  ...
-
-📋 20 tasks would be migrated. Run with --execute to apply.
-```
-
-執行後：
-
-```
-  ✅ TASK_134 ← dev/pipeline/completed/TASK_134_legacy.yaml
-  ✅ TASK_135 ← dev/pipeline/TASK_QUEUE.json
-  ...
-
-✅ Migrated 20 tasks to .collaboration/tasks/archived/
-```
-
-### 3.4 轉換邏輯
-
-#### 狀態映射
-
-| 舊系統 | 新系統 |
-|-------|-------|
-| `pending` | `backlog` |
-| `in_progress` | `active` |
-| `completed` | `completed` |
-| `cancelled` | `cancel` |
-| `blocked` | `blocked` |
-| `done` | `completed` |
-| `split` | `backlog` |
-
-#### 角色處理
-
-- 優先使用 `role`
-- 否則使用 `agent_type`
-- 否則使用 `assigned_team`
-- 預設 `developer`
-
-#### 欄位補充
-
-- 自動生成 `hash`（UUID v4）
-- `rigor` 預設為 `low`
-- `created_by` 設為 `"Legacy Migration"`
-- `metadata.migrated_from` 記錄來源路徑
-- `metadata.migrated_at` 記錄遷移時間
-
-### 3.5 JavaScript 使用
-
-遷移工具目前為純 CLI 工具，沒有提供 JS API。建議透過 child_process 執行：
-
-```javascript
-const { execSync } = require('child_process');
-
-// 預覽
-const preview = execSync('node .collaboration/core/migrate-legacy.js', { encoding: 'utf8' });
-console.log(preview);
-
-// 執行
-const result = execSync('node .collaboration/core/migrate-legacy.js --execute', { encoding: 'utf8' });
-console.log(result);
-```
-
----
-
-## 4. 完整範例
-
-### 4.1 創建並執行任務的完整流程
-
-```javascript
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-
-async function workflow() {
-  // 1. 建立任務
-  const task = await api.createTask({
-    title: "實作登入功能",
-    description: "建立用戶登入頁面和 API",
-    priority: "P1",
-    role: "frontend",
-    rigor: "high",
-    tags: ["code", "feature"],
-    dependencies: ["TASK_170"],
-    scope_paths: ["dashboard/src/pages/Login.tsx"],
-    requirements: ["建立登入表單", "實作 JWT 驗證"],
-    acceptance_criteria: ["登入表單正常顯示", "JWT 驗證正常運作"],
-    estimated_hours: 8
-  });
-  console.log(`✅ 任務已建立: ${task.id}`);
-
-  // 2. 認領任務
-  await api.claimTask(task.id);
-  console.log(`✅ 任務已認領: ${task.id}`);
-
-  // 3. 執行工作...
-  console.log('🔨 執行中...');
-
-  // 4. 完成任務
-  await api.completeTask(task.id, { actual_hours: 6.5 });
-  console.log(`✅ 任務已完成: ${task.id}`);
-
-  // 5. 查詢統計
-  const stats = await api.getStatistics();
-  console.log(`📊 總任務數: ${stats.total}`);
-  console.log(`📊 已完成: ${stats.byStatus.completed}`);
-}
-
-workflow();
-```
-
-### 4.2 批次處理任務
-
-```javascript
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-
-async function batchProcess() {
-  // 找出所有 P1 pending 任務
-  const tasks = await api.queryTasks({
-    status: 'pending',
-    priority: 'P1',
-    role: 'developer'
-  });
-
-  console.log(`找到 ${tasks.length} 個高優先級待處理任務`);
-
-  // 批次認領
-  for (const task of tasks) {
-    await api.claimTask(task.id);
-    console.log(`✅ 認領: ${task.id} - ${task.title}`);
-  }
-}
-
-batchProcess();
-```
-
-### 4.3 監控任務狀態
-
-```javascript
-const { TaskAPI } = require('./.collaboration/core/task-api.js');
-const api = new TaskAPI();
-
-async function monitor() {
-  const stats = await api.getStatistics();
-
-  console.log('===== 任務儀表板 =====');
-  console.log(`總任務數: ${stats.total}`);
-  console.log('');
-  console.log('按狀態:');
-  for (const [status, count] of Object.entries(stats.byStatus)) {
-    console.log(`  ${status}: ${count}`);
-  }
-  console.log('');
-  console.log('按優先級:');
-  for (const [priority, count] of Object.entries(stats.byPriority)) {
-    console.log(`  ${priority}: ${count}`);
-  }
-  console.log('');
-  console.log('按角色:');
-  for (const [role, count] of Object.entries(stats.byRole)) {
-    console.log(`  ${role}: ${count}`);
-  }
-  console.log('');
-  console.log('按標籤:');
-  for (const [tag, count] of Object.entries(stats.byTags)) {
-    console.log(`  ${tag}: ${count}`);
-  }
-}
-
-monitor();
-```
-
----
-
-## 5. 常見問題
-
-### 5.1 如何處理任務 ID 衝突？
-
-任務 ID 衝突時，使用 `hash` 欄位（UUID v4）進行唯一識別。
-
-### 5.2 如何恢復已取消的任務？
-
-```bash
-node .collaboration/core/task-api.js move TASK_XXX backlog
-```
-
-### 5.3 如何強制移動到不允許的狀態？
-
-```bash
-node .collaboration/core/task-api.js move TASK_XXX TARGET_STATUS --force
-```
-
-### 5.4 如何批次封存舊任務？
-
-```bash
-# 保留最新 10 個 done 任務，其餘封存
-node .collaboration/core/task-api.js archive --keep 10
-```
-
-### 5.5 為什麼 requirements 變成了字串陣列？
-
-v3.2 改進：確保 `requirements`、`acceptance_criteria`、`technical_notes` 一律是字串陣列，避免物件混入導致的 Rust 解析錯誤。
-
-### 5.6 rigor 欄位的作用？
-
-`rigor`（嚴謹度）決定任務是否需要 team 執行：
-- `high` — 需要 team 執行（多 Agent 協作）
-- `medium` — 可選 team 或單一 Agent
-- `low` — 單一 Agent 即可
-
----
-
-## 6. 版本歷史
-
-### v3.3.0 (2026-02-14)
-- ✅ 新增 `rigor` 欄位（嚴謹度）
-- ✅ CLI 支援 `--rigor` 篩選和建立
-
-### v3.2.0 (2026-02-14)
-- ✅ 新增 `hash` 欄位（UUID v4）
-- ✅ `agent_type` 改名為 `role`（保持向後相容）
-- ✅ 新增 `tags` 欄位（陣列）
-- ✅ 新增 `actual_hours` 和 `branch` 欄位
-- ✅ 簡化人員追蹤（移除 assigned_to, collaborators, metadata）
-
-### v3.1.0 (2026-02-14)
-- ✅ 使用 js-yaml 替代自訂 YAML 解析器
-- ✅ `moveTask` 原子性操作
-- ✅ 狀態機驗證
-
-### v3.0.0 (2026-02-14)
-- ✅ 目錄即狀態設計
-- ✅ YAML 格式任務檔案
-- ✅ 移除 JSONL 索引依賴
-
----
-
-## 7. 相關文檔
-
-- [.collaboration/README.md](../../.collaboration/README.md) — 系統概述
-- [CLAUDE.md](../../CLAUDE.md) — 專案指導
-- [.system/collaboration/README.md](../collaboration/README.md) — 新舊系統對比