kenaz 0.3.22 → 0.3.23

package/core/.kenaz/main-memory/knowledge/patterns/005_file_lock_pattern.md

@@ -1,274 +0,0 @@
-# 文件鎖模式（並發寫入保護）
-
-**ID**: K-PAT-005
-**分類**: 通用技術模式
-**重要性**: ⭐⭐⭐⭐
-**標籤**: `concurrency`, `file-lock`, `async-await`, `nodejs`, `windows`
-
----
-
-## 問題描述
-
-多個進程並發寫入同一文件時，會發生競爭條件（Race Condition），導致：
-- 數據損壞（部分寫入）
-- 數據丟失（覆蓋寫入）
-- 不一致狀態（讀取-修改-寫入衝突）
-
----
-
-## 解決方案：文件鎖模式
-
-### 核心概念
-使用鎖文件（Lock File）確保同一時間只有一個進程可以修改目標文件。
-
-### 實現架構
-```
-進程 A                    進程 B
-  ↓                         ↓
-嘗試獲取鎖                嘗試獲取鎖
-  ↓                         ↓
-✅ 成功（創建 .lock）      ❌ 失敗（.lock 已存在）
-  ↓                         ↓
-讀取文件                  等待重試（非阻塞）
-  ↓                         ↓
-修改數據                  等待重試
-  ↓                         ↓
-寫入文件                  等待重試
-  ↓                         ↓
-釋放鎖（刪除 .lock）      ✅ 成功（A 已釋放）
-                            ↓
-                          讀取、修改、寫入
-                            ↓
-                          釋放鎖
-```
-
----
-
-## 實現細節（Node.js）
-
-### 1. 嘗試獲取鎖（原子操作）
-```javascript
-function tryAcquireLock(lockFile) {
-  try {
-    // 檢查鎖是否存在
-    if (fs.existsSync(lockFile)) {
-      const lockStat = fs.statSync(lockFile);
-      const lockAge = Date.now() - lockStat.mtimeMs;
-
-      // 陳舊鎖清理（防止死鎖）
-      if (lockAge > 10000) {  // 10 秒超時
-        console.log('⚠️ 檢測到陳舊鎖，強制釋放');
-        fs.unlinkSync(lockFile);
-      } else {
-        return false;  // 鎖被佔用
-      }
-    }
-
-    // 原子創建鎖文件
-    const lockData = {
-      pid: process.pid,
-      timestamp: new Date().toISOString()
-    };
-    fs.writeFileSync(lockFile, JSON.stringify(lockData, null, 2), {
-      flag: 'wx'  // 排他性創建（文件存在則失敗）
-    });
-    return true;
-  } catch (error) {
-    if (error.code === 'EEXIST') {
-      return false;  // 其他進程剛好建立了鎖
-    }
-    throw error;
-  }
-}
-```
-
-### 2. 非阻塞重試機制
-```javascript
-async function acquireLock(lockFile, maxRetries = 50, retryDelay = 100) {
-  let retries = 0;
-
-  while (retries < maxRetries) {
-    if (tryAcquireLock(lockFile)) {
-      return true;
-    }
-
-    // 使用 setTimeout（非阻塞）
-    await new Promise(resolve => setTimeout(resolve, retryDelay));
-    retries++;
-  }
-
-  console.log('❌ 無法獲取鎖，超過最大重試次數');
-  return false;
-}
-```
-
-### 3. 安全的文件更新流程
-```javascript
-async function updateFile(filePath, updateFn) {
-  const lockFile = filePath + '.lock';
-
-  // 獲取鎖（防止並發寫入）
-  const acquired = await acquireLock(lockFile);
-  if (!acquired) {
-    throw new Error('無法獲取文件鎖');
-  }
-
-  try {
-    // 讀取現有數據
-    let data = {};
-    if (fs.existsSync(filePath)) {
-      data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    }
-
-    // 應用更新函數
-    const newData = updateFn(data);
-
-    // 寫入文件
-    fs.writeFileSync(filePath, JSON.stringify(newData, null, 2));
-
-  } finally {
-    // 確保總是釋放鎖（即使發生錯誤）
-    releaseLock(lockFile);
-  }
-}
-```
-
-### 4. 釋放鎖
-```javascript
-function releaseLock(lockFile) {
-  try {
-    if (fs.existsSync(lockFile)) {
-      fs.unlinkSync(lockFile);
-    }
-  } catch (err) {
-    console.warn('⚠️ 釋放鎖失敗:', err.message);
-  }
-}
-```
-
----
-
-## 關鍵特性
-
-### ✅ 原子操作
-- 使用 `flag: 'wx'`（排他性創建）
-- 確保鎖文件創建的原子性
-
-### ✅ 非阻塞等待
-- 使用 `async/await + setTimeout`
-- 不佔用 CPU，避免忙等待（busy-wait）
-
-### ✅ 陳舊鎖清理
-- 10 秒超時自動釋放
-- 防止進程崩潰導致死鎖
-
-### ✅ 確保鎖釋放
-- 使用 `finally` 塊
-- 即使發生錯誤也能釋放鎖
-
----
-
-## 適用場景
-
-### ✅ 適用
-- 多進程並發寫入同一文件（如 state.json, config.json）
-- 需要讀取-修改-寫入的原子操作
-- 短時間的文件操作（幾秒內完成）
-
-### ❌ 不適用
-- 跨機器的分佈式鎖（需要使用 Redis、ZooKeeper）
-- 長時間持有鎖的場景（> 10 秒）
-- 高頻並發（毫秒級，建議使用數據庫）
-
----
-
-## 注意事項
-
-### 1. Windows 文件系統限制
-在極短時間內（< 5ms），`flag: 'wx'` 的原子性不完全可靠。
-
-**解決方案**：配合啟動間隔（1-3 秒）使用。
-**參考**：`K-SOL-003` Windows 文件系統競爭條件解決方案
-
-### 2. 重試次數與延遲設置
-```javascript
-maxRetries = 50   // 最多重試 50 次
-retryDelay = 100  // 每次間隔 100ms
-// 總等待時間 = 50 * 100ms = 5 秒
-```
-
-根據任務執行時間調整參數。
-
-### 3. 錯誤處理
-- 超過重試次數時應該返回錯誤，而不是靜默失敗
-- 記錄鎖衝突日誌，便於調試
-
----
-
-## 實際應用
-
-### .team 系統狀態管理
-```javascript
-async function updateTeamState(teamId, status, extraData = {}) {
-  const stateFile = path.join('.team', teamId, 'state.json');
-  const lockFile = stateFile + '.lock';
-
-  const acquired = await acquireLock(lockFile);
-  if (!acquired) {
-    console.log('❌ 無法獲取鎖，放棄更新狀態');
-    return;
-  }
-
-  try {
-    let existingState = {};
-    if (fs.existsSync(stateFile)) {
-      existingState = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-    }
-
-    const state = {
-      ...existingState,
-      teamId,
-      status,
-      updatedAt: new Date().toISOString(),
-      ...extraData
-    };
-
-    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
-  } finally {
-    releaseLock(lockFile);
-  }
-}
-```
-
----
-
-## 測試驗證
-
-### 測試場景
-5 個 worker 進程並發更新同一文件，每個進程添加一條記錄。
-
-### 預期結果
-- ✅ 所有 5 條記錄都正確保存
-- ✅ 無數據損壞或丟失
-- ✅ 每個進程按順序執行（通過鎖機制）
-
-### 實際測試
-```bash
-node test-file-lock.js
-# 結果：5 個更新全部成功保存，無競爭條件
-```
-
----
-
-## 相關記憶
-
-- `K-SOL-003`: Windows 文件系統競爭條件解決方案
-- `KZ-TEAM-004`: .team 並行處理能力
-- `K-PAT-002`: Leader-Worker 協作模式
-
----
-
-**建立日期**: 2026-02-11
-**來源**: .team 並行處理實現
-**重要性**: 4/5
-**適用範圍**: 所有需要並發文件操作的 Node.js 應用

