docs(ws0): Hermes × 12-Agent Telegram 整合治理文件（ADR-093/094/095）

## 新增
- ADR-093: Telegram 告警全面遷移至 SRE 戰情室群組
  - 混合策略 allowlist 模式（TYPE-3/4/4D/8M → 群組 + user_id binding）
  - nonce 新格式 apr:{short_id}:{action}:{user_id_hash} + Redis 後端映射
  - Feature flag TG_GROUP_CUTOVER 灰階切流

- ADR-094: Hermes 自然語言介面（@mention 對話）
  - Option C：單 bot + Claude Agent SDK 虛擬分派
  - Webhook secret_token + allowed_updates = [message, callback_query, chat_member]
  - Prompt Injection 防護：query/describe/summarize only，mutate 走 ApprovalRecord
  - Redis session TTL=300s + turn>=5 壓縮

- ADR-095: 12-Agent Claude SDK 整合 × Telegram 視覺分派
  - 12 位 agent 完整 emoji/hashtag/handle 表格
  - ConsensusEngine weights 擴充（security=0.4 鎖定）
  - display_names.py 命名隔離（.claude/agents/ vs src/agents/）

## 更新
- ADR-009: 加 v0.3 變更紀錄指向 ADR-095
- ADR-075: 加更新引用表（ADR-093 D4 allowlist 子條款、ADR-094/095）
- docs/design/hermes-telegram-flows/hermes-flows.html: F1-F7 完整流程圖

## Pre-Flight 確認
- approval_records 表尚不存在 → 將用 BIGINT 全新建立
- docker-compose.yml:78 明碼 token 🔴 P0 待 WS1 修復
- awoooi_migrator 角色尚未建立 → WS2 建立
- claude-agent-sdk 升至 0.1.66（最新）

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/adr/ADR-009-openclaw-agent-teams.md

@@ -596,3 +596,4 @@ python scripts/test-agent-team.py
 |------|------|------|------|
 | 2026-03-23 | v0.1 | 初稿提議 | AI 架構師 |
 | 2026-03-23 | v0.2 | SDK 研究完成，加入具體整合方案 | AI 架構師 |
+| 2026-04-24 | v0.3 | 由 [ADR-095](ADR-095-12agent-sdk-integration.md) 擴充 ConsensusEngine weights 為 12-agent（security=0.4 鎖定，其餘 0.6 重分配），原 3 核心 agent 保留 | 12-Agent 全景分析 |

docs/adr/ADR-075-telegram-notification-standard.md

