# ADR-100: AI 自主化飛輪 SLO

<!-- 2026-04-27 P3.4 by Claude — AI SLO -->

## 狀態：Active（2026-04-27）

## 背景

plan_complete_v3.0 P3.4 要求為 AI 自主化飛輪定義可量測的 SLO（Service Level Objectives），
以便持續追蹤飛輪健康度，並在 SLO 違反時自動降級行為，防止錯誤決策擴散。

## 4 個 SLO

---

### SLO 1 — 自主化率 ≥ 80%

**定義**：AI 自動執行的操作佔全部處理操作（含人工審核）的比例

**SLI 計算式**:
```promql
sum(rate(automation_operation_log_total{outcome="auto_executed"}[5m]))
/
sum(rate(automation_operation_log_total{}[5m]))
```

**Recording rule**: `sli:autonomy_rate:5m`

**目標值（SLO）**: ≥ 0.80

**Error budget（28d）**: 20%（即 28d × 20% = 5.6d 容許人工審核比例偏高）

**Burn rate alerts**:
| 視窗 | 消耗閾值 | 動作 |
|------|---------|------|
| Fast (1h) | budget × 14.4 = 2.88 | page（critical） |
| Medium (6h) | budget × 6 = 1.2 | ticket（warning） |
| Slow (3d) | budget × 1 → 累積 10% | review（info） |

**SLO 違反降級行為**:
- `< 0.70`（硬紅線）：降低 fusion auto-execute 閾值要求，發送 Telegram P0 告警
- `< 0.75`：governance_agent 加強監控頻率（30min → 15min）

---

### SLO 2 — 決策準確率 ≥ 90%

**定義**：自動執行後，verifier 驗證通過的比例

**SLI 計算式**:
```promql
sum(rate(post_execution_verification_total{outcome="success"}[5m]))
/
sum(rate(automation_operation_log_total{outcome="auto_executed"}[5m]))
```

**Recording rule**: `sli:decision_accuracy:5m`

**目標值（SLO）**: ≥ 0.90

**Error budget（28d）**: 10%（比自主化率更嚴格）

**Burn rate alerts**:
| 視窗 | 消耗閾值 | 動作 |
|------|---------|------|
| Fast (1h) | budget × 14.4 = 1.44 | page（critical） |
| Medium (6h) | budget × 6 = 0.6 | ticket（warning） |
| Slow (3d) | budget × 1 → 累積 10% | review（info） |

**SLO 違反降級行為**:
- `< 0.85`（硬紅線）：**凍結 auto_execute**，全部降級為 `human_required`，
  直到滑動窗口回到 ≥ 0.90 才解凍
- `< 0.88`：增加 verifier 嚴格度（多一輪二次驗證）

---

### SLO 3 — 信心校準準確度 ≥ 80%

**定義**：AI 信心值 ≥ 0.8 的決策中，實際驗證通過的比例（高信心不能亂說）

**SLI 計算式**:
```promql
sum(rate(approval_records_high_confidence_success_total[1h]))
/
sum(rate(approval_records_high_confidence_total[1h]))
```

**Recording rule**: `sli:confidence_calibration:1h`

**目標值（SLO）**: ≥ 0.80

**Error budget（28d）**: 20%

**Burn rate alerts**:
| 視窗 | 消耗閾值 | 動作 |
|------|---------|------|
| Fast (1h) | budget × 14.4 = 2.88 | page（critical） |
| Medium (6h) | budget × 6 = 1.2 | ticket（warning） |
| Slow (3d) | budget × 1 → 累積 10% | review（info） |

**SLO 違反降級行為**:
- `< 0.70`（硬紅線）：觸發 P3.3 fine-tune 重訓流程，Telegram 通知人工介入
- `< 0.75`：將高信心閾值從 0.8 上調至 0.85（更嚴格的信心要求）

---

### SLO 4 — KM 增長率 ≥ +20 筆/day

**定義**：每 24h 新增的知識條目數，衡量飛輪學習輸出是否健康

