kenaz 0.3.18 → 0.3.20

package/core/.failure/agent-execution/FAIL-001-agent-no-output.yaml

@@ -1,391 +0,0 @@
-# [FAIL-001] Agent 執行無輸出問題
-
-_meta:
-  id: "FAIL-001"
-  category: "agent_execution"
-  severity: "critical"
-  date: "2026-02-05"
-  related_tasks: ["TASK_078"]
-  related_commits: []
-  status: "resolved"
-
-## 失敗描述
-
-**現象**：Agent 被 Multi-Agent Scheduler 調用執行任務後，沒有產生任何實際輸出或結果。
-
-**預期行為**：
-- Agent 應該讀取任務規格
-- 執行任務要求的代碼實現
-- 產生可見的輸出（文件變更、代碼提交）
-- 更新任務狀態到 completed
-
-**實際結果**：
-- Agent 進程啟動並執行
-- 但未產生任何文件變更或提交
-- 任務保持 in_progress 狀態
-- 日誌中無明確錯誤信息，只有空輸出
-
-## 根本原因
-
-深入分析後，發現此問題的根本原因通常有以下幾種：
-
-### 1. Skill 路徑錯誤或不存在
-```yaml
-# TASK_QUEUE.json 中的錯誤示例
-"skill_path": ".claude/skills/nonexistent_agent/SKILL.md"  # 路徑不存在
-```
-
-- Agent 無法載入正確的技能定義
-- 導致執行邏輯缺失，無法理解任務要求
-- 進程執行但不知道要做什麼
-
-### 2. Agent 執行邏輯問題
-```bash
-# Scheduler 調用 Claude CLI 時的命令結構問題
-claude -p "/agent-worker --task TASK_XXX --agent agent_XXX"
-
-# 如果 /agent-worker 指令未正確定義或解析失敗：
-- Agent 收到指令但無法解析參數
-- 任務 ID、Agent ID、Branch 信息丟失
-- 無法載入任務規格，導致空跑
-```
-
-### 3. 輸出格式問題
-- Agent 產生了輸出，但格式不符合預期
-- 輸出被寫入錯誤位置（如 /tmp 而非專案目錄）
-- Git commit 失敗但未報錯
-
-### 4. Context 不足
-- Agent 未讀取 .memory/CONTEXT.md
-- 缺少專案背景信息
-- 無法理解任務在整體架構中的位置
-
-## 影響範圍
-
-### 受影響的模組/文件
-- `dev/pipeline/TASK_QUEUE.json` - 任務佇列
-- `dashboard/src-tauri/src/cmd_modules/scheduler/` - Scheduler 模組
-- `.claude/commands/agent-worker.md` - Agent Worker 指令定義
-- `dev/pipeline/logs/` - 執行日誌（空日誌）
-
-### 受影響的功能
-- Multi-Agent 並行開發系統無法正常運作
-- 任務卡在 in_progress 狀態
-- 路徑鎖定無法釋放（其他 Agent 被阻塞）
-- Scheduler 無法繼續調度新任務
-
-### 潛在的連鎖反應
-- 整個 Pipeline 停滯
-- 路徑鎖定洩漏（dead lock）
-- 需要手動清理 LOCK_STATE.json
-- 影響其他依賴此任務的 Agent
-
-## 重現步驟
-
-1. 建立一個任務，skill_path 指向不存在的路徑
-```json
-{
-  "id": "TASK_999",
-  "skill_path": ".claude/skills/invalid_agent/SKILL.md",
-  "status": "pending"
-}
-```
-
-2. 啟動 Multi-Agent Scheduler
-```bash
-.\dev\scripts\START_MULTI_AGENT.bat
-```
-
-3. 觀察到的錯誤：
-- Agent 進程啟動
-- 任務狀態變為 in_progress
-- 等待數分鐘後，無任何輸出
-- git log main..HEAD 顯示無提交
-- 任務仍然 in_progress
-
-## 解決方案
-
-### 短期修復（手動干預）
-
-#### 步驟 1：驗證 Skill 路徑
-```bash
-# 檢查 TASK_QUEUE.json 中的 skill_path 是否存在
-node -e "
-const queue = require('./dev/pipeline/TASK_QUEUE.json');
-const fs = require('fs');
-queue.tasks.forEach(t => {
-  if (t.skill_path && !fs.existsSync(t.skill_path)) {
-    console.error(\`❌ TASK \${t.id}: skill_path不存在 - \${t.skill_path}\`);
-  } else if (t.skill_path) {
-    console.log(\`✅ TASK \${t.id}: skill_path有效\`);
-  }
-});
-"
-```
-
-#### 步驟 2：檢查執行日誌
-```bash
-# 查看最新的 Agent 執行日誌
-Get-ChildItem dev/pipeline/logs/*.log | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 50
-```
-
-#### 步驟 3：清理卡住的任務
-```javascript
-// cleanup_stuck_tasks.js
-const fs = require('fs');
-const queue = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
-
-// 將長時間 in_progress 的任務標記為 blocked
-queue.tasks.forEach(t => {
-  if (t.status === 'in_progress') {
-    const startTime = new Date(t.started_at);
-    const now = new Date();
-    const hours = (now - startTime) / (1000 * 60 * 60);
-
-    if (hours > 2) {  // 超過 2 小時視為卡住
-      console.log(`⚠️ Task ${t.id} stuck for ${hours.toFixed(1)} hours, marking as blocked`);
-      t.status = 'blocked';
-      t.blocked_reason = 'Agent execution timeout - no output';
-    }
-  }
-});
-
-fs.writeFileSync('dev/pipeline/TASK_QUEUE.json', JSON.stringify(queue, null, 2));
-```
-
-#### 步驟 4：釋放路徑鎖定
-```bash
-# 清理卡住任務的路徑鎖定
-node -e "
-const fs = require('fs');
-const locks = JSON.parse(fs.readFileSync('dev/pipeline/LOCK_STATE.json', 'utf8'));
-const queue = JSON.parse(fs.readFileSync('dev/pipeline/TASK_QUEUE.json', 'utf8'));
-
-// 獲取所有 blocked 任務的 Agent ID
-const blockedAgents = queue.tasks
-  .filter(t => t.status === 'blocked')
-  .map(t => t.assigned_agent);
-
-// 清理這些 Agent 的鎖定
-Object.keys(locks.path_locks).forEach(path => {
-  if (blockedAgents.includes(locks.path_locks[path].locked_by)) {
-    console.log(\`🔓 Releasing lock on \${path}\`);
-    delete locks.path_locks[path];
-  }
-});
-
-fs.writeFileSync('dev/pipeline/LOCK_STATE.json', JSON.stringify(locks, null, 2));
-"
-```
-
-### 長期解決方案（預防機制）
-
-#### 1. Scheduler 驗證增強
-```rust
-// dashboard/src-tauri/src/cmd_modules/scheduler/dispatcher.rs
-async fn assign_task_to_agent(&mut self, task: &Task) -> Result<(), SchedulerError> {
-    // ✅ 新增：驗證 skill_path 存在性
-    if let Some(skill_path) = &task.skill_path {
-        if !std::path::Path::new(skill_path).exists() {
-            return Err(SchedulerError::InvalidSkillPath {
-                task_id: task.id.clone(),
-                path: skill_path.clone(),
-            });
-        }
-    }
-
-    // 原有邏輯...
-}
-```
-
-#### 2. Agent 輸出驗證
-```rust
-// 執行 Agent 後驗證輸出
-async fn monitor_agent_execution(&self, agent_id: &str, task_id: &str) -> Result<(), SchedulerError> {
-    // 等待執行完成
-    let result = self.wait_for_agent(agent_id).await?;
-
-    // ✅ 新增：驗證是否有 Git commit
-    let has_commits = Command::new("git")
-        .args(&["log", "main..HEAD", "--oneline"])
-        .output()
-        .await?
-        .stdout
-        .len() > 0;
-
-    if !has_commits && result.exit_code == 0 {
-        return Err(SchedulerError::AgentNoOutput {
-            agent_id: agent_id.to_string(),
-            task_id: task_id.to_string(),
-        });
-    }
-
-    Ok(())
-}
-```
-
-#### 3. 超時機制
-```rust
-// 為每個 Agent 設置執行超時
-use tokio::time::{timeout, Duration};
-
-let execution_timeout = Duration::from_secs(60 * 60);  // 1 小時
-
-match timeout(execution_timeout, self.execute_agent(agent_id, task_id)).await {
-    Ok(Ok(_)) => {
-        // 執行成功
-    }
-    Ok(Err(e)) => {
-        // 執行失敗
-        error!("Agent execution failed: {}", e);
-    }
-    Err(_) => {
-        // 超時
-        error!("Agent execution timeout for task {}", task_id);
-        self.mark_task_blocked(task_id, "Execution timeout").await?;
-    }
-}
-```
-
-## 預防措施
-
-### 檢查清單
-
-在任務分配前（Scheduler 層面）：
-- [ ] 驗證 task.skill_path 文件存在
-- [ ] 驗證 task.scope_paths 目錄存在且可訪問
-- [ ] 驗證 Git branch 已建立且可切換
-- [ ] 驗證路徑鎖定可以成功獲取
-
-在 Agent 執行前（Agent 層面）：
-- [ ] 確認已讀取 .memory/CONTEXT.md
-- [ ] 確認任務 ID、Agent ID、Branch 參數正確解析
-- [ ] 確認 Skill 文件已載入並解析成功
-- [ ] 確認目前在正確的 Git branch
-
-在 Agent 執行後（驗證層面）：
-- [ ] 檢查 git log main..HEAD 有無新 commit
-- [ ] 檢查 scope_paths 內有無文件變更
-- [ ] 檢查執行日誌有無錯誤信息
-- [ ] 驗證任務狀態已更新為 completed
-
-### 規則建議
-
-建議建立以下 .rule/ 規則：
-
-#### AGT-005: Agent 輸出驗證規則
-```yaml
-# .rule/general/agent-execution.yaml (新增規則)
-
-AGT-005:
-  title: "Agent 必須產生可驗證的輸出"
-  priority: "critical"
-
-  requirements:
-    - "每個 Agent 執行必須產生至少一個 Git commit"
-    - "Commit message 必須包含 Task ID"
-    - "修改的文件必須在 scope_paths 範圍內"
-
-  validation:
-    pre_execution:
-      - "驗證 skill_path 存在"
-      - "驗證 scope_paths 可訪問"
-      - "驗證 Git branch 正確"
-
-    post_execution:
-      - "git log main..HEAD --oneline | wc -l > 0"
-      - "git diff main --name-only 在 scope_paths 內"
-
-  failure_handling:
-    - "如無 commit，標記任務為 blocked"
-    - "記錄失敗原因到 dev/pipeline/logs/"
-    - "釋放路徑鎖定"
-    - "通知 Scheduler 重新調度"
-```
-
-#### PPL-003: Scheduler 驗證規則
-```yaml
-# .rule/pipeline/scheduler-validation.yaml (新增規則)
-
-PPL-003:
-  title: "Scheduler 必須驗證任務有效性"
-  priority: "high"
-
-  validation_steps:
-    before_assignment:
-      - "檢查 skill_path 存在性"
-      - "檢查 scope_paths 有效性"
-      - "檢查依賴任務已完成"
-      - "檢查路徑鎖定可獲取"
-
-    during_execution:
-      - "每 5 分鐘檢查 Agent 心跳"
-      - "監控輸出日誌大小"
-      - "超時後自動中止進程"
-
-    after_execution:
-      - "驗證有 Git commit"
-      - "驗證任務狀態已更新"
-      - "釋放資源和鎖定"
-```
-
-## 教訓與啟示
-
-### 關鍵教訓
-
-1. **驗證優於信任**
-   - 不能假設 TASK_QUEUE.json 中的數據都是正確的
-   - 必須在執行前驗證所有路徑和文件存在性
-   - 特別是 skill_path，這是 Agent 行為的核心依賴
-
-2. **可觀測性至關重要**
-   - 空輸出比錯誤輸出更難診斷
-   - 必須有心跳機制和進度報告
-   - 日誌需要結構化，便於快速定位問題
-
-3. **超時是必要的防護**
-   - Agent 可能因各種原因卡住
-   - 必須有超時機制自動中止
-   - 超時後必須清理資源（路徑鎖定、Git branch）
-
-4. **失敗恢復機制**
-   - 不能讓一個 Agent 失敗影響整個 Pipeline
-   - 必須有自動清理和恢復機制
-   - blocked 任務應該可以手動或自動重試
-
-### 如何避免類似問題
-
-1. **在 Scheduler 層面**
-   - 實作完整的預執行驗證（見 PPL-003 規則）
-   - 加入執行監控和超時機制
-   - 提供清理工具和恢復命令
-
-2. **在 Agent 層面**
-   - 強制要求載入 CONTEXT.md（見 .rule/general/agent-workflow.yaml）
-   - 執行完必須產生可驗證的輸出（見 AGT-005 規則）
-   - 失敗時必須明確報告原因
-
-3. **在測試層面**
-   - 建立 Scheduler 集成測試
-   - 模擬各種失敗場景（skill_path 不存在、超時、空輸出）
-   - 驗證恢復機制正確運作
-
-4. **在文檔層面**
-   - 更新 .claude/commands/agent-worker.md 說明輸出要求
-   - 在 .failure/INDEX.yaml 記錄此失敗模式
-   - 提供故障排查指南
-
-### 與現有系統整合
-
-此失敗記錄已整合到以下系統：
-
-- **規則系統**：建議建立 AGT-005 和 PPL-003 規則
-- **記憶系統**：已記錄到全局 MEMORY.md（JSON 編輯最佳實踐可參考）
-- **Pipeline 系統**：Scheduler 應該實作此驗證邏輯
-- **失敗系統**：此記錄成為 Agent 執行前必讀的檢查清單
-
----
-
-**最後更新**: 2026-02-05
-**貢獻者**: Developer Agent (TASK_078)
-**狀態**: Resolved - 已提出規則建議和預防機制

