docs: 更新 CLAUDE.md + HARD_RULES.md v2.0 + LOGBOOK (2026-04-16)

- HARD_RULES.md v2.0: 新增 Self-Loop Workflow、Circuit Breaker Exception、State & Flow Validation - CLAUDE.md: 補充 §4 必讀Memory 表格 - LOGBOOK: 記錄 AIOps E2E 修復進度 2026-04-16 Claude Sonnet 4.6 Asia/Taipei Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-16 01:09:26 +08:00
parent 3fc2c41216
commit bb7441ec8a
3 changed files with 201 additions and 4 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -73,7 +73,10 @@ Tier 3 核心檔案 (decision_manager, trust_engine, config 等) 修改需首席
 | OpenClaw | `feedback_architecture_openclaw_core.md` |
 | 命名規範 | `feedback_openclaw_naming.md` |
 | i18n | `feedback_i18n_zero_hardcode.md` |
-| 防禦性工程 | `feedback_defensive_engineering.md` |
+| 防禦性工程/狀態機驗證 | `feedback_defensive_engineering.md` |
+| 禁止孤島開發 🔴🔴 | `HARD_RULES.md` → No Island Coding |
+| 主動執行與熔斷 🔴🔴 | `feedback_proactive_execution.md` + `HARD_RULES.md` → Circuit Breaker |
+| 自循環工作流 🔴🔴 | `HARD_RULES.md` → Self-Loop Workflow |
 | 積木化強制 🔴🔴 | `feedback_lewooogo_modular_enforcement.md` |
 | API 整合 | `feedback_api_response_verification.md` |
 | 構建部署 | `feedback_build_from_git_only.md` |
--- a/docs/HARD_RULES.md
+++ b/docs/HARD_RULES.md
@@ -8,11 +8,11 @@

 | 欄位 | 值 |
 |------|-----|
-| **版本** | v1.9 |
+| **版本** | v2.0 |
 | **建立日期** | 2026-03-20 (台北) |
 | **建立者** | Claude Code |
-| **最後修改** | 2026-04-15 (台北) |
-| **修改者** | Claude Code + ogt (ADR-080 AI 自主化飛輪 Phase 退出條件鐵律) |
+| **最後修改** | 2026-04-16 (台北) |
+| **修改者** | Claude Code + ogt (新增孤島開發/主動執行熔斷/自循環工作流/狀態機驗證鐵律) |

 ### 變更紀錄

@@ -28,6 +28,7 @@
 | v1.7 | 2026-04-02 | Claude Code | Phase 24 AI Router 重構規範 (DI/隱私/絞殺者) |
 | v1.8 | 2026-04-03 | Claude Code | 🔴🔴🔴 費用變更強制審批 (統帥指示) |
 | v1.9 | 2026-04-15 | Claude Code + ogt | 🔴🔴🔴 AI 自主化飛輪 Phase 退出條件鐵律 (ADR-080) |
+| v2.0 | 2026-04-16 | Claude Code + ogt | 新增 No Island Coding / 主動執行熔斷機制 / 自循環工作流 / 狀態機驗證鐵律 |

 ---

