kenaz 0.3.18 → 0.3.20

package/core/.failure/pipeline/FAIL-003-queue-pollution.yaml

@@ -1,335 +0,0 @@
-# FAIL-003: TASK_QUEUE 污染問題
-
-_meta:
-  id: "FAIL-003"
-  category: "pipeline"
-  severity: "high"
-  date: "2026-02-05"
-  related_tasks: ["TASK_077", "TASK_078", "TASK_079", "TASK_080"]
-  related_commits: []
-  discovered_by: "Multi-Agent Scheduler"
-  affected_versions: ["1.0.0"]
-
-## 失敗描述
-
-**問題現象**：已完成任務被移到 `.memory/COMPLETED_TASKS.json` 後，Multi-Agent Scheduler 又把它們加回 `TASK_QUEUE.json` 並標記為 `completed`，污染佇列。
-
-**預期行為**：
-- 已完成任務應該只存在於 `dev/pipeline/completed/` 目錄和 `.memory/COMPLETED_TASKS.json`
-- `TASK_QUEUE.json` 應該只包含待處理任務（`pending`, `in_progress`, `blocked`）
-- 統計數據應該準確反映當前佇列狀態
-
-**實際結果**：
-- `TASK_QUEUE.json` 被大量 `status: completed` 的任務污染
-- 統計數據混亂，`total` 包含大量歷史任務
-- Agent 任務選取時需要過濾大量已完成任務，影響效率
-
-## 根本原因
-
-Multi-Agent Scheduler 的任務同步邏輯存在缺陷：
-
-1. **錯誤的同步來源**：Scheduler 從 `dev/pipeline/completed/` 資料夾同步任務時，會把所有歷史任務重新加入 `TASK_QUEUE.json`
-2. **缺乏狀態過濾**：同步時沒有過濾 `completed` 狀態的任務
-3. **累積制誤解**：將統計數據的累積制（total = 佇列 + 歷史）誤解為佇列應該包含所有歷史任務
-
-**代碼位置**：
-```
-dashboard/src-tauri/src/cmd_modules/scheduler/
-  - task_queue.rs（任務佇列管理）
-  - dispatcher.rs（任務同步邏輯）
-```
-
-## 影響範圍
-
-### 受影響的模組
-- `dev/pipeline/TASK_QUEUE.json` - 任務佇列數據污染
-- `dev/pipeline/PROGRESS.md` - 進度統計不準確
-- Multi-Agent Scheduler - 任務選取效率降低
-- Dashboard UI - 任務列表顯示混亂
-
-### 受影響的功能
-- 任務佇列管理
-- 統計數據計算
-- Agent 任務分配
-- 進度追蹤
-
-### 潛在的連鎖反應
-- Agent 可能重複執行已完成任務
-- 統計數據無法反映真實進度
-- 佇列文件體積持續增長
-- 影響多專案並行開發的隔離性
-
-## 重現步驟
-
-1. 完成一個或多個任務（狀態變為 `completed`）
-2. 將已完成任務從 `dev/pipeline/tasks/` 移到 `dev/pipeline/completed/`
-3. 將已完成任務記錄封存到 `.memory/COMPLETED_TASKS.json`
-4. 啟動 Multi-Agent Scheduler
-5. 觀察 `TASK_QUEUE.json`：已完成任務重新出現，狀態為 `completed`
-6. 統計數據 `total` 包含大量歷史任務
-
-## 解決方案
-
-### 1. 立即清理 TASK_QUEUE.json
-
-使用以下腳本清理已完成任務：
-
-```javascript
-// cleanup-queue.js
-const fs = require('fs');
-const path = require('path');
-
-const queuePath = 'dev/pipeline/TASK_QUEUE.json';
-
-// 讀取並移除 BOM（如果存在）
-let content = fs.readFileSync(queuePath, 'utf8');
-if (content.charCodeAt(0) === 0xFEFF) {
-  content = content.slice(1);
-}
-
-const data = JSON.parse(content);
-
-// 只保留 pending/in_progress/blocked 任務
-data.tasks = data.tasks.filter(t =>
-  ['pending', 'in_progress', 'blocked'].includes(t.status)
-);
-
-// 重新計算統計數據（當前佇列制）
-data.statistics = {
-  total: data.tasks.length,
-  pending: data.tasks.filter(t => t.status === 'pending').length,
-  in_progress: data.tasks.filter(t => t.status === 'in_progress').length,
-  blocked: data.tasks.filter(t => t.status === 'blocked').length,
-  completed: 0,
-  cancelled: 0
-};
-
-// 更新時間戳
-data.last_updated = new Date().toISOString();
-
-// 寫回文件
-fs.writeFileSync(queuePath, JSON.stringify(data, null, 2));
-
-console.log(`✅ 清理完成！保留 ${data.tasks.length} 個任務`);
-console.log(`  - pending: ${data.statistics.pending}`);
-console.log(`  - in_progress: ${data.statistics.in_progress}`);
-console.log(`  - blocked: ${data.statistics.blocked}`);
-```
-
-執行方式：
-```bash
-node cleanup-queue.js
-```
-
-### 2. 修改 Scheduler 同步邏輯
-
-**修改文件**：`dashboard/src-tauri/src/cmd_modules/scheduler/task_queue.rs`
-
-**關鍵修改**：
-```rust
-// 同步任務時，只從 tasks/ 目錄讀取，不從 completed/ 讀取
-pub fn sync_tasks_from_filesystem(&mut self, project_path: &Path) -> Result<()> {
-    let tasks_dir = project_path.join("dev/pipeline/tasks");
-
-    // ❌ 錯誤：不要從 completed/ 讀取
-    // let completed_dir = project_path.join("dev/pipeline/completed");
-
-    // ✅ 正確：只從 tasks/ 讀取
-    self.load_tasks_from_directory(&tasks_dir)?;
-
-    Ok(())
-}
-
-// 過濾 completed 狀態的任務
-pub fn filter_active_tasks(&mut self) {
-    self.tasks.retain(|task| {
-        matches!(task.status, TaskStatus::Pending | TaskStatus::InProgress | TaskStatus::Blocked)
-    });
-}
-```
-
-### 3. 建立定期清理機制
-
-在 `dev/scripts/` 建立定期清理腳本：
-
-```powershell
-# cleanup-completed-tasks.ps1
-# 定期清理 TASK_QUEUE.json 中的已完成任務
-
-param(
-    [switch]$DryRun,
-    [switch]$Verbose
-)
-
-$QueuePath = "dev/pipeline/TASK_QUEUE.json"
-$BackupPath = "dev/pipeline/backups/queue_backup_$(Get-Date -Format 'yyyyMMdd_HHmmss').json"
-
-# 備份
-if (-not $DryRun) {
-    Copy-Item $QueuePath $BackupPath -Force
-    Write-Host "✅ 已備份到 $BackupPath"
-}
-
-# 清理
-node cleanup-queue.js
-
-# 驗證
-$data = Get-Content $QueuePath | ConvertFrom-Json
-$completedCount = ($data.tasks | Where-Object { $_.status -eq 'completed' }).Count
-
-if ($completedCount -gt 0) {
-    Write-Warning "⚠️ 仍有 $completedCount 個已完成任務！"
-    exit 1
-} else {
-    Write-Host "✅ 佇列已清理，無已完成任務"
-}
-```
-
-## 預防措施
-
-### 檢查清單
-
-- [ ] **任務完成後立即封存**：完成任務後，立即將 YAML 移到 `completed/` 並更新 Queue
-- [ ] **Scheduler 啟動前驗證**：Scheduler 啟動前，驗證 Queue 中無 `completed` 任務
-- [ ] **定期執行清理腳本**：每週執行一次 `cleanup-queue.js` 確保佇列乾淨
-- [ ] **監控統計數據異常**：當 `total` 超過 100 或 `completed > 0` 時觸發警報
-- [ ] **禁止從 completed/ 同步**：Scheduler 代碼禁止從 `completed/` 目錄讀取任務
-- [ ] **統一狀態更新邏輯**：所有狀態更新必須通過 `task_queue.rs` 的 API
-
-### 自動化驗證
-
-在 Scheduler 啟動時加入驗證：
-
-```rust
-pub fn validate_queue_integrity(&self) -> Result<()> {
-    let completed_count = self.tasks.iter()
-        .filter(|t| t.status == TaskStatus::Completed)
-        .count();
-
-    if completed_count > 0 {
-        return Err(SchedulerError::QueuePollution(
-            format!("發現 {} 個已完成任務污染佇列！請執行清理腳本。", completed_count)
-        ));
-    }
-
-    Ok(())
-}
-```
-
-### 規則建議
-
-如果此失敗模式重複出現，建議建立 `.rule/general/pipeline.yaml` 規則：
-
-**規則 ID**: `PPL-002`
-
-**規則描述**: 已完成任務封存規範
-```yaml
-id: "PPL-002"
-category: "pipeline"
-priority: "high"
-title: "已完成任務必須立即封存"
-
-rules:
-  - name: "任務完成後立即移動"
-    description: |
-      任務狀態變為 completed 後，必須在同一操作中：
-      1. 將 YAML 從 tasks/ 移到 completed/
-      2. 從 TASK_QUEUE.json 移除該任務
-      3. 記錄到 .memory/COMPLETED_TASKS.json
-      4. 更新統計數據
-
-  - name: "禁止從 completed/ 同步"
-    description: |
-      Multi-Agent Scheduler 的任務同步邏輯必須只從 tasks/ 目錄讀取，
-      completed/ 目錄僅供歷史記錄和審計使用。
-
-  - name: "啟動時驗證佇列完整性"
-    description: |
-      Scheduler 啟動時必須驗證 TASK_QUEUE.json 中無 completed 狀態任務，
-      如有則拒絕啟動並提示執行清理腳本。
-
-enforcement:
-  - type: "code_validation"
-    tool: "rust_clippy"
-    check: "禁止 Scheduler 讀取 completed/ 目錄"
-
-  - type: "pre_commit_hook"
-    script: "validate-queue-integrity.sh"
-    description: "提交前驗證 TASK_QUEUE.json 完整性"
-```
-
-## 統計數據規範澄清
-
-**重要**：`TASK_QUEUE.json` 的統計應該是**累積制**（記錄在 `.memory/MEMORY.md`），但這不代表佇列要包含已完成任務！
-
-### 正確的統計數據模型
-
-```javascript
-// TASK_QUEUE.json 中的統計
-statistics: {
-  // 當前佇列任務總數（不含已完成）
-  total: queue.tasks.length,
-
-  // 當前佇列狀態分布
-  pending: queue.tasks.filter(t => t.status === 'pending').length,
-  in_progress: queue.tasks.filter(t => t.status === 'in_progress').length,
-  blocked: queue.tasks.filter(t => t.status === 'blocked').length,
-
-  // 歷史統計（從外部讀取）
-  completed: readFromMemory('.memory/COMPLETED_TASKS.json').length,
-  cancelled: readFromMemory('.memory/CANCELLED_TASKS.json').length
-}
-```
-
-### 累積制的正確實現
-
-**佇列文件**（`TASK_QUEUE.json`）：只存當前任務
-**歷史文件**（`.memory/COMPLETED_TASKS.json`）：累積所有已完成任務
-**統計計算**：累積制 = 佇列 + 歷史
-
-這樣既能保持統計數據的累積特性，又不會污染佇列。
-
-## 教訓與啟示
-
-### 1. 數據模型要清晰分離
-
-不要在單一文件（`TASK_QUEUE.json`）中混合當前狀態和歷史記錄。應該：
-- **Queue**：只存當前待處理任務
-- **Memory**：存歷史已完成任務
-- **Statistics**：計算時合併兩者
-
-### 2. 累積制 ≠ 全部塞進佇列
-
-累積制統計數據是指「統計總數包含歷史」，而非「佇列包含歷史任務」。這是兩個層面的概念，不應混淆。
-
-### 3. 同步邏輯要明確來源
-
-Scheduler 同步任務時，必須明確：
-- ✅ 從 `tasks/` 讀取 → 待處理任務
-- ❌ 從 `completed/` 讀取 → 污染佇列
-
-### 4. 啟動前驗證資料完整性
-
-系統啟動時應驗證核心數據文件的完整性，發現異常立即拒絕啟動，避免帶病運行。
-
-### 5. 自動化清理優於手動維護
-
-定期自動化清理比依賴開發者記憶更可靠。
-
-## 相關資源
-
-- **任務佇列管理**：`dashboard/src-tauri/src/cmd_modules/scheduler/task_queue.rs`
-- **調度器邏輯**：`dashboard/src-tauri/src/cmd_modules/scheduler/dispatcher.rs`
-- **Pipeline 配置**：`dev/pipeline/PIPELINE_CONFIG.json`
-- **統計數據規範**：`.memory/MEMORY.md` - Pipeline 系統章節
-- **清理腳本**：`dev/scripts/cleanup-queue.js`（待建立）
-
-## 修復進度
-
-- [x] 問題識別與記錄
-- [x] 根本原因分析
-- [ ] 建立清理腳本（`cleanup-queue.js`）
-- [ ] 修改 Scheduler 同步邏輯
-- [ ] 加入啟動時驗證
-- [ ] 建立定期清理機制
-- [ ] 轉化為 `.rule/` 規則（如重複發生）

