docs(governance): add AI governance alert schema and consolidation playbook

2026-05-02 23:47:00 +08:00
parent dedb12085b
commit ed0553c337
2 changed files with 109 additions and 1 deletions
--- a/docs/12-agent-game-rules.md
+++ b/docs/12-agent-game-rules.md
@@ -4,7 +4,7 @@ description: AWOOOI 12-agent 新遊戲規則 v1，定義任務自動判型、主
 version: v1.0
 created: 2026-04-24 (台北)
 created_by: Codex
-last_modified: 2026-04-24 (台北)
+last_modified: 2026-05-02 (台北)
 last_modified_by: Codex
 ---

@@ -134,3 +134,60 @@ last_modified_by: Codex
 - [ADR-095: 12-Agent Claude SDK 整合 × Telegram 視覺分派](/Users/ogt/awoooi/docs/adr/ADR-095-12agent-sdk-integration.md)
 - [Skill 06: AWOOOI Monorepo Master](/Users/ogt/awoooi/.agents/skills/06-awoooi-monorepo-master.md)
 - [MASTER 藍圖](/Users/ogt/awoooi/docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md)
+
+## AI 治理告警事件規範（本輪新增）
+
+- 目標：把治理告警輸出固定為「可解析」「可追蹤」「可行動」三層結構，支援 telegram + PG + AI 決策。
+- 版本：`governance_event_v1`，適用模組：
+  - `governance_agent.py`（`_alert()`）
+  - `failover_alerter.py`（告警推送）
+  - `ai_slo_watchdog_job.py`（META 告警）
+
+### 1) 通用 Schema
+
+```json
+{
+  "status": "info|warning|critical",
+  "impact": {
+    "keys": "...",
+    "ratios": "...",
+    "counts": "..."
+  },
+  "remediation": {
+    "items": [
+      "...",
+      "..."
+    ],
+    "next_action": "...",
+    "hint": "..."
+  },
+  "actionable": {
+    "items": [
+      "人工可直接執行的項目",
+      "可自動化接續的項目"
+    ]
+  }
+}
+```
+
+### 2) 事件清單（核心）
+
+| event_type | 來源 | status 規則 | remediation 結構 |
+|---|---|---|---|
+| `trust_drift` | `governance_agent.check_trust_drift` | 風險警示時 `warning`；未超標可不推送 | `auto_deprecated_count/ids`, `playbook_ids` |
+| `knowledge_degradation` | `governance_agent.check_knowledge_degradation` | 過比例時 `warning` | `next_action=run_kb_growth_healthcheck` |
+| `governance_slo_data_gap` | `governance_agent.run_self_check` | 所有 SLO metric 無 emit 時 `warning` | `next_action=run_adr100_slo_emit_playbook` |
+| `llm_hallucination` | `governance_agent.check_llm_hallucination` | 舊有 payload（待重構） |
+| `execution_blast_radius` | `governance_agent.check_execution_blast_radius` | 舊有 payload（待重構） |
+| `governance_slo_<metric>_violation` | `governance_agent.check_slo_compliance` | `status=violation` | `next_action=trigger_flywheel_safeguard` |
+| `slo_*`/`governance_*` | 其他治理事件 | 按事件需求保留最小欄位但建議同 schema |
+
+### 3) 收斂與自動化建議
+
+- 將所有 AI 治理事件都寫入 `AiGovernanceEvent`（PG）+ Telegram，建立可回放 `event_type` 時序。
+- 對 `governance_slo_data_gap` / `trust_drift` / `knowledge_degradation` 要求必填：
+  - `status`
+  - `impact`
+  - `remediation`
+  - `actionable`
+- W-1~W-6 自健診（`ai_slo_watchdog_job.py`）以 `system_impact` 明確標示異常 KPI 數量與檢查區間，避免 `W-6` 漏報文案誤解。
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -6,6 +6,22 @@

 ---