@@ -54,6 +55,10 @@
 | **AI Router** | **Router import 具體 Provider** | **只依賴 Protocol** | [→ OpenClaw](#openclaw) |
 | **🔴🔴🔴 費用變更** | **擅自切換/新增付費 AI Provider** | **先讀憲法第五章，再請統帥批准** | [→ Cost Change Approval](#cost-change-approval) |
 | **🔴🔴🔴 AI 飛輪 Phase** | **未過退出條件就宣告完成** | **必須逐條驗收 exit conditions** | [→ AI Phase Exit Conditions](#ai-phase-exit-conditions) |
+| **🔴🔴 孤島開發** | **局部最佳化不查 Callers** | **grep 全域掃描後才動手** | [→ No Island Coding](#no-island-coding) |
+| **🔴🔴 熔斷機制** | **不確定就停下來問** | **主動做完，爆炸半徑 >3 模組才熔斷** | [→ 主動執行與熔斷](#proactive-execution--circuit-breaker) |
+| **🔴🔴 工作流節奏** | **每步都來回報** | **內部自循環，全局單次回報** | [→ 自循環工作流](#self-loop-workflow) |
+| **🟡 狀態機驗證** | **不查中間狀態卡死** | **必驗 TTL + Cleanup + Fallback** | [→ State & Flow Validation](#state--flow-validation) |

 ---

@@ -491,6 +496,136 @@ def new_function():

 ---

+---
+
+## 🔴🔴 No Island Coding — 禁止孤島開發
+
+> 任何程式碼修改，必定影響上下游。未經全域檢視的局部最佳化，視為嚴重失職。
+
+### 三條鐵律
+
+| 情境 | 必做動作 |
+|------|---------|
+| **變更函數簽名** | `grep -rn "函數名" apps/ packages/` 找出所有 Callers，一併更新 |
+| **變更資料模型 (DB/Pydantic)** | 同步確認 Write 層、Read 層、Redis Cache 序列化/反序列化邏輯一致 |
+| **任何局部修改** | 禁止「假設它會動」，必須全域掃描才能動手 |
+
+```bash
+# 修改函數前的強制指令
+grep -rn "target_function_name" apps/ packages/ --include="*.py"
+# 列出所有 Caller，逐一確認影響範圍
+```
+
+**與積木化的關係：** No Island Coding 是「橫向」掃描（找所有呼叫者），leWOOOgo 積木化是「縱向」邊界（Router 不能越界）。兩者並行，缺一不可。
+
+---
+
+## 🔴🔴 Proactive Execution & Circuit Breaker — 主動執行與熔斷機制
+
+> 整合 `feedback_proactive_execution.md`（主動執行，2026-04-05）與孤島開發停問規則。
+> **主動執行為絕對預設，停下問是唯一例外。**
+
+### 預設：主動狂奔
+
+看到任務與規格後，**一口氣實作到底**：
+
+```
+✅ 自己寫 Code
+✅ 自己跑測試
+✅ 自己修 Error
+✅ 全部跑通後才回報
+```
+
+```
+❌ 禁止：列出步驟然後問「統帥可不可以開始」
+❌ 禁止：把「不確定」當作不寫 Code 的藉口
+❌ 禁止：拿中間的 Error 來打斷統帥
+```
+
+### 唯一熔斷條件（Circuit Breaker）
+
+**必須同時滿足以下兩個條件**，才可暫停並請求裁示：
+
+1. 修改的檔案是 **Tier 3 核心紅區**（如 `decision_manager.py`、`db/base.py`）
+2. 透過 `grep` 發現這個修改會直接導致 **超過 3 個以上未關聯模組**發生不可預期的 Crash
+
+熔斷時的回報格式：
+```
+發現連鎖爆炸半徑，涉及 [A, B, C]，請求裁示
+```
+
+**其餘所有情況，全部自己解決。**
+
+---
+
+## 🔴🔴 Self-Loop Workflow — 自循環工作流與全局回報
+
+> 四步工作流是 AI 的**內部背景作業**，不是與統帥的來回節奏。
+
+### 內部自循環（不對外打斷）
+
+```
+[1. 影響評估] → [2. 實作] → [3. 串接驗證]
+                                    ↓ Error
+                               [4. 自動修復] → 回到 [3. 串接驗證]
+```
+
+遇到驗證腳本報錯，**必須自動遞迴修復，不得中斷統帥。**
+
+### 全局單次回報（唯一一次）
+
+當整個任務 100% 通過時，進行唯一一次成果彙報，必須包含：
+
+```
+1. 修改了哪些檔案（逐一列出）
+2. 最終成功的終端機輸出（Console Output）
+3. 是否有潛在副作用
+```
+
+等待統帥批准後，才能執行 `git commit` 與 `push`。
+
+### 驗證腳本規範 — Live-Fire Only（實彈演習）
+
+根據 [No Mock Testing](#no-mock-testing) 鐵律，`verify_script.py` **絕對禁止使用任何 Mock 套件**：
+
+```python
+# ❌ 禁止 — 自己 mock 自己測，驗證毫無意義
+from unittest.mock import MagicMock
+db = MagicMock()
+
+# ✅ 正確 — 打真實 PostgreSQL / Redis / HTTP
+async with get_session() as session:
+    result = await session.execute(select(MyModel).where(...))
+
+# 驗證完畢後必須 Teardown，清理測試資料
+await session.execute(delete(MyModel).where(MyModel.id == test_id))
+```
+
+---
+
+## 🟡 State & Flow Validation — 狀態機與流程驗證
+
+修改涉及 **async、background jobs、DB 狀態轉換** 的邏輯時，必須驗證以下清單。
+
+### 必查斷點
+
+| 風險類型 | 必查項目 |
+|---------|---------|
+| **中間狀態卡死** | `PENDING` 是否有機制轉為 `EXPIRED`？`PROCESSING` 超時後誰負責撿起？ |
+| **Fire-and-forget 無聲失敗** | 異步任務失敗時，Exception 是否被吞掉？有無 dead letter / retry？ |
+| **新增資料實體** | TTL 多長？Cleanup Job 是什麼？錯誤降級策略（Fallback）定義了嗎？ |
+| **生命週期完整性** | 建立 → 處理 → 結案 → 清理，四個階段必須全部有對應的程式碼 |
+
+```python
+# 新增資料實體的最低要求
+class MyEntity(Base):
+    expires_at: datetime   # TTL 必填
+    # 對應 Cleanup Job: scheduler/cleanup_expired_entities.py
+    # 降級策略: 超時 → status = EXPIRED → Telegram 告警
+```
+
+---
+
 ## 如何新增規則

 1. 在此文件新增章節
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -6,6 +6,65 @@

 ---

+## 📍 2026-04-15 深夜 — AI 自主化飛輪 Phase 4-6 全完成 + 生產全開 🎉
+
+### Phase 4 異常偵測升級（commit 14a0226，ADR-084）
+
+| 成品 | 路徑 |
+|------|------|
+| TrendPredictor | `services/trend_predictor.py` — statsmodels ARIMA 趨勢預測 |
+| ProactiveInspector | `services/proactive_inspector.py` — 主動巡檢（L1-L4 四層） |
+| 8D 感官升級 | `services/pre_decision_investigator.py` — anomaly_context 增強 |
+
+### Phase 5 修復抽象化（commit 655d1a5，ADR-086）
+
+| 成品 | 路徑 |
+|------|------|
+| BlastRadiusCalculator | `services/blast_radius_calculator.py` — CRITICAL/HIGH/MEDIUM/LOW 分控 |
+| DeclarativeRemediation | `services/declarative_remediation.py` — dry-run → apply 分階段 rollout |
+| GitOpsPRService | `services/gitops_pr_service.py` — 自動 PR 生成 IaC 修復 |
+| RollbackManager | `services/rollback_manager.py` — 自動回滾策略 |
+| DecisionManager 接線 | `AIOPS_P5_BLAST_RADIUS_CHECK` gate 守衛 |
+
+### Phase 6 自我治理閉環（commit 05b7743 + 77a92eb）
+
+| 成品 | 路徑 |
+|------|------|
+| AiSloCalculator | `services/ai_slo_calculator.py` — SLO 計算器 |
+| TrustDriftDetector | `services/trust_drift_detector.py` — 信任度漂移偵測 |
+| KbRotCleaner | `jobs/kb_rot_cleaner.py` — 知識庫腐爛清理 Job |
+| 自我降級引擎 | `services/decision_manager.py` 接線 |
+| SLO REST API | `api/v1/ai_slo.py` — GET /api/v1/ai/slo |
+| OfflineReplayService | `services/offline_replay_service.py` — 離線回放驗證 |
+| ModelRollbackService | `services/model_rollback_service.py` — 模型回滾機制 |
+| DB 表 | `db/models.py` AiGovernanceEvent + 3 index |
+
+### P1-P6 全開（commit 76558a3）
+
+```
+AIOPS_P1_ENABLED=True ... AIOPS_P6_ENABLED=True（全部）
+Nemotron 接線 + offline replay loop 啟動
+```
+
+### 生產修補（全開後，2026-04-15 深夜）
+
+| Commit | 修復內容 |
+|--------|---------|
+| `85c4e3b` | KM 寫入全為 unknown 根因（alertname/affected_services/category 三節點） |
+| `ecfb714` | YAML 規則引擎與自動執行路徑核心斷點接通 |
+| `3696fb5` | host_resource 誤發 K8s kubectl + 自動執行重複風暴 |
+| `67f4370` | 四個生產致命 bug（outcome 寫入/OpenClaw/Telegram/LLM 規則顯示） |
+| `256a24e` | drain3/statsmodels 依賴補入 + warmup skip 舊資料 |
+| `c05bac6` | Playbook seed tuple unpack + text[]→jsonb migration |
+| `da871fc` | AIOps P1/P2/P6 migration SQL 補齊（已 prod 套用） |
+
+### 技術債（下次 Sprint）
+
+- `send_notification()` 未私有化（raw text bypass 可能）
+- `approval_repository.py:find_by_fingerprint()` 無 TTL
+
+---
+
 ## 📍 2026-04-15 — AI 自主化飛輪 Phase 0 防護欄建立

 ### 完成項目