docs(slo+ops): SLO-SLI 定義文件 + Human-in-the-Loop 規格書 v1.0

補建業界標準 P0 文件（量尺 + 煞車）：

SLO-SLI-DEFINITION.md:
- 5 個 SLI 定義（成功率/延遲/可用性/KM沉澱/送達率）
- SLO 目標值表（及格線 + 卓越線）
- Error Budget 規則（充裕/注意/警戒/耗盡 4 級）
- SLO 違規告警規則（連結 TYPE-8M 飛輪告警）
- 里程碑目標（4 個 Phase 演進路線）

HUMAN-IN-THE-LOOP.md:
- 9 種人工介入觸發條件（HITL-1 ~ HITL-9）
- 破壞性操作強制人工清單（scale=0, delete pvc 等）
- Fail-safe 逾時行為（0→15→30→35 分鐘升級）
- Kill Switch 三種啟動方式（Telegram/API/EnvVar）
- 人工接管標準 SOP（情境 A/B/C）
- 人工介入記錄規範（alert_operation_log 格式）

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

docs/operations/HUMAN-IN-THE-LOOP.md

@@ -0,0 +1,285 @@
+# AWOOOI Human-in-the-Loop 規格書
+
+> **文件類型**: 人工介入標準操作程序（Human-in-the-Loop Specification）  
+> **版本**: v1.0  
+> **建立日期**: 2026-04-14（台北時間）  
+> **建立者**: Claude Sonnet 4.6（首席架構師）+ 統帥確認  
+> **核心問題**: AI 判斷錯了、超時沒決定、或系統失控時，人類如何接管？
+
+---
+
+## 0. 設計哲學
+
+> **AI 是副駕駛，統帥是機長。**
+
+AWOOOI AIOps 的設計原則：
+
+- AI **永遠可以被人類覆蓋**，任何時候
+- **高風險操作**（P0/P1）必須人工確認，不例外
+- AI 超時或信心不足時，系統**主動交還控制權**，不沉默失敗
+- **Kill Switch** 永遠可用，一鍵讓 AI 停止所有自動操作
+
+---
+
+## 1. 人工介入觸發條件（When）
+
+### 觸發矩陣
+
+| 情況 | 觸發條件 | 系統行為 | 介入方式 |
+|------|---------|---------|---------|
+| **HITL-1** | 風險等級 P0（CRITICAL） | 強制人工審核 | Telegram 審核卡 |
+| **HITL-2** | 風險等級 P1（HIGH） | 強制人工審核 | Telegram 審核卡 |
+| **HITL-3** | AI 信心度 < 0.65 | 無法自動執行 | TYPE-4 通知，等人決定 |
+| **HITL-4** | LLM 超時（> 25s） | 降級 Expert System | Expert System 決策，低信心 → 人工 |
+| **HITL-5** | 破壞性操作檢測 | 強制升級為人工 | TYPE-3 審核卡，含警告標示 |
+| **HITL-6** | 審核逾時（> 30 分鐘）| 自動升級通知 | P0 告警發至統帥 + SRE 群組 |
+| **HITL-7** | 自動修復連續失敗 2 次 | 停止重試 | TYPE-4 通知，等人接手 |
+| **HITL-8** | SLO-1 < 50%（連續 2h） | 飛輪異常 | TYPE-8M 告警，建議暫停自動修復 |
+| **HITL-9** | Kill Switch 啟動 | 立即凍結所有自動操作 | 無自動行為，等人工重啟 |
+
+### 破壞性操作關鍵字（HITL-5 觸發清單）
+
+以下任一 kubectl 命令出現 → 強制人工審核，不論信心度：
+
+```
+scale ... --replicas=0   ← 縮容至零（服務停止）
+delete pod               ← 刪除 Pod（短暫中斷）
+delete deployment        ← 刪除部署（資料風險）
+delete pvc               ← 刪除持久磁碟（資料永久消失）
+delete namespace         ← 刪除命名空間（災難性）
+rm -rf                   ← 主機層刪除（絕對禁止）
+DROP TABLE               ← 資料庫破壞性操作（絕對禁止）
+```
+
+---
+
+## 2. 誰來介入（Who）
+
+### 介入層級
+
+```
+Level 1 — 統帥（最終決策者）
+  角色: ogt（系統擁有者）
+  Telegram: 個人 DM（OPENCLAW_TG_CHAT_ID）
+  負責: 所有 P0/P1 審核、Kill Switch、重大策略決定
+
+Level 2 — SRE On-call（未來擴充）
+  角色: 待定（目前只有統帥）
+  Telegram: SRE 群組（SRE_GROUP_CHAT_ID）
+  負責: P2 例行審核、監控告警響應
+
+Level 3 — AI 系統（降級自動處理）
+  角色: OpenClaw + Expert System
+  負責: P3（低風險）自動執行，無需人工
+```
+
+### 當前實際狀態（2026-04-14）
+
+```
+統帥 = Level 1 + Level 2（一人承擔所有層級）
+AI   = Level 3（P3 自動，P0/1/2 部分自動）
+```
+
+---
+
+## 3. 怎麼介入（How）
+
+### 3.1 Telegram 審核卡操作
+
+當系統發送 TYPE-3 審核卡到統帥個人 DM：
+
+```
+╔══════════════════════════════════════╗
+║  🔧 需要您的決策                       ║
+║                                      ║
+║  告警: KubePodCrashLooping           ║
+║  目標: awoooi-api @ awoooi-prod      ║
+║  風險: 🟡 MEDIUM                     ║
+║  AI信心: 82%                         ║
+║  建議動作: kubectl rollout restart    ║
+║             deployment/awoooi-api    ║
+║  影響估計: ~30s 服務中斷              ║
+║                                      ║
+║  [ ✅ 批准執行 ]  [ ❌ 拒絕 ]         ║
+║  [ 🔍 查看詳情 ]  [ 📋 Postmortem ]  ║
+╚══════════════════════════════════════╝
+```
+
+**批准後**：系統立即執行，並發送執行結果通知  
+**拒絕後**：Incident 標記為 `human_rejected`，不再自動重試  
+**不操作**：30 分鐘後觸發 HITL-6（逾時升級）
+
+### 3.2 Fail-safe 逾時行為（HITL-6 細節）
+
+```
+審核卡發出後：
+
+  0 分鐘:  審核卡發送到個人 DM
+  15 分鐘: 提醒訊息（同一個 DM）:
+           "⚠️ 此審核已等待 15 分鐘，請盡快處理"
+  30 分鐘: 升級告警發送到 SRE 群組:
+           "🔴 審核逾時！Incident #XXX 已等待 30 分鐘未處理
+            若不處理，系統將在 5 分鐘後自動標記為 ESCALATED"
+  35 分鐘: Incident 狀態 → ESCALATED
+           記錄到 alert_operation_log（事後可查）
+           不執行任何破壞性操作（Fail-safe：寧可不動也不亂動）
+```
+
+**重要**：AWOOOI 的 Fail-safe 預設行為是**不執行**，而非自動執行。
+若 AI 不確定或人類沒有回應，系統**保持現狀**，不主動改變任何東西。
+
+### 3.3 人工直接操作（繞過 AI）
+
+統帥可以隨時直接操作，AI 不會干預：
+
+```bash
+# 直接 kubectl 操作（AI 不知道，但 AWOOOI 不阻擋）
+kubectl rollout restart deployment/awoooi-api -n awoooi-prod
+
+# 透過 AWOOOI API 手動觸發（有記錄）
+POST /api/v1/approvals/{id}/manual-execute
+  Authorization: Bearer {token}
+  Body: {"reason": "AI 判斷錯誤，手動修復"}
+```
+
+---
+
+## 4. Kill Switch（緊急停止）
+
+### 4.1 Kill Switch 是什麼
+
+Kill Switch = 立即凍結 AWOOOI 所有自動操作的緊急機制。
+
+啟動後：
+- ✅ 繼續接收告警（不停止監控）
+- ✅ 繼續發送通知（讓統帥知道發生什麼）
+- ❌ 停止所有自動執行（kubectl / SSH）
+- ❌ 停止所有自動批准（AutoApprovePolicy 凍結）
+- ❌ 停止新 DecisionToken 進入執行階段
+
+### 4.2 如何啟動 Kill Switch
+
+**方法 1：Telegram 指令**（推薦，最快）
+```
+在個人 DM 輸入：
+/kill_switch enable
+
+系統回應：
+🛑 KILL SWITCH 已啟動
+  - 所有自動執行已凍結
+  - 現有 pending 審核不受影響
+  - 統帥可手動批准個別操作
+  - 輸入 /kill_switch disable 解除
+```
+
+**方法 2：API 呼叫**
+```bash
+curl -X POST https://api.awoooi.internal/api/v1/system/kill-switch \
+  -H "Authorization: Bearer {admin_token}" \
+  -d '{"enabled": true, "reason": "系統異常，緊急凍結"}'
+```
+
+**方法 3：環境變數（重啟後生效）**
+```bash
+# 在 K8s ConfigMap 設定
+AIOPS_AUTO_EXECUTE_ENABLED=false
+```
+
+### 4.3 Kill Switch 啟動場景
+
+| 場景 | 建議行動 |
+|------|---------|
+| AI 連續執行錯誤動作 | 立即啟動，調查根因 |
+| 生產環境重大變更前 | 啟動 Kill Switch，變更完成後解除 |
+| SLO-1 連續 4h < 30% | 評估啟動（飛輪嚴重異常） |
+| 不明告警風暴（10 分鐘 > 50 個） | 啟動 + 調查聚合引擎是否失效 |
+| 週末/假日不在線 | 可啟動，讓系統進入純監控模式 |
+
+---
+
+## 5. 人工接管標準流程（SOP）
+
+### 情境 A：收到 TYPE-3 審核卡
+
+```
+Step 1: 閱讀審核卡（告警類型、目標、AI 建議動作、風險評估）
+Step 2: 若不確定，點擊「查看詳情」查看完整 AI 分析
+Step 3: 判斷：
+  - AI 建議合理 + 風險可接受 → 批准
+  - AI 建議有疑慮 → 拒絕，手動研究後再決定
+  - 看不懂 → 拒絕，kubectl describe 自己看
+Step 4: 不論批准或拒絕，系統都會記錄到 alert_operation_log
+```
+
+### 情境 B：自動修復失敗，AI 交還控制
+
+```
+Step 1: 收到 TYPE-4 通知（AI 無法判斷或已重試 2 次）
+Step 2: 查看 Incident 詳情（/api/v1/incidents/{id}）
+Step 3: 手動分析根因（kubectl logs / describe）
+Step 4: 手動執行修復命令
+Step 5: 確認服務恢復後，在 AWOOOI UI 標記 Incident 為 RESOLVED
+```
+
+### 情境 C：發現 AI 判斷持續錯誤
+
+```
+Step 1: 啟動 Kill Switch
+Step 2: 查看最近 N 個錯誤 DecisionToken 的 reasoning
+Step 3: 識別根因（Prompt 問題？LLM 模型切換？規則配置錯誤？）
+Step 4: 修復根因（可能需要更新 alert_rules.yaml 或 Playbook）
+Step 5: 在 staging 環境驗證（用 DRY_RUN=true）
+Step 6: 解除 Kill Switch，觀察 1 小時
+```
+
+---
+
+## 6. 人工介入記錄規範
+
+所有人工介入必須記錄到 `alert_operation_log`，欄位包含：
+
+```python
+{
+  "event_type": "human_intervention",
+  "action": "approved" | "rejected" | "manual_execute" | "kill_switch",
+  "actor": "統帥",
+  "actor_role": "owner",
+  "reason": "string（人工填寫）",
+  "approval_id": "uuid（若有）",
+  "incident_id": "string（若有）",
+  "timestamp": "2026-04-14T08:00:00+08:00",  # 台北時間
+}
+```
+
+這些記錄用於：
+- Postmortem 自動組裝時間軸
+- SLO 計算（區分 AI 自動 vs 人工介入）
+- 飛輪學習（識別 AI 哪裡判斷錯，更新 Playbook）
+
+---
+
+## 7. 與系統各層的接點
+
+| 系統層 | Human-in-the-Loop 接點 |
+|-------|----------------------|
+| `webhooks.py` | Kill Switch 檢查（進入決策前） |
+| `auto_approve.py` | P0/P1 強制人工路由 |
+| `decision_manager.py` | LLM 超時 → Expert System → 信心不足 → TYPE-4 |
+| `approval_execution.py` | 重試失敗 → TYPE-4 交還人工 |
+| `telegram_gateway.py` | 審核卡 + 逾時提醒 + Kill Switch 指令接收 |
+| `incident_service.py` | 人工標記 RESOLVED / ESCALATED |
+
+---
+
+## 8. 未來擴充計畫
+
+| 功能 | 說明 | 時程 |
+|------|------|------|
+| 審核逾時自動降級（保守） | 超過 60 分鐘 → 自動執行最低風險操作 | Phase 3 後評估 |
+| 多人簽核（Multi-Sig） | P0 需要 2 人確認 | 待統帥指示 |
+| 行動 App 通知 | iOS 通知支援 | 低優先 |
+| SRE On-call 輪值 | 第二個人類接管層 | 未來需求 |
+
+---
+
+*最後更新: 2026-04-14 台北時間 | 建立者: Claude Sonnet 4.6 + 統帥*