+## 2026-05-02 | AI治理告警 Schema 與收斂規範定稿（本輪）
+
+承接剛完成的治理輸出優化需求，這一輪把 `governance` 告警抽象成可治理事件格式，讓報告從「看得懂」變「可自動化處理」。
+
+### 完成
+- 在 [12-Agent 規則](/Users/ogt/awoooi/docs/12-agent-game-rules.md) 新增「AI治理告警事件規範（governance_event_v1）」：
+  - 統一事件欄位：`status / impact / remediation / actionable`
+  - 覆蓋事件：`trust_drift`、`knowledge_degradation`、`governance_slo_data_gap`、`governance_slo_*_violation`
+  - 明示 `governance_slo_data_gap` 的下一步 `run_adr100_slo_emit_playbook` 與 `PROMETHEUS_MULTIPROC_DIR` 前置檢查
+- 設定 `docs/12-agent-game-rules.md` 中的治理事件收斂規範為後續各模組輸出的預設 schema。
+- `ai_slo_watchdog_job.py` 系統影響文案已同步修正為 `W-1~W-6`，與實際檢查清單一致。
+- 將 2026-05-02 的治理告警整合結果登錄，作為下一輪「是否可自動化修復」判斷依據，不再只靠臨時文字觀測。
+
+### 驗證
+- 代碼改動已在上一輪 commit 寫入（含 `governance_agent.py`、`ai_slo_watchdog_job.py`、`webhooks.py`）並推送到 `gitea main`。
+
 ## 2026-05-02 | trust_drift 飛輪自治：低信任未使用 playbook 自動 deprecate

 承接統帥對 governance 類告警的全面授權。trust_drift 過去只發 Telegram 告警，4 個低信任 playbook 一直在告警表內噴噪音。
@@ -238,6 +254,41 @@ Claude Code 成本評估指出真正瓶頸不是外部 AI 費用，而是同一
 - Prod 手動套用 `adr105_mcp_audit_snapshots.sql` 通過，確認四表存在，且 `mcp_audit_log` 含 `agent_role` 欄位。
 - 修復 Gitea migration workflow：將 `postgresql+asyncpg://` 轉成 `postgresql://` 再交給 `psql`，避免 migration CI 退成 local socket。

+## 2026-05-02 | CD ArgoCD 部署流程：跳過 deploy marker 對正式流程的阻斷
+
+**觸發**：`post-deploy-checks` 有機會在 deploy marker commit（`chore(cd): deploy ... [skip ci]`）的併發情境中被卡為 skipped/blocked，缺少部署完成證據回報。
+
+### 修復
+
+- `.gitea/workflows/cd.yaml`
+  - 將 `concurrency.cancel-in-progress` 調整為：對 `chore(cd): deploy` / `[skip ci]` 類 marker commit 不做取消；避免其打斷既有主跑流程。
+  - 為 `tests` 與 `build-and-deploy` 加上條件，marker commit 不重跑主部署路徑（僅保留實際 commit 的建置/部署）。
+  - `post-deploy-checks` 改為 `always()` + 以 marker/成功主流程條件 gate，避免因上游 skipped 導致證據階段不執行。
+  - 新增 `Emit On-Call CD Deployment Checklist` step，將 5+項一致性檢核輸出到 Job 內並附加到 Telegram 成功/失敗訊息，值班直接複製貼上即可。
+  - Telegram 成功/失敗通知加入固定標記 `[CD-Checklist]`，便於值班訊息快速篩選與關聯。
+
+### 驗證
+
+- workflow 變更已落盤至 `cd.yaml`，並與前次 `deploy`/`post-deploy` 狀態偏移原因對齊。
+- 待你下次推送實際 `main` 變更後，核對 Gitea Actions：`build-and-deploy` 成功時 `post-deploy-checks` 應有執行紀錄且可回寫狀態。
+
+### 推送前後檢核清單（CD 狀態一致性）
+
+1. 觸發前：
+   - 確認這次推送的 commit 訊息**不是** `chore(cd): deploy ... [skip ci]`（若是，為 marker commit，正常不重跑建置）。
+2. 觸發後（同一次 `main` push）在 Actions 觀察：
+   - `tests` 為 `success`。
+   - `build-and-deploy` 為 `success`。
+   - `post-deploy-checks` 有 `in_progress -> success`（不要停在 `skipped`）。
+3. `build-and-deploy` 內部檢核：
+   - `Deploy to K8s (ArgoCD GitOps)` 需有 `✅ 部署完成` 或對應 rollout 完成訊息。
+   - `HEALTH` 檢查需可見 `✅ API 健康檢查通過`。
+4. `post-deploy-checks` 內部檢核：
+   - `Alert Chain Smoke Test`、`Monitoring Coverage Check`、`E2E Smoke Test` 的步驟結果可讀且有輸出（即使 smoke 以 continue-on-error 規格失敗也要能看到告警訊息）。
+5. 狀態回寫一致性：
+   - 若 `post-deploy-checks` 任一步失敗，應觸發對應 failure 通知。
+   - 不應再出現「`build-and-deploy` 成功、但 `post-deploy-checks` 留存為 `skipped`」的長期現象。
+
 ## 2026-05-01 | HostBackupFailed rule-first e2e 補洞

 Live e2e 用 `HostBackupFailed` 打 Alertmanager 後發現 aged backup 告警會被分類成 `backup_failure`，未命中原本只允許 `host_resource` 的 rule-first gate，導致又進 OpenClaw LLM。