**SLI 計算式**:
```promql
max(knowledge_entries_created_24h)
or
max(increase(knowledge_entries_total[24h]))
```

**Recording rule**: `sli:km_growth_rate:24h`

**資料來源備註（2026-05-14 T19）**：`knowledge_entries_created_24h`
是 API `/metrics` 直接從 PostgreSQL `knowledge_entries.created_at >= now()-24h`
產出的 gauge。`increase(knowledge_entries_total[24h])` 只作舊 counter fallback，
避免 emitter 新上線時 Prometheus 還沒有 24h counter history 而誤報 KM 增長為 0。

**目標值（SLO）**: ≥ 20 筆/day

**Error budget**：不適用標準 burn rate（絕對值 SLO），改用閾值告警

**告警閾值**:
| 值 | 動作 |
|----|------|
| `< 20/day` | warning：調查 KM 寫入路徑 |
| `< 5/day` | critical：疑似 KM 鏈斷裂，Telegram P0 告警 |
| `= 0` (持續 2h) | emergency：governance_agent 立即執行診斷 |

**SLO 違反降級行為**:
- `< 5/day`（硬紅線）：告警，疑似 KM 鏈又斷，自動觸發 `check_knowledge_degradation`
- `= 0` 持續 2h：立即執行 `governance_agent.run_self_check()`

---

## SLO 違反時的降級行為矩陣

| SLO | 輕度違反 | 硬紅線違反 | 降級行為 |
|-----|---------|-----------|---------|
| SLO 1 自主化率 | < 0.75 | < 0.70 | 降低 fusion 閾值 + Telegram |
| SLO 2 決策準確率 | < 0.88 | < 0.85 | **凍結 auto_execute** |
| SLO 3 信心校準 | < 0.75 | < 0.70 | 觸發 fine-tune + 提高信心閾值 |
| SLO 4 KM 增長率 | < 20/day | < 5/day | 告警 + 觸發 KM 診斷 |

## 與 governance_agent 整合

`GovernanceAgent.check_slo_compliance()` 實作（`apps/api/src/services/governance_agent.py`）：

- 每 1h 執行（與既有 4 項自檢合併為第 5 項）
- 從 Prometheus Recording rules 讀取 SLI 值（`PROMETHEUS_URL` from settings）
- 違反硬紅線時呼叫 `self._alert()` 寫 PG + 推 Telegram
- 異常隔離：任一 SLO 查詢失敗不阻斷其他項目

## 實作檔案

| 檔案 | 用途 |
|------|------|
| `ops/monitoring/slo-rules.yml` | Prometheus recording rules + 12 burn rate alerts |
| `ops/monitoring/tests/test_slo_rules.yaml` | promtool 單元測試 |
| `ops/monitoring/grafana/dashboards/ai-slo-dashboard.json` | Grafana SLO Dashboard |
| `apps/api/src/services/governance_agent.py` | `check_slo_compliance()` 整合 |
| `apps/api/src/services/adr100_slo_metrics_service.py` | 2026-05-14 T18：從 PostgreSQL 事實來源輸出 ADR-100 底層 Prometheus series；`automation_operation_log_total` 僅納入 remediation / PlayBook / auto-repair 範圍，背景治理工作不進 AI 自動修復 SLO 分母。2026-05-14 T19：追加 `*_created_24h` gauges，供治理 Agent / 前端直接顯示最近 24h 事實量，避免 counter 暖機造成 false red |
| `apps/api/src/main.py` `/metrics` | 2026-05-14 T18：追加 DB-derived SLO emitter，讓既有 `awoooi-api` scrape job 取得底層 series |

## 決策理由

1. **Recording rules 優先**：SLI 計算複雜，先存 recording rule 避免 Grafana/alert 重複計算
2. **3 窗口 burn rate**：參考 Google SRE 書 6.5 節，fast/medium/slow 三層防禦
3. **SLO 4 用絕對值**：KM 增長率是累積計數，burn rate 模型不適用
4. **governance_agent 整合**：SLO 違反直接觸發降級行為，閉合飛輪的自我修復迴圈