kenaz 0.0.0-stage → 0.3.2

package/core/.system/collaboration/KNOWLEDGE.md

@@ -0,0 +1,65 @@
+# Per-Project Knowledge Convention
+
+## Summary
+
+KenazAI uses two memory layers:
+
+| Layer | Location | Contains |
+|-------|----------|----------|
+| Core auto-memory | `~/.claude/.../MEMORY.md` + Synapse runes | User preferences, cross-project facts, architectural decisions that span projects |
+| Project knowledge | `<project>/.kenaz/knowledge/*.md` | Facts, decisions, and context specific to one sub-project |
+
+**Rule**: Core `MEMORY.md` entries should only contain user-level or core-system facts.
+Project-specific facts (e.g., hardware pinouts, API contracts, deployment topology for a sub-project)
+belong in `<project>/.kenaz/knowledge/`.
+
+## How Project Knowledge Works
+
+When Ansuz boots pinned to a sub-project (via `--project-path` or session pin), the boot
+banner automatically lists the contents of `<project>/.kenaz/knowledge/`:
+
+```
+[pin:cli] Session bound: MyProject  /path/to/MyProject
+[knowledge] MyProject .kenaz/knowledge/:
+   api-design.md -- API Design Principles
+   deployment.md -- Deployment Guide
+```
+
+No extra steps needed — the listing is automatic at every pinned boot.
+
+## File Format
+
+Each knowledge file is a plain Markdown file:
+
+```markdown
+# File Title (shown in boot index)
+
+Content...
+```
+
+The boot banner extracts the **first  heading** as the file description.
+Files without a  heading are still listed (filename only).
+
+## Naming Convention
+
+Use descriptive kebab-case filenames:
+- `architecture.md` — system design decisions
+- `api-design.md` — API contracts
+- `deployment.md` — deployment topology
+- `hardware-pinout.md` — hardware-specific facts
+
+## Creating a Knowledge Directory
+
+```bash
+mkdir -p <project>/.kenaz/knowledge/
+# Then create .md files as needed
+```
+
+## Relationship to Synapse / Hippocampus
+
+- **Synapse runes** () = code-linked memory, searchable by symbol
+- **Hippocampus episodes** = session-level episodic memory
+- **Knowledge files** = stable, human-authored reference docs that persist with the repo
+
+Knowledge files are read at boot time only — they are not indexed by Synapse.
+For dynamic memory (decisions, fixes, risks), use  with .

package/core/.system/collaboration/README.md

