kenaz 0.3.21 → 0.3.23

package/core/.kenaz/main-memory/knowledge/patterns/002_scope_path_conflict.md

@@ -1,115 +0,0 @@
-# Scope Path Conflict - 任務路徑衝突檢測
-
-**記憶 ID**: knowledge/patterns/002
-**類型**: Best Practice
-**標籤**: #pipeline #parallelism #conflict-detection
-**建立時間**: 2026-02-10
-**適用於**: 所有使用 Kenaz AI Pipeline 的專案
-**規則來源**: PPL-111
-
----
-
-## 核心概念
-
-**路徑包含或被包含 = 衝突**
-
-在 Kenaz AI Pipeline 中，並行執行的任務必須檢查 `scope_paths` 是否衝突。
-
-## 衝突規則
-
-### 1. 完全相同
-
-```yaml
-TASK_A: scope_paths: ["CLAUDE.md"]
-TASK_B: scope_paths: ["CLAUDE.md"]
-```
-**結果**: ❌ 衝突（必須順序執行）
-
-### 2. 父目錄包含子目錄
-
-```yaml
-TASK_A: scope_paths: [".rule/pipeline/"]
-TASK_B: scope_paths: [".rule/pipeline/task-execution.yaml"]
-```
-**結果**: ❌ 衝突（B 的路徑在 A 的範圍內）
-
-### 3. 完全不同
-
-```yaml
-TASK_A: scope_paths: ["CLAUDE.md"]
-TASK_B: scope_paths: [".formation/tools/runner.js"]
-```
-**結果**: ✅ 無衝突（可並行執行）
-
-## 檢測方法
-
-```javascript
-function hasPathConflict(pathsA, pathsB) {
-  for (const pathA of pathsA) {
-    for (const pathB of pathsB) {
-      // 檢查包含關係
-      if (pathB.startsWith(pathA) || pathA.startsWith(pathB)) {
-        return true; // 衝突
-      }
-    }
-  }
-  return false; // 無衝突
-}
-```
-
-## 實際範例
-
-### 無衝突（可並行）
-
-```yaml
-TASK_148:
-  scope_paths: ["CLAUDE.md"]
-
-TASK_149:
-  scope_paths: [".formation/tools/runner.js"]
-```
-
-→ 可以同時執行
-
-### 有衝突（必須順序）
-
-```yaml
-TASK_147:
-  scope_paths: [".rule/pipeline/"]
-
-TASK_148:
-  scope_paths: [".rule/pipeline/task-execution.yaml"]
-```
-
-→ TASK_148 必須等 TASK_147 完成
-
-## 路徑鎖定系統
-
-Kenaz AI 使用路徑鎖定系統防止衝突：
-
-```json
-// dev/pipeline/LOCK_STATE.json
-{
-  "locks": {
-    ".rule/pipeline/": {
-      "taskId": "TASK_147",
-      "agentId": "developer_001",
-      "lockedAt": "2026-02-10T12:00:00Z"
-    }
-  }
-}
-```
-
-- 任務開始前檢查路徑鎖定
-- 完成後自動釋放鎖定
-- 防止並發修改
-
-## 相關規則
-
-- **PPL-111**: scope_paths 衝突檢測
-- **PPL-102**: 任務依賴分析
-
-## 參考文檔
-
-- `.rule/pipeline/task-execution.yaml` - 任務執行規範
-- `dev/pipeline/orchestrator/lock_manager.py` - 鎖定管理器

package/core/.kenaz/main-memory/knowledge/patterns/002_task_dependency_resolution.md

