kenaz 0.3.21 → 0.3.23

package/core/dev/pipeline/archived/TASK_167_llm_module_summary.yaml

@@ -1,55 +0,0 @@
-# TASK_167: LLM Module Summary 生成系統
-# Schema: dev/schemas/TASK.schema.json
-
-id: "TASK_167"
-title: "LLM Module Summary 生成系統"
-description: |
-  使用 LLM（Claude API）為每個目錄/模組自動生成 100-200 字摘要。
-  讓 Agent 先讀摘要再決定往哪裡深挖，避免「亂槍打鳥」式的向量檢索。
-
-  快取機制確保不重複調用 API，基於 Git hash 失效。
-
-priority: "P1"
-status: "pending"
-agent_type: "backend"
-source: "F-018"
-feature_ids:
-  - "F-018"
-
-dependencies:
-  - "TASK_164"
-
-scope_paths:
-  - "kenaz-cortex/src/cortex/summary/"
-  - "kenaz-cortex/src/cortex/config.py"
-
-requirements:
-  - "建立 kenaz-cortex/src/cortex/summary/ 模組"
-  - "建立 ModuleSummaryGenerator 類"
-  - "使用 Claude API（anthropic SDK）為每個目錄生成 100-200 字摘要"
-  - "輸入組裝：目錄下的 exports + 函數簽名 + docstrings + README（max 2000 tokens）"
-  - "快取機制：儲存在 .cortex/summaries/，key 為目錄路徑 + Git hash"
-  - "支援批量生成（全量）和單一模組更新（增量）"
-  - "在 config.py 新增 SummaryConfig 配置類"
-  - "API Key 從環境變數 ANTHROPIC_API_KEY 讀取"
-
-acceptance_criteria:
-  - "每個目錄能生成 100-200 字的功能描述"
-  - "快取命中時不調用 LLM API（0 成本）"
-  - "Git commit 後只更新有變更的目錄摘要"
-  - "摘要內容準確描述模組的核心功能和職責"
-  - "API Key 缺失時 graceful degradation（返回靜態摘要或空）"
-
-technical_notes:
-  - "使用 anthropic SDK，model 建議 claude-haiku-4-5-20251001（低成本）"
-  - "Prompt 設計：提供函數列表和 docstrings，要求生成模組功能摘要"
-  - "快取格式：.cortex/summaries/{dir_path_hash}.json"
-  - "Git hash 用 git rev-parse HEAD:{dir_path} 獲取"
-  - "批量生成時可並行調用 API（asyncio）"
-
-estimated_hours: 8
-complexity: "medium"
-
-metadata:
-  created_at: "2026-02-12T00:00:00+08:00"
-  created_by: "PM Lead"

package/core/dev/pipeline/archived/TASK_168_map_reduce_context.yaml

@@ -1,51 +0,0 @@
-# TASK_168: Map-Reduce Context 聚合模式
-# Schema: dev/schemas/TASK.schema.json
-
-id: "TASK_168"
-title: "Map-Reduce Context 聚合模式"
-description: |
-  當 Agent 需要理解「整個專案的邏輯」時，不要一次塞 50 個檔案。
-  先讓 Agent 針對每個文件/模組生成摘要（Map），再匯總為專案級概覽（Reduce）。
-
-  利用 TASK_167 的 Module Summary 快取，實現高效的全局理解。
-
-priority: "P2"
-status: "pending"
-agent_type: "backend"
-source: "F-018"
-feature_ids:
-  - "F-018"
-
-dependencies:
-  - "TASK_167"
-
-scope_paths:
-  - "kenaz-cortex/src/cortex/context/"
-  - "kenaz-cortex/src/cortex/mcp/server.py"
-
-requirements:
-  - "建立 MapReduceContext 類"
-  - "Map 階段：收集每個模組的摘要（複用 TASK_167 的快取）"
-  - "Reduce 階段：匯總所有摘要，生成專案級概覽（模組關係 + 職責 + 技術棧）"
-  - "新增 cortex_overview MCP 工具（或增強 cortex_context）"
-  - "自動判斷：當查詢是「全局理解」類型時觸發 Map-Reduce"
-  - "結果快取：專案級概覽按 Git HEAD hash 快取"
-
-acceptance_criteria:
-  - "50 個文件的專案能在 < 5 秒生成概覽（大部分使用快取）"
-  - "概覽包含各模組關係和職責描述"
-  - "快取命中率 > 80%"
-  - "MCP 工具可正常調用並返回結構化結果"
-
-technical_notes:
-  - "Map 階段使用 TASK_167 的 ModuleSummaryGenerator"
-  - "Reduce 階段可使用 LLM 或模板拼接"
-  - "快取 key：project_root + git_head_hash"
-  - "考慮 Reduce 結果的 token 上限（建議 2000-3000 tokens）"
-
-estimated_hours: 6
-complexity: "medium"
-
-metadata:
-  created_at: "2026-02-12T00:00:00+08:00"
-  created_by: "PM Lead"