@@ -0,0 +1,570 @@
+# .collaboration 新任務系統
+
+## 系統概述
+
+`.collaboration/` 是 Kenaz AI 專案的**第二代任務管理系統**（v3.x），採用「目錄即狀態」架構，用 YAML 格式儲存任務，並提供 Node.js CLI 和 JSON 輸出介面。
+
+**設計理念**：
+- **目錄即狀態**：任務狀態由檔案所在目錄決定，無需在檔案中維護狀態欄位
+- **YAML 格式**：人類可讀，支援多行文字和結構化資料
+- **雙層 API**：task-api.js（完整功能）+ task-api-json.js（JSON 輸出供 Dashboard 使用）
+- **向後相容**：與舊 TASK_QUEUE.json 格式相容，支援平滑遷移
+
+---
+
+## 目錄結構
+
+```
+.collaboration/
+├── core/                    # 核心 API
+│   ├── task-api.js          # 主 API（完整功能 + CLI）
+│   ├── task-api-json.js     # JSON 輸出包裝（供 Dashboard 使用）
+│   └── migrate-legacy.js    # 遷移工具（dev/pipeline → .collaboration）
+├── tasks/                   # 任務檔案（目錄即狀態）
+│   ├── backlog/             # 待處理任務 (status: pending)
+│   ├── active/              # 進行中任務 (status: in_progress)
+│   ├── done/                # 已完成任務 (status: completed)
+│   ├── blocked/             # 阻塞中任務 (status: blocked)
+│   ├── cancel/              # 已取消任務 (status: cancelled)
+│   └── archived/            # 已封存任務（長期保留）
+└── cli/                     # CLI 工具（未來擴展）
+```
+
+**任務檔名格式**：`TASK_<ID>_<git_user>.yaml`
+- 範例：`TASK_194_{git_user}.yaml`
+- `<ID>`：遞增數字（由系統自動生成）
+- `<git_user>`：Git 用戶名（email @ 前的部分，防止多用戶衝突）
+
+---
+
+## 核心 API
+
+### 1. task-api.js（主 API）
+
+**版本**：v3.3.0
+
+**主要功能**：
+- 任務 CRUD（建立、查詢、更新、刪除）
+- 狀態轉換（含狀態機驗證）
+- 任務認領與完成
+- 查詢與統計
+
+**使用方式**：
+
+```bash
+# 查看幫助
+node .collaboration/core/task-api.js --help
+
+# 列出所有任務
+node .collaboration/core/task-api.js list
+
+# 過濾查詢
+node .collaboration/core/task-api.js list --status pending --role developer --rigor high --tags code
+
+# 取得單個任務
+node .collaboration/core/task-api.js get TASK_194
+
+# 建立任務
+node .collaboration/core/task-api.js create \
+  --title "系統文檔：任務 API" \
+  --priority P1 \
+  --role developer \
+  --rigor medium \
+  --tags docs,code \
+  --scope-paths ".collaboration/core/" \
+  --estimated-hours 0.5
+
+# 認領任務（移動到 active）
+node .collaboration/core/task-api.js claim TASK_194
+
+# 完成任務（移動到 done）
+node .collaboration/core/task-api.js complete TASK_194 --actual-hours 0.3
+
+# 移動任務到其他狀態
+node .collaboration/core/task-api.js move TASK_194 blocked
+
+# 搜尋任務
+node .collaboration/core/task-api.js search "文檔"
+
+# 統計資訊
+node .collaboration/core/task-api.js stats
+```
+
+**關鍵欄位說明**：
+
+| 欄位 | 類型 | 說明 | 值 |
+|------|------|------|-----|
+| `id` | string | 任務 ID | `TASK_123` |
+| `hash` | string | UUID v4（ID 衝突時的唯一識別） | `550e8400-e29b-41d4-a716-446655440000` |
+| `title` | string | 任務標題 | - |
+| `description` | string | 詳細描述 | - |
+| `priority` | string | 優先級 | `P0` (最高) > `P1` > `P2` > `P3` |
+| `status` | string | 任務狀態 | `pending`, `in_progress`, `completed`, `blocked`, `cancelled` |
+| `role` | string | 預計分配角色 | `designer`, `developer`, `frontend`, `pm`, `sre`, `team_developer`, `team_strategy` |
+| `tags` | array | 任務標籤 | `doc`, `code`, `plan`, `fix`, `refactor`, `test`, `design`, `review` |
+| `complexity` | string | 複雜度 | `simple`, `medium`, `complex` |
+| `rigor` | string | 嚴謹度 | `high` (需 team), `medium`, `low` (單 Agent) |
+| `estimated_hours` | number | 預估工時（小時） | - |
+| `actual_hours` | number | 實際工時（任務完成後填入） | - |
+| `branch` | string | Git 分支 | - |
+| `dependencies` | array | 依賴任務 | `["TASK_100", "TASK_101"]` |
+| `scope_paths` | array | 影響範圍（修改的檔案/目錄） | `[".collaboration/core/"]` |
+| `requirements` | array | 功能需求 | `["支援建立任務", "支援查詢"]` |
+| `acceptance_criteria` | array | 驗收標準 | `["所有 API 有測試", "文檔更新完成"]` |
+| `technical_notes` | array | 技術筆記 | `["使用 js-yaml", "注意轉義"]` |
+| `created_by` | object | 建立者 | `{ name, git_user, timestamp }` |
+| `executed_by` | object | 執行者 | `{ name, git_user, timestamp }` |
+
+**狀態機轉換規則**：
+
+```
+backlog → active, cancel, blocked
+active  → done, blocked, cancel, backlog
+blocked → active, backlog, cancel
+done    → backlog（重新開啟）, archived（封存）
+cancel  → backlog（重新開啟）
+```
+
+使用 `--force` 可跳過驗證：
+```bash
+node .collaboration/core/task-api.js move TASK_194 blocked --force
+```
+
+---
+
+### 1b. k-cli task submit（TASK_2147：最小子專案任務生產者 API）
+
+**用途**：子專案自己的 process（例如 in-app agent）想把一個改良提案變成 Kenaz 任務、之後讀回結果，但不想複製
+`core-resolve.js` 的 core 解析邏輯（`__kenaz_core__` token、`KENAZ_SOURCE_DIR`、安裝目錄探索）。
+`k-cli task submit` 是這個需求的單一文件化入口：core 解析由 Kenaz 處理，呼叫者不需要知道 core 在哪。
+
+**跟 `k-cli task create` 的差異**（兩者都存在，各司其職）：
+
+| | `task create` | `task submit` |
+|---|---|---|
+| 用途 | 人類用自然語言描述需求 | process/script 已知所有欄位，要直接建卡 |
+| 執行方式 | spawnClaude → Ansuz 分析 + Agent tool 呼叫 Amelia 審查 role | 直接呼叫 `task-api.js create`，無 LLM、無 Claude CLI 依賴 |
+| 延遲/成本 | 一次 Claude session | 一次 node 子行程（毫秒級） |
+| 欄位 | 自由文字描述 | 與 `task-api.js create` 相同的旗標（`--title`/`--description`/`--requirements`...） |
+
+**核心解析**：沿用 `resolveProject()`（讀取 `.kenaz/project.yaml` 的 `core_path`，由 `k-cli project initialize`
+在子專案第一次初始化時寫入，當時的值來自 k-cli 自身執行檔的位置）。因此從任何已初始化的子專案 cwd 呼叫，
+**不需要設定 `KENAZ_SOURCE_DIR`**。
+
+**Origin 標記**：每個透過 `submit` 建立的任務都會寫入 `task.source`（對應 `task-api.js create` 新增的
+`--source`/`--origin` 旗標，兩者等價）。未明確指定時，預設為呼叫端的子專案名稱（`.kenaz/project.yaml` 的
+`project_name`）；需要更精確的來源（例如具體的 in-app agent 名稱）可用 `--origin <name>` 覆寫。
+
+**不是 auto-pipeline**：`createTask()` 一律寫入 `backlog/`（`pending` 狀態），走正常 triage 流程 ——
+`submit` 完全不呼叫 dispatch/headless.js，不會自動執行任務。來源內容（title/description 等）視為未信任資料，
+與 field report 相同處理方式（寫入前不會被當作指令執行）。
+
+**為什麼不是 HTTP server**：呼叫方本身就是一個能 spawn `node`/`k-cli` 的本地 process；開一個 HTTP server
+會多一個 port、生命週期管理、認證面，但目前只有一個消費者（子專案自己的 process），不需要網路介面——
+違反 YAGNI。CLI 已經是「任何 process 都能呼叫」的最小可行形式。
+
+```bash
+# 建立任務（在子專案 cwd 下，假設已 `k-cli project initialize` 過）
+node <core>/k-cli/dist/index.js task submit \
+  --project-path . \
+  --title "改良提案：XXX" \
+  --description "來自 in-app agent 的提案" \
+  --priority P3 --role developer \
+  --requirements "r1" --requirements "r2" --requirements "r3" \
+  --acceptance-criteria "a1" --acceptance-criteria "a2" --acceptance-criteria "a3" \
+  --technical-notes "n1" --technical-notes "n2" \
+  --origin "freya-in-app-agent" \
+  --json
+# → stdout 為建立後的完整任務 JSON（含 id、source、status）
+
+# 讀回結果（任何時間點，包含 complete 之後）
+node <core>/k-cli/dist/index.js task get TASK_XXX --project-path . --json
+# → status: "completed" 後，description/notes/technical_notes 即為完成摘要
+```
+
+`--dry-run` 支援（驗證會送出的 task-api.js 指令但不執行）；品質門檻（requirements/acceptance_criteria
+最少 3 條、technical_notes 最少 2 條）與 `task-api.js create` 完全一致，不因走這條路徑而放寬——
+需要跳過時呼叫端自行加 `--force`（不是預設行為）。
+
+實作：`k-cli/src/task/submit.ts`（thin passthrough）、`.collaboration/core/task-api.js` 的
+`--source`/`--origin` 旗標（寫入既有的 `task.source` 欄位）。
+
+---
+
+### 2. task-api-json.js（JSON 輸出包裝）
+
+**用途**：包裝 `task-api.js`，輸出純 JSON 格式（與舊版 TASK_QUEUE.json 相容），供 Tauri Dashboard 使用。
+
+**使用方式**：
+
+```bash
+# 輸出所有任務（JSON 格式）
+node .collaboration/core/task-api-json.js
+
+# 輸出單個任務
+node .collaboration/core/task-api-json.js --task TASK_194
+```
+
+**輸出格式**：
+
+```json
+{
+  "version": "3.3.0",
+  "tasks": [
+    {
+      "id": "TASK_194",
+      "hash": "357cd130-e843-4718-b858-7cc56bdae4e5",
+      "title": "系統文檔：.collaboration 新任務系統",
+      "status": "in_progress",
+      "priority": "P1",
+      "role": "developer",
+      "rigor": "medium",
+      "tags": ["docs"],
+      "complexity": "simple",
+      "estimated_hours": 0.3,
+      "dependencies": [],
+      "scope_paths": [".system/collaboration/"],
+      "requirements": ["閱讀核心 JS 檔案", "建立 README.md"],
+      "acceptance_criteria": ["README.md 涵蓋 API 使用方式"],
+      "created_by": {
+        "name": "{os_user}",
+        "git_user": "{git_user}",
+        "timestamp": "2026-02-18T15:07:00.995Z"
+      },
+      "_file_path": ".collaboration/tasks/active/TASK_194_{git_user}.yaml",
+      "_source": "collaboration"
+    }
+  ],
+  "statistics": {
+    "total": 124,
+    "pending": 2,
+    "in_progress": 1,
+    "completed": 108,
+    "blocked": 0,
+    "cancelled": 13
+  },
+  "metadata": {
+    "last_updated": "2026-02-18T15:30:00.000Z",
+    "directories": ["backlog", "active", "done", "cancel", "blocked", "archived"]
+  }
+}
+```
+
+**關鍵轉換**：
+- `role` 向後相容為 `agent_type`
+- 人員欄位 (`created_by`, `executed_by`) 轉為 `TaskPerson` 格式（匹配 Rust struct）
+- 陣列欄位確保為字串陣列（避免物件混入）
+
+---
+
+## 任務 YAML 格式
+
+完整範例：`.collaboration/tasks/TASK_Example_{git_user}.yaml`
+
+**最小範例**：
+
+```yaml
+id: TASK_194
+hash: 357cd130-e843-4718-b858-7cc56bdae4e5
+title: 系統文檔：.collaboration 新任務系統
+description: ''
+priority: P1
+status: in_progress
+role: developer
+tags:
+  - docs
+complexity: simple
+rigor: medium
+estimated_hours: 0.3
+actual_hours: null
+branch: null
+dependencies: []
+scope_paths:
+  - .system/collaboration/
+requirements:
+  - 閱讀核心 JS 檔案
+  - 建立 README.md
+acceptance_criteria:
+  - README.md 涵蓋 API 使用方式
+technical_notes: []
+created_by:
+  name: '{os_user}'
+  git_user: {git_user}
+  timestamp: '2026-02-18T15:07:00.995Z'
+executed_by: null
+feature_ids: []
+keywords: []
+```
+
+**注意事項**：
+- 使用 `js-yaml` 解析（v3.1+ 版本）
+- 避免使用特殊字元（冒號、引號）在未加引號的字串中
+- 多行文字使用 `|` 或 `>` 語法
+- 陣列欄位必須是字串陣列（避免物件混入）
+
+---
+
+## 與舊系統的關係
+
+### 雙軌制說明
+
+專案同時維護兩套任務系統，處於**漸進式遷移**階段：
+
+| 系統 | 路徑 | ID 範圍 | 格式 | 狀態 | 適用場景 |
+|------|------|---------|------|------|---------|
+| **新系統（Collaboration）** | `.collaboration/tasks/{status}/` | TASK_151~196+ | 目錄 + YAML | ✅ 主力系統（推薦） | 手動協作、簡單流程 |
+| **舊系統（Pipeline）** | `dev/pipeline/TASK_QUEUE.json` + `completed/` | TASK_134~187 | JSON + YAML | ⚠️ 相容支援（逐步淘汰） | 排程器、Multi-Agent 並行開發 |
+
+**查詢任務時必須兩邊都查**：
+- 新系統：`node .collaboration/core/task-api.js get TASK_XXX`
+- 舊系統：`dev/pipeline/completed/TASK_XXX_*.yaml` 或 `dev/pipeline/TASK_QUEUE.json`
+
+---
+
+### 詳細差異對照
+
+| 特性 | Pipeline System（舊） | Collaboration System（新） | 說明 |
+|------|---------------------|--------------------------|------|
+| **狀態管理** | JSON 索引集中式 | 目錄分散式 | 新系統移動檔案即改變狀態，簡化流程 |
+| **任務格式** | JSON 索引 + YAML 檔案 | 純 YAML（目錄即狀態） | 新系統無需在 YAML 中維護狀態欄位 |
+| **查詢介面** | Python API + JSON | Node.js CLI + JSON 輸出 | 新系統支援 `--help` 和過濾查詢 |
+| **路徑鎖定** | ✅ `lock_manager.py` | ❌ 無 | 舊系統支援並行開發衝突檢測 |
+| **依賴解析** | ✅ `dependency_resolver.py` | ⚠️ 基礎支援 | 舊系統有拓撲排序、循環檢測、關鍵路徑 |
+| **統計查詢** | ✅ 豐富（含關鍵路徑、依賴圖） | ⚠️ 基礎（僅數量統計） | 舊系統功能更完善 |
+| **排程器整合** | ✅ Single-Agent、Multi-Agent | ⚠️ Formation 有限支援 | 舊系統為排程器設計 |
+| **Dashboard 支援** | ✅ Tauri API 呼叫 | ✅ Tauri API 呼叫 | 兩者皆支援 JSON 輸出 |
+| **衝突避免** | ✅ `scope_paths` + 路徑鎖定 | ⚠️ `scope_paths` 欄位（無自動檢測） | 舊系統自動防衝突 |
+| **孤兒鎖定清理** | ✅ 自動清理 | ❌ 不適用 | 舊系統處理 Agent crash |
+| **驗證腳本** | ✅ `validate_pipeline.ps1` | ❌ 無 | 舊系統有一致性檢查 |
+| **複雜度** | ⚠️ 較高（需理解鎖定機制） | ✅ 較低（目錄即狀態） | 新系統更易上手 |
+| **適用場景** | 排程器、並行開發 | 手動協作、簡單流程 | 根據場景選擇系統 |
+
+**選擇建議**：
+- ✅ **使用新系統（Collaboration）**：手動協作、簡單任務流程、不需要並行開發
+- ✅ **使用舊系統（Pipeline）**：需要自動化排程器、Multi-Agent 並行開發、路徑衝突檢測
+
+---
+
+### 遷移方向
+
+**目標**：逐步將 Pipeline 系統的功能整合到 Collaboration 系統，最終淘汰舊系統。
+
+**階段 1：雙軌制運行**（當前階段）
+- ✅ 兩套系統並存，保持相容
+- ✅ 新任務優先建立在 Collaboration 系統
+- ✅ Formation 系統已支援三層 fallback（新系統 → 舊 YAML → 舊 JSON）
+
+**階段 2：功能補齊**（計劃中）
+- [ ] 實現路徑鎖定機制（移植 `lock_manager.py` 到 Node.js）
+- [ ] 增強依賴解析（拓撲排序、循環檢測、關鍵路徑）
+- [ ] 建立驗證工具（`validate_collaboration.js`）
+- [ ] 統計查詢增強（依賴圖、執行時間預估）
+
+**階段 3：排程器遷移**（計劃中）
+- [ ] 更新 Single-Agent 排程器使用新系統
+- [ ] 更新 Multi-Agent 排程器使用新系統
+- [ ] 保留舊系統的 Python orchestrator 模組作為參考實現
+
+**階段 4：全面遷移**（計劃中）
+- [ ] 將 `dev/pipeline/TASK_QUEUE.json` 中的任務匯入新系統
+- [ ] 封存舊系統文件至 `.legacy/`
+- [ ] 更新 CLAUDE.md、規則文檔移除舊系統引用
+
+**遷移工具**：
+```bash
+# 匯出新系統任務為舊格式（供排程器使用）
+node .collaboration/core/migrate-legacy.js export
+
+# 匯入舊系統任務到新系統（未來遷移用）
+node .collaboration/core/migrate-legacy.js import
+
+# 雙向同步（開發中）
+node .collaboration/core/migrate-legacy.js sync
+```
+
+**相關文檔**：
+- 舊系統文檔：`.system/pipeline/README.md`
+- 遷移腳本：`.collaboration/core/migrate-legacy.js`
+- Formation 整合：`.formation/tools/loader.js:180-220`
+
+---
+
+## 整合與使用場景
+
+### 1. Formation 系統整合
+
+`.formation/tools/loader.js` 已更新為三層 fallback：
+1. 優先讀取新系統（`.collaboration/tasks/`）
+2. 降級讀取舊 YAML（`dev/pipeline/completed/`）
+3. 最終降級讀取舊 JSON（`dev/pipeline/TASK_QUEUE.json`）
+
+### 2. Dashboard 整合
+
+Tauri Dashboard 透過 Rust API 呼叫 `task-api-json.js`：
+```rust
+// dashboard/src-tauri/src/features/task/manager.rs
+pub async fn get_tasks() -> Result<TaskQueue, TaskError> {
+    let output = Command::new("node")
+        .args(&[".collaboration/core/task-api-json.js"])
+        .output()?;
+    let json = String::from_utf8(output.stdout)?;
+    serde_json::from_str(&json)
+}
+```
+
+### 3. Dev Agent 整合
+
+Dev Agent 使用新系統查詢任務：
+```bash
+# 列出待辦任務
+node .collaboration/core/task-api.js list --status pending --role developer
+
+# 認領任務
+node .collaboration/core/task-api.js claim TASK_194
+
+# 完成任務
+node .collaboration/core/task-api.js complete TASK_194 --actual-hours 0.3
+```
+
+---
+
+## 最佳實踐
+
+### 建立任務
+
+1. **使用 CLI 建立**（推薦）：
+```bash
+node .collaboration/core/task-api.js create \
+  --title "任務標題" \
+  --priority P1 \
+  --role developer \
+  --rigor medium \
+  --tags code,docs \
+  --scope-paths "path/to/change" \
+  --dependencies TASK_192,TASK_193 \
+  --estimated-hours 0.5 \
+  --requirements "需求 1" \
+  --requirements "需求 2" \
+  --acceptance-criteria "驗收標準 1"
+```
+
+2. **手動建立 YAML**（僅限特殊情況）：
+   - 複製 `TASK_Example_{git_user}.yaml`
+   - 修改欄位
+   - 放入 `backlog/` 目錄
+   - 檔名格式：`TASK_<ID>_<git_user>.yaml`
+
+### 更新任務狀態
+
+使用 `move` 指令而非手動移動檔案：
+```bash
+# 正確（使用 CLI）
+node .collaboration/core/task-api.js move TASK_194 active
+
+# 錯誤（手動移動會導致狀態不一致）
+mv .collaboration/tasks/backlog/TASK_194_{git_user}.yaml .collaboration/tasks/active/
+```
+
+### 避免衝突
+
+- 多人協作時，使用 `hash` 欄位作為唯一識別
+- 檔名含有 `git_user` 避免撞名
+- 依賴 Git 合併機制處理衝突
+
+---
+
+## 技術細節
+
+### 狀態機驗證
+
+`validateTransition()` 方法檢查狀態轉換合法性：
+```javascript
+const validation = api.validateTransition('backlog', 'done');
+if (!validation.valid) {
+  console.error(validation.reason);
+  // 輸出：不允許的狀態轉換: backlog → done。允許的目標: active, cancel, blocked
+}
+```
+
+### YAML 解析
+
+使用 `js-yaml` 替代自訂解析器（v3.1+ 版本），修復 round-trip 資料損壞 Bug：
+```javascript
+const yaml = require('js-yaml');
+
+function parseYAML(content) {
+  try {
+    return yaml.load(content) || {};
+  } catch (error) {
+    console.error('YAML 解析錯誤:', error.message);
+    return {};
+  }
+}
+```
+
+### 原子性操作
+
+`moveTask()` 使用「先複製後刪除」策略確保原子性：
+```javascript
+async moveTask(taskId, newStatus) {
+  // Step 1: 寫入新位置
+  await fs.writeFile(newFilePath, yamlContent);
+  // Step 2: 驗證寫入成功
+  await fs.access(newFilePath);
+  // Step 3: 刪除舊檔案（僅當路徑不同時）
+  if (oldFilePath !== newFilePath) {
+    await fs.unlink(oldFilePath);
+  }
+}
+```
+
+---
+
+## 已知問題與限制
+
+1. **ID 衝突**：多人同時建立任務可能產生相同 ID，使用 `hash` 欄位區分
+2. **檔名編碼**：Windows 環境需注意 UTF-8 編碼（BOM 問題）
+3. **Git 合併**：手動解決 YAML 合併衝突（未來可改用 Git attributes）
+4. **效能**：大量任務（>1000）時掃描目錄較慢（未來可加索引）
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 主要變更 |
+|------|------|---------|
+| v3.3 | 2026-02-18 | 新增 `rigor` 欄位（嚴謹度） |
+| v3.6 | 2026-06-11 | Yggdrasil 共享任務編號（relay 配號 + lease + Lamport merge）；claim 保號 + hash 同卡判定 |
+| v3.2 | 2026-02-17 | 新增 `hash` (UUID)、`tags`、`actual_hours`、`branch` 欄位；簡化人員追蹤 |
+| v3.1 | 2026-02-15 | 使用 `js-yaml` 替代自訂解析器；原子性操作；狀態機驗證 |
+| v3.0 | 2026-02-10 | 首次發布「目錄即狀態」架構 |
+
+---
+
+## Yggdrasil 共享任務編號（v3.6, TASK_1610-1613）
+
+多機協作時，同一 team 的所有節點共享一條任務編號序列 — `TASK_1612` 對所有組員指同一張卡；solo 開發者（未啟用 Yggdrasil）的本地編號行為完全不變。
+
+**模式偵測**（三者皆成立才走共享模式）：`.kenaz/yggdrasil.yaml` 的 `enabled !== false` 且 `relay_url` 非空 且 `shared_task_ids !== false`（新增 key，預設視為 true；設 `shared_task_ids: false` 可在協作下保留本地編號）。
+
+**運作方式**：
+- `generateTaskID()` 從本地 lease 快取（`{tasksDir}/.id_lease.json`）消耗編號；耗盡時向 relay `POST /api/tasks/allocate-ids` 預租一段（預設 20 個）。
+- **Lamport merge**：要號請求帶 `local_max`（本地最大編號），relay 回 `max(relay_counter, local_max+1)` 起算的號段 — 節點首次加入 team 時，歷史 solo 編號自動墊高共享序列，永不重發。
+- **離線韌性**：3 秒總超時；relay 不可達且 lease 耗盡時退回本地 counter，任務標記 `id_alloc: local_fallback`。任務創建永不因 relay 阻塞。
+- **Claim 保號**：共享模式下從 Pool 認領任務保留原編號；只有真正的本地檔案碰撞才重編號（碰撞時先比對 `hash` 欄位 — 相同代表同一張卡返家，原地更新不重編）。重編號從 lease 消耗（counter 在共享模式下只記錄最後消耗的 lease 編號，不是配號權威）。
+- **Relay 端**：`id_counters` 表以 `(team_id, project)` 隔離，單一 transaction 內原子配號。
+
+**相關實作**：`task-api.js generateTaskID()/_allocateFromRelay()`、`dashboard/src/app/api/tasks/move/route.ts`（claim 路徑）、`yggdrasil-relay/src/routes/tasks.rs allocate_ids`（端點文檔見 `yggdrasil-relay/DESIGN.md`）。
+
+---
+
+## 參考連結
+
+- YAML 範例：`.collaboration/tasks/TASK_Example_{git_user}.yaml`
+- 舊系統文檔：`.system/pipeline/README.md`（待建立）
+- Formation 整合：`.formation/tools/loader.js:180-220`
+- Dashboard 整合：`dashboard/src-tauri/src/features/task/manager.rs`
+
+---
+
+*Generated by Dev Agent | 2026-02-18*