@@ -1,223 +0,0 @@
-# 任務依賴解析模式
-
-**ID**: KNZ-PATTERN-002
-**分類**: patterns
-**標籤**: #dependency-resolution #task-scheduling #dag
-
-## 概述
-
-任務依賴解析是一種確保任務按正確順序執行的模式，使用 DAG（有向無環圖）表示任務間的依賴關係。
-
-## 核心概念
-
-### 依賴類型
-
-#### 1. 強依賴（Must-Have）
-```yaml
-TASK_B:
-  dependencies: [TASK_A]  # TASK_B 必須等 TASK_A 完成
-```
-
-#### 2. 弱依賴（Nice-to-Have）
-```yaml
-TASK_B:
-  soft_dependencies: [TASK_A]  # TASK_A 完成更好，但非必須
-```
-
-#### 3. 路徑依賴（Conflict）
-```yaml
-TASK_A:
-  scope_paths: [".rule/pipeline/"]
-
-TASK_B:
-  scope_paths: [".rule/pipeline/task-execution.yaml"]
-  # 路徑衝突！必須順序執行
-```
-
-## 依賴圖結構
-
-### DAG 表示
-```
-TASK_A
-  ├─→ TASK_B
-  │     ├─→ TASK_D
-  │     └─→ TASK_E
-  └─→ TASK_C
-        └─→ TASK_E
-```
-
-### 拓撲排序
-**執行順序**：
-```
-Level 0: TASK_A
-Level 1: TASK_B, TASK_C (並行)
-Level 2: TASK_D, TASK_E (並行)
-```
-
-## 依賴解析算法
-
-### 算法步驟
-
-1. **建立依賴圖**
-```python
-graph = {}
-for task in tasks:
-    graph[task.id] = task.dependencies
-```
-
-2. **檢測循環依賴**
-```python
-def has_cycle(graph):
-    visited = set()
-    rec_stack = set()
-
-    for node in graph:
-        if detect_cycle(node, visited, rec_stack):
-            return True
-    return False
-```
-
-3. **拓撲排序**
-```python
-def topological_sort(graph):
-    in_degree = calculate_in_degree(graph)
-    queue = [node for node in graph if in_degree[node] == 0]
-    result = []
-
-    while queue:
-        node = queue.pop(0)
-        result.append(node)
-
-        for neighbor in graph[node]:
-            in_degree[neighbor] -= 1
-            if in_degree[neighbor] == 0:
-                queue.append(neighbor)
-
-    return result
-```
-
-4. **分層執行**
-```python
-levels = []
-current_level = get_ready_tasks()
-
-while current_level:
-    levels.append(current_level)
-    execute_parallel(current_level)
-    current_level = get_ready_tasks()
-```
-
-## 路徑衝突檢測
-
-### 衝突規則
-```python
-def has_path_conflict(task_a, task_b):
-    for path_a in task_a.scope_paths:
-        for path_b in task_b.scope_paths:
-            # 路徑包含或被包含 = 衝突
-            if is_subpath(path_a, path_b) or is_subpath(path_b, path_a):
-                return True
-    return False
-```
-
-### 範例
-```yaml
-# 無衝突（可並行）
-TASK_A: scope_paths: ["CLAUDE.md"]
-TASK_B: scope_paths: [".formation/tools/runner.js"]
-
-# 有衝突（必須順序執行）
-TASK_A: scope_paths: [".rule/pipeline/"]
-TASK_B: scope_paths: [".rule/pipeline/task-execution.yaml"]
-```
-
-## 執行策略
-
-### 策略 1：最大並行
-```
-盡可能並行執行無依賴的任務
-優點：最快完成
-缺點：資源消耗大
-```
-
-### 策略 2：保守執行
-```
-一次只執行一個任務
-優點：資源消耗小、易於調試
-缺點：耗時長
-```
-
-### 策略 3：限制並行數（推薦）
-```
-同時執行最多 N 個任務（如 N=3）
-優點：平衡速度和資源
-缺點：需要配置參數
-```
-
-## Kenaz AI 實現
-
-### 配置
-```yaml
-# dev/pipeline/PIPELINE_CONFIG.json
-{
-  "maxParallelTasks": 3,
-  "checkInterval": 30,
-  "dependencyResolution": "strict"
-}
-```
-
-### 使用
-```bash
-# 多 Agent 模式會自動解析依賴
-.\dev\scripts\START_MULTI_AGENT.bat
-```
-
-### 監控
-```bash
-# 查看當前執行狀態
-cat dev/pipeline/AGENT_STATE.json
-
-# 查看路徑鎖定狀態
-cat dev/pipeline/LOCK_STATE.json
-```
-
-## 錯誤處理
-
-### 循環依賴
-```
-TASK_A → TASK_B → TASK_C → TASK_A
-           ↑_______________|
-```
-
-**檢測**：
-```bash
-# 工具會自動檢測並報錯
-Error: Circular dependency detected: TASK_A → TASK_B → TASK_C → TASK_A
-```
-
-### 阻塞任務
-```
-TASK_B 依賴 TASK_A
-但 TASK_A 狀態為 blocked
-→ TASK_B 無法執行
-```
-
-**處理**：
-1. 識別阻塞原因
-2. 解決 TASK_A 的問題
-3. 更新狀態為 pending
-4. 自動重新調度
-
-## 最佳實踐
-
-1. ✅ **最小化依賴**：只定義必要的依賴
-2. ✅ **細粒度拆分**：任務粒度 15-20 分鐘
-3. ✅ **明確 scope_paths**：避免隱式衝突
-4. ✅ **定期檢查狀態**：監控阻塞任務
-5. ✅ **避免循環依賴**：設計前先畫依賴圖
-
-## 參考資料
-
-- `.rule/pipeline/task-execution.yaml` - PPL-102, PPL-111
-- `dev/pipeline/orchestrator/dependency_resolver.py` - 實現代碼
-- `CLAUDE.md` - Lead Agent 開發流程（Stage 5）