docs/slo/SLO-SLI-DEFINITION.md

@@ -0,0 +1,240 @@
+# AWOOOI AIOps SLO/SLI 定義文件
+
+> **文件類型**: 服務層級目標（Service Level Objectives）  
+> **版本**: v1.0  
+> **建立日期**: 2026-04-14（台北時間）  
+> **建立者**: Claude Sonnet 4.6（首席架構師）+ 統帥確認  
+> **審查週期**: 每月第一週複查，重大事件後即時更新  
+> **權威性**: 本文件是 AWOOOI 系統「好不好」的唯一量尺
+
+---
+
+## 0. 為什麼需要 SLO？
+
+> **沒有量尺，就不知道飛輪轉得好不好。**
+
+在自動化系統中，以下問題沒有 SLO 就無法回答：
+
+- 「今天的自動修復成功率算好還是算差？」
+- 「上週比這週好多少？」
+- 「現在該出手介入了嗎？還是讓系統自己處理？」
+- 「我們的 Error Budget 還剩多少？能不能再做一次有風險的部署？」
+
+SLO 把「系統表現好壞」從**主觀感受**變成**可量化的數字**。
+
+---
+
+## 1. SLI 定義（Service Level Indicators — 量什麼）
+
+> SLI = 我們用來量測系統健康狀態的**指標**
+
+### SLI-1：自動修復執行成功率
+
+```
+定義: 在給定時間窗口內，auto_repair 執行成功次數 / 總執行次數
+
+計算:
+  分子: ApprovalRequest.execution_success = True 的筆數
+  分母: ApprovalRequest.execution_success IS NOT NULL 的筆數
+
+查詢:
+  SELECT
+    COUNT(*) FILTER (WHERE execution_success = true) * 100.0 /
+    COUNT(*) FILTER (WHERE execution_success IS NOT NULL)
+  FROM approval_requests
+  WHERE created_at >= NOW() - INTERVAL '24 hours';
+
+單位: 百分比（%）
+時間窗口: 24 小時滾動 / 7 天滾動
+```
+
+### SLI-2：告警分析延遲（從告警進入到 Telegram 卡片發出）
+
+```
+定義: webhook 接收告警 → Telegram 卡片成功發出的時間
+
+計算:
+  開始: POST /webhooks/alerts 收到請求時間戳
+  結束: Telegram sendMessage API 成功回應時間戳
+
+目前測量方式:
+  - Langfuse trace duration（已整合）
+  - structlog "telegram_card_sent" 與 "alertmanager_received" 的 delta
+
+單位: 秒（s）
+時間窗口: P50 / P95 / P99 百分位數
+```
+
+### SLI-3：決策引擎可用性（LLM 路徑成功率）
+
+```
+定義: LLM 分析請求中，成功返回決策的比率（含降級到 Expert System 的情況）
+
+計算:
+  分子: 有 analysis_result 且 confidence > 0 的決策數
+  分母: 進入 LLM 分析路徑的告警總數
+
+注意:
+  - LLM timeout → 降級 Expert System = 計為「成功」（有決策輸出）
+  - LLM 完全失敗（exception）= 計為「失敗」
+
+單位: 百分比（%）
+```
+
+### SLI-4：KM 知識沉澱率（飛輪健康指標）
+
+```
+定義: 在執行完成的 Incident 中，成功產出 KM Entry 的比率
+
+計算:
+  分子: 有對應 KM Entry（category='execution_result' 或 'auto_repair'）的 Incident 數
+  分母: status='resolved' 的 Incident 總數
+
+單位: 百分比（%）
+時間窗口: 7 天滾動
+```
+
+### SLI-5：Telegram 通知送達率
+
+```
+定義: 應發送的 Telegram 通知中，成功送達的比率
+
+計算:
+  分子: structlog "telegram_card_sent" 事件數
+  分母: structlog "telegram_card_sent" + "telegram_send_failed" 事件數
+
+單位: 百分比（%）
+```
+
+---
+
+## 2. SLO 目標值（Service Level Objectives — 要到多好）
+
+> SLO = 我們**承諾**系統要達到的水準
+
+### 主要 SLO 表
+
+| SLO ID | SLI | 及格線（Minimum） | 卓越線（Target） | 測量窗口 |
+|--------|-----|-----------------|-----------------|---------|
+| **SLO-1** | 自動修復執行成功率 | **≥ 70%** | ≥ 85% | 24h 滾動 |
+| **SLO-2** | 告警分析延遲 P95 | **≤ 60s** | ≤ 30s | 7d 滾動 |
+| **SLO-3** | 決策引擎可用性 | **≥ 95%** | ≥ 99% | 24h 滾動 |
+| **SLO-4** | KM 知識沉澱率 | **≥ 60%** | ≥ 80% | 7d 滾動 |
+| **SLO-5** | Telegram 通知送達率 | **≥ 98%** | ≥ 99.5% | 24h 滾動 |
+
+### 各 SLO 設定理由
+
+**SLO-1（自動修復成功率 ≥ 70%）**
+
+目前系統基準：~0.5%（ADR-073 盤點發現）。
+設定 70% 為及格是因為：
+- K8s 操作本身有 ~10-15% 失敗率（網路短暫不通、資源不足）
+- 含重試後，70% 是合理的第一個里程碑
+- 卓越線 85% = 業界 AIOps 成熟系統的平均水準（Google SRE 報告）
+
+**SLO-2（分析延遲 P95 ≤ 60s）**
+
+- 告警→卡片 60s 以內 = 人可接受的「準即時」反應
+- P95 而非 P99 = 允許偶發的 LLM 高延遲（deepseek-r1:14b 推理本身需 15-40s）
+- 30s 卓越線 = Playbook RAG 命中時的典型速度
+
+**SLO-3（決策引擎可用性 ≥ 95%）**
+
+- 95% = 每 20 個告警允許 1 個完全失敗（Expert System 也無法決策）
+- 99% 卓越線 = 幾乎零失敗，依賴 LLM 穩定性提升
+
+**SLO-4（KM 沉澱率 ≥ 60%）**
+
+- 當前基準：接近 0%（BP-1 修復前 KM 幾乎不寫入）
+- 60% 及格線 = 允許 40% Incident 因各種原因未能沉澱（DB 失敗、無 incident_id 等）
+- 80% 卓越線 = 飛輪「穩定運轉」的健康標準
+
+**SLO-5（Telegram 送達率 ≥ 98%）**
+
+- 通知是 AWOOOI 對外的唯一溝通渠道
+- 98% = 每 50 個通知允許 1 個失敗（網路短暫中斷）
+- 99.5% 卓越線 = 等同電信級別的高可用
+
+---
+
+## 3. Error Budget（錯誤預算）
+
+> Error Budget = 我們「允許系統不完美」的配額
+
+### 計算方式
+
+```
+Error Budget = 1 - SLO 目標值
+
+以 SLO-1（自動修復成功率，卓越線 85%）為例：
+  Error Budget = 1 - 0.85 = 15%
+
+含義：在 100 次自動修復中，允許最多 15 次失敗。
+當失敗次數超過 15 次，Error Budget 耗盡 → 凍結新功能部署，優先修復。
+```
+
+### Error Budget 使用規則
+
+| 剩餘預算 | 狀態 | 允許行為 |
+|---------|------|---------|
+| > 50% | 🟢 充裕 | 可推高風險變更（新功能、架構調整） |
+| 20-50% | 🟡 注意 | 只推低風險變更（Bug Fix、配置調整） |
+| 5-20% | 🟠 警戒 | 凍結所有非緊急變更，優先修復 SLO |
+| < 5% | 🔴 耗盡 | 緊急模式：所有 PR 需統帥親自批准 |
+
+---
+
+## 4. SLO 監控與告警
+
+### 當前監控方式
+
+| SLO | 資料來源 | 查看位置 |
+|-----|---------|---------|
+| SLO-1 | PostgreSQL `approval_requests` 表 | 日度報告（08:00 台北）|
+| SLO-2 | Langfuse trace duration | Langfuse Dashboard |
+| SLO-3 | structlog 決策成功/失敗計數 | SignOz Logs |
+| SLO-4 | PostgreSQL incidents + knowledge_entries JOIN | 日度報告 |
+| SLO-5 | structlog telegram_card_sent/failed | SignOz Logs |
+
+### SLO 違規告警規則
+
+```yaml
+# 以下情況 → TYPE-8M「飛輪健康告警」→ 發統帥個人 DM
+
+SLO-1 連續 2 小時 < 50%:
+  告警: "⚠️ 自動修復成功率跌破 50%，飛輪瀕死"
+  
+SLO-2 P95 連續 15 分鐘 > 120s:
+  告警: "⚠️ LLM 分析嚴重延遲，可能 OOM 或網路問題"
+  
+SLO-3 連續 30 分鐘 < 90%:
+  告警: "🔴 決策引擎大規模失敗，立即介入"
+  
+SLO-5 連續 10 分鐘 < 95%:
+  告警: "🔴 Telegram 送達率跌破 95%，告警鏈路中斷"
+```
+
+---
+
+## 5. 里程碑目標（隨飛輪成熟演進）
+
+| 時間點 | SLO-1 目標 | 備註 |
+|-------|-----------|------|
+| **現在（2026-04-14）** | 基準：~0.5% | ADR-073 盤點確認 |
+| **Phase 1 完成（+2 週）** | ≥ 40% | KM 寫入、重試邏輯生效後 |
+| **Phase 2 完成（+4 週）** | ≥ 70% | 告警聚合、規則覆蓋強化 |
+| **Phase 3 完成（+6 週）** | ≥ 80% | 飛輪閉環、SSH KM 沉澱 |
+| **成熟運轉（+3 個月）** | ≥ 85% | 達到業界 AIOps 平均水準 |
+
+---
+
+## 6. 本文件更新規則
+
+1. **每週**: 日度報告自動收集 SLO-1、SLO-4 數值，存入趨勢記錄
+2. **每月第一週**: 統帥 + 首席架構師 review SLO 達成情況，決定是否調整目標值
+3. **重大 Incident 後**: 立即評估是否有 SLO 被違反，更新 Error Budget
+4. **目標值調整**: 達到「卓越線」穩定 4 週後，將卓越線升為新的及格線
+
+---
+
+*最後更新: 2026-04-14 台北時間 | 建立者: Claude Sonnet 4.6 + 統帥*