package/core/dev/pipeline/archived/TASK_169_v2_integration_testing.yaml

@@ -1,52 +0,0 @@
-# TASK_169: V2 架構層整合 + 端到端測試
-# Schema: dev/schemas/TASK.schema.json
-
-id: "TASK_169"
-title: "V2 架構層整合 + 端到端測試"
-description: |
-  將 Symbol Index、Module Summary、Map-Reduce 三個新能力
-  整合到 V2 四層架構中，並進行端到端測試確保所有 MCP 工具正常。
-
-priority: "P1"
-status: "pending"
-agent_type: "backend"
-source: "F-018"
-feature_ids:
-  - "F-018"
-
-dependencies:
-  - "TASK_165"
-  - "TASK_166"
-  - "TASK_167"
-
-scope_paths:
-  - "kenaz-cortex/src/cortex/retrieval/architecture.py"
-  - "kenaz-cortex/src/cortex/retrieval/strategy.py"
-  - "kenaz-cortex/src/cortex/context/smart_switch.py"
-  - "kenaz-cortex/src/cortex/mcp/server.py"
-
-requirements:
-  - "Layer 2 (Architecture) 輸出加入 Symbol Index 概覽（Top-level 符號列表）"
-  - "cortex_context 輸出加入 Module Summaries（每個目錄一行摘要）"
-  - "V2 策略選擇器新增 SYMBOL_LOOKUP 任務類型"
-  - "端到端測試：連續調用所有 MCP 工具確認無 error"
-  - "更新 .cortex.yaml 配置以包含新功能開關"
-
-acceptance_criteria:
-  - "cortex_context 返回包含符號概覽 + 模組摘要"
-  - "cortex_search + cortex_symbols 互補工作（語義 + 精確）"
-  - "V2 策略自動選擇正確層組合"
-  - "所有 8 個 MCP 工具（原 6 + cortex_symbols + cortex_overview）無 error"
-  - "README.md 更新以反映新功能"
-
-technical_notes:
-  - "architecture.py 的 get_architecture_context() 需要整合 SymbolIndex"
-  - "strategy.py 的 TASK_TYPE_STRATEGIES 需要新增 SYMBOL_LOOKUP"
-  - "考慮向後相容：Symbol Index 和 Summary 都是可選的增強"
-
-estimated_hours: 4
-complexity: "medium"
-
-metadata:
-  created_at: "2026-02-12T00:00:00+08:00"
-  created_by: "PM Lead"

package/core/dev/pipeline/backups/archive_2026-02-04T22-07-22/TASK_QUEUE_backup.json