package/core/.failure/agent-execution/FAIL-010-phase0-poem-format-skipped.yaml

@@ -1,28 +0,0 @@
-id: "FAIL-010"
-category: "agent_execution"
-severity: "medium"
-date: "2026-03-21"
-title: "Phase 0 記憶之烏鴉歸巢段落持續缺失"
-related_tasks: []
-
-## 失敗描述
-Phase 0 初始化輸出缺少「🪶 記憶之烏鴉歸巢」段落（header + 分隔線 + episode 白話摘要列表）。
-Agent 只輸出裸詩句，每次都只部分完成 cli_format。
-用戶反映「幾乎沒有完整正常進行過」。
-
-## 根本原因
-phase-gate.js Phase 0 enter response 只注入 `poem_stanza`（裸詩句），
-`cli_format`（完整輸出模板含 🪶 header、分隔線、episode 列表格式）從未注入。
-Agent 看到 `poem_stanza` 就只輸出詩句，沒有模板可以參考。
-
-次要原因：`extractBlockScalar` regex 在空行處截斷，導致即使加入 `poem_cli_format`
-也只拿到 cli_format 的前半段（統計表部分），烏鴉段落被截掉。
-
-## 修復
-1. phase-gate.js 加入 `poem_cli_format` 欄位到 Phase 0 enter response
-2. 修復 `extractBlockScalar` 以支援 YAML block scalar 內的空行（改用逐行掃描取代 regex）
-
-## 預防措施
-- phase-gate.js Phase 0 enter 現在同時提供 `poem_stanza` 和 `poem_cli_format`
-- Agent 應以 `poem_cli_format` 為模板，填入實際數據後輸出
-- `poem_cli_format` 包含 🪶 section：若有 episodes → 顯示完整段落；無 episodes → 省略

