kenaz 0.3.18 → 0.3.20

package/core/.rule/pipeline/PPL-002-completed-task-archival.yaml

@@ -1,528 +0,0 @@
-# PPL-002: 已完成任務必須封存到 .memory/
-# 嚴重程度: high
-# 來源: FAIL-003 (TASK_QUEUE 污染問題)
-
-_meta:
-  id: "PPL-002"
-  category: "pipeline"
-  severity: "high"
-  version: "1.0.0"
-  created_at: "2026-02-05"
-  last_updated: "2026-02-05"
-  applies_to:
-    - "ai_agent"
-    - "human_developer"
-    - "ci_cd"
-  related_failures:
-    - "FAIL-003"  # TASK_QUEUE 污染問題
-  priority: 1  # 高優先級，影響系統穩定性
-
-# ============================================================
-# 規則定義
-# ============================================================
-
-title: "已完成任務必須立即封存到 .memory/"
-
-description: |
-  當任務狀態變為 completed 時，必須在同一操作中將任務從 TASK_QUEUE.json
-  移除並封存到 .memory/COMPLETED_TASKS.json，確保佇列只包含活躍任務
-  (pending/in_progress/blocked)。
-
-rationale: |
-  **為什麼需要此規則**：
-  - 保持 TASK_QUEUE.json 精簡，提升載入和解析效率
-  - 防止 Multi-Agent Scheduler 重複載入已完成任務
-  - 避免佇列污染（completed 任務混入 active 佇列）
-  - 確保統計數據準確反映專案進度
-  - 減少 token 消耗（Agent 不需要過濾大量歷史任務）
-
-background: |
-  **失敗歷史**：
-  此規則源於 FAIL-003（TASK_QUEUE 污染問題），該問題已重複發生 2 次：
-
-  **問題現象**：
-  已完成任務被移到 .memory/ 後，Multi-Agent Scheduler 又把它們加回
-  TASK_QUEUE.json 並標記為 completed，導致：
-  - 佇列文件體積持續增長
-  - 統計數據混亂（total 包含大量歷史任務）
-  - Agent 任務選取效率降低（需過濾大量已完成任務）
-  - 潛在的任務重複執行風險
-
-  **根本原因**：
-  Scheduler 同步邏輯從 dev/pipeline/completed/ 目錄讀取任務，將歷史任務
-  重新加入佇列，且沒有過濾 completed 狀態。
-
-# ============================================================
-# 強制執行規則
-# ============================================================
-
-rules:
-  # ----------------------------------------------------------
-  # PPL-002.1: 佇列只包含活躍任務
-  # ----------------------------------------------------------
-  - id: "PPL-002.1"
-    name: "佇列只包含活躍任務"
-    severity: "must"
-    description: |
-      TASK_QUEUE.json 的 tasks 陣列只能包含狀態為 pending, in_progress,
-      或 blocked 的任務。不允許 completed 或 cancelled 任務存在。
-
-    definition:
-      active_states: ["pending", "in_progress", "blocked"]
-      forbidden_states: ["completed", "cancelled"]
-
-    validation:
-      - type: "json_schema"
-        rule: "tasks[*].status MUST BE IN ['pending', 'in_progress', 'blocked']"
-      - type: "count"
-        rule: "tasks.filter(t => t.status == 'completed').length MUST BE 0"
-
-    violation_detection: |
-      # 檢測佇列污染
-      const queue = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
-      const polluted = queue.tasks.filter(t =>
-        ['completed', 'cancelled'].includes(t.status)
-      );
-
-      if (polluted.length > 0) {
-        console.error(`❌ 違反 PPL-002.1: 發現 ${polluted.length} 個已完成任務污染佇列`);
-        console.error('任務 ID:', polluted.map(t => t.id).join(', '));
-        process.exit(1);
-      }
-
-  # ----------------------------------------------------------
-  # PPL-002.2: 任務完成後立即封存
-  # ----------------------------------------------------------
-  - id: "PPL-002.2"
-    name: "任務完成後立即封存"
-    severity: "must"
-    description: |
-      當任務狀態變為 completed 時，必須在同一個操作流程中執行以下步驟，
-      不可跳過或延遲任何步驟。
-
-    workflow:
-      - step: 1
-        action: "移動任務 YAML 文件"
-        source: "dev/pipeline/tasks/TASK_XXX.yaml"
-        destination: "dev/pipeline/completed/TASK_XXX.yaml"
-        command: "mv dev/pipeline/tasks/TASK_XXX.yaml dev/pipeline/completed/"
-
-      - step: 2
-        action: "從 TASK_QUEUE.json 移除該任務"
-        implementation: |
-          const queue = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
-          queue.tasks = queue.tasks.filter(t => t.id !== 'TASK_XXX');
-          fs.writeFileSync('dev/pipeline/TASK_QUEUE.json', JSON.stringify(queue, null, 2));
-
-      - step: 3
-        action: "封存到 .memory/COMPLETED_TASKS.json"
-        implementation: |
-          const completed = JSON.parse(fs.readFileSync('.memory/COMPLETED_TASKS.json', 'utf8'));
-          completed.push({
-            id: task.id,
-            title: task.title,
-            priority: task.priority,
-            agent_type: task.agent_type,
-            source: task.source,
-            estimated_hours: task.estimated_hours,
-            complexity: task.complexity,
-            source_file: task.source_file,
-            completed_at: new Date().toISOString()
-          });
-          fs.writeFileSync('.memory/COMPLETED_TASKS.json', JSON.stringify(completed, null, 2));
-
-      - step: 4
-        action: "更新統計數據"
-        implementation: |
-          queue.statistics = {
-            total: queue.tasks.length + completed.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: completed.length,
-            cancelled: 0
-          };
-          queue.last_updated = new Date().toISOString();
-
-    atomic_requirement: |
-      所有四個步驟必須作為一個原子操作執行。如果任何步驟失敗，
-      必須回滾所有變更，避免數據不一致。
-
-  # ----------------------------------------------------------
-  # PPL-002.3: Scheduler 禁止從 completed/ 同步
-  # ----------------------------------------------------------
-  - id: "PPL-002.3"
-    name: "Scheduler 禁止從 completed/ 同步"
-    severity: "must"
-    description: |
-      Multi-Agent Scheduler 的任務同步邏輯必須只從 dev/pipeline/tasks/
-      目錄讀取，completed/ 目錄僅供歷史記錄和審計使用。
-
-    allowed_source: "dev/pipeline/tasks/"
-    forbidden_sources:
-      - "dev/pipeline/completed/"
-      - ".memory/COMPLETED_TASKS.json"
-
-    implementation_guide: |
-      // ✅ 正確：只從 tasks/ 讀取
-      pub fn sync_tasks_from_filesystem(&mut self, project_path: &Path) -> Result<()> {
-          let tasks_dir = project_path.join("dev/pipeline/tasks");
-          self.load_tasks_from_directory(&tasks_dir)?;
-          Ok(())
-      }
-
-      // ❌ 錯誤：從 completed/ 讀取
-      pub fn sync_tasks_from_filesystem(&mut self, project_path: &Path) -> Result<()> {
-          let tasks_dir = project_path.join("dev/pipeline/tasks");
-          let completed_dir = project_path.join("dev/pipeline/completed");  // ❌ 禁止
-          self.load_tasks_from_directory(&tasks_dir)?;
-          self.load_tasks_from_directory(&completed_dir)?;  // ❌ 污染源頭
-          Ok(())
-      }
-
-    code_review_checklist:
-      - "Scheduler 代碼不包含 'completed/' 路徑引用"
-      - "沒有從 .memory/ 讀取任務並加入佇列"
-      - "同步邏輯只掃描 tasks/ 目錄"
-
-  # ----------------------------------------------------------
-  # PPL-002.4: 啟動時驗證佇列完整性
-  # ----------------------------------------------------------
-  - id: "PPL-002.4"
-    name: "啟動時驗證佇列完整性"
-    severity: "must"
-    description: |
-      Multi-Agent Scheduler 啟動時必須驗證 TASK_QUEUE.json 中無 completed
-      狀態任務。如果發現污染，拒絕啟動並提示執行清理腳本。
-
-    validation_logic: |
-      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!(
-                      "❌ 發現 {} 個已完成任務污染佇列！\n\
-                       請執行清理腳本：node dev/scripts/cleanup-queue.js",
-                      completed_count
-                  )
-              ));
-          }
-
-          Ok(())
-      }
-
-    startup_sequence:
-      - step: 1
-        action: "載入 TASK_QUEUE.json"
-      - step: 2
-        action: "執行完整性驗證 (validate_queue_integrity)"
-      - step: 3
-        action: "如果驗證失敗，拒絕啟動並輸出錯誤訊息"
-      - step: 4
-        action: "如果驗證通過，繼續正常啟動流程"
-
-  # ----------------------------------------------------------
-  # PPL-002.5: 定期清理機制
-  # ----------------------------------------------------------
-  - id: "PPL-002.5"
-    name: "定期清理機制"
-    severity: "should"
-    description: |
-      建立自動化清理腳本，定期清除 TASK_QUEUE.json 中的 completed 任務。
-      雖然正常流程不應產生污染，但作為安全網機制。
-
-    frequency: "每週一次，或當檢測到污染時手動執行"
-
-    cleanup_script_path: "dev/scripts/cleanup-queue.js"
-
-    cleanup_script: |
-      // dev/scripts/cleanup-queue.js
-      const fs = require('fs');
-      const path = require('path');
-
-      const queuePath = 'dev/pipeline/TASK_QUEUE.json';
-      const memoryPath = '.memory/COMPLETED_TASKS.json';
-      const backupDir = 'dev/pipeline/backups';
-
-      // 備份
-      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-      const backupPath = path.join(backupDir, `queue_backup_${timestamp}.json`);
-      fs.mkdirSync(backupDir, { recursive: true });
-      fs.copyFileSync(queuePath, backupPath);
-      console.log(`✅ 已備份到 ${backupPath}`);
-
-      // 讀取並移除 BOM
-      let content = fs.readFileSync(queuePath, 'utf8');
-      if (content.charCodeAt(0) === 0xFEFF) {
-        content = content.slice(1);
-      }
-
-      const queue = JSON.parse(content);
-      const completed = JSON.parse(fs.readFileSync(memoryPath, 'utf8'));
-
-      // 過濾已完成任務
-      const beforeCount = queue.tasks.length;
-      queue.tasks = queue.tasks.filter(t =>
-        ['pending', 'in_progress', 'blocked'].includes(t.status)
-      );
-      const afterCount = queue.tasks.length;
-      const removedCount = beforeCount - afterCount;
-
-      // 重新計算統計
-      queue.statistics = {
-        total: queue.tasks.length + completed.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: completed.length,
-        cancelled: 0
-      };
-
-      queue.last_updated = new Date().toISOString();
-
-      // 寫回文件
-      fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2));
-
-      console.log(`✅ 清理完成！移除 ${removedCount} 個已完成任務`);
-      console.log(`  - 當前佇列: ${queue.tasks.length} 個任務`);
-      console.log(`  - pending: ${queue.statistics.pending}`);
-      console.log(`  - in_progress: ${queue.statistics.in_progress}`);
-      console.log(`  - blocked: ${queue.statistics.blocked}`);
-      console.log(`  - 累積完成: ${queue.statistics.completed}`);
-
-    powershell_wrapper: |
-      # dev/scripts/cleanup-completed-tasks.ps1
-      param(
-          [switch]$DryRun,
-          [switch]$Verbose
-      )
-
-      $QueuePath = "dev/pipeline/TASK_QUEUE.json"
-
-      # 執行清理腳本
-      node dev/scripts/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 "✅ 佇列已清理，無已完成任務" -ForegroundColor Green
-      }
-
-# ============================================================
-# 預防措施
-# ============================================================
-
-prevention:
-  checklist:
-    - item: "任務完成後立即封存"
-      description: "完成任務後，立即將 YAML 移到 completed/ 並更新 Queue"
-      responsibility: "Dev Agent, Human Developer"
-
-    - item: "Scheduler 啟動前驗證"
-      description: "Scheduler 啟動前，驗證 Queue 中無 completed 任務"
-      responsibility: "Multi-Agent Scheduler"
-
-    - item: "定期執行清理腳本"
-      description: "每週執行一次 cleanup-queue.js 確保佇列乾淨"
-      responsibility: "CI/CD Pipeline, Human Developer"
-
-    - item: "監控統計數據異常"
-      description: "當 total > 100 或 completed > 0 in queue 時觸發警報"
-      responsibility: "Monitoring System"
-
-    - item: "禁止從 completed/ 同步"
-      description: "Scheduler 代碼禁止從 completed/ 目錄讀取任務"
-      responsibility: "Code Review"
-
-    - item: "統一狀態更新邏輯"
-      description: "所有狀態更新必須通過 task_queue.rs 的 API"
-      responsibility: "All Developers"
-
-  automated_checks:
-    - type: "pre_commit_hook"
-      name: "validate-queue-integrity.sh"
-      description: "提交前驗證 TASK_QUEUE.json 完整性"
-      implementation: |
-        #!/bin/bash
-        # .git/hooks/pre-commit
-        queue_file="dev/pipeline/TASK_QUEUE.json"
-
-        if [ -f "$queue_file" ]; then
-          completed_count=$(jq '[.tasks[] | select(.status == "completed")] | length' "$queue_file")
-
-          if [ "$completed_count" -gt 0 ]; then
-            echo "❌ 錯誤：TASK_QUEUE.json 包含 $completed_count 個已完成任務"
-            echo "請執行：node dev/scripts/cleanup-queue.js"
-            exit 1
-          fi
-        fi
-
-    - type: "ci_cd_check"
-      name: "Queue Integrity Check"
-      description: "CI/CD Pipeline 驗證佇列完整性"
-      implementation: |
-        # .github/workflows/validate-queue.yml
-        name: Validate Queue Integrity
-        on: [push, pull_request]
-        jobs:
-          validate:
-            runs-on: ubuntu-latest
-            steps:
-              - uses: actions/checkout@v3
-              - name: Check Queue
-                run: |
-                  completed=$(jq '[.tasks[] | select(.status == "completed")] | length' dev/pipeline/TASK_QUEUE.json)
-                  if [ "$completed" -gt 0 ]; then
-                    echo "❌ Queue污染: $completed 個已完成任務"
-                    exit 1
-                  fi
-
-    - type: "monitoring"
-      name: "Queue Health Monitor"
-      description: "監控 TASK_QUEUE.json 健康狀態"
-      metrics:
-        - metric: "queue_size"
-          threshold: 100
-          alert: "佇列任務數超過 100，可能有污染"
-        - metric: "completed_in_queue"
-          threshold: 0
-          alert: "發現已完成任務在佇列中"
-
-# ============================================================
-# 違規處理
-# ============================================================
-
-enforcement:
-  - type: "blocking"
-    severity: "critical"
-    action: "拒絕 Scheduler 啟動"
-    condition: "TASK_QUEUE.json 包含 completed 任務"
-    message: |
-      ❌ 無法啟動 Multi-Agent Scheduler
-
-      原因：發現 {count} 個已完成任務污染佇列
-      任務 ID: {task_ids}
-
-      解決方案：
-      1. 執行清理腳本：node dev/scripts/cleanup-queue.js
-      2. 或手動移除 completed 任務
-      3. 重新啟動 Scheduler
-
-      規則：PPL-002.1, PPL-002.4
-
-  - type: "warning"
-    severity: "high"
-    action: "Code Review 警告"
-    condition: "Scheduler 代碼包含 'completed/' 路徑引用"
-    message: |
-      ⚠️ Code Review 警告
-
-      發現 Scheduler 代碼引用 completed/ 目錄，這可能導致佇列污染。
-
-      違反規則：PPL-002.3
-      請移除對 completed/ 的引用，只從 tasks/ 讀取任務。
-
-  - type: "auto_fix"
-    severity: "medium"
-    action: "自動清理"
-    condition: "定期清理腳本執行"
-    message: |
-      ✅ 自動清理完成
-
-      已移除 {count} 個已完成任務
-      當前佇列: {queue_size} 個任務
-
-      規則：PPL-002.5
-
-# ============================================================
-# 相關資源
-# ============================================================
-
-related_resources:
-  failure_records:
-    - id: "FAIL-003"
-      title: "TASK_QUEUE 污染問題"
-      path: ".failure/pipeline/FAIL-003-queue-pollution.yaml"
-      description: "此規則的源頭失敗記錄"
-
-  # The TASK_QUEUE.json scheduler (cmd_modules/scheduler/task_queue.rs,
-  # dispatcher.rs) this rule was written against no longer exists. Task state,
-  # including done -> archived, now lives in the task-api state machine.
-  code_locations:
-    - component: "Task state machine (done -> archived)"
-      path: ".collaboration/core/task-api.js"
-      description: "ALL_STATUS_DIRS / 允許的狀態轉移，含 done → archived 封存"
-
-  scripts:
-    - name: "cleanup-queue.js"
-      path: "dev/scripts/cleanup-queue.js"
-      description: "清理佇列腳本（Node.js）"
-
-    - name: "cleanup-completed-tasks.ps1"
-      path: "dev/scripts/cleanup-completed-tasks.ps1"
-      description: "清理佇列腳本（PowerShell wrapper）"
-
-  documentation:
-    - title: "Pipeline 系統規範"
-      path: ".rule/general/pipeline.yaml"
-      description: "Pipeline 系統的整體規則"
-
-    - title: "統計數據規範"
-      path: ".memory/MEMORY.md"
-      section: "Pipeline 管理"
-      description: "累積制統計數據的詳細說明"
-
-# ============================================================
-# 教訓與啟示
-# ============================================================
-
-lessons_learned:
-  - lesson: "數據模型要清晰分離"
-    description: |
-      不要在單一文件（TASK_QUEUE.json）中混合當前狀態和歷史記錄。
-      應該：
-      - Queue: 只存當前待處理任務
-      - Memory: 存歷史已完成任務
-      - Statistics: 計算時合併兩者
-
-  - lesson: "累積制 ≠ 全部塞進佇列"
-    description: |
-      累積制統計數據是指「統計總數包含歷史」，而非「佇列包含歷史任務」。
-      這是兩個層面的概念，不應混淆。
-
-  - lesson: "同步邏輯要明確來源"
-    description: |
-      Scheduler 同步任務時，必須明確：
-      - ✅ 從 tasks/ 讀取 → 待處理任務
-      - ❌ 從 completed/ 讀取 → 污染佇列
-
-  - lesson: "啟動前驗證資料完整性"
-    description: |
-      系統啟動時應驗證核心數據文件的完整性，發現異常立即拒絕啟動，
-      避免帶病運行。
-
-  - lesson: "自動化清理優於手動維護"
-    description: |
-      定期自動化清理比依賴開發者記憶更可靠。
-
-# ============================================================
-# 修訂歷史
-# ============================================================
-
-changelog:
-  - version: "1.0.0"
-    date: "2026-02-05"
-    author: "Developer Agent"
-    changes:
-      - "初始建立規則，源於 FAIL-003"
-      - "定義五大子規則（PPL-002.1 ~ PPL-002.5）"
-      - "提供清理腳本和驗證邏輯"
-      - "建立預防措施和自動化檢查"