kenaz 0.3.18 → 0.3.20

package/core/.system/rule/README.md

@@ -1,794 +0,0 @@
-# .rule - 規則系統
-
-## 系統概述
-
-`.rule/` 是 Kenaz AI 專案的**最高優先級規則庫**，定義所有 AI Agent 和人類開發者必須遵守的核心約束與標準。
-
-**設計理念**：
-- **規則優先**：凌駕於 `CLAUDE.md`、`.claude/skills/` 之上
-- **模塊化組織**：按領域分類（general、code、design、pipeline 等）
-- **層級式載入**：從核心原則到具體實踐，由上至下載入
-- **嚴重程度分級**：MUST（必須）、SHOULD（應該）、MAY（建議）
-
----
-
-## 規則優先級
-
-當規則發生衝突時，按以下優先級順序執行：
-
-```
-1. .rule/*           ← 最高優先級（所有人必須遵守）
-2. CLAUDE.md         ← 專案級指令與工作流程
-3. .claude/skills/   ← Agent 行為定義
-4. .agents/skills/   ← 外部安裝的最佳實踐
-```
-
-**範例衝突場景**：
-- `.rule/general/project-self-containment.yaml` (GEN-007) 禁止在專案目錄外操作
-- 即使 `CLAUDE.md` 或某個 Skill 要求安裝全局工具，也必須遵守 GEN-007，改為專案內解決方案
-
----
-
-## 目錄結構
-
-```
-.rule/
-├── INDEX.yaml                  # 規則索引與載入順序（核心入口點）
-├── general/                    # 通用規則（所有 Agent 適用）
-│   ├── principles.yaml         # 核心原則（最優先載入）
-│   ├── project-self-containment.yaml  # GEN-007: 專案自包含原則
-│   ├── agent-workflow.yaml     # AGT-001~008: Agent 工作流程規範
-│   ├── sunny-access-control.yaml      # SEC-010: Sunny 存取控制
-│   ├── cortex-memory-recall.yaml      # CTX-001~004: Cortex 記憶回想規則
-│   └── pipeline.yaml           # Pipeline 系統規則
-├── pipeline/                   # Pipeline 專用規則
-│   ├── task-execution.yaml     # PPL-101~112: 任務執行規範（拆分、依賴、並行等）
-│   ├── PPL-002-completed-task-archival.yaml  # 已完成任務封存規則
-│   └── auto-update.yaml        # PPL-003: Pipeline 自動更新規則
-├── code/                       # 代碼規範（按層級組織）
-│   ├── principles.yaml         # 代碼核心原則（模塊化、複用性、可維護性）
-│   ├── naming.yaml             # 命名規則
-│   ├── structure.yaml          # 結構規則（目錄組織、模塊化設計）
-│   ├── reusability.yaml        # 複用性規則（組件/Hook/邏輯複用）
-│   ├── maintainability.yaml    # 可維護性規則（狀態管理、錯誤處理）
-│   ├── style.yaml              # 風格規則（TypeScript、格式化、註釋）
-│   ├── backend.yaml            # 後端規範（API 設計、資料庫、架構分層）
-│   ├── checklist.yaml          # 代碼提交前檢查清單
-│   └── README.md               # 代碼規範說明文檔
-├── design/                     # 設計規範
-│   ├── ui.yaml                 # UI 標準
-│   ├── ux.yaml                 # UX 原則
-│   └── colors.yaml             # 色彩系統
-├── architecture/               # 架構決策（未來擴展）
-│   └── decisions.yaml          # ADR 記錄
-└── business/                   # 業務邏輯約束（未來擴展）
-    └── constraints.yaml
-```
-
----
-
-## 核心規則索引（INDEX.yaml）
-
-所有規則通過 `INDEX.yaml` 統一管理，定義載入順序與優先級。
-
-### 載入順序
-
-規則按以下順序載入（由上至下）：
-
-1. **核心原則** → `general/principles.yaml`
-2. **專案自包含** → `general/project-self-containment.yaml` (GEN-007)
-3. **Agent 工作流程** → `general/agent-workflow.yaml` (AGT-001~008)
-4. **存取控制** → `general/sunny-access-control.yaml` (SEC-010)
-5. **Cortex 記憶回想** → `general/cortex-memory-recall.yaml` (CTX-001~004)
-6. **Pipeline 系統** → `general/pipeline.yaml`
-7. **已完成任務封存** → `pipeline/PPL-002-completed-task-archival.yaml`
-8. **Pipeline 自動更新** → `pipeline/auto-update.yaml` (PPL-003)
-9. **任務執行規範** → `pipeline/task-execution.yaml` (PPL-101~112)
-10. **代碼核心原則** → `code/principles.yaml`
-11. **代碼命名** → `code/naming.yaml`
-12. **代碼結構** → `code/structure.yaml`
-13. **代碼複用性** → `code/reusability.yaml`
-14. **代碼可維護性** → `code/maintainability.yaml`
-15. **代碼風格** → `code/style.yaml`
-16. **後端規範** → `code/backend.yaml`
-17. **代碼檢查清單** → `code/checklist.yaml`
-18. **設計規範** → `design/ui.yaml`, `design/ux.yaml`, `design/colors.yaml`
-19. **架構決策** → `architecture/decisions.yaml`（未來）
-20. **業務約束** → `business/constraints.yaml`（未來）
-
-**重要**：載入順序從最通用的原則開始，逐步深入到具體實踐，確保基礎規則優先於細節規則。
-
----
-
-## 嚴重程度定義
-
-每條規則都標記了嚴重程度（severity），指導 Agent 和開發者的行為：
-
-| 級別 | 說明 | 圖標 | 行為要求 |
-|------|------|------|---------|
-| **MUST** | 必須遵守，違反將導致拒絕合併 | 🔴 | 強制執行，無例外 |
-| **SHOULD** | 應該遵守，除非有合理理由 | 🟡 | 優先遵守，需註明偏離原因 |
-| **MAY** | 建議遵守，可依情況調整 | 🟢 | 參考建議，自由選擇 |
-
-**範例**：
-```yaml
-rules:
-  - id: "GEN-007"
-    severity: "must"  # 🔴 必須遵守
-    title: "專案自包含原則"
-```
-
----
-
-## 適用對象
-
-規則定義了 `applies_to` 字段，指定規則適用範圍：
-
-| 對象 | 說明 |
-|------|------|
-| `ai_agent` | AI Agent（Claude Code、Dev Agent 等） |
-| `human_developer` | 人類開發者 |
-| `ci_cd` | CI/CD Pipeline |
-| `code_review` | Code Review 階段 |
-
-**範例**：
-```yaml
-rules:
-  - id: "PPL-101"
-    applies_to: ["ai_agent", "human_developer"]  # 所有開發者都適用
-```
-
----
-
-## 規則 ID 編號系統
-
-所有規則遵循統一的 ID 編號格式：`<PREFIX>-<NUMBER>`
-
-### 前綴定義（Prefix）
-
-| 前綴 | 領域 | 範圍 | 範例 |
-|------|------|------|------|
-| **GEN** | General | 通用原則（001-099） | GEN-001, GEN-007 |
-| **AGT** | Agent | Agent 工作流程（001-099） | AGT-001, AGT-005, AGT-007 |
-| **PPL** | Pipeline | Pipeline 任務管理（001-199） | PPL-002, PPL-101, PPL-107 |
-| **SEC** | Security | 安全與存取控制（001-099） | SEC-010 |
-| **CTX** | Cortex | Cortex/RAG 系統（001-099） | CTX-001, CTX-002 |
-| **CD** | Code | 代碼規範（001-199） | CD-001, CD-002 |
-| **UI** | UI/UX | 設計規範（001-099） | UI-001（未來） |
-| **DATA** | Data | 數據完整性（001-099） | DATA-001（未來） |
-
-### 編號邏輯
-
-**範圍分配**：
-- **001-099**：基礎規則（核心原則、通用約束）
-- **100-199**：進階規則（具體實踐、細節規範）
-- **200-299**：擴展規則（未來預留）
-
-**範例**：
-```yaml
-# Pipeline 基礎規則（001-099）
-- id: "PPL-002"  # 已完成任務封存
-- id: "PPL-003"  # Pipeline 自動更新
-
-# Pipeline 進階規則（100-199）
-- id: "PPL-101"  # 任務拆分粒度
-- id: "PPL-107"  # 工作啟動前展示計劃
-- id: "PPL-111"  # scope_paths 衝突檢測
-```
-
-### 新增規則 ID 選擇策略
-
-1. **選擇前綴**：根據規則領域選擇對應前綴（GEN/AGT/PPL 等）
-2. **選擇編號範圍**：
-   - 核心原則 → 001-099
-   - 具體實踐 → 100-199
-3. **檢查衝突**：搜尋現有規則避免 ID 重複
-   ```bash
-   grep -r "id: \"PPL-" .rule/
-   ```
-4. **填補空缺**：優先使用空缺的編號（如 PPL-004、AGT-006）
-5. **連續編號**：同類規則使用連續編號（PPL-101, PPL-102, PPL-103）
-
----
-
-## 規則優先級邏輯
-
-### 層級式優先級
-
-規則優先級由 **3 個維度** 決定：
-
-```
-優先級 = severity（嚴重程度）× priority（meta 優先級）× load_order（載入順序）
-```
-
-#### 1. Severity（嚴重程度）
-
-| 級別 | 說明 | 權重 | 行為 |
-|------|------|------|------|
-| **MUST** | 必須遵守 | 🔴 最高 | 強制執行，無例外 |
-| **SHOULD** | 應該遵守 | 🟡 中等 | 優先遵守，需註明偏離原因 |
-| **MAY** | 建議遵守 | 🟢 最低 | 參考建議，自由選擇 |
-
-#### 2. Priority（Meta 優先級）
-
-定義於規則檔案的 `_meta.priority` 字段：
-
-```yaml
-_meta:
-  priority: 0  # 0=最高, 1=高, 2=中, 3=低
-```
-
-| 數值 | 說明 | 適用規則 |
-|------|------|---------|
-| **0** | 最高優先 | 核心原則（GEN-001~007） |
-| **1** | 高優先 | Agent 工作流程（AGT-001~008）、Pipeline 規則（PPL-101~112） |
-| **2** | 中優先 | 代碼規範（CD-001~099）、設計規範（UI-001~099） |
-| **3** | 低優先 | 業務邏輯約束（未來） |
-
-#### 3. Load Order（載入順序）
-
-定義於 `INDEX.yaml` 的 `load_order` 列表，**越早載入優先級越高**。
-
-**範例**：
-```yaml
-load_order:
-  - path: "general/principles.yaml"      # 第 1 順位（優先級最高）
-  - path: "general/agent-workflow.yaml"  # 第 2 順位
-  - path: "pipeline/task-execution.yaml" # 第 N 順位
-```
-
-### 衝突解決範例
-
-**場景**：兩條規則衝突時如何決定？
-
-```yaml
-# 規則 A: GEN-007（專案自包含原則）
-_meta:
-  priority: 0
-  severity: must
-  load_order: 2
-
-# 規則 B: 某個 Skill 要求全局安裝工具
-severity: should
-load_order: N/A（不在 .rule/ 中）
-
-# 結果：GEN-007 優先（.rule/ > .claude/skills/）
-```
-
----
-
-## 重要規則速查
-
-### 通用規則（General）
-
-| 規則 ID | 標題 | 嚴重程度 | 說明 |
-|---------|------|---------|------|
-| **GEN-001** | 規格優先原則 | 🔴 MUST | 開發工作必須以 PRODUCT_SPEC.md 為依據 |
-| **GEN-002** | 簡單優於複雜 | 🟡 SHOULD | 選擇最簡單的解決方案 |
-| **GEN-007** | 專案自包含原則 | 🔴 MUST | 所有操作必須在專案目錄內進行 |
-| **AGT-001** | 記憶點優先 | 🔴 MUST | 任務開始前檢查 .memory/ |
-| **AGT-005** | 失敗經驗查閱 | 🔴 MUST | 失敗時必須查閱 .failure/ |
-| **AGT-007** | 禁止訪問私有配置 | 🔴 MUST | 禁止訪問 ~/.claude/ 等用戶私有目錄 |
-| **AGT-008** | 完成即停止原則 | 🟡 SHOULD | 任務完成後立即停止，不做額外步驟 |
-| **SEC-010** | Sunny 存取控制 | 🔴 MUST | 禁止非 Sunny Agent 存取 .system/sunny/ |
-| **CTX-001** | Cortex 優先 | 🔴 MUST | 「怎麼運作」類問題直接用 Cortex |
-
-### Pipeline 規則
-
-| 規則 ID | 標題 | 嚴重程度 | 說明 |
-|---------|------|---------|------|
-| **PPL-002** | 已完成任務封存 | 🔴 MUST | 任務完成後封存到 .memory/ |
-| **PPL-003** | Pipeline 自動更新 | 🔴 MUST | 任務完成後更新 TASK_QUEUE.json |
-| **PPL-101** | 任務拆分粒度 | 🔴 MUST | 每個任務 15-20 分鐘可完成 |
-| **PPL-102** | 依賴管理規則 | 🔴 MUST | 明確定義 dependencies 字段 |
-| **PPL-103** | 並行執行策略 | 🟡 SHOULD | 無依賴 + 無衝突 → 可並行 |
-| **PPL-105** | agent_type 命名規則 | 🔴 MUST | 使用 Agent 名稱（developer, strategy） |
-| **PPL-106** | Feature ID 自動分配 | 🔴 MUST | 為同功能任務分配 F-XXX ID |
-| **PPL-107** | 工作啟動前展示計劃 | 🔴 MUST | 必須向用戶展示計劃並等待確認 |
-| **PPL-108** | 任務失敗立即報告 | 🔴 MUST | 失敗時立即停止並通知 |
-| **PPL-109** | 階段性 Git Commit | 🔴 MUST | 每個階段建立 commit |
-| **PPL-110** | 任務完成後續動作 | 🔴 MUST | 自動更新 TASK_QUEUE.json 並解除阻塞 |
-| **PPL-111** | scope_paths 衝突檢測 | 🔴 MUST | 並行任務不可有路徑衝突 |
-| **PPL-112** | 驗收標準驗證 | 🔴 MUST | 任務完成後驗證驗收標準 |
-
-### 代碼規則（Code）
-
-| 規則 ID | 標題 | 嚴重程度 | 說明 |
-|---------|------|---------|------|
-| **CD-001** | 模塊化設計 | 🔴 MUST | 單一職責、低耦合 |
-| **CD-002** | 代碼複用優先 | 🟡 SHOULD | 複用現有代碼，避免重複實現 |
-| **CD-003** | 可維護性優先 | 🔴 MUST | 清晰命名、錯誤處理、調試支援 |
-
-完整規則請參閱各分類目錄下的 YAML 檔案。
-
----
-
-## Agent 使用指南
-
-### 任務開始前
-
-1. **讀取規則索引**：
-   ```bash
-   cat .rule/INDEX.yaml
-   ```
-
-2. **檢查相關規則**：
-   ```bash
-   # 根據任務類型檢查對應規則
-   cat .rule/general/agent-workflow.yaml  # 所有 Agent 必讀
-   cat .rule/pipeline/task-execution.yaml  # Pipeline 任務必讀
-   cat .rule/code/checklist.yaml          # 代碼提交前必讀
-   ```
-
-3. **檢查失敗經驗**（AGT-005）：
-   ```powershell
-   .\.failure\tools\check_failures.ps1 -TaskID "TASK_XXX"
-   ```
-
-### 任務執行中
-
-- **遵守核心規則**：所有 🔴 MUST 規則必須嚴格遵守
-- **路徑衝突檢測**（PPL-111）：並行任務前檢查 scope_paths
-- **自包含原則**（GEN-007）：所有操作在專案目錄內進行
-
-### 任務完成後
-
-- **Pipeline 自動更新**（PPL-003）：更新 TASK_QUEUE.json
-- **任務封存**（PPL-002）：移動已完成任務到 .memory/
-- **記憶點新增**（AGT-001）：記錄重要決策與經驗
-
----
-
-## 規則版本與更新
-
-**元資料**（定義於 `INDEX.yaml`）：
-- **版本**：v1.0.0
-- **最後更新**：2026-02-06T22:10:00+08:00
-
-**更新流程**：
-1. 修改對應規則檔案（如 `code/naming.yaml`）
-2. 更新 `INDEX.yaml` 中的 `last_updated` 時間戳
-3. 如有新規則檔案，加入到 `load_order` 列表
-4. 建立 Git commit：`[RULE] 簡短描述`
-
----
-
-## 與其他系統的關係
-
-### 規則優先級體系
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                   規則優先級體系                         │
-│                                                          │
-│  1️⃣  .rule/*               ← 最高優先級（強制約束）      │
-│  ├─ general/               ← 所有人必須遵守              │
-│  ├─ code/                  ← 代碼開發必須遵守            │
-│  └─ pipeline/              ← Pipeline 任務必須遵守       │
-│                                                          │
-│  2️⃣  CLAUDE.md             ← 專案級指令與工作流程        │
-│                                                          │
-│  3️⃣  .claude/skills/       ← Agent 行為定義              │
-│                                                          │
-│  4️⃣  .agents/skills/       ← 外部最佳實踐（參考）        │
-│                                                          │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 與 .failure/ 的關係
-
-**失敗學習系統** (`.failure/`) 記錄已發生的失敗經驗：
-
-```
-失敗 → 記錄到 .failure/ → 分析根因 → 重複發生（>2 次）→ 提升為 .rule/
-```
-
-**範例**：
-- FAIL-003（TASK_QUEUE 污染）→ 提升為 PPL-002（已完成任務封存規則）
-
-### 與 .memory/ 的關係
-
-**記憶系統** (`.memory/`) 儲存開發經驗與決策：
-
-```
-.rule/ (強制約束) > .failure/ (應避免模式) > .memory/ (經驗記錄)
-```
-
-**使用流程**：
-1. 檢查 `.rule/`（必須遵守）
-2. 檢查 `.failure/`（避免重複錯誤）
-3. 查詢 `.memory/`（參考歷史經驗）
-
----
-
-## 常見問題（FAQ）
-
-### Q1: 規則衝突時怎麼辦？
-
-**A**: 遵循優先級順序。`.rule/` 優先於 `CLAUDE.md`，`CLAUDE.md` 優先於 `.claude/skills/`。
-
-### Q2: 如何新增規則？
-
-**A**: 參考下方「新增規則完整流程」章節。
-
-### Q3: MUST 規則可以違反嗎？
-
-**A**: 不可以。🔴 MUST 規則是強制約束，違反將導致任務失敗或 Pull Request 被拒絕。
-
-### Q4: 規則適用於哪些對象？
-
-**A**: 根據 `applies_to` 字段決定：
-- `ai_agent`：所有 AI Agent
-- `human_developer`：人類開發者
-- `ci_cd`：CI/CD Pipeline
-- `code_review`：Code Review 階段
-
-### Q5: 規則如何與 Cortex 整合？
-
-**A**: Agent 在任務開始前會透過 Cortex 系統載入相關規則：
-```bash
-# Cortex 自動載入高優先級規則
-node .cortex/api/context.js --task-id TASK_XXX
-```
-
----
-
-## 新增規則完整流程
-
-### 流程概覽
-
-```
-識別需求 → 選擇分類 → 分配 ID → 撰寫規則 → 更新索引 → 測試驗證 → 提交 Commit
-```
-
-### 詳細步驟
-
-#### 1. 識別需求
-
-**確認是否需要新增規則**：
-- 是否為重複出現的問題（>2 次）？
-- 是否需要強制約束所有 Agent/開發者？
-- 是否已在 `.failure/` 中記錄為失敗模式？
-
-**範例**：
-```
-問題：Multi-Agent 並行開發時，多個 Agent 同時修改同一檔案導致 Git 衝突
-結論：需要新增規則（PPL-111: scope_paths 衝突檢測）
-```
-
-#### 2. 選擇分類與 ID
-
-**步驟 A：選擇分類目錄**
-
-根據規則性質選擇目錄：
-- 通用原則 → `general/`
-- Agent 工作流程 → `general/agent-workflow.yaml`
-- Pipeline 任務 → `pipeline/`
-- 代碼規範 → `code/`
-- 設計規範 → `design/`
-
-**步驟 B：分配規則 ID**
-
-1. 選擇前綴（GEN/AGT/PPL/SEC/CTX/CD/UI/DATA）
-2. 選擇編號範圍（001-099 基礎，100-199 進階）
-3. 檢查現有 ID，避免衝突：
-   ```bash
-   grep -r "id: \"PPL-" .rule/
-   ```
-4. 填補空缺或使用連續編號
-
-**範例**：
-```yaml
-# 新增 Pipeline 進階規則
-id: "PPL-111"  # scope_paths 衝突檢測
-```
-
-#### 3. 撰寫規則檔案
-
-**模板**：
-```yaml
-# .rule/<category>/<file-name>.yaml
-# <規則簡短描述>
-
-_meta:
-  category: "<category>"  # general/pipeline/code/design
-  priority: 1             # 0=最高, 1=高, 2=中, 3=低
-  applies_to:
-    - "ai_agent"          # ai_agent/human_developer/ci_cd/code_review
-  last_updated: "YYYY-MM-DD"
-  description: |
-    規則集的總體描述
-
-rules:
-  - id: "<PREFIX>-<NUMBER>"
-    title: "規則標題"
-    description: |
-      詳細描述規則內容、適用場景、具體要求
-    severity: "must"  # must/should/may
-    rationale: "為什麼需要這條規則（理由與效益）"
-
-    # 可選字段
-    examples:
-      - good: "正確做法範例"
-      - bad: "錯誤做法範例"
-
-    workflow:
-      - step: 1
-        action: "具體步驟"
-        required: true
-
-    anti_patterns:
-      - "應避免的模式"
-
-    checklist:
-      - item: "檢查項目"
-        importance: "critical"
-```
-
-**實際範例**（PPL-111）：
-```yaml
-# .rule/pipeline/task-execution.yaml
-
-rules:
-  - id: "PPL-111"
-    title: "scope_paths 衝突檢測"
-    description: |
-      Lead Agent 啟動任務前必須檢測：
-      - 讀取所有 in_progress 任務的 scope_paths
-      - 檢查新任務的 scope_paths 是否衝突
-      - 衝突定義：路徑重疊（包含或被包含）
-
-      衝突處理：
-      - 有衝突 → 等待衝突任務完成
-      - 無衝突 → 啟動新任務
-    severity: "must"
-    rationale: "防止多個 Agent 同時修改相同文件，避免 Git 衝突"
-    examples:
-      - conflict: |
-          - TASK_A: scope_paths: [".rule/pipeline/"]
-          - TASK_B: scope_paths: [".rule/pipeline/task-execution.yaml"]
-          → 衝突（B 包含在 A 中）
-      - no_conflict: |
-          - TASK_A: scope_paths: [".rule/pipeline/"]
-          - TASK_B: scope_paths: [".rule/general/"]
-          → 無衝突（路徑不重疊）
-```
-
-#### 4. 更新 INDEX.yaml
-
-在 `load_order` 列表中加入新規則：
-
-```yaml
-load_order:
-  # 現有規則...
-
-  - path: "pipeline/task-execution.yaml"
-    description: "PPL-101 至 PPL-112 - Pipeline 任務執行規範（拆分、依賴、並行等）"
-
-  # 新增規則在此加入
-```
-
-**注意載入順序**：
-- 核心原則在最前面
-- 依賴性規則按依賴關係排序
-- 同類規則放在一起
-
-#### 5. 測試驗證
-
-**檢查清單**：
-- [ ] YAML 語法正確（無縮進錯誤）
-- [ ] 規則 ID 無衝突（唯一性）
-- [ ] `severity` 字段正確（must/should/may）
-- [ ] `applies_to` 字段明確
-- [ ] `INDEX.yaml` 載入順序合理
-- [ ] 範例清晰易懂
-
-**驗證命令**：
-```bash
-# YAML 語法檢查
-node -e "const yaml = require('yaml'); const fs = require('fs'); yaml.parse(fs.readFileSync('.rule/pipeline/task-execution.yaml', 'utf8'))"
-
-# 檢查規則 ID 唯一性
-grep -r "id: \"PPL-111\"" .rule/
-```
-
-#### 6. 提交 Git Commit
-
-```bash
-git add .rule/
-git commit -m "[RULE] 新增 PPL-111: scope_paths 衝突檢測規則
-
-- 防止並行任務修改相同文件
-- 新增衝突檢測邏輯與範例
-- 更新 INDEX.yaml 載入順序
-"
-```
-
-### 新增規則檢查清單
-
-**必填字段**：
-- [ ] `id` - 規則 ID（格式正確，無衝突）
-- [ ] `title` - 規則標題（簡短明確）
-- [ ] `description` - 規則描述（詳細清晰）
-- [ ] `severity` - 嚴重程度（must/should/may）
-- [ ] `rationale` - 理由說明（為什麼需要）
-- [ ] `_meta.category` - 分類（general/pipeline/code/design）
-- [ ] `_meta.priority` - 優先級（0-3）
-- [ ] `_meta.applies_to` - 適用對象（ai_agent/human_developer 等）
-
-**推薦字段**：
-- [ ] `examples` - 範例（good/bad）
-- [ ] `workflow` - 操作流程（step-by-step）
-- [ ] `checklist` - 檢查清單
-- [ ] `anti_patterns` - 反模式（應避免的做法）
-
----
-
-## 規則與 .failure 的升級機制
-
-### 系統關係
-
-```
-.failure/ (失敗記錄) → 重複發生 (>2 次) → .rule/ (強制規則)
-```
-
-**設計理念**：
-- **失敗經驗** (`.failure/`)：記錄已發生的錯誤，提供解決方案
-- **強制規則** (`.rule/`)：將重複失敗模式提升為約束，防止再次發生
-
-### 升級流程
-
-#### 階段 1：記錄失敗（Agent 執行）
-
-當任務失敗時，Agent 必須：
-1. 記錄失敗到 `.failure/<category>/FAIL-XXX_*.md`
-2. 填寫失敗模板（描述、根因、解決方案、預防措施）
-3. 在「規則建議」章節提出潛在規則
-
-**範例**（FAIL-003）：
-```markdown
-# [FAIL-003] TASK_QUEUE 污染問題
-
-## 規則建議
-如果此失敗模式重複出現，建議建立 .rule/ 規則：
-- 規則 ID: PPL-002
-- 規則描述: 已完成任務必須封存到 .memory/
-- 嚴重程度: must
-```
-
-#### 階段 2：追蹤重複發生（Product Manager）
-
-**觸發條件**：
-- 相同失敗模式出現 **>2 次**
-- 影響範圍廣（多個 Agent 或任務）
-- 修復成本高（>1 小時）
-
-**檢查方式**：
-```bash
-# 檢查失敗記錄統計
-cat .failure/INDEX.yaml | grep "total_failures"
-
-# 搜尋相同根因的失敗
-grep -r "TASK_QUEUE 污染" .failure/
-```
-
-#### 階段 3：建立規則（Product Manager）
-
-**步驟**：
-1. 從失敗記錄中提取「規則建議」章節
-2. 依照「新增規則完整流程」建立規則
-3. 引用失敗記錄作為背景
-
-**範例**（PPL-002）：
-```yaml
-# .rule/pipeline/PPL-002-completed-task-archival.yaml
-
-rules:
-  - id: "PPL-002"
-    title: "已完成任務必須封存"
-    description: |
-      所有 completed 狀態的任務必須封存到 .memory/completed/
-      不可留在 dev/pipeline/completed/ 或 TASK_QUEUE.json 中
-    severity: "must"
-    rationale: |
-      防止 TASK_QUEUE 被歷史任務污染（參考 FAIL-003）
-      確保 Multi-Agent Scheduler 只處理當前任務
-
-    background:
-      failure_record: "FAIL-003: TASK_QUEUE 污染問題"
-      occurrence_count: 3
-      last_occurred: "2026-02-06"
-```
-
-#### 階段 4：更新失敗記錄（標記已升級）
-
-在失敗記錄中標記已轉化為規則：
-
-```markdown
-# [FAIL-003] TASK_QUEUE 污染問題
-
-_meta:
-  converted_to_rule: true
-  rule_id: "PPL-002"
-  converted_at: "2026-02-06"
-
-## 規則建議
-✅ **已轉化為規則**：PPL-002（已完成任務必須封存）
-```
-
-#### 階段 5：監控規則效果
-
-**檢查項目**：
-- [ ] 新規則是否防止了失敗重複發生？
-- [ ] Agent 是否正確遵守規則？
-- [ ] 規則是否需要調整（severity/description）？
-
-**監控週期**：規則建立後 1 週內每日檢查
-
-### 升級統計
-
-在 `.failure/INDEX.yaml` 中記錄轉化統計：
-
-```yaml
-statistics:
-  total_failures: 6
-  converted_to_rules: 2  # 已轉化為 .rule/ 規則
-
-  conversions:
-    - failure_id: "FAIL-003"
-      rule_id: "PPL-002"
-      converted_at: "2026-02-06"
-    - failure_id: "FAIL-001"
-      rule_id: "AGT-006"
-      converted_at: "2026-02-05"
-```
-
-### 升級決策矩陣
-
-| 失敗次數 | 影響範圍 | 修復成本 | 行動 |
-|---------|---------|---------|------|
-| 1 次 | 單一任務 | <30 分鐘 | 記錄到 .failure/，觀察 |
-| 2 次 | 單一 Agent | <1 小時 | 記錄，考慮建立規則 |
-| >2 次 | 多個 Agent | >1 小時 | **必須建立規則** |
-| >3 次 | 系統級 | >2 小時 | **Critical 規則，立即建立** |
-
-### 範例：完整升級流程
-
-**背景**：Multi-Agent 並行開發時，3 次因路徑衝突導致 Git 衝突
-
-```
-2026-02-01: FAIL-XXX 記錄第 1 次路徑衝突
-2026-02-03: FAIL-XXX 更新（第 2 次發生）
-2026-02-05: FAIL-XXX 更新（第 3 次發生）→ 觸發升級
-    ↓
-2026-02-06: 建立 PPL-111 規則（scope_paths 衝突檢測）
-    ↓
-2026-02-07: 更新 FAIL-XXX（標記已轉化）
-    ↓
-2026-02-08~14: 監控規則效果（無新衝突）→ 規則有效 ✅
-```
-
----
-
-## 相關文檔
-
-| 文檔 | 路徑 | 說明 |
-|------|------|------|
-| **規則索引** | `.rule/INDEX.yaml` | 所有規則的載入順序與元資料 |
-| **代碼規範** | `.rule/code/README.md` | 代碼規則詳細說明 |
-| **失敗學習系統** | `.system/failure/README.md` | 失敗經驗記錄與工具 |
-| **記憶系統** | `.memory/CORTEX_GUIDE.md` | Cortex 整合指南 |
-| **CLAUDE.md** | `CLAUDE.md` | 專案級指令與工作流程 |
-
----
-
-## 更新記錄
-
-| 日期 | 版本 | 更新內容 |
-|------|------|---------|
-| 2026-02-20 | v1.1.0 | 新增規則 ID 編號系統、規則優先級邏輯、新增規則完整流程、規則與 .failure 升級機制 |
-| 2026-02-19 | v1.0.0 | 初始版本，建立規則系統基礎文檔 |
-
----
-
-*建立日期: 2026-02-19 | 當前版本: v1.1.0 | 最後更新: 2026-02-20*