package/core/.failure/agent-execution/FAIL-010-skipping-cognitive-checkpoint-after-verification.yaml

@@ -1,59 +0,0 @@
-id: FAIL-010
-title: "Ansuz 跳過 Phase 9 cognitive checkpoint — 多任務並行時遺忘認知融合"
-category: agent_execution
-severity: high
-
-description: |
-  Ansuz 在 Phase 9 驗證通過後直接 complete + post-complete，
-  跳過 cognitive_checkpoint（rune/sigil 評估）。
-  三個任務全部未寫入任何 rune 或 sigil，直到用戶指出才補做。
-
-incident:
-  date: "2026-03-18"
-  project: "kenaz-web"
-  context: "TASK_10/11/12 — ControlPlane scroll lock、EngineRoom expo-slider、Step3 mock web 滾動"
-  what_happened: |
-    Ansuz 並行 dispatch 三個任務，每個完成後只做了：
-    驗證 acceptance criteria → complete → post-complete → 回報
-    完全跳過 cognitive_checkpoint。
-    三個任務共解決了 5 個 non-obvious pattern/decision，產出為 0 rune、0 sigil。
-  what_was_missed: |
-    應記錄的知識：
-    - Unified scroll lock pattern (IntersectionObserver + body.position=fixed + wheel/touch)
-    - Interactive embedded content event routing (data-attribute + closest() delegation)
-    - Terminal auto-scroll pattern (scrollRef + useEffect on content changes)
-    - Expo-slider 3D parameters (perspective:1200, rotateY:±35°, translateZ:-250 per offset)
-    - Focus-captures-scroll UX decision (boundary-based → full capture, user-driven pivot)
-
-root_cause: |
-  兩個因素疊加：
-  1. 多任務並行時注意力分散 — 急著驗證下一個完成的任務，把 checkpoint 當可選步驟跳過
-  2. 對 rune 價值的誤判 — 只在「遇到 bug 或風險」時才想到 inscribe，
-     忽略了 pattern 和 decision 級的知識才是最高價值的認知資產
-
-  深層原因：Ansuz 把 cognitive_checkpoint 理解為「有空就做」的軟性建議，
-  而非 workflow.yaml 明確定義的 hard gate。
-
-prevention:
-  rule: "Phase 9 cognitive_checkpoint 是 hard gate，與 acceptance criteria 驗證同級"
-  mental_model: |
-    錯誤模型：「驗證通過 → 完成 → 下一個」
-    正確模型：「驗證通過 → 認知評估 → inscribe/skip（顯式決定）→ 完成」
-
-    cognitive_checkpoint 不是額外工作 — 是 Phase 9 的一部分。
-    跳過它等同於跳過 acceptance criteria 驗證。
-  checklist:
-    - "Phase 9 驗證通過後，必須問：這次有 pattern/decision/fix/risk 值得記錄嗎？"
-    - "多任務並行不是跳過的理由 — 每個任務獨立 checkpoint"
-    - "設計決策和互動模式是 HIGH-VALUE rune 目標，不只是 bug fix"
-    - "3+ symbols 涉及的跨切面模式 → 必須評估是否 forge Sigil"
-    - "顯式 skip：如果真的沒什麼可寫，在回報中寫「cognitive checkpoint: no rune needed」"
-
-  prevention_primary: "workflow.yaml phase_9 已有 cognitive_checkpoint.rule — 問題不是規則缺失而是執行遺忘"
-  prevention_secondary: "Phase 11 回報格式應包含 🧠 認知層更新區塊（即使是空的），強迫 Ansuz 意識到這個步驟"
-  prevention_tertiary: "多任務並行時，每個 Phase 9 開始前 re-read workflow.yaml post-dispatch 區塊（memory_refresh 機制）"
-
-related:
-  - "FAIL-009: 跳過 pulse — 同類問題的上游版本（寫前不查 vs 寫後不記）"
-  - "SYN-008~011: 認知融合規則"
-  - ".rule/general/synapse-cognitive-fusion.yaml"