package/core/.kenaz/main-memory/knowledge/patterns/003_question_protocol.md

@@ -1,242 +0,0 @@
-# 問題規則：不猜測，一個一個問
-
-**ID**: K-PAT-005
-**分類**: patterns
-**標籤**: #communication #agent-behavior #workflow #best-practice
-
-## 概述
-
-當 Agent 遇到不確定的需求時，應遵循系統化的問題規則，而不是直接猜測。這是一個跨專案適用的通用溝通模式。
-
-## 核心規則
-
-### 規則 1：不要直接猜測
-當需求不明確時，主動發問而不是假設。
-
-**❌ 錯誤做法**：
-```
-Agent：「我假設您想要 X 方式，所以我實現了...」
-```
-
-**✅ 正確做法**：
-```
-Agent：「關於這個需求，有兩種可能的實現方式：
-A. 方式 X（優點...缺點...）
-B. 方式 Y（優點...缺點...）
-您希望選擇哪一種？」
-```
-
-### 規則 2：提供選項讓用戶選擇
-發問時應提供具體選項，而不是開放式問題。
-
-**❌ 錯誤做法**：
-```
-Agent：「您想要怎麼做？」
-```
-
-**✅ 正確做法**：
-```
-Agent：「請選擇架構方案：
-A. 單體架構（簡單快速）
-B. 微服務架構（可擴展）
-C. 模塊化單體（平衡）」
-```
-
-### 規則 3：有多個問題時，先說總數
-讓用戶知道問題的數量和進度。
-
-**❌ 錯誤做法**：
-```
-Agent：「問題：您要用 TypeScript 嗎？」
-用戶：「是」
-Agent：「問題：您要用 ESLint 嗎？」（用戶不知道還有多少問題）
-```
-
-**✅ 正確做法**：
-```
-Agent：「我有 3 個問題需要確認。
-
-問題 1/3：您要用 TypeScript 嗎？」
-用戶：「是」
-Agent：「✅ 收到。
-
-問題 2/3：您要用 ESLint 嗎？」
-```
-
-### 規則 4：一個一個問，等待回答後再繼續
-不要一次問多個問題，避免用戶混淆。
-
-**❌ 錯誤做法**：
-```
-Agent：「我有以下問題：
-1. 您要用 TypeScript 嗎？
-2. 您要用 ESLint 嗎？
-3. 您要用 Prettier 嗎？
-4. 您要用 Husky 嗎？
-5. 您要用 Lint-staged 嗎？」
-（用戶需要一次回答所有問題，容易遺漏）
-```
-
-**✅ 正確做法**：
-```
-Agent：「總共 5 個問題。
-
-問題 1/5：您要用 TypeScript 嗎？」
-用戶：「是」
-Agent：「✅ 收到。
-
-問題 2/5：您要用 ESLint 嗎？」
-（等待用戶回答後再繼續）
-```
-
-## 完整工作流程
-
-```
-Agent 遇到不確定需求
-         ↓
-    計算問題數量（N 個）
-         ↓
-告訴用戶：「總共 N 個問題」
-         ↓
-┌─────────────────────┐
-│  For i = 1 to N:    │
-│                     │
-│  1. 顯示「問題 i/N」│
-│  2. 提供選項（A/B/C）│
-│  3. 等待用戶回答    │
-│  4. 確認收到        │
-│                     │
-└─────────────────────┘
-         ↓
-   所有問題回答完畢
-         ↓
-    繼續執行任務
-```
-
-## 實際案例
-
-### 案例：Agent/User 數據結構設計（2026-02-11）
-
-**背景**：需要定義 Agent 和 User 的身份數據結構。
-
-**錯誤做法**：
-```
-Agent：「我假設 Agent 應該有 git_user 和 email 欄位...」
-（直接猜測，導致用戶糾正）
-```
-
-**正確做法**：
-```
-Agent：「關於 Agent 和 User 的數據結構，我有 5 個問題需要確認。
-
-問題 1/5：Agent 的身份欄位應該如何設計？
-A. 有 git_user/email（與 User 相同）
-B. 有 agent_id（專用欄位）
-C. 有 agent_id + role（帶角色資訊）⭐ 推薦
-
-您選擇哪個？」
-
-用戶：「C，然後 User 的 role 一律為 'user'」
-
-Agent：「✅ 收到。
-
-問題 2/5：Agent 需要 timestamp 欄位嗎？
-A. 需要
-B. 不需要
-
-您選擇哪個？」
-
-用戶：「A」
-
-Agent：「✅ 收到。
-
-問題 3/5：User 需要 is_agent 標記嗎？...」
-
-（依此類推，逐一確認）
-```
-
-**結果**：
-- 透過 5 個系統性問題逐一確認
-- 最終建立清晰的 Agent/User 數據結構規範
-- 避免了重複修改和猜測錯誤
-
-## 關鍵優勢
-
-1. **避免猜測錯誤**：減少返工和修改
-2. **用戶體驗好**：清楚知道進度和問題數量
-3. **系統化溝通**：結構化的問題流程
-4. **記錄決策**：每個選擇都有明確記錄
-5. **可追溯性**：方便回顧決策過程
-
-## 適用場景
-
-✅ **適合使用**：
-- 架構設計選擇（技術選型、設計模式）
-- 數據結構定義（欄位、類型、關係）
-- 配置參數確認（開關、參數、選項）
-- 多種實現方案（優劣權衡）
-- 用戶偏好設定（風格、習慣）
-
-❌ **不適合使用**：
-- 已有明確規範的標準操作
-- 用戶已提供詳細需求
-- 簡單的 Yes/No 單一問題
-- 緊急修復（需要快速響應）
-
-## 與其他模式的關係
-
-- **AGT-005**（失敗時必須查閱失敗經驗）：遇到不確定時，先查閱是否有相關失敗案例，再發問
-- **AskUserQuestion 工具**：Claude Code 提供的結構化問題工具，完美支援此模式
-- **Leader-Worker 模式**：Leader 在分派任務前，應使用此模式確認需求
-
-## 工具支援
-
-### Claude Code AskUserQuestion 工具
-
-Claude Code 提供的 `AskUserQuestion` 工具完美支援此模式：
-
-```javascript
-AskUserQuestion({
-  questions: [{
-    question: "您要使用哪種架構方案？",
-    header: "架構選擇",
-    options: [
-      {
-        label: "單體架構",
-        description: "簡單快速，適合小型專案"
-      },
-      {
-        label: "微服務架構",
-        description: "可擴展，適合大型系統"
-      },
-      {
-        label: "模塊化單體",
-        description: "平衡方案，易於升級"
-      }
-    ],
-    multiSelect: false
-  }]
-})
-```
-
-**特性**：
-- 結構化選項
-- 清晰的描述
-- 支援單選/多選
-- 自動提供「Other」選項
-
-## 參考資料
-
-- `.memory/tools/LEARNING_MECHANISM.md` - 學習機制文檔（包含此規則的建立過程）
-- `.collaboration/tasks/db/all/TASK_5KPEES80*.json` - 實際應用案例
-- `C:\Users\User\.claude\projects\D--repo-side-ava-KenazAI\memory\MEMORY.md` - 核心原則 #6
-
-## 版本歷史
-
-- **v1.0.0** (2026-02-11): 初始版本，基於 Agent/User 數據結構設計案例建立
-
----
-
-**建立日期**: 2026-02-11
-**維護者**: Kenaz AI Development Team
-**重要性**: ⭐⭐⭐⭐⭐ (核心原則)