package/core/.failure/pipeline/README.md

@@ -1,95 +0,0 @@
-# ⚙️ Pipeline System Failures
-
-## 分類說明
-
-此目錄記錄 **Pipeline 系統失敗** 相關的問題，包括：
-
-- 任務管理和佇列問題
-- 任務狀態同步錯誤
-- 統計數據不準確
-- Agent 調度問題
-- 路徑鎖定和衝突
-- Pipeline 配置錯誤
-
-## 嚴重程度範例
-
-### 🔴 Critical
-- 任務佇列數據損壞導致系統無法運作
-- 路徑鎖定失效導致多 Agent 衝突
-- 統計數據嚴重錯誤影響決策
-
-### 🟠 High
-- 任務狀態同步錯誤導致重複執行
-- Agent 調度邏輯錯誤影響效率
-- 已完成任務污染佇列
-
-### 🟡 Medium
-- 統計數據輕微不準確
-- Pipeline 配置不夠彈性
-- 日誌記錄不完整
-
-### 🟢 Low
-- 進度顯示格式問題
-- 任務描述不清晰
-- 日誌輸出冗餘
-
-## 記錄指南
-
-當遇到 Pipeline 系統問題時，請遵循以下步驟：
-
-### 1. 確認問題範圍
-確認問題屬於 Pipeline 系統層面，而非單一任務的執行問題。
-
-### 2. 建立失敗記錄
-使用失敗記錄模板建立 YAML 文件。
-
-```yaml
-# 文件命名格式: FAIL-XXX-short-description.yaml
-# 範例: FAIL-003-queue-pollution.yaml
-```
-
-### 3. 包含系統狀態
-記錄失敗時的系統狀態：
-- `TASK_QUEUE.json` 的內容
-- `LOCK_STATE.json` 的內容
-- `PROGRESS.md` 的狀態
-- Agent 執行日誌
-
-### 4. 分析數據流
-追蹤數據流動路徑，找出數據損壞或同步錯誤的位置：
-- 任務建立 → 任務佇列 → Agent 執行 → 狀態更新 → 統計計算
-
-### 5. 建立預防措施
-- 添加數據驗證腳本
-- 增強狀態同步機制
-- 改進錯誤恢復邏輯
-- 考慮轉化為 `.rule/general/` 規則
-
-## 常見 Pipeline 問題模式
-
-### 1. 數據完整性問題
-- **問題**：JSON 文件損壞、BOM 編碼問題
-- **預防**：使用驗證腳本、統一編碼處理
-
-### 2. 狀態同步問題
-- **問題**：多處狀態不一致
-- **預防**：單一數據源、原子性更新
-
-### 3. 統計數據錯誤
-- **問題**：累積制 vs 當前制混淆
-- **預防**：明確定義統計規範
-
-### 4. 路徑鎖定失效
-- **問題**：多 Agent 同時修改相同文件
-- **預防**：嚴格執行 scope_paths 限制
-
-## 已記錄的失敗
-
-請參考 `.failure/INDEX.yaml` 的 `load_order` 部分查看已記錄的失敗。
-
-## 相關資源
-
-- **Pipeline 規則**：`.rule/general/pipeline.yaml`
-- **任務管理文檔**：`dev/pipeline/README.md`
-- **失敗記錄模板**：`.failure/INDEX.yaml` - `failure_template`
-- **Multi-Agent Scheduler**：`dashboard/src-tauri/src/cmd_modules/scheduler/`