package/core/.failure/agent-execution/FAIL-012-grep-shortcut-during-investigation.yaml

@@ -1,85 +0,0 @@
-id: FAIL-012
-title: "Agent 在調查/診斷模式下跳過 Synapse 直接用 Grep"
-category: agent_execution
-severity: high
-
-description: |
-  Agent 收到 Bug 報告（截圖/錯誤訊息）後，直接用 Grep 搜精確字串，
-  繞過 Synapse 的語義搜尋和 pulse 分析。
-  理由通常是「我知道要搜什麼字串」「這是精確搜尋，Grep 更適合」。
-  但調查需要的是理解拓撲和關係，不只是找到字串。
-
-incident:
-  date: "2026-03-26"
-  context: "用戶報告 HTTP Server health check 間歇性 timeout，附截圖"
-  what_happened: |
-    Ansuz 看到截圖後：
-    1. 用 synapse_search 找到 checkHealth 和 health_check（正確）
-    2. 但隨即切換到 Grep 搜 "signal timed out" 和 "spawn_blocking"（錯誤）
-    3. 被用戶糾正後才補做 synapse_pulse
-    第 2 步的思維捷徑：「我已經知道要找什麼了，Grep 更快」
-  what_was_missed: |
-    如果先跑 pulse：
-    - checkHealth 的 48 個 impacted symbol 和 43 個 community crossings 會立即可見
-    - 會發現 health_check 有 2 個同名 symbol 需要消歧
-    - 會看到 Real-Time Agent Coordination Bus sigil 的 known_risk 關聯
-    - 語義搜尋能找到 tokio runtime 相關的架構模式（connection pool、blocking patterns）
-    Grep 只能找到你已經猜到的字串 — Synapse 能找到你不知道要找的東西。
-
-root_cause: |
-  FAIL-009 的心理模型修正只覆蓋了「修改代碼前」，
-  但「調查/診斷」是另一個高頻場景，沒有被規則明確覆蓋。
-
-  Agent 的認知分裂：
-  - 修改模式 → 知道要 pulse（FAIL-009 訓練過）
-  - 調查模式 → 覺得「不改代碼，查就好」→ 退化為 Grep
-
-  根因：Synapse-first 規則的措辭聚焦在「修改前」，
-  沒有明確說「調查時也必須 Synapse-first」。
-  Agent 把 Synapse 歸類為「寫代碼的前置步驟」而非「所有代碼認知的入口」。
-
-prevention:
-  rule: |
-    SYN-001 擴展：Synapse 是所有代碼認知的入口，不只是修改前。
-    三個場景都必須 Synapse-first：
-    1. 修改代碼前 → pulse（已有規則）
-    2. 調查/診斷 → synapse_search + pulse 目標 symbol（本次新增）
-    3. 回答「怎麼運作」→ synapse_search（已有規則）
-  mental_model: |
-    Grep 回答「這個字串在哪裡？」
-    Synapse 回答「這個概念的拓撲長什麼樣？」
-    調查 Bug 需要的是拓撲理解，不是字串定位。
-
-    診斷三步驟（強制順序）：
-    Step 1: synapse_search（語義找相關 symbol）
-    Step 2: synapse_pulse（目標 symbol 的爆炸半徑 + 已知風險）
-    Step 3: 需要時才 Grep（精確字串匹配作為補充）
-
-    觸發信號：如果你發現自己在想「我知道要搜什麼字串」—
-    這正是你需要 Synapse 的時候，因為你只知道你知道的，
-    不知道你不知道的。
-  trigger: |
-    任何以下情境都必須走「診斷三步驟」：
-    - 用戶報告 Bug（截圖、錯誤訊息、異常行為）
-    - 調查間歇性問題
-    - 理解一段不熟悉的代碼
-    - 追蹤 error propagation path
-
-checklist:
-  - "收到 Bug 報告後，是否先用 synapse_search 語義搜尋？"
-  - "是否對目標 symbol 執行了 synapse_pulse？"
-  - "Grep 是否只用於補充 Synapse 結果（而非替代）？"
-  - "如果跳過 Synapse，理由是什麼？「已知字串」不是合理理由"
-
-related:
-  rules:
-    - ".rule/general/synapse-code-intelligence.yaml (SYN-001~007)"
-  failures:
-    - "FAIL-009: 跳過 pulse 直接修改代碼（修改場景）"
-    - "FAIL-011: CGDD 選擇性執行（只 pulse 重要的 symbol）"
-  pattern: |
-    FAIL-009 + FAIL-011 + FAIL-012 構成三連擊：
-    - FAIL-009: 修改時跳過 pulse（「太簡單」）
-    - FAIL-011: 修改時選擇性 pulse（「只 pulse 重要的」）
-    - FAIL-012: 調查時完全跳過 Synapse（「不改代碼不需要」）
-    共同根因：把 Synapse 視為「風險工具」而非「認知入口」