package/core/.kenaz/main-memory/knowledge/references/001_ppl_rules.md

@@ -1,28 +0,0 @@
-# PPL Rules Reference - Pipeline 規則快速參考
-
-**記憶 ID**: knowledge/references/001
-**類型**: Quick Reference
-**標籤**: #pipeline #rules #reference
-**建立時間**: 2026-02-10
-
----
-
-## 關鍵 Pipeline 規則
-
-| 規則 ID | 說明 |
-|--------|------|
-| PPL-101 | 任務拆分粒度（15-20 分鐘） |
-| PPL-102 | 任務依賴分析 |
-| PPL-104 | Team 優先原則 |
-| PPL-105 | agent_type 命名規範 |
-| PPL-106 | Feature ID 自動分配 |
-| PPL-107 | 工作啟動前展示計劃（必須） |
-| PPL-108 | 失敗處理流程 |
-| PPL-109 | Commit 策略 |
-| PPL-110 | 監控與自動化 |
-| PPL-111 | scope_paths 衝突檢測 |
-| PPL-112 | 驗收標準驗證 |
-
-## 完整文檔
-
-`.rule/pipeline/task-execution.yaml`

package/core/.kenaz/main-memory/knowledge/solutions/001_json_bom_issue.md

@@ -1,137 +0,0 @@
-# JSON BOM 編碼問題
-
-**ID**: KNZ-SOLUTION-001
-**分類**: solutions
-**標籤**: #json #encoding #windows #troubleshooting
-
-## 問題描述
-
-Windows 環境下編輯 JSON 文件時，可能會自動添加 UTF-8 BOM（Byte Order Mark），導致 JSON 解析失敗。
-
-## 症狀
-
-```javascript
-// 錯誤訊息
-SyntaxError: Unexpected token  in JSON at position 0
-
-// 文件看起來正常，但無法解析
-{
-  "key": "value"
-}
-```
-
-## 根本原因
-
-Windows 編輯器（如 Notepad）預設使用 UTF-8 with BOM：
-- BOM 是不可見字符（`\uFEFF`）
-- 位於文件開頭
-- JSON 規範不允許 BOM
-- Node.js `JSON.parse()` 無法處理
-
-## 解決方案
-
-### 方案 1：使用自動修復工具（推薦）
-
-```bash
-# 一鍵修復（移除 BOM + 驗證 + 格式化）
-node .failure/tools/fix_json.js dev/pipeline/TASK_QUEUE.json
-```
-
-**功能**：
-- ✅ 自動移除 BOM
-- ✅ 驗證 JSON 語法
-- ✅ 格式化 JSON（2 空格縮進）
-- ✅ 備份原文件
-
-### 方案 2：手動移除 BOM
-
-```bash
-# 僅移除 BOM
-node .failure/tools/remove_bom.js dev/pipeline/TASK_QUEUE.json
-```
-
-### 方案 3：批量檢查
-
-```bash
-# 檢查所有 JSON 文件是否有 BOM
-node .failure/tools/check_bom.js
-```
-
-## 預防措施
-
-### 1. 使用正確的編輯器
-推薦使用：
-- VS Code（預設 UTF-8 without BOM）
-- Notepad++（可設置 UTF-8 without BOM）
-- Sublime Text
-
-避免使用：
-- Windows Notepad（預設 UTF-8 with BOM）
-
-### 2. 編輯後立即驗證
-
-```bash
-# 驗證 JSON 語法
-node .failure/tools/validate_json.js file.json
-
-# 或使用 Node.js 快速驗證
-node -e "JSON.parse(require('fs').readFileSync('file.json', 'utf8'))"
-```
-
-### 3. Git 配置
-
-在 `.gitattributes` 中設置：
-```
-*.json text eol=lf
-```
-
-確保所有 JSON 文件使用 LF 換行符，避免 BOM 問題。
-
-## 檢測方法
-
-### 方法 1：使用工具
-```bash
-node .failure/tools/check_bom.js file.json
-```
-
-### 方法 2：手動檢查
-```bash
-# Windows PowerShell
-Get-Content file.json -Encoding Byte -TotalCount 3
-
-# 如果輸出是 239 187 191，則有 BOM（EF BB BF）
-```
-
-### 方法 3：Node.js 檢測
-```javascript
-const fs = require('fs');
-const buffer = fs.readFileSync('file.json');
-const hasBOM = buffer[0] === 0xEF && buffer[1] === 0xBB && buffer[2] === 0xBF;
-console.log('Has BOM:', hasBOM);
-```
-
-## 相關失敗記錄
-
-參考 `.failure/data-integrity/FAIL-002_json_bom_encoding.md`
-
-## 工具清單
-
-| 工具 | 用途 | 使用時機 |
-|------|------|---------|
-| `fix_json.js` | 一鍵修復 | 編輯 JSON 後（推薦） |
-| `validate_json.js` | 驗證語法 | 編輯 JSON 後 |
-| `remove_bom.js` | 移除 BOM | BOM 錯誤時 |
-| `check_bom.js` | 批量檢查 | 定期維護 |
-
-## 最佳實踐
-
-1. ✅ 編輯 JSON 後立即驗證
-2. ✅ 使用自動修復工具
-3. ✅ 配置編輯器為 UTF-8 without BOM
-4. ✅ 定期批量檢查
-5. ✅ 遵循 `.gitattributes` 規範
-
-## 參考資料
-
-- `.failure/tools/README.md` - 工具使用指南
-- `.failure/data-integrity/FAIL-002_json_bom_encoding.md` - 失敗記錄