package/core/.kenaz/main-memory/knowledge/patterns/004_user_insight_value.md

@@ -1,111 +0,0 @@
-# 用戶領域知識的價值
-
-**ID**: K-PAT-004
-**分類**: 通用協作模式
-**重要性**: ⭐⭐⭐⭐⭐（核心原則級別）
-**標籤**: `collaboration`, `user-communication`, `pragmatism`, `requirements`
-
----
-
-## 核心原則
-
-**用戶領域知識 > 技術細節**
-
-用戶對實際需求的理解往往比 Agent 的技術探索更有價值。一句關鍵的用戶建議可能立即解決 Agent 花費數小時仍無法突破的問題。
-
----
-
-## 實際案例
-
-### 問題場景
-在解決 .team 系統並行處理問題時，Agent 花費大量精力追求極短時間並發（< 5ms），試圖在 Windows 文件系統的競爭條件窗口內實現完美的原子操作。
-
-### 用戶洞察
-用戶的一句話立即解決了問題：
-
-> "那不要極短時間 我們可以 1-3秒 放一個團隊出發 我覺得是沒問題的"
-
-### 關鍵認知
-- 團隊任務通常需要幾分鐘執行時間
-- 幾秒的啟動間隔完全可以接受
-- 不需要追求技術上的極限優化
-
----
-
-## 核心教訓
-
-### 1. 優先詢問用戶實際需求
-在開始複雜的技術方案前，先問：
-- 實際使用場景是什麼？
-- 可接受的性能指標是什麼？
-- 有哪些約束條件可以放寬？
-
-### 2. 避免過度工程
-- 簡單有效的方案 > 技術完美但過度複雜的方案
-- 實用性 > 技術炫技
-- 滿足需求即可，不追求極限
-
-### 3. 用戶比 Agent 更了解業務邏輯
-- 用戶知道任務的實際執行時間
-- 用戶知道可接受的性能範圍
-- 用戶知道真正的痛點在哪裡
-
-### 4. 技術細節服務於實際需求
-- 技術方案應該基於實際需求設計
-- 不要為了技術而技術
-- 常識判斷往往比技術分析更有效
-
----
-
-## 實踐建議
-
-### Agent 工作流程
-```
-遇到技術難題
-  ↓
-詢問用戶：實際需求、性能要求、可接受約束
-  ↓
-基於用戶反饋設計方案
-  ↓
-優先簡單有效的方案
-  ↓
-避免過度優化
-```
-
-### 關鍵問題清單
-執行複雜任務前，問自己：
-1. ✅ 我是否詢問過用戶的實際需求？
-2. ✅ 我是否了解可接受的性能指標？
-3. ✅ 我是否在追求不必要的技術完美？
-4. ✅ 是否有更簡單的方案可以滿足需求？
-
----
-
-## 反面案例
-
-### ❌ 錯誤做法
-- 假設用戶需要極致性能
-- 花費大量時間優化不重要的指標
-- 沒有詢問用戶就做複雜的技術決策
-- 為了技術優雅犧牲實用性
-
-### ✅ 正確做法
-- 先詢問用戶實際需求和約束
-- 基於用戶反饋選擇技術方案
-- 優先實用性，技術優雅次之
-- 滿足需求即可，不過度優化
-
----
-
-## 相關記憶
-
-- `K-PAT-003`: 提問協議（003_question_protocol.md）
-- `K-PAT-002`: Leader-Worker 協作模式
-- `K-SOL-003`: Windows 文件系統競爭條件解決方案
-
----
-
-**建立日期**: 2026-02-11
-**來源**: TASK_TEST_PARALLEL_001/002 並行處理測試
-**重要性**: 5/5（核心原則）
-**適用範圍**: 所有 Agent 協作場景