package/core/.failure/retired/FAIL-009-skipping-synapse-pulse-before-code-change.yaml

@@ -1,49 +0,0 @@
-id: FAIL-009
-title: "Agent 跳過 synapse_pulse 直接修改代碼"
-category: agent_execution
-severity: high
-
-description: |
-  Agent 在修改代碼前跳過 synapse_pulse（神經脈衝），直接編輯文件。
-  通常的理由是「這只是小改動」「只是 UI 修改」「沒有風險」。
-  但 pulse 的目的不是風險評估 — 是認知覺察（awareness）。
-
-incident:
-  date: "2026-03-17"
-  context: "Ansuz 修改 LoadingScreen.tsx，將 Unicode 符文替換為 SVG 石頭符文"
-  what_happened: |
-    Ansuz 判定「這只是 UI 修改，不需要查圖譜」，跳過 synapse_pulse 直接編輯。
-    修改本身沒有問題，但違反了 SYN-001（禁止盲寫）。
-  what_was_missed: |
-    Pulse 本可以揭示：
-    - 同一個 ᚢ Unicode 字元是否在其他文件使用
-    - LoadingScreen 的 callers 是否依賴其 DOM 結構
-    - 是否有相關的歷史 rune（設計決策等）
-
-root_cause: |
-  Agent 將 synapse_pulse 視為「風險評估工具」而非「認知習慣」。
-  當心理模型是「風險高才需要脈衝」時，Agent 會對「看起來簡單的任務」跳過。
-  正確的心理模型：pulse 是肌肉記憶，不是風險計算後的選擇。
-
-prevention:
-  rule: "SYN-001: 修改任何 symbol 前，必須先做 synapse_pulse"
-  mental_model: |
-    Pulse 不是問「這個改動危險嗎？」
-    Pulse 是問「關於這個 symbol，我還不知道什麼？」
-    10 秒的 pulse 可以揭示你未預料到的依賴、歷史決策、已知風險。
-  trigger: |
-    如果你發現自己在想「這太簡單了不需要 pulse」—
-    這正是你最需要 pulse 的時候。
-    因為「覺得簡單」可能是「不知道自己不知道」。
-
-checklist:
-  - "修改代碼前是否執行了 synapse_pulse？"
-  - "如果跳過了，理由是什麼？「太簡單」不是合理理由"
-  - "pulse 結果是否影響了你的實作方案？"
-
-related:
-  rules:
-    - ".rule/general/synapse-code-intelligence.yaml (SYN-001~007)"
-  runes:
-    - "rune_a7049ab7 (LoadingScreen risk)"
-    - "rune_da740eee (Ansuz workflow fix)"