package/core/.kenaz/main-memory/knowledge/solutions/003_windows_file_race_condition.md

@@ -1,239 +0,0 @@
-# Windows 文件系統競爭條件解決方案
-
-**ID**: K-SOL-003
-**分類**: 問題解決方案
-**重要性**: ⭐⭐⭐⭐
-**標籤**: `windows`, `race-condition`, `file-system`, `concurrency`, `nodejs`
-
----
-
-## 問題描述
-
-### 現象
-在 Windows 環境下，多個進程在極短時間內（< 5ms）並發創建/寫入文件時，即使使用原子操作（如 `fs.writeFileSync(..., { flag: 'wx' })`），仍然會發生競爭條件。
-
-### 實際案例
-```javascript
-// 進程 A 和進程 B 同時執行（間隔 < 5ms）
-// 兩者都成功創建了鎖文件！
-tryAcquireLock('state.json.lock');  // A: true
-tryAcquireLock('state.json.lock');  // B: true ❌ 應該失敗但成功了
-```
-
-### 根本原因
-Windows 文件系統的原子操作在極短時間窗口內不完全可靠：
-- NTFS 文件系統的元數據更新存在延遲
-- `CreateFile` API 在極短時間內可能返回不一致結果
-- 反病毒軟件可能干擾文件操作的原子性
-
----
-
-## 解決方案：文件鎖 + 啟動間隔
-
-### 核心策略
-**組合方案**，而非單一技術方案：
-1. **文件鎖機制**：防止競爭條件（主要防護）
-2. **啟動間隔**：避開不可靠的時間窗口（輔助防護）
-
-### 為什麼需要啟動間隔？
-雖然文件鎖已經提供保護，但在 Windows 極短時間窗口內，原子操作可能失效。啟動間隔確保進程不會在這個窗口內同時啟動。
-
----
-
-## 實現方案
-
-### 1. 文件鎖機制（參考 K-PAT-005）
-```javascript
-async function acquireLock(lockFile, maxRetries = 50, retryDelay = 100) {
-  let retries = 0;
-  while (retries < maxRetries) {
-    if (tryAcquireLock(lockFile)) {
-      return true;
-    }
-    await new Promise(resolve => setTimeout(resolve, retryDelay));
-    retries++;
-  }
-  return false;
-}
-
-function tryAcquireLock(lockFile) {
-  try {
-    // 陳舊鎖清理
-    if (fs.existsSync(lockFile)) {
-      const lockAge = Date.now() - fs.statSync(lockFile).mtimeMs;
-      if (lockAge > 10000) {  // 10 秒超時
-        fs.unlinkSync(lockFile);
-      } else {
-        return false;
-      }
-    }
-
-    // 原子創建
-    fs.writeFileSync(lockFile, JSON.stringify({
-      pid: process.pid,
-      timestamp: new Date().toISOString()
-    }), { flag: 'wx' });
-
-    return true;
-  } catch (error) {
-    if (error.code === 'EEXIST') return false;
-    throw error;
-  }
-}
-```
-
-### 2. 啟動間隔策略
-```javascript
-// ❌ 錯誤：極短時間啟動
-for (let i = 0; i < 5; i++) {
-  spawn('node', ['worker.js']);  // 間隔 < 1ms
-}
-
-// ✅ 正確：加入啟動間隔
-for (let i = 0; i < 5; i++) {
-  spawn('node', ['worker.js']);
-
-  if (i < 4) {
-    await new Promise(resolve => setTimeout(resolve, 2000));  // 2 秒間隔
-  }
-}
-```
-
-### 3. 間隔時間選擇
-
-| 間隔時間 | 適用場景 | 說明 |
-|---------|---------|------|
-| < 100ms | ❌ 不推薦 | Windows 文件系統可能失效 |
-| 100-500ms | ⚠️ 謹慎 | 仍有小概率失效 |
-| 1-3 秒 | ✅ 推薦 | 完全避開競爭條件窗口 |
-| > 5 秒 | ⚠️ 過度 | 沒有必要，浪費時間 |
-
-**推薦值**：2 秒（實測有效）
-
----
-
-## 決策依據
-
-### 關鍵洞察
-> "那不要極短時間 我們可以 1-3秒 放一個團隊出發 我覺得是沒問題的"
-> — 用戶洞察
-
-### 為什麼 2 秒間隔可以接受？
-1. **任務執行時間**：團隊任務通常需要幾分鐘
-2. **相對成本**：2 秒 vs 3 分鐘 = 1.1% 時間增加
-3. **可靠性提升**：從可能失敗 → 100% 成功
-4. **實用性原則**：滿足需求即可，不追求極限
-
-**結論**：實用性 > 技術炫技
-
----
-
-## 測試驗證
-
-### 測試場景 1：5 Worker 並發（2 秒間隔）
-```bash
-node test-file-lock.js
-```
-
-**結果**：
-```
-✅ 所有 5 個更新都正確保存
-- W1: value 100 (0 → 1)
-- W2: value 200 (1 → 2)
-- W3: value 300 (2 → 3)
-- W4: value 400 (3 → 4)
-- W5: value 500 (4 → 5)
-```
-
-### 測試場景 2：2 Team 並行（2 秒間隔）
-```bash
-node test-parallel-teams.js
-```
-
-**結果**：
-```
-✅ Team 1: 成功（exit code: 0, 62 秒）
-✅ Team 2: 成功（exit code: 0, 123 秒）
-✅ state.json 無競爭條件，數據完整
-```
-
----
-
-## 為什麼不使用其他方案？
-
-### 方案 A：追求極短時間並發
-- ❌ Windows 文件系統不可靠（< 5ms）
-- ❌ 需要更複雜的鎖機制（如分佈式鎖）
-- ❌ 成本高，收益低（任務本身需要幾分鐘）
-
-### 方案 B：使用數據庫或外部服務
-- ❌ 違反 GEN-007 規則（專案自包含原則）
-- ❌ 增加外部依賴
-- ❌ 過度工程（問題不需要這麼複雜的方案）
-
-### 方案 C：文件鎖 + 啟動間隔 ✅
-- ✅ 簡單有效
-- ✅ 完全符合 GEN-007 規則
-- ✅ 成本可接受（2 秒 vs 幾分鐘任務）
-- ✅ 實測 100% 成功
-
----
-
-## 適用場景
-
-### ✅ 推薦使用
-- Windows 環境的並行處理
-- 多進程並發寫入文件
-- 任務執行時間 > 30 秒
-- 需要保證數據完整性
-
-### ❌ 不推薦
-- Linux/macOS 環境（原子操作更可靠，可能不需要間隔）
-- 實時性要求極高（毫秒級響應）
-- 高頻並發（每秒上百次）
-
----
-
-## 注意事項
-
-### 1. 間隔時間調整
-根據實際任務執行時間調整：
-- 任務 < 10 秒：使用 500ms 間隔
-- 任務 10-60 秒：使用 1 秒間隔
-- 任務 > 60 秒：使用 2-3 秒間隔
-
-### 2. 監控與日誌
-記錄鎖衝突情況：
-```javascript
-if (!acquired) {
-  console.log(`❌ 無法獲取鎖: ${lockFile}，已重試 ${maxRetries} 次`);
-}
-```
-
-### 3. 錯誤處理
-- 超時應該拋出錯誤而不是靜默失敗
-- 記錄競爭條件發生的頻率
-- 如果頻繁發生，考慮增加間隔時間
-
----
-
-## 相關記憶
-
-- `K-PAT-005`: 文件鎖模式
-- `K-PAT-004`: 用戶領域知識的價值
-- `KZ-TEAM-004`: .team 並行處理能力
-
----
-
-## 參考資料
-
-- Windows NTFS 文件系統文檔
-- Node.js `fs.writeFileSync` flag 選項
-- .team 並行處理測試腳本
-
----
-
-**建立日期**: 2026-02-11
-**來源**: .team 並行處理問題解決
-**重要性**: 4/5
-**適用範圍**: Windows 環境的 Node.js 並行處理