@@ -157,3 +157,13 @@ NOTIFICATION_TYPE_RULES = {
 **CR 評分**：7/10（首席架構師審查通過，P0/P1 全修補）
 
 **Phase 3（Prometheus 規則）**：尚未實作，不阻擋 Phase 1/2 上線
+
+---
+
+## 更新引用（2026-04-24）
+
+| ADR | 影響 | 說明 |
+|-----|------|------|
+| [ADR-093](ADR-093-telegram-group-migration.md) | 🔄 更新 D4 雙頻道路由 | 加「群組 Callback Button 授權模式」子條款：TYPE-3/4/4D/8M 解除 `_interactive_types` 黑名單，改以 callback_data + user_id binding + Approvers 白名單保護（P0-1 修）|
+| [ADR-094](ADR-094-hermes-nl-interface.md) | ➕ 新增 NL 對話入口 | Hermes 透過 @mention 在群組處理自然語言對話，輸出仍遵守 ADR-075 D5 格式規則 |
+| [ADR-095](ADR-095-12agent-sdk-integration.md) | ➕ 12-Agent 視覺分派 | TG 訊息加 `@hermes-*` 前綴 + emoji + hashtag 三件套，符合 ADR-086 UI 清洗後的視覺規範 |

docs/adr/ADR-093-telegram-group-migration.md

@@ -0,0 +1,76 @@
+# ADR-093: Telegram 告警全面遷移至 SRE 戰情室群組
+
+> **狀態**: Proposed
+> **日期**: 2026-04-24
+> **決策者**: 統帥 + 12-Agent 全景分析團隊（onboarder / debugger / db-expert / tool-expert / web-researcher / planner / critic / frontend-designer / fullstack-engineer / refactor-specialist / migration-engineer / vuln-verifier）
+
+## 背景
+
+當前 Telegram 告警雙軌路由設計（`telegram_gateway.py:1667 vs 4570`）：
+- 所有告警類（TYPE-3/4/4D/8M）預設發私人 DM `OPENCLAW_TG_CHAT_ID=5619078117`
+- 僅心跳報告、週月報、AI 三頭分析發群組 `SRE_GROUP_CHAT_ID=-1003711974679`
+- `_interactive_types` 黑名單（ADR-075 斷點 C）把互動式告警擋在群組外，**原因是 callback 按鈕 nonce 只綁 approval_id 不綁 user_id，進群組 = 任何成員都能簽核**
+
+使用者需求：把**所有**告警（含需人工簽核的 TYPE-3/4/4D/8M）遷到 AwoooI SRE 戰情室群組（4 名成員），以便團隊共同監察。
+
+## 決策
+
+採取**混合策略（allowlist 模式）**：
+
+1. **TYPE-1/TYPE-2/TYPE-6B**（純資訊、自動修復完成、業務告警）→ 群組
+2. **TYPE-3/TYPE-4/TYPE-4D/TYPE-8M**（互動式）→ **群組**，但 callback_data 必須包含 `user_id` binding + Approvers 白名單
+3. **TYPE-5S/TYPE-7E**（資安、重大事故）→ 暫留 DM，v2 再討論
+
+詳細觸發條件由 `apps/api/src/services/notification_matrix.py` 單一矩陣維護，**取代 telegram_gateway.py 內 24 處硬編 chat_id**。
+
+## 理由
+
+### 為什麼是群組（而非純 DM）
+- SRE 戰情室 4 名成員需**即時共同監察**，避免單一收件人漏讀
+- 系統日報已在群組，告警分散到 DM 造成資訊割裂
+- 符合 SRE best practice（PagerDuty / Opsgenie 都是群組導向）
+
+### 為什麼需要新 nonce 模型（P0-1 修）
+- 現有 callback_data 格式 `approve:{approval_id}:{timestamp}:{random}` 不含 user_id 簽章
+- 進群組 = CSRF 簽核漏洞：任何 member 可按批准按鈕
+- **新格式** `apr:{short_id}:{action}:{user_id_hash}` + Redis `cb:{short_id}` 後端映射
+- Handler 強制 `callback_query.from.id == bound_user_id`，違反 → 回 `answer_callback_query(text="⛔ 你未被指派")`
+
+### 為什麼要 Approvers Allowlist
+- Telegram group admin 可在未通知下新增成員
+- `chat_member` webhook 事件同步維護 Approvers 白名單
+- 按鈕先顯示給所有人，**按下後檢查** `from.id ∈ APPROVERS_WHITELIST`
+
+## 後果
+
+### 優點
+- SRE 團隊共同可見所有告警，降低漏讀率
+- 清理 24 處硬編 chat_id 技術債
+- 統一路由矩陣便於未來擴充
+
+### 缺點
+- 遷移期間 pending ApprovalRecord 卡片需重發（48h editMessage 限制，見 ADR-094 §F1）
+- 需新建 Approvers 白名單 + `chat_member` 同步機制
+- 破壞 ADR-075 斷點 C 的「DM only」假設 → 修訂 ADR-075 D4
+
+### 風險
+- **CSRF 簽核**：若 user_id binding 實作有缺陷，非授權者可簽核 → 必須有 Round 3 vuln-verifier 的 PoC 測試把關
+- **Telegram group 20 msg/min rate limit**：12 agent 回覆 + 告警齊發可能觸 429 → 必須走 `TelegramRouter` token bucket
+- **群組成員動態變動**：admin 隨時可拉人進群 → `chat_member` webhook 必須即時同步 Approvers
+
+## Rollback
+
+Feature flag `TG_GROUP_CUTOVER ∈ {off, 10%, 50%, 100%}`，以 `alert.labels.env` hash 分桶切流。失敗回 `off` 恢復 DM 模式。
+
+## 參考
+
+- 上位：[ADR-075](ADR-075-telegram-notification-standard.md)（需修訂 D4 加 allowlist 子條款）
+- 平行：[ADR-094](ADR-094-hermes-nl-interface.md) / [ADR-095](ADR-095-12agent-sdk-integration.md)
+- Memory: `feedback_no_ghost_buttons.md` / `feedback_telegram_alert_format.md`
+- 實施：Round 3 planner 的 WS0-WS5（`/Users/ogt/awoooi/docs/design/hermes-telegram-flows/hermes-flows.html`）
+
+## 變更紀錄
+
+| 版本 | 日期 | 執行者 | 變更內容 |
+|------|------|--------|---------|
+| v1.0 | 2026-04-24 | 12-Agent 全景分析 | 初版 Proposed |

docs/adr/ADR-094-hermes-nl-interface.md

@@ -0,0 +1,89 @@
+# ADR-094: Hermes 自然語言介面（@mention 對話）
+
+> **狀態**: Proposed
+> **日期**: 2026-04-24
+> **決策者**: 統帥 + 12-Agent 全景分析團隊
+
+## 背景
+
+Hermes 目前是 AWOOOI 的 rule quality scanner（`apps/api/src/jobs/hermes_rule_quality_job.py`，每日 04:00 用 LLM 分析噪音規則），**不是對話型 bot**。
+
+使用者需求：把 Hermes 升級為 SRE 戰情室群組中的**自然語言對話入口**，團隊成員可 `@Hermes` 問任何 SRE 問題，系統自動派對應 Claude Code subagent 回答。
+
+Web Research 查證（Telegram Bot API 官方文件）：
+- **Bot-to-bot 訊息永遠互不可讀**（即使關 privacy、設 admin）→ 12 獨立 bot 方案不可行
+- `editMessage` **48h 硬上限** → pending 卡跨日需 `copyMessage` fallback
+- `setWebhook` 需 `secret_token` 防偽
+- `allowed_updates` 需明列 `chat_member` 才能收群組成員變動
+
+## 決策
+
+**方案 C：單 bot + Claude Agent SDK 虛擬分派**。
+
+1. **對外**：沿用既有 `OPENCLAW_TG_BOT_TOKEN`，不新增 BotFather bot 帳號
+2. **Webhook**：新增 `/api/v1/telegram/webhook` 取代/共存 Long Polling（ADR-091 §4），含：
+   - `secret_token` header 驗證
+   - `allowed_updates=["message","callback_query","chat_member","my_chat_member"]`
+3. **意圖路由**（`apps/api/src/hermes/router.py`）：
+   - Layer 1 規則引擎（關鍵字正則，<10ms）
+   - Layer 2 LLM 分類（Haiku，<1s，觸發條件 confidence<0.6）
+   - Layer 3 default = `debugger`（最常見「X 為什麼壞了」）
+4. **SDK 共存**（**不替換** `ai_router.py`）：
+   - ADR-082 Phase 2 incident 決策仍走 `ai_router.py`（Ollama/NIM）
+   - Hermes NL 走 `claude-agent-sdk`（Anthropic API，需 allowlist）
+   - 兩者透過 `HERMES_ENABLED` feature flag 切換
+
+## 理由
+
+### 為什麼不多 bot（方案 B 否決）
+- Telegram API 硬性封鎖 bot-to-bot 訊息 → 12 獨立 bot 後端要用 Redis message bus 繞路
+- 單人維運 12 token 違反最小憑證面（`feedback_secrets_leak_incidents_2026-04-18`）
+- 方案 C 從方案 A/B 的遷移都是**單向相容**的（可後加 bot），但 B→C 要回收 12 bot 麻煩
+
+### Prompt Injection 防護（P0-2 修）
+- NL 輸入 → 意圖分類**只允** `query/describe/summarize`
+- `mutate/approve/deploy` 動作必須走 `ApprovalRecord` 二次確認
+- `danger:*`（`rm -rf` / force push）直接硬拒
+- system prompt 前置 `<user_input>...</user_input>` 隔離標籤
+- SanitizationService 擴充 12 pattern（既有 LOGBOOK L956）
+
+### 多輪對話（context engineering）
+- **短期記憶**（當前 session）：Redis Hash `hermes:session:{chat_id}:{user_id}`，TTL 300s
+- **Compaction**：turn ≥5 觸發 summary 壓縮節省 60% token
+- **長期記憶**：未來 v2 PostgreSQL `hermes_user_memory` 表
+
+## 後果
+
+### 優點
+- 對話體感延遲 <3s（首字元）
+- 零新增 Telegram bot，沿用現有 `httpx` 裸打 API 架構（切換成本零）
+- `claude-agent-sdk>=0.1.50` 已在 `pyproject.toml` 宣告，無新依賴
+
+### 缺點
+- LLM 費用增加（Anthropic Sonnet/Opus API）→ 需 per-user 每小時 10 query 速率限制 + 月度 budget hard cap
+- Hermes 現有 scanner job 命名空間與新服務衝突 → 新檔改名 `hermes_nl_gateway.py`（避開 `hermes_service.py`）
+- `claude-agent-sdk` 的 `.claude/agents/*.md` **在 SDK 不會自動載入**，需自寫 loader
+
+### 風險
+- **LLM 幻覺** → 新增 `hermes_dispatch_log` audit 表 + P95 confidence 監控（ADR-092 Evidence-First Protocol）
+- **Rate limit 撞牆** → Redis token bucket per chat_id（20/min 群組上限，預留 5/min buffer）
+- **成本失控** → Langfuse trace + per-user budget
+
+## Rollback
+
+Feature flag `HERMES_NL_ENABLED=off` → Hermes 退回純 scanner 模式，不接 Telegram webhook。
+SDK 延遲 > 10s P95 → 自動降級 `debugger` agent 預設回覆。
+
+## 參考
+
+- 上位：[ADR-050](ADR-050-telegram-interactive-incident-v2.md) / [ADR-091](ADR-091-telegram-subsystem-round3.md)
+- 平行：[ADR-093](ADR-093-telegram-group-migration.md) / [ADR-095](ADR-095-12agent-sdk-integration.md)
+- Claude Agent SDK: https://code.claude.com/docs/en/agent-sdk/python
+- Anthropic Context Engineering: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+- 設計: `/Users/ogt/awoooi/docs/design/hermes-telegram-flows/hermes-flows.html`（Flow 1-7）
+
+## 變更紀錄
+
+| 版本 | 日期 | 執行者 | 變更內容 |
+|------|------|--------|---------|
+| v1.0 | 2026-04-24 | 12-Agent 全景分析 | 初版 Proposed |

docs/adr/ADR-095-12agent-sdk-integration.md

@@ -0,0 +1,130 @@
+# ADR-095: 12-Agent Claude SDK 整合 × Telegram 視覺分派
+
+> **狀態**: Proposed
+> **日期**: 2026-04-24
+> **決策者**: 統帥 + 12-Agent 全景分析團隊
+
+## 背景
+
+AWOOOI 已有兩套 agent 系統：
+
+1. **ADR-009 OpenClaw Agent Teams**（內部 Python class，`src/agents/critic_agent.py` 等）
+   - 3 核心 agent：SecurityAgent (weight=0.4) / BlastRadiusAgent (0.3) / ActionPlannerAgent (0.3)
+   - ConsensusEngine 加權投票
+   - 用於 incident 決策自動化
+
+2. **ADR-082 Phase 2 Multi-Agent Collaboration**（5-agent 辯證）
+   - Diagnostician / Solver / Reviewer / Critic / Coordinator
+   - `agent_orchestrator.py` 編排，走 `ai_router.py` (Ollama/NIM)
+   - 用於 alert → incident 決策鏈
+
+**第三套 agent 系統**：Claude Code `.claude/agents/*.md` 12 份檔案定義（critic / debugger / db-expert / planner / fullstack-engineer / frontend-designer / refactor-specialist / migration-engineer / onboarder / tool-expert / web-researcher / vuln-verifier）。原本只供 Claude Code CLI 使用，**後端 AWOOOI API 未曾調用**。
+
+使用者需求：把這 12 位 Claude Code agent 透過 **Hermes NL 介面**（ADR-094）暴露給 Telegram 群組使用者，以視覺化方式呈現「12 位專家協作」。
+
+## 決策
+
+**視覺分派模式（非多 bot）**，三層共存：
+
+| 系統 | 用途 | 後端 | 狀態 |
+|------|------|------|------|
+| ADR-009 3 核心 agent | Incident 決策自動化 | Python class | 保留 |
+| ADR-082 5-agent 辯證 | Alert → incident 鏈 | `ai_router.py` → Ollama/NIM | 保留 |
+| **本 ADR-095 12 Claude Code agent** | Hermes NL 對話回覆 | **`claude-agent-sdk` → Anthropic API** | **新增** |
+
+### 視覺規格（單 bot，用文字前綴模擬 12 分身）
+
+| Agent | Emoji | Hashtag | 中文短稱 | TG handle（文字 prefix，非真 bot）|
+|-------|-------|---------|---------|--------------------------------|
+| critic | 🔍 | #審查 | 找碴專家 | @hermes-critic |
+| vuln-verifier | 🎯 | #漏洞驗證 | 漏洞驗證官 | @hermes-verifier |
+| debugger | 🐛 | #除錯 | 除錯偵探 | @hermes-debugger |
+| db-expert | 💾 | #資料庫 | DB 軍師 | @hermes-db |
+| planner | 📋 | #拆解 | 任務拆解官 | @hermes-planner |
+| fullstack-engineer | 🛠️ | #工程 | 全端工程師 | @hermes-engineer |
+| frontend-designer | 🎨 | #設計 | 前端設計師 | @hermes-designer |
+| refactor-specialist | ♻️ | #重構 | 重構專家 | @hermes-refactor |
+| migration-engineer | 🚚 | #升級 | 升級工程師 | @hermes-migration |
+| onboarder | 🗺️ | #導覽 | 領航員 | @hermes-onboarder |
+| tool-expert | 🧰 | #工具 | 工具專家 | @hermes-tools |
+| web-researcher | 📚 | #文檔 | 文獻研究員 | @hermes-web |
+
+### ADR-009 ConsensusEngine weights 擴充（向後相容）
+
+```python
+# 保留 SecurityAgent weight=0.4（資安永遠最高）
+# 其餘 11 agent 分配 0.6
+CONSENSUS_WEIGHTS = {
+    "SecurityAgent": 0.4,      # 保留 (ADR-009)
+    "BlastRadiusAgent": 0.15,  # 原 0.3 → 0.15
+    "ActionPlannerAgent": 0.15, # 原 0.3 → 0.15
+    # 新增 9 個 Claude Code agent（只有「核心 3 Consensus + 9 按需」模式下才參與投票）
+    "critic": 0.06,
+    "debugger": 0.06,
+    "db-expert": 0.04,
+    "vuln-verifier": 0.04,
+    "planner": 0.02,
+    "fullstack-engineer": 0.02,
+    "refactor-specialist": 0.02,
+    "migration-engineer": 0.02,
+    "tool-expert": 0.02,
+    # onboarder / frontend-designer / web-researcher 不參與投票（諮詢型）
+}
+# sum = 1.0
+```
+
+## 理由
+
+### 為什麼視覺分派而非多 bot
+- Telegram API 硬性封鎖 bot-to-bot 訊息（ADR-094 §web-researcher 查證）
+- 單人維運 12 token 違反最小憑證面（`reference_secrets_architecture_v2`）
+- 視覺識別可達成 80% 多 bot 效果（文字 prefix + emoji + hashtag 三件套）
+- 未來若真要多 bot 化，本方案是**前向相容**的（加 token 即可）
+
+### 命名隔離（P0-D3 修）
+- `.claude/agents/critic.md`（Claude Code subagent）與 `src/agents/critic_agent.py`（ADR-082 內部 dataclass）**同名不同物**
+- 對外 TG 統一呈現為 `@hermes-critic`，內部程式碼名稱不改
+- 映射表：`apps/api/src/hermes/display_names.py`
+
+### Claude Agent SDK 整合範式
+- SDK 版本：`claude-agent-sdk>=0.1.50`（已裝）→ 0.1.65（最新，升級決策待 T1.2）
+- Loader：`apps/api/src/hermes/agent_loader.py` 解析 frontmatter → `AgentDefinition`（camelCase 鍵）
+- Hooks：`hermes_hooks.py` **完整複製** `.claude/hooks/awoooi-guard.js` 9 條 DENY 正則（Node hook 對 SDK subprocess 無效，必須 Python 重做）
+- MCP：registry 加 `asyncio.Semaphore(5)` 防併發過載
+
+## 後果
+
+### 優點
+- 12 位 Claude Code agent 完整對外，覆蓋 SRE 戰情室 80% 諮詢情境
+- 視覺分派直觀（`🔍 找碴專家 @hermes-critic #審查`）
+- Agent `.md` 定義可熱更新（watch mtime）
+
+### 缺點
+- **命名衝突風險**：`.claude/agents/critic.md` vs `src/agents/critic_agent.py` 未來新人易混淆 → 強制 `display_names.py` 單點映射
+- **Anthropic API 費用**：每個 NL 回覆 ~$0.01-0.05（Sonnet），濫用需 budget 管控
+- **SDK subprocess**：每個 `ClaudeSDKClient` = 一個 subprocess，建議 pool 5 個 client 複用
+
+### 風險
+- **12 agent `.md` 變更守門**：需加 CODEOWNERS 強制 PR review，否則誰都能改 system prompt
+- **Consensus weights 重分配對現有 incident 決策的回歸影響**：security=0.4 鎖定可緩解，其他 weights 需單元測試覆蓋
+- **subagent 無法 spawn 自己的 subagent**（SDK 官方限制）→ 12 agent 不能互相調用，必須由 Hermes router 統一編排
+
+## Rollback
+
+- Feature flag `HERMES_12AGENT_ENABLED=off` → 全部 NL 回覆走 `debugger` 預設 agent
+- ConsensusEngine 如有回歸：`ENABLE_12AGENT_CONSENSUS=false` 退回 ADR-009 原 3 agent
+- 12 agent `.md` 檔案如有污染：從 `backup/pre-migration-*` tag 還原
+
+## 參考
+
+- 上位：[ADR-009](ADR-009-openclaw-agent-teams.md) / [ADR-082](ADR-082-multi-agent-collaboration.md)
+- 平行：[ADR-093](ADR-093-telegram-group-migration.md) / [ADR-094](ADR-094-hermes-nl-interface.md)
+- 設計：`/Users/ogt/awoooi/docs/design/hermes-telegram-flows/hermes-flows.html`（Flow 4/5）
+- Memory: `feedback_no_ghost_buttons.md` / `project_phase7_round3_telegram_subsystem.md`
+- SDK docs: https://code.claude.com/docs/en/agent-sdk/subagents
+
+## 變更紀錄
+
+| 版本 | 日期 | 執行者 | 變更內容 |
+|------|------|--------|---------|
+| v1.0 | 2026-04-24 | 12-Agent 全景分析 | 初版 Proposed |