kenaz 0.3.22 → 0.3.24

package/core/.kenaz/main-memory/kenaz/memory-system/001_three_tier_architecture.md

@@ -1,361 +0,0 @@
-# Kenaz AI 三層記憶架構
-
-**ID**: KZ-MEM-001
-**分類**: Kenaz 系統專屬 - 記憶系統
-**重要性**: ⭐⭐⭐⭐⭐（核心原則級別）
-**標籤**: `memory-system`, `architecture`, `meta-learning`, `project-structure`
-
----
-
-## 核心概念
-
-Kenaz AI 使用**三層記憶架構**，不同層級的記憶有不同的用途、壽命和權限。
-
-**關鍵原則**：優先級高的記憶會覆蓋優先級低的記憶。
-
----
-
-## 三層記憶架構
-
-```
-┌─────────────────────────────────────────┐
-│ 1. 專案記憶 (.memory/)                  │  ← 最高優先級
-│    - 專案專屬                          │
-│    - 短期、易變                        │
-│    - Agent 可自動更新                  │
-├─────────────────────────────────────────┤
-│ 2. 主記憶 (.kenaz/main-memory/) ⭐      │  ← 中等優先級
-│    - 跨專案共享                        │
-│    - 長期、穩定                        │
-│    - 僅開發者手動更新                  │
-├─────────────────────────────────────────┤
-│ 3. 系統預設 (Claude Code 內建)         │  ← 最低優先級
-│    - 全局                              │
-│    - 最穩定                            │
-│    - 不可更新                          │
-└─────────────────────────────────────────┘
-```
-
----
-
-## 層級 1：專案記憶 (.memory/)
-
-### 特性
-- **路徑**：`.memory/`（專案根目錄）
-- **範圍**：當前專案專屬
-- **壽命**：短期、易變（隨專案開發而變化）
-- **權限**：Agent 可自動更新、開發者可手動更新
-
-### 用途
-- 專案當前狀態（Context、Progress）
-- 階段性記憶（某個功能開發過程）
-- 臨時決策記錄
-- 專案特定的失敗經驗
-
-### 典型文件
-```
-.memory/
-├── CONTEXT.md              # 專案當前狀態
-├── INDEX.md                # 記憶索引
-├── registry.json           # 記憶註冊表
-├── patterns/               # 專案特定模式
-├── insights/               # 專案洞察
-├── failures/               # 專案失敗記錄
-└── decisions/              # 專案決策記錄
-```
-
-### 特點
-- ✅ 可以隨時修改（反映專案最新狀態）
-- ✅ Agent 自動記錄重要事件
-- ⚠️ 不適合長期知識（應提升到主記憶）
-
----
-
-## 層級 2：主記憶 (.kenaz/main-memory/) ⭐
-
-### 特性
-- **路徑**：`.kenaz/main-memory/`（專案內，但獨立子目錄）
-- **範圍**：跨專案共享（所有 Kenaz AI 專案）
-- **壽命**：長期、穩定（核心知識庫）
-- **權限**：僅開發者手動更新（避免知識污染）
-
-### 用途
-- 通用軟體開發知識（patterns, solutions, references）
-- Kenaz 系統專屬知識（team-system, pipeline, rules, cortex）
-- 核心原則和最佳實踐
-- 已驗證的問題解決方案
-
-### 目錄結構
-```
-.kenaz/main-memory/
-├── README.md               # 主記憶系統說明
-├── registry.json           # 主記憶索引（29 條記憶）
-├── version.yaml            # 版本與變更日誌
-│
-├── knowledge/              # 通用知識
-│   ├── patterns/           # 設計模式、最佳實踐
-│   ├── solutions/          # 問題解決方案
-│   └── references/         # 技術參考文檔
-│
-└── kenaz/                  # Kenaz 系統專屬
-    ├── pipeline/           # 開發流程知識
-    ├── rules/              # 規則系統知識
-    ├── cortex/             # RAG 引擎知識
-    └── memory-system/      # 記憶系統知識（本文件）
-```
-
-### 特點
-- ✅ 長期穩定（只在驗證後才加入）
-- ✅ 跨專案共享（避免重複學習）
-- ✅ 整合 Cortex RAG 引擎（自動查詢）
-- ❌ Agent 不可自動修改（防止污染）
-
----
-
-## 層級 3：系統預設 (Claude Code 內建)
-
-### 特性
-- **路徑**：Claude Code 內建（不在專案內）
-- **範圍**：全局（所有 Claude Code 用戶）
-- **壽命**：最穩定（Anthropic 維護）
-- **權限**：不可更新（由 Claude Code 團隊管理）
-
-### 用途
-- Claude Code 基本功能說明
-- 通用程式設計知識
-- 標準工具使用指南
-
-### 特點
-- ✅ 最權威（Anthropic 官方維護）
-- ✅ 最穩定（很少變動）
-- ❌ 不可客製化
-
----
-
-## 優先級繼承機制
-
-### 查詢順序
-```
-Agent 需要某個知識
-  ↓
-1. 先查專案記憶 (.memory/)
-   ↓ 找到 → 使用
-   ↓ 未找到
-2. 再查主記憶 (.kenaz/main-memory/)
-   ↓ 找到 → 使用
-   ↓ 未找到
-3. 最後查系統預設
-   ↓ 找到 → 使用
-   ↓ 未找到
-4. 無相關知識
-```
-
-### 覆蓋規則
-當多個層級包含相同主題的記憶時：
-- **專案記憶覆蓋主記憶** - 例如：專案特定的命名規則覆蓋通用規則
-- **主記憶覆蓋系統預設** - 例如：Kenaz 特定的工作流程覆蓋通用流程
-
----
-
-## 如何找到主記憶系統？⭐
-
-### 常見錯誤（避免）
-
-#### ❌ 錯誤 1：猜測路徑
-```bash
-# 錯誤：猜測在 Claude Code 配置目錄
-C:\Users\User\.claude\projects\{project}\memory\
-# 結果：空目錄，不是主記憶
-```
-
-#### ❌ 錯誤 2：認為 .memory/ 就是主記憶
-```bash
-# 錯誤：認為專案記憶就是主記憶
-.memory/CONTEXT.md
-# 結果：這是專案記憶（短期），不是主記憶（長期）
-```
-
-#### ❌ 錯誤 3：不知道 .kenaz/ 目錄的存在
-```bash
-# 錯誤：沒有意識到 .kenaz/ 是 Kenaz 系統核心
-# 結果：找不到主記憶、RAG 配置等核心文件
-```
-
----
-
-### ✅ 正確方法：系統性搜尋
-
-#### Step 1：全局搜尋專案內記憶相關目錄
-```bash
-find . -type d \( -name "*memory*" -o -name "*kenaz*" \) 2>/dev/null
-```
-
-**預期輸出**：
-```
-./.memory          # 專案記憶
-./.kenaz           # Kenaz 系統核心
-./.kenaz/main-memory  # ⭐ 主記憶（這就是！）
-```
-
-#### Step 2：檢查 README 文件
-```bash
-# 主記憶的 README 會清楚說明這是跨專案共享知識庫
-cat .kenaz/main-memory/README.md
-```
-
-#### Step 3：驗證目錄結構
-```bash
-ls -la .kenaz/main-memory/
-```
-
-**應該看到**：
-```
-README.md          # 主記憶說明
-registry.json      # 記憶索引
-version.yaml       # 版本控制
-knowledge/         # 通用知識
-kenaz/             # Kenaz 專屬知識
-```
-
----
-
-## 專案結構意識 ⭐
-
-### Kenaz AI 核心目錄
-
-```
-專案根目錄/
-├── .claude/          # Claude Code Skills（斜線指令）
-├── .agents/          # 外部安裝的 Skills
-├── .memory/          # 專案記憶（短期） 📝
-├── .kenaz/           # Kenaz 系統核心 🎯
-│   ├── main-memory/  # 主記憶（長期） ⭐⭐⭐
-│   ├── cortex.yaml   # RAG 引擎配置
-│   └── docs/         # 系統文檔
-├── .rule/            # 專案規則庫
-├── .failure/         # 失敗學習系統
-├── .formation/       # Formation 多 Agent 協作系統
-├── dev/              # 開發流程（Pipeline, PRODUCT_SPEC）
-└── dashboard/        # Kenaz Dashboard（如果有）
-```
-
-**關鍵認知**：
-- `.kenaz/` 是 Kenaz AI 的核心目錄
-- `.kenaz/main-memory/` 是主記憶系統
-- 其他以 `.` 開頭的目錄也都很重要
-
----
-
-## 實際案例：找不到主記憶的問題
-
-### 問題場景
-Agent 被要求"更新主記憶"，但找不到正確的位置。
-
-### 錯誤路徑
-1. 嘗試 `C:\Users\User\.claude\projects\{project}\memory\` ❌
-   - 這是 Claude Code 的專案配置目錄（空的）
-2. 嘗試 `.memory/CONTEXT.md` ❌
-   - 這是專案記憶（短期），不是主記憶（長期）
-3. 嘗試訪問 `$HOME/.claude/...` ❌
-   - 被 AGT-007 規則阻止（不應訪問用戶私有配置）
-
-### 正確路徑
-```bash
-# 系統性搜尋
-find . -type d -name "*memory*"
-# 找到 .kenaz/main-memory/ ✅
-
-# 驗證
-cat .kenaz/main-memory/README.md
-# 確認這是"Kenaz AI 主記憶系統 - 跨專案共享的核心知識庫" ✅
-```
-
-### 根本原因
-- **缺乏專案結構意識** - 不知道 `.kenaz/` 目錄的存在
-- **沒有系統性搜尋** - 直接猜測路徑而不是搜尋
-- **混淆不同的記憶系統** - 把專案記憶、主記憶、系統預設混為一談
-
----
-
-## Agent 工作流程
-
-### 讀取記憶
-```bash
-# Agent 啟動時自動執行（透過 Cortex RAG）
-cortex_search(query="主題關鍵詞", scope=["project", "main", "system"])
-```
-
-### 更新記憶
-
-#### 更新專案記憶（Agent 可執行）
-```bash
-node .memory/tools/memory-tools.js add \
-  --type pattern \
-  --title "新學到的模式" \
-  --summary "詳細描述" \
-  --importance 3
-```
-
-#### 更新主記憶（僅開發者手動）
-```bash
-# 1. 創建 Markdown 文件
-touch .kenaz/main-memory/knowledge/patterns/008_new_pattern.md
-
-# 2. 撰寫內容（包含 ID, 標籤, 描述, 範例）
-
-# 3. 更新 registry.json 索引
-
-# 4. 更新 version.yaml 變更日誌
-
-# 5. Git commit
-```
-
----
-
-## 檢查清單
-
-### 🔍 找到主記憶
-- [ ] 知道主記憶路徑是 `.kenaz/main-memory/`
-- [ ] 知道專案記憶路徑是 `.memory/`
-- [ ] 理解兩者的區別（短期 vs 長期）
-- [ ] 能夠使用 `find` 命令搜尋記憶目錄
-
-### 📖 理解記憶架構
-- [ ] 理解三層記憶架構（專案、主記憶、系統預設）
-- [ ] 理解優先級繼承機制
-- [ ] 知道什麼知識應該放在哪一層
-
-### ✏️ 更新記憶
-- [ ] 知道專案記憶可以自動更新
-- [ ] 知道主記憶只能手動更新
-- [ ] 知道如何更新 registry.json
-- [ ] 知道如何更新 version.yaml
-
----
-
-## 相關記憶
-
-- `KZ-CTX-001`: RAG 引擎系統概覽
-- `KZ-CTX-002`: Cortex 知識檢索系統
-- `KZ-RULE-002`: GEN-007 專案自包含原則
-- `K-PAT-004`: 用戶領域知識的價值
-
----
-
-## 關鍵教訓
-
-1. **不要猜測路徑** - 使用 `find` 命令全局搜尋
-2. **先搜尋專案內** - 遵循 GEN-007 規則（專案自包含）
-3. **建立專案結構意識** - 特別注意以 `.` 開頭的隱藏目錄
-4. **遇到歧義時立即詢問** - 不要浪費時間在錯誤的路徑上
-5. **閱讀 README** - 幾乎所有目錄都有 README 說明用途
-6. **理解記憶層次** - 專案記憶 ≠ 主記憶 ≠ 系統預設
-
----
-
-**建立日期**: 2026-02-11
-**來源**: 主記憶更新過程中的實際經驗
-**重要性**: 5/5（核心原則）
-**狀態**: ✅ Production Ready
-
-**這是 meta-learning（關於學習本身的學習）**：每個 Agent 都應該首先閱讀此記憶，理解 Kenaz AI 的記憶系統架構。

package/core/.kenaz/main-memory/kenaz/pipeline/001_task_execution_flow.md

@@ -1,117 +0,0 @@
-# 任務執行流程
-
-**ID**: KNZ-PIPELINE-001
-**分類**: pipeline
-**標籤**: #task-execution #12-steps #lead-workflow
-
-## 核心概念
-
-Lead Agent 執行任務時遵循標準化的 12 步流程。
-
-## 完整 12 步流程
-
-參考規則：`.rule/pipeline/task-execution.yaml`（PPL-101 至 PPL-112）
-
-### Stage 1-3: 需求分析與拆分
-
-#### 1. 接收用戶需求
-- 讀取用戶輸入或 Feature 文檔（如 `F-XXX.md`）
-- 理解功能範圍、目標、限制條件
-- 確認是新功能開發、Bug 修復還是重構
-
-#### 2. 自動分配 Feature ID（PPL-106）
-- 為新功能分配唯一 ID：`F-XXX`（3 位數字）
-- 檢查現有 Feature ID，避免重複
-- 記錄 Feature 概述到 `dev/features/F-XXX.md`（可選）
-
-#### 3. 拆分任務（PPL-101）
-**粒度標準**：每個任務 15-20 分鐘可完成
-
-**拆分原則**：
-- 一個任務 = 一個功能點/組件/API/文檔
-- 避免過大（> 1 小時）或過小（< 5 分鐘）
-- 每個任務必須有明確的驗收標準
-
-**任務 ID**：`TASK_XXX`（遞增數字）
-
-### Stage 4-6: 執行規劃
-
-#### 4. 判斷 agent_type（PPL-104, PPL-105）
-**Team 優先原則**：預設使用 `xxx_team`
-
-**使用單一 Agent 的情況**：
-- 極簡單任務（< 10 分鐘，如文檔小修改）
-- 不需要多角色分工的任務
-
-**命名規範**：
-- Team: `developer_team`, `backend_team`（底線 + _team）
-- 單一: `developer`, `backend`
-
-#### 5. 分析依賴與路徑衝突（PPL-102, PPL-111）
-**依賴分析**：
-- 識別任務間的依賴關係
-- 記錄到 `dependencies: []`
-
-**路徑衝突檢測**：
-- 定義每個任務的 `scope_paths: []`
-- 檢查並行任務的路徑是否重疊
-- **衝突規則**：路徑包含或被包含 = 衝突
-
-#### 6. 規劃 commit 策略（PPL-109）
-- **階段性 Commit**：每完成一個階段建立一次
-- **Commit Message 格式**：`[TASK_XXX] 簡短描述`
-- **最低要求**：每個任務至少 1 個 commit
-
-### Stage 7-9: 展示計劃與執行
-
-#### 7. 展示計劃給用戶（PPL-107 ⭐ 關鍵步驟）
-**必須包含**：
-- 所有任務列表（ID、標題、優先級）
-- 預估執行時間
-- 並行執行策略
-- 依賴關係圖
-
-#### 8. 等待用戶確認
-- 停止執行，等待用戶回應
-- 接受用戶的修改建議
-- 確認後再進入下一階段
-
-#### 9. 建立任務卡（YAML 格式）
-為每個任務建立 `dev/pipeline/tasks/TASK_XXX_<slug>.yaml`
-
-### Stage 10-12: 執行與監控
-
-#### 10. 啟動執行
-使用 Formation 系統啟動執行。
-
-**並行執行**：同時啟動多個無衝突的任務
-
-#### 11. 監控與自動化（PPL-110）
-- 檢查執行狀態
-- 自動更新 TASK_QUEUE.json
-- 自動解除被阻塞的任務
-- 自動啟動下一個可執行任務
-
-#### 12. 失敗處理（PPL-108）
-**Worker Agent 職責**：
-- 失敗時立即停止
-- 記錄失敗原因到日誌
-- 更新任務狀態為 `blocked`
-
-**Leader Agent 職責**：
-- 檢測到失敗後暫停後續任務
-- 分析失敗原因
-- 決定是重試、跳過還是調整計劃
-
-## 關鍵規則引用
-
-- **PPL-101**: 任務拆分粒度標準（15-20 分鐘）
-- **PPL-104**: Team 優先原則
-- **PPL-107**: 工作啟動前展示計劃（必須）
-- **PPL-111**: scope_paths 衝突檢測
-- **PPL-112**: 驗收標準驗證
-
-## 參考資料
-
-- `.rule/pipeline/task-execution.yaml` - 完整規則定義
-- `CLAUDE.md` - Lead Agent 開發流程章節

package/core/.kenaz/main-memory/kenaz/pipeline/001_task_granularity.md

@@ -1,154 +0,0 @@
-# Task Granularity - 任務拆分粒度標準
-
-**記憶 ID**: kenaz/pipeline/001
-**類型**: Best Practice
-**標籤**: #pipeline #task-management #kenaz-ai #ppl-101
-**建立時間**: 2026-02-10
-**適用於**: 所有使用 Kenaz AI 的專案
-**規則來源**: PPL-101
-
----
-
-## 核心原則
-
-**每個任務應該在 15-20 分鐘內可完成**
-
-這是 Kenaz AI Pipeline 系統的任務拆分標準，確保任務可管理、可追蹤、可並行。
-
-## 拆分標準
-
-### 理想粒度
-
-- ✅ **15-20 分鐘**：理想的任務大小
-- ⚠️ **20-30 分鐘**：可接受，但優先考慮拆分
-- ❌ **> 30 分鐘**：必須拆分成多個子任務
-- ❌ **< 5 分鐘**：太瑣碎，考慮合併
-
-### 拆分原則
-
-**一個任務 = 一個功能點/組件/API/文檔**
-
-**範例**：
-
-**❌ 過大任務**（2 小時）：
-```yaml
-id: TASK_001
-title: "實現用戶認證系統"
-estimated_hours: 2
-```
-
-**✅ 正確拆分**（4 個任務，各 30 分鐘）：
-```yaml
-id: TASK_001
-title: "設計認證 API 接口"
-estimated_hours: 0.5
-
-id: TASK_002
-title: "實現 JWT Token 生成與驗證"
-estimated_hours: 0.5
-
-id: TASK_003
-title: "建立認證中介層（Middleware）"
-estimated_hours: 0.5
-
-id: TASK_004
-title: "撰寫認證 API 測試與文檔"
-estimated_hours: 0.5
-```
-
-## 實際範例
-
-### 範例 1: 搜尋功能改進
-
-**功能**：改進統一文檔系統的搜尋功能
-
-**拆分結果**：
-```yaml
-TASK_151:
-  title: "分析當前搜尋邏輯缺陷"
-  estimated_hours: 0.25  # 15 分鐘
-
-TASK_152:
-  title: "設計規則 ID 搜尋方案"
-  estimated_hours: 0.33  # 20 分鐘
-
-TASK_153:
-  title: "實現 YAML 深度解析"
-  estimated_hours: 0.42  # 25 分鐘
-
-TASK_154:
-  title: "更新搜尋 API"
-  estimated_hours: 0.33  # 20 分鐘
-
-TASK_155:
-  title: "建立測試案例"
-  estimated_hours: 0.25  # 15 分鐘
-```
-
-### 範例 2: 記憶系統建立
-
-**功能**：建立雙層記憶系統
-
-**拆分結果**：
-```yaml
-TASK_158:
-  title: "記憶系統基礎架構 - 目錄結構與 Schema"
-  estimated_hours: 2  # 特殊情況：架構設計任務
-
-TASK_159:
-  title: "專案記憶系統 - CLI 工具與查詢接口"
-  estimated_hours: 4  # 特殊情況：工具開發
-
-TASK_160:
-  title: "記憶系統整合 - Git Hooks 與 RAG 同步"
-  estimated_hours: 3  # 特殊情況：系統整合
-
-TASK_161:
-  title: "主記憶系統 - 文檔撰寫與 CLI 整合"
-  estimated_hours: 6  # 特殊情況：知識庫建立
-```
-
-**注意**：架構設計類任務可以超過 20 分鐘，但仍需明確範圍。
-
-## 判斷標準
-
-### 何時需要拆分？
-
-**檢查清單**：
-- [ ] 任務涉及多個文件/模組？
-- [ ] 任務包含多個子步驟？
-- [ ] 預估時間 > 30 分鐘？
-- [ ] 需要等待外部資源？
-- [ ] 可以拆分成獨立可測試的部分？
-
-如果有 2 個以上「是」，考慮拆分。
-
-### 何時可以合併？
-
-**檢查清單**：
-- [ ] 多個任務修改同一文件？
-- [ ] 多個任務高度相關？
-- [ ] 單個任務 < 5 分鐘？
-- [ ] 無法獨立測試？
-
-如果有 2 個以上「是」，考慮合併。
-
-## 拆分的好處
-
-1. **可並行**：小任務更容易並行執行
-2. **可追蹤**：每個任務獨立追蹤進度
-3. **可恢復**：失敗時只需重試單一任務
-4. **可驗證**：每個任務獨立驗收
-5. **可估算**：預估時間更準確
-
-## 相關規則
-
-- **PPL-101**: 任務拆分粒度標準（本文檔）
-- **PPL-102**: 任務依賴分析
-- **PPL-111**: scope_paths 衝突檢測
-- **PPL-107**: 工作啟動前展示計劃
-
-## 參考文檔
-
-- `.rule/pipeline/task-execution.yaml` - Pipeline 任務執行規範
-- `CLAUDE.md` - Lead Agent 開發流程

package/core/.kenaz/main-memory/kenaz/pipeline/002_team_priority.md

@@ -1,51 +0,0 @@
-# Team Priority - Team 優先原則
-
-**記憶 ID**: kenaz/pipeline/002
-**類型**: Best Practice
-**標籤**: #pipeline #team-selection #ppl-104
-**建立時間**: 2026-02-10
-**規則來源**: PPL-104
-
----
-
-## 核心原則
-
-**預設使用 Team 模式**（`xxx_team`），而非單一 Agent。
-
-## 選擇標準
-
-### 使用 Team 模式
-
-- ✅ 複雜任務需要多角色分工
-- ✅ 需要專業審查（安全、性能、文檔）
-- ✅ 任務預估 > 2 小時
-- ✅ 影響多個模組/組件
-
-### 使用單一 Agent
-
-- ✅ 極簡單任務（< 10 分鐘）
-- ✅ 文檔小修改
-- ✅ 不需要多角色分工
-
-## 命名規範
-
-- **Team**: `developer_team`, `backend_team`, `qa_team`（底線 + _team）
-- **單一**: `developer`, `backend`, `qa`
-
-## 範例
-
-```yaml
-# Team 模式（推薦）
-TASK_148:
-  agent_type: "developer_team"
-  complexity: "medium"
-
-# 單一 Agent（極簡單任務）
-TASK_149:
-  agent_type: "developer"
-  complexity: "trivial"
-```
-
-## 參考
-
-- `.rule/pipeline/task-execution.yaml` - PPL-104