@@ -1,95 +0,0 @@
-{
-  "version": "1.0.0",
-  "tasks": [
-    {
-      "id": "TASK_083",
-      "title": "TASK_QUEUE 清理機制（移除已完成任務）",
-      "priority": "P0",
-      "status": "completed",
-      "agent_type": "developer",
-      "skill_path": ".claude/skills/developer/SKILL.md",
-      "source_file": "TASK_083_task_queue_cleanup.yaml",
-      "scope_paths": [
-        "dev/pipeline/TASK_QUEUE.json",
-        "dev/pipeline/PROGRESS.md",
-        "dev/scripts/"
-      ],
-      "dependencies": [
-        "TASK_080"
-      ]
-    },
-    {
-      "id": "TASK_084",
-      "title": "修復 Multi-Agent Scheduler 的任務同步邏輯",
-      "priority": "P0",
-      "status": "completed",
-      "agent_type": "backend",
-      "skill_path": ".claude/skills/backend_engineer/SKILL.md",
-      "source_file": "TASK_084_scheduler_sync_logic_fix.yaml",
-      "scope_paths": [
-        "dashboard/src-tauri/src/cmd_modules/scheduler/",
-        "dev/scripts/multi_agent_scheduler.ps1"
-      ],
-      "dependencies": [
-        "TASK_083"
-      ]
-    },
-    {
-      "id": "TASK_085",
-      "title": "整合 2/4-2/5 開發記憶點到 .memory/ 系統",
-      "priority": "P1",
-      "status": "completed",
-      "agent_type": "developer",
-      "skill_path": ".claude/skills/developer/SKILL.md",
-      "source_file": "TASK_085_memory_consolidation_0204_0205.yaml",
-      "scope_paths": [
-        ".memory/CONTEXT.md",
-        "C:/Users/User/.claude/projects/D--repo-side-ava-KenazAI/memory/MEMORY.md"
-      ],
-      "dependencies": []
-    },
-    {
-      "id": "TASK_086",
-      "title": "AgentCreateWizard 可摺疊大綱式預覽面板",
-      "priority": "P1",
-      "status": "completed",
-      "agent_type": "frontend",
-      "skill_path": ".claude/skills/frontend_agent/SKILL.md",
-      "source_file": "TASK_086_collapsible_preview_panel.yaml",
-      "scope_paths": [
-        "dashboard/src/components/agent-section/AgentCreateWizard.tsx",
-        "dashboard/src/components/agent-section/CollapsiblePreview.tsx"
-      ],
-      "dependencies": []
-    },
-    {
-      "id": "TASK_087",
-      "title": "建立手動記憶點封存指令（取代自動清理）",
-      "priority": "P0",
-      "status": "completed",
-      "agent_type": "developer",
-      "skill_path": ".claude/skills/developer/SKILL.md",
-      "source_file": "TASK_087_manual_memory_archival.yaml",
-      "scope_paths": [
-        "dev/scripts/",
-        "dashboard/src-tauri/src/cmd_modules/scheduler/",
-        ".claude/commands/"
-      ],
-      "dependencies": []
-    }
-  ],
-  "statistics": {
-    "total": 55,
-    "pending": 0,
-    "in_progress": 0,
-    "blocked": 0,
-    "completed": 5,
-    "cancelled": 0
-  },
-  "metadata": {
-    "created_at": "2026-02-05T05:27:20.2281213+08:00",
-    "source_spec": "dev/PRODUCT_SPEC.md"
-  },
-  "last_updated": "2026-02-04T22:06:04.445Z",
-  "project": "kenaz-dashboard"
-}

package/core/dev/pipeline/docs/multi-agent-coordination.md

@@ -1,446 +0,0 @@
----
-type: guide
-title: Multi-Agent Coordination Guide
-description: 多 Agent 並行開發協作機制與最佳實踐
-tags: [pipeline, multi-agent, coordination, parallel, locking]
-audience: developer
----
-
-# Multi-Agent Coordination Guide
-
-## 概述
-
-多 Agent 協作模式允許多個 Agent 並行執行不同任務，大幅提升開發效率。
-
-## 架構設計
-
-```
-Multi-Agent Scheduler
-    ↓
-分析 TASK_QUEUE → 找出無衝突任務組
-    ↓
-┌─────────────────┼─────────────────┐
-↓                 ↓                 ↓
-Feature Agent 1   Feature Agent 2   Feature Agent 3
-Branch: task/101  Branch: task/102  Branch: task/103
-Scope: api/       Scope: ui/        Scope: tests/
-TASK_101          TASK_102          TASK_103
-    ↓                 ↓                 ↓
-Commit & Merge    Commit & Merge    Commit & Merge
-```
-
-## 無衝突任務檢測
-
-### 衝突定義
-
-兩個任務衝突的條件：
-1. **Scope 重疊** - 修改相同或包含的路徑
-2. **依賴關係** - 一個任務依賴另一個
-3. **資源競爭** - 需要獨占同一資源
-
-### 衝突檢測算法
-
-```python
-def check_conflict(task_a, task_b):
-    # 1. 檢查 scope 重疊
-    if has_path_overlap(task_a.scope, task_b.scope):
-        return True
-
-    # 2. 檢查依賴關係
-    if task_b.id in task_a.dependencies:
-        return True
-    if task_a.id in task_b.dependencies:
-        return True
-
-    # 3. 檢查資源競爭
-    if has_resource_conflict(task_a, task_b):
-        return True
-
-    return False
-
-def has_path_overlap(paths_a, paths_b):
-    for path_a in paths_a:
-        for path_b in paths_b:
-            # 檢查包含關係
-            if path_a.startswith(path_b) or path_b.startswith(path_a):
-                return True
-            # 檢查相同路徑
-            if path_a == path_b:
-                return True
-    return False
-```
-
-### 範例
-
-```yaml
-# 無衝突（可並行）
-TASK_101:
-  scope: [src/api/auth/]
-
-TASK_102:
-  scope: [src/ui/login/]
-
-TASK_103:
-  scope: [tests/integration/]
-
-# 有衝突（不可並行）
-TASK_201:
-  scope: [src/api/]        # 包含 auth/
-
-TASK_202:
-  scope: [src/api/auth/]   # 被 api/ 包含
-```
-
-## 路徑鎖定機制
-
-### 鎖定模式
-
-```python
-class LockMode(Enum):
-    EXCLUSIVE = "exclusive"  # 排他性（寫入）
-    SHARED = "shared"        # 共享（只讀）
-```
-
-### 獲取鎖定
-
-```python
-from dev.pipeline.orchestrator.lock_manager import LockManager
-
-lock_mgr = LockManager()
-
-# 嘗試獲取排他鎖
-success = lock_mgr.acquire_lock(
-    path="src/api/auth/",
-    agent_id="agent_001",
-    task_id="TASK_101",
-    mode=LockMode.EXCLUSIVE
-)
-
-if success:
-    # 執行任務
-    execute_task("TASK_101")
-
-    # 釋放鎖定
-    lock_mgr.release_lock("src/api/auth/", "agent_001")
-else:
-    print("路徑已被鎖定，等待中...")
-```
-
-### 鎖定狀態
-
-`LOCK_STATE.json`:
-```json
-{
-  "src/api/auth/": {
-    "locked_by": "agent_001",
-    "task_id": "TASK_101",
-    "mode": "exclusive",
-    "locked_at": "2026-02-09T10:30:00Z"
-  },
-  "src/ui/": {
-    "locked_by": "agent_002",
-    "task_id": "TASK_102",
-    "mode": "exclusive",
-    "locked_at": "2026-02-09T10:31:00Z"
-  }
-}
-```
-
-### 自動釋放
-
-鎖定會在以下情況自動釋放：
-- 任務完成
-- 任務失敗
-- 超時（預設 4 小時）
-
-## Scheduler 調度策略
-
-### 1. 優先級排序
-
-```
-P0 (Critical) > P1 (High) > P2 (Medium) > P3 (Low)
-```
-
-### 2. 依賴解析
-
-```python
-from dev.pipeline.orchestrator.dependency_resolver import DependencyResolver
-
-resolver = DependencyResolver()
-
-# 獲取可執行的任務（依賴已滿足）
-ready_tasks = resolver.get_ready_tasks(pending_tasks)
-```
-
-### 3. 衝突檢測
-
-```python
-# 找出無衝突的任務組
-def find_non_conflicting_group(tasks, max_agents=3):
-    selected = []
-    for task in tasks:
-        # 檢查是否與已選擇的任務衝突
-        if not any(check_conflict(task, t) for t in selected):
-            selected.append(task)
-            if len(selected) >= max_agents:
-                break
-    return selected
-```
-
-### 完整調度流程
-
-```python
-def schedule_tasks(max_agents=3):
-    # 1. 載入任務佇列
-    queue = TaskQueue()
-    pending = queue.get_pending_tasks()
-
-    # 2. 依賴解析
-    resolver = DependencyResolver()
-    ready = resolver.get_ready_tasks(pending)
-
-    # 3. 優先級排序
-    sorted_tasks = sorted(ready, key=lambda t: t.priority)
-
-    # 4. 找出無衝突任務組
-    selected = find_non_conflicting_group(sorted_tasks, max_agents)
-
-    # 5. 分派任務
-    for task in selected:
-        assign_to_feature_agent(task)
-
-    return selected
-```
-
-## Agent 類型
-
-### Dev Agent (單一模式)
-
-```bash
-# 使用者調用
-/dev
-
-# 行為
-- 單一 Agent 執行
-- 順序處理任務
-- 直接在 main branch 工作
-- 適合簡單任務
-```
-
-### Feature Agent (並行模式)
-
-```bash
-# 系統調用
-.\dev\scripts\START_MULTI_AGENT.bat
-
-# 行為
-- 多 Agent 並行執行
-- 各自獨立 branch
-- 自動合併到 main
-- 適合複雜專案
-```
-
-### 比較
-
-| 特性 | Dev Agent | Feature Agent |
-|------|-----------|---------------|
-| 並行數量 | 1 | 1-5 |
-| Branch 隔離 | 否 | 是 |
-| 路徑鎖定 | 不需要 | 需要 |
-| 適用場景 | 單任務、學習 | 多任務、生產 |
-| 執行速度 | 慢 | 快 (3倍) |
-
-## Git Branch 策略
-
-### Branch 命名
-
-```
-task/{task_id}-{slug}
-
-範例:
-task/101-auth-api
-task/102-login-ui
-task/103-auth-tests
-```
-
-### 工作流程
-
-```bash
-# Feature Agent 1
-git checkout -b task/101-auth-api
-# 開發...
-git commit -m "[TASK_101] 實現認證 API"
-git checkout main
-git merge task/101-auth-api
-git branch -d task/101-auth-api
-
-# Feature Agent 2 (並行)
-git checkout -b task/102-login-ui
-# 開發...
-git commit -m "[TASK_102] 建立登入 UI"
-git checkout main
-git merge task/102-login-ui
-git branch -d task/102-login-ui
-```
-
-### 衝突解決
-
-如果合併時發生衝突：
-1. **自動解決** - 使用 Git 的自動合併
-2. **手動介入** - 標記任務為 blocked，通知用戶
-3. **重新排程** - 將衝突任務延後執行
-
-## Agent 狀態管理
-
-### AGENT_STATE.json
-
-```json
-{
-  "active_agents": [
-    {
-      "id": "agent_001",
-      "type": "feature_agent",
-      "task_id": "TASK_101",
-      "branch": "task/101-auth-api",
-      "started_at": "2026-02-09T10:30:00Z",
-      "status": "running"
-    },
-    {
-      "id": "agent_002",
-      "type": "feature_agent",
-      "task_id": "TASK_102",
-      "branch": "task/102-login-ui",
-      "started_at": "2026-02-09T10:31:00Z",
-      "status": "running"
-    }
-  ],
-  "max_agents": 3,
-  "updated_at": "2026-02-09T10:31:00Z"
-}
-```
-
-### 狀態監控
-
-```python
-from dev.pipeline.orchestrator.agent_assigner import AgentAssigner
-
-assigner = AgentAssigner()
-
-# 獲取活躍 Agent 數量
-active_count = assigner.get_active_agent_count()
-
-# 檢查是否可以分派新任務
-can_assign = active_count < assigner.max_agents
-
-# 獲取 Agent 狀態
-agents = assigner.get_active_agents()
-for agent in agents:
-    print(f"{agent['id']}: {agent['task_id']} ({agent['status']})")
-```
-
-## 成本控制
-
-### 並行數量限制
-
-```yaml
-# PIPELINE_CONFIG.json - cost_control
-cost_control:
-  enabled: true
-  max_parallel_agents: 3
-  token_budget_per_task: 100000
-```
-
-### 動態調整
-
-```python
-# 根據任務複雜度調整並行數量
-def calculate_max_agents(task_complexity):
-    if task_complexity == "high":
-        return 2  # 複雜任務用較少 Agent
-    elif task_complexity == "medium":
-        return 3
-    else:
-        return 5  # 簡單任務可以多並行
-```
-
-## 最佳實踐
-
-### ✅ 推薦
-
-1. **明確的 Scope** - 確保任務 scope 不重疊
-2. **合理拆分** - 任務大小適中（2-4 小時）
-3. **依賴最小化** - 減少任務間依賴
-4. **定期合併** - 避免 branch 過時
-5. **監控狀態** - 追蹤 Agent 執行情況
-
-### ❌ 避免
-
-1. **過度並行** - 超過 5 個 Agent 會降低效率
-2. **Scope 過大** - 單一任務影響太多文件
-3. **忽略依賴** - 導致執行順序錯誤
-4. **長時間 branch** - 增加合併衝突風險
-
-## 效能對比
-
-### 單 Agent vs 多 Agent
-
-| 場景 | 單 Agent | 3 Agent 並行 |
-|------|---------|--------------|
-| 10 個獨立任務 | 150 分鐘 | 50-60 分鐘 |
-| 複雜任務（有依賴） | 120 分鐘 | 80-90 分鐘 |
-| 緊急修復 | 15 分鐘 | 15 分鐘（無優勢） |
-
-### 建議
-
-- **< 3 個任務** - 使用單 Agent
-- **3-10 個任務** - 使用 3 Agent 並行
-- **> 10 個任務** - 使用 5 Agent 並行
-- **緊急任務** - 使用單 Agent（更快啟動）
-
-## 故障排查
-
-### Agent 卡住
-
-**症狀**: Agent 長時間無回應
-
-**檢查**:
-```bash
-cat dev/pipeline/AGENT_STATE.json
-```
-
-**解決**:
-1. 手動停止 Agent
-2. 釋放路徑鎖定
-3. 重新分派任務
-
-### 路徑鎖定死鎖
-
-**症狀**: 多個任務互相等待
-
-**檢查**:
-```bash
-cat dev/pipeline/LOCK_STATE.json
-```
-
-**解決**:
-1. 強制釋放超時鎖定
-2. 調整任務順序
-3. 拆分衝突任務
-
-### 合併衝突
-
-**症狀**: Git merge 失敗
-
-**解決**:
-```bash
-# 手動解決衝突
-git checkout main
-git merge task/101-auth-api
-# 解決衝突...
-git commit
-```
-
----
-
-**建立日期**: 2026-02-09
-**維護者**: Developer Team