# AwoooP 完整詳細實施計畫

**版本**：v1.0（12-Agent 全景審查後整合版）
**日期**：2026-05-03（台北時區）
**建立者**：12-Agent 聯合審查 × Codex 整合
**基礎文件**：MASTER-WORKPLAN.md、ADR-106、ADR-107
**⚠️ ADR 編號修正**：ADR-108/109/110 已被其他 ADR 占用 → AwoooP 專用 ADR 從 ADR-111 開始

> 本文件是 MASTER-WORKPLAN.md 的完整展開版。
> MASTER-WORKPLAN 是主索引，本文是執行細節。
> 任何矛盾以本文為準（本文更新日期更晚）。

---

## 0. 全景背景

### 0.1 基礎架構現況（截至 2026-05-03）

| 組件 | 現況 | 備註 |
|------|------|------|
| Ollama Primary | GCP-A `34.143.170.20:11434`（SSD）| ADR-110，取代 ADR-105 |
| Ollama Secondary | GCP-B `34.21.145.224:11434`（SSD）| 新增，2026-05-03 上線 |
| Ollama Fallback | Local `192.168.0.111:11434`（HDD）| 最後防線，非 Primary |
| PostgreSQL | `192.168.0.188`（私網）| AwoooP 控制面唯一 source of truth |
| Redis | `192.168.0.188`（私網）| cache/watch/counter only（ADR-107 D4）|
| K3s 叢集 | `awoooi-prod` namespace | AWOOOI first tenant |
| Gitea CI/CD | `192.168.0.110`（或 Gitea Cloud）| ADR-039，所有 build 從 Gitea |

### 0.2 12-Agent 審查發現彙整

原始 MASTER-WORKPLAN 有 24 項共識問題。12 位 Agent 並行深度審查後新增：

| Agent | 新增 P0/P1 問題數 | 新增 ADR 需求 | 新增 Inventory |
|-------|-----------------|--------------|----------------|
| critic | 10 | 1（ADR-116 Migration Discipline）| INV-5、INV-6、INV-7 |
| vuln-verifier | 8（含 PoC 確認 3 個）| 2（ADR-116/117 安全系列）| — |
| debugger | 12（故障情境）| — | 8 份 Runbook |
| db-expert | 8（表設計缺陷）+ RLS 完全空白 | 1（ADR-118 RLS 策略）| — |
| planner | 7 粒度過粗 + 10 acceptance 不閉環 | — | — |
| fullstack-engineer | 7 API endpoint 缺失 + 9 error code | — | — |
| frontend-designer | 8 UI 模組完全缺失 | ADR-UI-01~04 | — |
| refactor-specialist | 8 重構地雷 + 11 PR 方案 | — | — |
| migration-engineer | 7 相容性風險 | — | version matrix |
| onboarder | 31 background loop（vs 估計 ~10）+ 13 模組衝突 | — | INV-8 |
| tool-expert | 8 工具容量不足 + 8 工具缺失 | — | — |
| web-researcher | 業界 5 大對齊缺口（SAGA/Token Kill/MCP OAuth 2.1/OTel/OWASP）| 5（ADR-119~123）| — |
| **合計新增** | **~70 個問題** | **~12 份 ADR** | **~4 份 Inventory** |

**結論：不先補完 Pre-flight Audit，Phase 1 必爆。**

---

## 1. 完整問題清單（P0 優先順序）

### P0 — 直接爆炸（必須在 Phase 1 之前修補）

| # | 問題 | 來源 | 影響範圍 |
|---|------|------|---------|
| P0-01 | Redis key 直接改名無雙寫期（費用計數歸零、Telegram 409、silence 失效、Ollama failover 三層拓撲雙寫不到）| critic | 費用、告警、Ollama |
| P0-02 | Migration SQL 表名錯（`incident_records` / `mcp_audit_snapshots`）、無 rollback、ORM 1.x vs 2.x | critic | Phase 1 migration |
| P0-03 | `project_id` / `tenant_id` 在 codebase 0 命中，30+ 業務表無此欄 | onboarder | 全系統 |
| P0-04 | `requires_approval` 欄位由 LLM output 決定（security_interceptor.py:451-490）| vuln-verifier（PoC 確認）| approval 鏈 |
| P0-05 | callback nonce 偽造：server nonce 邏輯可不知 secret 構造通過驗證（security_interceptor.py:451-490）| vuln-verifier（PoC 確認）| Telegram approval |
| P0-06 | Webhook HMAC replay 無 timestamp/nonce（webhooks.py:679-728）| vuln-verifier（PoC 確認）| 所有 webhook |
| P0-07 | 31 個 background loop 全無 project_id（main.py）| onboarder（實測）| 多租戶全崩 |
| P0-08 | `telemetry.py:71` 硬碼 `if "192.168.0.188" not in endpoint: raise`，EwoooC 啟動必失敗 | onboarder | EwoooC Phase 6 |
| P0-09 | `project_migration_state` 表缺失，Strangler Fig 無資料載體 | db-expert | Phase 1 |
| P0-10 | Task 9 順序倒置（agent prompt 載入點在 ConfigMap 前）→ 全回 None | critic | Phase 1 任何 agent |
| P0-11 | `ollama:current_primary` 在 `ollama_auto_recovery.py:230` 有第二定義，三層拓撲遷移必裂 | onboarder | GCP Ollama 拓撲 |
| P0-12 | `consensus_engine.py` 中 `CONSENSUS_PREFIX="consensus:"` 無 project 前綴，multi-tenant 時跨 tenant 共用 | onboarder | 多租戶一致性 |
| P0-13 | `mcp_bridge.py:592-681` kubectl 呼叫硬碼 `namespace="awoooi-prod"` | onboarder | EwoooC K8s tool |

### P1 — 嚴重缺陷（Phase 2-4 之前必修）

| # | 問題 | 來源 | 影響範圍 |
|---|------|------|---------|
| P1-01 | AWOOOI Bootstrap Paradox：cron/job/healthcheck 全無 project_id | critic | 多租戶啟動 |
| P1-02 | EwoooC 接入零技術路徑（非只改 `OLLAMA_API_BASE`）| critic | Phase 6 |
| P1-03 | Strangler Fig shadow→canary→active 無量化 gate 條件 | planner | 切換決策 |
| P1-04 | Layer 3 redaction 零實作（helper 有但無 enforcement）| critic | 資訊安全 |
| P1-05 | `_provider` 屬性 public，可繞過 audit（mcp/registry.py:24-71）| critic | MCP 安全 |
| P1-06 | `WAITING_APPROVAL` resume 不驗 caller identity，無 approval_token 簽章 | critic | approval 安全 |
| P1-07 | Redis approval state 單點，無 PG sync | critic | approval 可靠性 |
| P1-08 | Audit log 本身會洩密（redaction 必須做在 audit sink 前）| critic | 資訊安全 |
| P1-09 | `sanitization_service.py` helper 無 enforcement point（MCP Gateway / AgentToolExecutor 都沒用）| critic | tool 安全 |
| P1-10 | Active revision 切換無 transactional outbox，worker 可能吃舊 policy | db-expert | policy 一致性 |
| P1-11 | Run/Channel idempotency 缺 key derivation 規則與 unique index | db-expert | 重複執行 |
| P1-12 | Async worker 缺 lease / heartbeat / stale reaper | db-expert | worker 可靠性 |
| P1-13 | 高流量表 partition + retention 需 Phase 1 就決定（不能後補）| db-expert | 長期可擴展 |
| P1-14 | Observability metrics label cardinality（run_id/trace_id/session_id 禁進 metrics）| fullstack | Prometheus |
| P1-15 | `multi_sig_redis.py:178-205` approval flow 零 trace_id | debugger | 故障排查 |
| P1-16 | `hermes/nl_gateway.py:7,146,163` Redis key 無 project 前綴 | onboarder | Hermes 隔離 |
| P1-17 | `anomaly_counter.py:790` AnomalyCounter 全域單例，6 個 prefix 無 tenant 隔離 | onboarder | 多租戶計數 |
| P1-18 | `incident_service.py:603-615` `SCAN incident:*` 無 project_id | onboarder | Redis 資料隔離 |
| P1-19 | Contract publish 權限與簽章未定義 | critic | contract 治理 |
| P1-20 | 13 個全域單例跨 tenant 共用（TrustEngine/ProviderRegistry/TelegramGateway/等）| onboarder | 多租戶隔離 |
| P1-21 | Token Budget 無 Hard Kill（$47k agent loop 事故教訓）| web-researcher | 費用控管 |
| P1-22 | RLS（Row Level Security）完全空白 | db-expert | DB 多租戶 |
| P1-23 | GCP Ollama 三層拓撲 Redis key 雙寫遷移未規劃（`ollama:current_primary` 舊 key 只知道 1 個 host）| critic | Ollama failover |
| P1-24 | `decision_manager.py:240` 硬碼 `telegram_silence:{target}` 未 import gateway 常數（跨兩處定義）| debugger | silence 功能 |

### P2 — 設計缺口（Phase 5-8 之前必補）

| # | 問題 | 來源 | 影響範圍 |
|---|------|------|---------|
| P2-01 | Telegram/LINE/Slack/API/Internal 缺 canonical principal mapping | critic | 身份統一 |
| P2-02 | Run FSM 零實作（只有表設計，無狀態機程式碼）| fullstack | Phase 4 |
| P2-03 | EwoooC Provider Proxy 不能只改 URL，需要完整 envelope+audit 入口 | critic | Phase 6 |
| P2-04 | 業界 Durable Execution / SAGA 補償交易機制缺失 | web-researcher | 長時 agent tool chain |
| P2-05 | MCP OAuth 2.1（RFC 9728 + RFC 7591）Confused Deputy 無防護 | web-researcher | MCP 安全 |
| P2-06 | OTel GenAI Semantic Conventions（span 命名 / attribute 規範）未對齊 | web-researcher | 可觀測性 |
| P2-07 | OWASP Agentic AI Top 10 對齊缺口（prompt injection、tool misuse 等 7 項）| web-researcher | AI 安全 |
| P2-08 | ISO 42001 AI 管理體系對齊文件缺失 | web-researcher | 合規 |
| P2-09 | 7 個 API endpoint 缺失（見 §6 fullstack 清單）| fullstack | API 完整性 |
| P2-10 | 9 個 error code 缺失（見 §7 error code 字典）| fullstack | 客戶端解析 |
| P2-11 | Progressive feedback policy（async run 無進度通知 ≤30s）| fullstack | UX |
| P2-12 | 8 個 Operator Console UI 模組完全缺失（見 §8 frontend）| frontend-designer | 運營可見性 |
| P2-13 | `awooop-ctl` CLI 工具缺失（現有 kubectl + curl 手動操作）| tool-expert | 運維體驗 |
| P2-14 | OPA/Cedar policy engine 缺失（現在 contract 授權邏輯散落程式碼）| tool-expert | 授權集中化 |
| P2-15 | chaostoolkit / LitmusChaos 缺失（Strangler Fig 切換無混沌驗證）| tool-expert | 容災驗證 |
| P2-16 | PgBouncer 缺失（AwoooP 多 worker 下 PG connection pool 會爆）| tool-expert | DB 可擴展性 |

---

## 2. Pre-flight Audit — Phase 0 完整清單

> Phase 0 全部 docs-only。無任何 runtime code 變動。
> 完成後才開新 Codex 對話進 Phase 1 code。

### 2.1 AwoooP 核心 ADR（ADR-111～115）

**注意：ADR-108/109/110 已被 incident fingerprint / telegram dedup / GCP Ollama 拓撲占用，AwoooP 從 ADR-111 起。**

| ADR | 主題 | 解決問題 | 主要內容 |
|-----|------|---------|---------|
| **ADR-111** | AwoooP Bootstrap Order & Identity Paradox | P0-07、P0-01、P1-01 | `platform_internal` / `requires_project_id` / `legacy_awoooi_default` 三種標記；31 個 background loop 分類；AWOOOI cron/job 過渡豁免時程；Ollama GCP 三層 failover 的 platform_resource 聲明 |
| **ADR-112** | Contract Governance & Publishing Workflow | P1-19 | 誰可 publish / activate；CODEOWNERS；HMAC 簽章；approval workflow；activation audit；draft 與 published 隔離 |
| **ADR-113** | Active Revision Invalidation & Outbox | P1-10 | `awooop_contract_outbox` 表設計；Redis pub/sub 通知；worker revision-aware cache；split-brain 防禦；GCP Ollama 拓撲切換事件 |
| **ADR-114** | Idempotency, Worker Lease & Run Recovery | P1-11、P1-12 | channel event dedupe；`(project_id, channel_type, provider_event_id)` unique；worker `lease_until` / `heartbeat_at` / `attempt_count`；stale run reaper；SKIP LOCKED |
| **ADR-115** | Canonical Principal Mapping & Tenant Onboarding | P2-01、P0-08 | Telegram/LINE/Slack/API/Internal → `platform_subject` 統一映射；EwoooC Proxy Adapter；Tsenyang/Bitan 模板；`telemetry.py:71` IP assert 修正方案 |

### 2.2 安全強化 ADR

| ADR | 主題 | 解決問題 | 主要內容 |
|-----|------|---------|---------|
| **ADR-116** | AwoooP Security Hardening | P0-04、P0-05、P0-06 | callback nonce 重設計（server_secret 必參與 HMAC）；webhook 加 timestamp/nonce 防 replay；`requires_approval` 改為 policy-derived（禁止 LLM 決定）；approval_token signing 規格（HS256，15min TTL，`jti` 唯一性）|
| **ADR-117** | MCP OAuth 2.1 & Confused Deputy Prevention | P2-05 | RFC 9728 Resource Indicators；RFC 7591 Dynamic Client Registration；per-tenant token scope；Confused Deputy 防護設計；MCP Server binding PKCE flow |

### 2.3 資料庫強化 ADR

| ADR | 主題 | 解決問題 | 主要內容 |
|-----|------|---------|---------|
| **ADR-118** | Row-Level Security & Tenant DB Isolation | P1-22 | 所有 AwoooP 表啟用 RLS；`current_setting('app.project_id')` 注入；RLS bypass role 設計；migration 驗收標準 |
| **ADR-119** | Durable Execution & SAGA Compensation | P2-04 | multi-step agent tool chain 的 step-level journal；補償交易觸發條件；checkpoint/resume 設計；與 Phase 4 run state machine 整合 |

### 2.4 可觀測性 & AI 安全 ADR

| ADR | 主題 | 解決問題 | 主要內容 |
|-----|------|---------|---------|
| **ADR-120** | Token Budget Hard Kill | P1-21 | 每 run / 每 project / 每 tenant 三層 budget limit；hard kill（不只 alert）；$47k agent loop 事故 RCA；`budget_ledger` 表設計；Redis hot counter + PG 事務 hard stop |
| **ADR-121** | OTel GenAI Semantic Conventions Alignment | P2-06 | span 命名規範（`gen_ai.request.*`）；token 計數 attribute；LLM provider attribute；與現有 SignOz（188:24318）整合；metrics label cardinality 規則 |
| **ADR-122** | OWASP Agentic AI Top 10 & ISO 42001 Alignment | P2-07、P2-08 | Top 10 逐項對應到 AwoooP 控制面；ISO 42001 AI 管理體系必要文件清單；每 Phase 對齊驗收項 |

### 2.5 Migration Discipline ADR

| ADR | 主題 | 解決問題 | 主要內容 |
|-----|------|---------|---------|
| **ADR-123** | Background Loop project_id Migration Strategy | P0-07、P1-01 | 31 個 background loop 分三類（platform_internal / legacy_awoooi_default / requires_project_id）；每類遷移策略；regression test 設計；完成標準（main.py 0 個無標記 loop）|
| **ADR-124** | Global Singleton Decomposition for Multi-tenancy | P1-20 | 13 個全域單例清單；分解策略（per-project registry / factory pattern）；AWOOOI 1.0 → AwoooP 1.0 遷移路徑；不能同時拆的依賴序 |

### 2.6 前端 Operator Console ADR（新增）

| ADR | 主題 | 解決問題 | 主要內容 |
|-----|------|---------|---------|
| **ADR-UI-01** | AwoooP Operator Console 架構 | P2-12 | 8 個 UI 模組規格；與現有 `apps/web/` 整合方式；多租戶視角設計；i18n（next-intl）規範 |
| **ADR-UI-02** | Contract Lifecycle UI | P2-12 | draft → publish → activate 操作流程；revision diff 視覺化；contract family 篩選 |
| **ADR-UI-03** | Run State & Shadow Monitoring UI | P2-12 | shadow/canary/active 切換 dashboard；run FSM 視覺化；Strangler Fig gate 量化指標展示 |
| **ADR-UI-04** | Tenant Budget & Audit UI | P2-12 | per-project token budget；hard kill 觸發歷史；audit log 查詢（含 redaction 遮蔽）|

### 2.7 ADR-106 補充章節

ADR-106 需新增：
- **Strangler Fig Quantified Gates**（量化切換條件）
- **GCP Ollama 拓撲影響**（三層 failover 如何成為 `platform_resource`，不屬於任何 tenant）
- **Bootstrap Order** 參照 ADR-111

### 2.8 Inventory 清單（9 份）

| Inventory | 位置 | 範圍 | 解決問題 |
|-----------|------|------|---------|
| **INV-1** | `docs/awooop/inventory/INV-1-redis-keys.md` | 全 codebase grep `redis_client.*\(["']` 等，列出 43+ 個 key、命名空間、TTL、用途、寫入/讀取點、是否硬碼 | P0-01、P1-18 |
| **INV-2** | `docs/awooop/inventory/INV-2-repository-project-id-retrofit.md` | 30+ 業務表 × 目前有無 `project_id` × 所有 repository 方法 × 需加 filter 的查詢 × 需 backfill 的歷史資料 | P0-03 |
| **INV-3** | `docs/awooop/inventory/INV-3-entrypoints.md` | 所有 cron job / scheduler / webhook / CLI / healthcheck / internal service call，標記三種類型 | P0-07、P1-01 |
| **INV-4** | `docs/awooop/inventory/INV-4-hardcoded-namespace-ip.md` | 硬碼 K8s namespace（`awoooi-prod`）、SSH 主機 IP、白名單（**含新 GCP IP：34.143.170.20、34.21.145.224**）| P0-08、P0-13 |
| **INV-5** | `docs/awooop/inventory/INV-5-migration-compatibility-matrix.md` | 版本相容矩陣：SQLAlchemy 1.x→2.x / Alembic / Pydantic v1→v2 / FastAPI 0.x / Python 3.10→3.12；每個 breaking change + 影響範圍 | critic |
| **INV-6** | `docs/awooop/inventory/INV-6-rollback-playbook-register.md` | 6 個 rollback playbook：Phase 1 schema rollback、Phase 2 Redis key rollback、Phase 5 MCP Gateway rollback、Phase 6 EwoooC rollback、Ollama GCP→Local fallback rollback、approval flow rollback | migration |
| **INV-7** | `docs/awooop/inventory/INV-7-pr-cutting-plan.md` | 11 個 PR 切割方案（refactor-specialist 設計）：每 PR 的範圍、前置依賴、review 者、合併順序 | refactor |
| **INV-8** | `docs/awooop/inventory/INV-8-background-loop-catalog.md` | 31 個 background loop 逐一列出：名稱、位置（main.py 行號）、類別標記、遷移策略、預計完成 Phase | onboarder |
| **INV-9** | `docs/awooop/inventory/INV-9-global-singleton-catalog.md` | 13 個全域單例逐一列出：名稱、位置、依賴方、分解策略、遷移風險 | onboarder |

### 2.9 Phase 0 驗收標準

- [ ] ADR-111～115（5 份 AwoooP 核心 ADR）全部 Accepted
- [ ] ADR-116～124（9 份強化 ADR）全部 Accepted
- [ ] ADR-UI-01～04（4 份 UI ADR）全部 Accepted（或 Proposed + 統帥批准開工）
- [ ] ADR-106 補入 Strangler Fig Quantified Gates + GCP Ollama 章節
- [ ] INV-1～INV-9（9 份 Inventory）完成初稿
- [ ] 無任何 runtime code 變動
- [ ] `git diff --check` 通過

---

## 3. 8-Phase 詳細工作項

> 每項含：目標、範圍（精確路徑）、輸入（前置依賴）、輸出（交付物）、驗收標準、邊界（禁止碰什麼）

### Phase 1 — Control Plane Schema Foundation

**目標**：建立 PostgreSQL contract control plane 最小可用骨架，修正舊 SQL migration 三大 blocker，決定高流量表 partition 策略。

**前置依賴**：Phase 0 全部完成（所有 ADR + Inventory）

**範圍（精確檔案）**：
- `apps/api/migrations/` — 新增 migration files
- `apps/api/src/models/` — 新增 AwoooP SQLAlchemy models
- `apps/api/src/repositories/` — 新增 AwoooP repositories
- `docs/runbooks/` — 新增 partition + retention runbook

**禁止碰**：
- 任何既有 repository 方法（留給 Phase 2）
- provider 行為（`ai_router.py` / `ollama_*.py`）
- Telegram/LINE webhook 路徑
- `apps/web/`
- 任何 K8s manifest

**工作項（順序執行）**：

```
1.1  表名核對
     - grep 確認 `incidents`（非 incident_records）
     - grep 確認 `mcp_audit_log`（非 mcp_audit_snapshots）
     - 修正 ORM: SQLAlchemy 2.x mapped_column、補齊 Numeric/UniqueConstraint/func import
     - 每個 migration 強制有 down migration（rollback SQL）

1.2  Task 9 順序修正（必須 Phase 1.1 之前完成）
     - Dockerfile: agent_loader default path 指向 ConfigMap mount
     - ConfigMap 預載: 確認 agent prompt 路徑在 ConfigMap 已存在
     - 驗收：dry-run 一個 agent loader，輸出非 None

1.3  AwoooP 控制面表（新增 migration）
     - awooop_projects（tenant 主表，project_id VARCHAR PK，budget，ACL）
     - awooop_contract_revisions（六合約共用 revision 表，append-only，見 §4.1 完整欄位）
     - awooop_active_revisions（active pointer，指向特定 revision_id）
     - awooop_artifact_refs（prompt/schema/eval ref + sha256 + type）
     - awooop_project_migration_state（Strangler Fig 階段追蹤，per project × per capability）
     - awooop_contract_outbox（ADR-113，active revision 切換事件，for worker invalidation）
     - awooop_channel_event_dedupe（ADR-114，idempotency，唯一鍵）
     - awooop_platform_subjects（ADR-115，canonical principal mapping）
     - awooop_budget_ledger（ADR-120，token budget，per project × per period）

1.4  高流量表（在 Phase 4/7 建立時已決定 partition，此時寫規則）
     - 須在本 Phase migration 中加 partition template comment（不執行，留 Phase 4）
     - awooop_run_state → range partition by created_at（月）
     - awooop_channel_event → range partition by created_at（月）
     - awooop_mcp_gateway_audit → range partition by created_at（月）
     - awooop_agent_audit_log → range partition by created_at（月）
     - retention: 90 天 hot + 1 年 warm（pg_partman / cron job）
     - 寫進 docs/runbooks/awooop-partition-retention.md

1.5  AWOOOI Bootstrap（seed data）
     - INSERT INTO awooop_projects(project_id='awoooi', display_name='AWOOOI', migration_mode='legacy_awoooi_default')
     - 驗收：AWOOOI 0 行為改動

1.6  RLS 骨架（ADR-118）
     - 所有 awooop_* 表啟用 RLS
     - policy: USING (project_id = current_setting('app.project_id', TRUE))
     - bypass role: awooop_platform（只給 platform worker 用）
     - 注意：RLS 需要 migration + 測試，不只是 ALTER TABLE ENABLE ROW LEVEL SECURITY

1.7  Immutability 測試
     - published contract revision 嘗試 UPDATE → 必失敗（trigger 或 check constraint）
     - draft 與 active 隔離：runtime 讀取 view 不含 draft
     - 自動化：pytest + db-expert review
```

**RACI**：
- R（執行）：fullstack-engineer
- A（負責）：db-expert review，統帥批准
- C（諮詢）：refactor-specialist（migration PR 切割）、critic（最終 review）
- I（通知）：migration-engineer（版本相容驗證）

**DoD**：
- 所有 migration up/down dry-run 通過
- AWOOOI 可表示為 `project_id=awoooi`，0 行為改動
- RLS 測試：cross-project SELECT 被拒絕
- partition runbook 已建立

---

### Phase 2 — Tenant Isolation & Namespace Hardening

**目標**：在開放任何下游 tenant 之前，把 AWOOOI 自己變成乾淨的 tenant。
**前置**：Phase 1 完成

**範圍**：
- `apps/api/src/services/` — Redis key 遷移（依 INV-1）
- `apps/api/src/repositories/` — 加 project_id filter（依 INV-2）
- `apps/api/src/services/security_interceptor.py` — nonce 修補（P0-05，ADR-116）
- `apps/api/src/api/v1/webhooks.py` — replay 防護（P0-06，ADR-116）
- `apps/api/src/core/telemetry.py:71` — 移除硬碼 IP assert（P0-08）
- `apps/api/src/services/decision_manager.py:240` — silence key 常數化（P1-24）
- `apps/api/src/services/ollama_auto_recovery.py:230` — 移除第二定義（P0-11）
- `apps/api/src/plugins/mcp/mcp_bridge.py:592-681` — namespace 動態化（P0-13）
- `apps/api/src/services/consensus_engine.py` — CONSENSUS_PREFIX 加 project 前綴（P0-12）
- `apps/api/src/hermes/nl_gateway.py` — Redis key 加 project 前綴（P1-16）
- `apps/api/src/services/anomaly_counter.py:790` — per-project 改造（P1-17）
- `apps/api/src/services/incident_service.py:603` — SCAN 加 prefix（P1-18）

**禁止碰**：
- `awooop_contract_revisions` 以外的 AwoooP Phase 1 新表結構
- EwoooC / Tsenyang 任何接入（留 Phase 6）
- 任何 provider routing 改動（Ollama GCP 拓撲已由 ADR-110 定案，不在此 Phase 改）

**工作項**：

```
2.1  Redis 三階段雙寫遷移計畫執行（依 INV-1，分三批）
     批次 A（Critical Path，影響 Ollama GCP 拓撲）：
     - ollama:current_primary（舊）→ {project_id}:ollama:primary（新）
       注意：要同時支援三層 GCP-A/GCP-B/Local，INV-1 需確認所有寫入點
     - ollama_auto_recovery.py:230 第二定義刪除，統一常數
     批次 B（費用 + 告警關鍵）：
     - ai_rate:total_cost:gemini → {project_id}:ai_rate:total_cost:gemini
     - telegram:polling:leader → platform:telegram:polling:leader（platform_resource）
     - telegram_silence:{target} → {project_id}:telegram_silence:{target}
       同步更新 decision_manager.py:240 import gateway 常數
     批次 C（working memory）：
     - consensus: → {project_id}:consensus:（consensus_engine.py）
     - hermes Redis keys（nl_gateway.py）
     - anomaly_counter 6 個 prefix
     - incident:* SCAN（incident_service.py:603）

     每批次：Phase A（雙寫 30 天）→ Phase B（雙讀 14 天）→ Phase C（移除舊 key）

2.2  Security hardening（ADR-116）
     - telemetry.py:71：移除 "192.168.0.188" 硬碼 assert，改為 config-driven allowed endpoints
     - security_interceptor.py:451-490：nonce 重設計，server_secret 必參與 HMAC
     - webhooks.py:679-728：加 timestamp（±5min window）+ nonce（Redis dedup）
     - requires_approval：改為從 policy contract 讀取，禁止 LLM output 決定
     - approval_token：HS256，15min TTL，jti 唯一性（Redis NX）

2.3  Repository project_id 改造（依 INV-2）
     - 所有 30+ repository 方法加 project_id filter
     - K8s namespace 白名單 → tenant-aware（mcp_bridge.py:592-681 動態化）
     - SSH 主機白名單 → tenant-aware（依 INV-4）

2.4  Background loop 標記（依 ADR-123，INV-3/INV-8）
     - 31 個 loop 標記為 platform_internal / legacy_awoooi_default / requires_project_id
     - platform_internal 帶 project_id=__platform__
     - legacy_awoooi_default fallback 到 project_id=awoooi，寫退場時程

2.5  Global singleton 分解第一步（依 ADR-124，INV-9）
     - 只做：AnomalyCounter（P1-17 已修）per-project 改造
     - 其餘 13 個全域單例列出退場時程（不在此 Phase 全拆，防爆炸半徑）

2.6  Token Budget Hard Kill 基礎（ADR-120）
     - budget_ledger 表 migration（Phase 1 已建，此 Phase 寫入邏輯）
     - 每 LLM call 前：check budget → hard kill if exceeded（不只 log）
     - Redis hot counter + PG 事務 hard stop
```

**RACI**：
- R：fullstack-engineer + refactor-specialist（大量 repository 改動）
- A：db-expert（repository 改動 review）、vuln-verifier（security hardening PoC 驗證）
- C：critic（整體 diff review）、migration-engineer（相容性確認）
- I：tool-expert（K8s namespace 改動相關）

**DoD**：
- INV-1 所有 P0 key 完成三階段遷移（Phase A 完成，Phase B/C 在觀察期）
- cross-project test 全紅（pytest 覆蓋）
- `grep -r "awoooi-prod" apps/api/src/` 結果為 0
- `grep -r "192.168.0.188" apps/api/src/` telemetry assert 消失
- vuln-verifier PoC 重跑：P0-05 nonce 偽造失敗、P0-06 webhook replay 失敗
- Budget hard kill 測試：超額後 LLM call 被拒絕

---

### Phase 3 — Contract Packages & Validators

**目標**：六合約從散文升級為可驗證程式。
**前置**：Phase 1 完成（contract_revisions 表存在）

**範圍**：
- `packages/awooop-contracts/`（此時才建立！）
- `apps/api/src/services/contract_service.py`（新建）
- `apps/api/src/repositories/contract_repository.py`（新建）

**禁止碰**：
- 任何既有 provider / router / telegram 路徑
- `apps/web/`（UI 留 Phase 8 之後）

**工作項**：

```
3.1  建立 packages/awooop-contracts/（此時才有真實內容）
     - 六合約 JSON Schema（Project/Tenant、Agent、MCP Gateway、Policy/Routing、Run State、Channel Event）
     - Pydantic v2 models 對應六合約
     - envelope schema：platform invocation、MCP tool call、run state transition、channel event
     - golden fixtures（valid × 6 + invalid × 6）

3.2  Contract lifecycle service
     - draft()：建立 draft revision，不可被 runtime 讀
     - publish()：產生 immutable published revision（body_hash = sha256(body_json)）
     - activate()：更新 active pointer，寫入 contract_outbox（ADR-113）
     - get_active()：runtime 讀取路徑，只返回 published + active
     - 全部操作記錄 audit log

3.3  Output schema validator middleware
     - LLM 回傳 → 過 schema validator → 失敗 → retry（上限 3 次）→ 失敗 → error code（E-SCHEMA-001）
     - 任何 schema 不符的 LLM 輸出無法到達 channel adapter

3.4  Contract governance（ADR-112）
     - CODEOWNERS 指定 packages/awooop-contracts/
     - publish API：HMAC 簽章驗證
     - activate API：approval workflow（multi_sig_redis 路徑）

3.5  SHA-256 artifact 驗證
     - 所有 artifact ref 含 sha256
     - runtime 讀取時驗 hash（與 DB 記錄比對）
```

**DoD**：
- schema 不符的 LLM 輸出無法到達 channel adapter（整合測試）
- AWOOOI 第一份 Agent contract 可 publish + activate（E2E）
- prompt/schema ref 必含 sha256

---

### Phase 4 — Platform Shell in Shadow Mode

**目標**：建立第一個 runtime shell，只跑 shadow，不改 legacy 行為。
**前置**：Phase 3 完成

**範圍**：
- `apps/api/src/api/v1/platform/` — 新增 platform runs API
- `apps/api/src/services/platform_runtime.py` — 新建
- `apps/api/src/services/run_state_machine.py` — Run FSM 實作（P2-02）
- `apps/api/src/workers/platform_worker.py` — 新建
- `apps/api/src/services/audit_sink.py` — 加 redaction（P1-08）

**禁止碰**：
- 任何既有 `/v1/incidents/`、`/v1/webhooks/` 路徑
- Telegram bot handler（legacy 維持）
- EwoooC 接入（留 Phase 6）

**工作項**：

```
4.1  Run API shell（shadow only）
     - POST /v1/platform/runs
     - 生成 run_id（UUID v7）、trace_id（W3C traceparent compatible）
     - 解析 project + agent contract active revision
     - 解析 EffectivePolicy（6 層合併，不改 provider 行為）

4.2  Run State Machine（ADR-114 + ADR-119）
     - States: PENDING → RUNNING → WAITING_TOOL → WAITING_APPROVAL → COMPLETED / FAILED / CANCELLED
     - lease_until、heartbeat_at、attempt_count 欄位
     - SKIP LOCKED 取單（防 double-pickup）
     - stale run reaper（每分鐘掃 expired lease，回到 PENDING 或 FAILED）
     - SAGA step journal（ADR-119）：每個 tool call 寫入 step_id、補償指令

4.3  Idempotency（ADR-114）
     - (project_id, channel_type, provider_event_id) 複合 unique
     - 重複事件 return 既有 run_id（不產生新 run）
     - Redis NX + PG constraint 雙層保護

4.4  Audit log redaction（ADR-116）
     - audit_sink 寫入前過 sanitization_service pipeline
     - PII / secret pattern 硬攔（含 GCP IP、PG password、Telegram token 等）
     - audit log 不記錄 raw LLM input/output，只記 hash + schema validation result

4.5  Observability（ADR-121）
     - OTel GenAI span 命名（gen_ai.request.*）
     - token 計數 attribute（gen_ai.usage.prompt_tokens 等）
     - metrics label：只 project_id / agent_id / status / provider（禁止 run_id/trace_id/session_id 進 metrics）
     - run_id / trace_id 只進 logs/traces（不進 metrics）

4.6  Shadow mode wiring
     - 選定 3 個 AWOOOI 事件 mirror 到 shadow（不發 user response）
     - shadow run 0 destructive tool call（MCP write/execute 全 block）

4.7  Token Budget Hard Kill（ADR-120）
     - per-run token budget（from EffectivePolicy）
     - 超額 → hard kill → FAILED state → error code E-BUDGET-001
     - 每 run 完成後寫入 budget_ledger（實際消耗）
```

**RACI**：
- R：fullstack-engineer（API + service）、db-expert（run state schema review）
- A：critic（shadow mode 設計 review）、vuln-verifier（redaction PoC）
- C：debugger（trace_id 貫穿設計）、tool-expert（OTel 整合）
- I：migration-engineer（worker lease 相容性）

**DoD**：
- shadow run 0 user-visible response、0 destructive tool call（vuln-verifier 驗證）
- legacy AWOOOI 行為 0 改變（回歸測試通過）
- worker crash 後 stale run 1 分鐘內被回收（自動化測試）
- duplicate event 不產生重複 run（idempotency 測試）
- audit log 0 secret 命中（vuln-verifier 抽樣 100 筆）
- token budget 超額觸發 hard kill（整合測試）

---

### Phase 5 — MCP Gateway First Slice

**目標**：tool 授權搬到 Gateway，read-only 工具先進，解決 sanitization enforcement。
**前置**：Phase 4 完成

**範圍**：
- `apps/api/src/plugins/mcp/gateway.py` — 新建 MCP Gateway
- `apps/api/src/plugins/mcp/registry.py:24-71` — `_provider` → `__provider`（P1-05）
- `apps/api/src/plugins/mcp/mcp_bridge.py` — 接入 Gateway
- `apps/api/src/services/sanitization_service.py` — enforcement point（P1-09）

**禁止碰**：
- MCP write/execute tools（寫/執行工具留 Phase 8）
- Telegram approval flow（改動在 Phase 8）

**工作項**：

```
5.1  MCP Gateway 表
     - awooop_mcp_tool_registry（tool_id, project_id, agent_id, tool_type, allowed_scopes）
     - awooop_mcp_grants（grant_id, project_id, agent_id, tool_id, granted_by, expires_at）
     - awooop_mcp_credential_refs（ref_id, tool_id, k8s_secret_ref, sha256）
     - awooop_mcp_gateway_audit（call_id, trace_id, run_id, tool_id, credential_ref, latency_ms, result_status）

5.2  Five-gate enforcement
     - Check: Project AND Agent AND Tool AND Environment AND Approval
     - 任一不符 → 拒絕 + 記錄 audit + error code E-MCP-GATE-XXX

5.3  Result sanitization enforcement（P1-04、P1-09）
     - 所有 MCP tool result 必經 sanitization_service pipeline
     - MCP Gateway 加 sanitization middleware（不允許 raw result 直接進 LLM context）
     - 進 LLM 前一層 + 進 audit sink 一層（雙層 redaction）
     - sast 掃描 agent 程式碼路徑：0 raw credential 接觸

5.4  _provider 修正（P1-05）
     - registry.py: _provider → __provider（雙底線 Python name mangling）
     - 加 unit test：外部 reflect 取用 → AttributeError

5.5  Credential isolation
     - agent 程式碼不直接存取 K8s Secret
     - Gateway 解析 credential_ref → 回傳 masked result（token 替換）
     - 2026-04-18 secret leak 重演測試：kubectl describe 輸出不出現在 LLM context

5.6  MCP OAuth 2.1（ADR-117）
     - 實作 per-tenant dynamic client registration（RFC 7591）
     - Resource Indicators（RFC 9728）防 Confused Deputy
     - PKCE flow for MCP Server binding
```

**RACI**：
- R：fullstack-engineer（Gateway service）
- A：vuln-verifier（credential isolation 驗證）、critic（架構 review）
- C：tool-expert（MCP spec 確認）、db-expert（Gateway 表設計 review）
- I：migration-engineer（MCP registry 相容性）

**DoD**：
- 2026-04-18 secret leak 重演測試通過（kubectl describe 輸出不出現在 LLM context 或 audit row）
- sast 掃描：agent 程式碼路徑 0 raw credential 接觸
- `__provider` 雙底線 unit test 通過
- Five-gate 全部 integration test 覆蓋

---

### Phase 6 — EwoooC Read-Only Tenant Onboarding

**目標**：以真實下游 tenant 驗證 AwoooP，全 read-only。
**前置**：Phase 5 完成、telemetry.py:71 hardcoded IP assert 已移除（Phase 2 完成）

**範圍**：
- `apps/api/src/` — EwoooC project provisioning
- `packages/awooop-contracts/` — EwoooC agent contract
- `apps/api/src/services/provider_proxy.py` — 新建 Provider Proxy Adapter（P1-02）

**禁止碰**：
- AWOOOI 任何既有業務邏輯
- MCP write/execute tools

**工作項**：

```
6.1  EwoooC project provisioning
     - INSERT INTO awooop_projects(project_id='ewoooc', ...)
     - 不可讀 AWOOOI data（RLS 驗證）

6.2  openclaw-biz agent contract
     - 針對市場情報 domain 設計 I/O schema
     - 安全 ceiling：read-only only，禁止 infra tool

6.3  Provider Proxy Adapter（P1-02，ADR-115）
     - 不只是改 OLLAMA_API_BASE
     - Proxy 入口強制注入 envelope：project_id / agent_id / trace_id / run_id
     - 過 EffectivePolicy + budget guard + audit
     - GCP Ollama 三層拓撲：EwoooC 走相同 primary/secondary/fallback 路由
     - read-only / model-call 入口優先啟用

6.4  Market intelligence MCP tools 註冊
     - 4 個 read-only tools：market_data_fetch、product_catalog_query、competitor_analysis、trend_report
     - 全部在 MCP Gateway 五重 gate 管控

6.5  Shadow → Canary 升級計畫
     - 先 14 天 shadow（Strangler Fig gate 量化）
     - 符合條件後升 canary（selected responses）
     - canary 通過再升 read_only
```

**RACI**：
- R：fullstack-engineer
- A：critic（EwoooC 資料隔離 review）、vuln-verifier（cross-tenant isolation PoC）
- C：db-expert（RLS 驗證）、migration-engineer（EwoooC rollback playbook，INV-6）
- I：tool-expert（GCP Ollama 拓撲 EwoooC 路由設定）

**DoD**：
- EwoooC SELECT 無法讀到 AWOOOI data（RLS + cross-tenant pytest）
- Provider Proxy Adapter E2E 測試：envelope 正確注入
- budget / audit 完全 project-scoped
- EwoooC 啟動時 telemetry.py 不再因 IP assert 失敗

---

### Phase 7 — Communication Hub Increment

**目標**：標準化 channel 但不切斷既有 bot。
**前置**：Phase 6 完成

**範圍**：
- `apps/api/src/services/channel_hub.py` — 新建
- `apps/api/src/services/telegram_gateway.py` — mirror inbound events
- `apps/api/src/api/v1/platform/channel.py` — 新建

**禁止碰**：
- 既有 telegram bot handler（維持 legacy 權威，直到 canary 量化 gate 通過）
- LINE / Slack 接入（留 v2）

**工作項**：

```
7.1  awooop_conversation_event + awooop_outbound_message 表
     - partition by created_at（月，Phase 1 已定策略）
     - retention policy 配置

7.2  Telegram inbound mirror
     - 現有 telegram_gateway.py 事件複製到 awooop_conversation_event
     - canonical principal mapping（ADR-115）：所有 sender 寫入 awooop_platform_subjects

7.3  Progressive Feedback Policy（P2-11）
     - WAITING_TOOL / RUNNING / WAITING_APPROVAL → 必發 Telegram 暫態訊息
     - 用 edit_message 更新（非新訊息，不觸發通知）
     - 首則進度訊息 ≤ 30s

7.4  Idempotency 驗證（已由 Phase 4 完成）
     - duplicate channel retry 不產生 duplicate run（整合測試）

7.5  Adapter-level 安全
     - 所有 channel adapter：escaping + redaction + idempotency + delivery audit
     - channel adapter 0 LLM 呼叫、0 MCP 呼叫（pytest 覆蓋）

7.6  量化 gate 監控儀表板（配合 ADR-UI-03）
     - Strangler Fig gate 指標：decision divergence / p95 latency / error rate
     - 供 Phase 8 升級決策用
```

**RACI**：
- R：fullstack-engineer（API + channel hub）
- A：critic（channel 設計 review）、debugger（trace_id 貫穿驗證）
- C：frontend-designer（進度訊息 UX）、tool-expert（Telegram API 規格確認）
- I：migration-engineer（channel 相容性）

**DoD**：
- channel adapter 0 LLM 呼叫、0 MCP 呼叫
- async run 首則進度訊息 ≤ 30s
- duplicate retry 不產生 duplicate run

---

### Phase 8 — Suggest & Controlled Write Paths

**目標**：從 read-only 升級到 propose，再到 controlled execute。
**前置**：Phase 7 完成 + Strangler Fig shadow→canary gate 全通過

**範圍**：
- `apps/api/src/services/multi_sig_redis.py` — approval token 簽章（P1-06）
- `apps/api/src/services/approval_timeout_resolver.py` — 加 trace_id（P1-15）
- `apps/api/src/api/v1/platform/suggest.py` — suggest mode endpoint
- Feature flags for write/execute paths

**禁止碰**：
- 任何 write/execute tool 的預設啟用
- Strangler Fig 量化 gate 通過前不做 auto_remediate

**工作項**：

```
8.1  Approval Token 安全強化（P1-06，ADR-116）
     - WAITING_APPROVAL resume API：強制驗 approval_token（HS256，15min TTL，jti Redis NX）
     - approval state：PG 為 source of truth，Redis 為 cache
     - 過期 / 已決 / 重放 → 全部拒絕 + error code E-APPROVAL-XXX

8.2  multi_sig_redis.py + approval_timeout_resolver.py trace_id 補入
     - 所有 approval 操作加 trace_id（P1-15）
     - 完整鏈路可追蹤（debugger 驗證）

8.3  Suggest mode for AWOOOI SRE flows
     - 選定低風險 3 個 SRE flow（e.g., 告警靜音建議、playbook 推薦）
     - suggest 模式：AI 輸出建議，人工決定執行
     - 量化 gate（ADR-106 補章）：
       * shadow → canary：≥14 天 + divergence <5% + p95 <10% + 0 P1 incident
       * canary → read_only：≥7 天 + error rate <0.5% + cost diff <50%
       * read_only → suggest：≥14 天 + accept rate ≥50% + 0 hallucination escalation
       * suggest → auto_remediate：≥30 天 + rollback evidence ≥3 次 + approval token live + dry-run ≥99%

8.4  Dry-run 與 rollback evidence gate
     - 每個 write/execute tool 必須有 dry-run mode
     - rollback playbook 寫入 INV-6（Phase 0 已完成，此時執行驗證）
     - 記錄每次 rollback 結果作為 Phase 8 gate evidence

8.5  Feature Flag Registry（見 §10）
     - suggest mode：feature flag AWOOOP_SUGGEST_MODE（default OFF）
     - controlled write：feature flag AWOOOP_WRITE_MODE（default OFF）
     - 需顯式 flip 才啟用，不能環境變數意外帶入

8.6  vuln-verifier PoC 驗收
     - WAITING_APPROVAL 無 token resume 必失敗
     - Redis 宕機時 approval 仍可從 PG 恢復
```

**RACI**：
- R：fullstack-engineer
- A：vuln-verifier（approval security PoC）、critic（write path review）
- C：debugger（trace_id 驗證）、db-expert（approval state PG review）
- I：migration-engineer（feature flag rollback）

**DoD**：
- WAITING_APPROVAL 無 token resume 被拒絕（vuln-verifier PoC 通過）
- Redis 宕機後 approval 從 PG 恢復（整合測試）
- write/execute 預設 OFF，feature flag 手動 flip 才啟用
- 所有 Strangler Fig gate 量化驗收通過（critic + db-expert + vuln-verifier 三方簽核）

---

## 4. 資料庫詳細 Schema

### 4.1 awooop_contract_revisions（六合約共用 revision 表）

```sql
CREATE TABLE awooop_contract_revisions (
    revision_id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    project_id      VARCHAR(64) NOT NULL REFERENCES awooop_projects(project_id),
    contract_family VARCHAR(32) NOT NULL  -- project_tenant/agent/mcp_gateway/policy_routing/run_state/channel_event
    contract_id     VARCHAR(128) NOT NULL,
    version         VARCHAR(32) NOT NULL,
    lifecycle_status VARCHAR(16) NOT NULL DEFAULT 'draft',  -- draft/published/superseded/revoked
    body_json       JSONB NOT NULL,
    body_schema_version VARCHAR(32) NOT NULL,
    body_hash       CHAR(64) NOT NULL,  -- SHA-256 hex
    created_by      VARCHAR(128) NOT NULL,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    published_at    TIMESTAMPTZ,
    supersedes_revision_id UUID REFERENCES awooop_contract_revisions(revision_id),
    -- Immutability constraint
    CONSTRAINT published_body_immutable CHECK (
        lifecycle_status = 'draft' OR body_json IS NOT NULL
    )
);

-- Runtime reads view（只看 published/active，不看 draft）
CREATE VIEW awooop_published_revisions AS
    SELECT * FROM awooop_contract_revisions
    WHERE lifecycle_status IN ('published', 'superseded');

-- Append-only trigger
CREATE OR REPLACE FUNCTION prevent_revision_update()
RETURNS TRIGGER AS $$
BEGIN
    IF OLD.lifecycle_status != 'draft' THEN
        RAISE EXCEPTION 'Published contract revision is immutable';
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER enforce_revision_immutability
    BEFORE UPDATE ON awooop_contract_revisions
    FOR EACH ROW EXECUTE FUNCTION prevent_revision_update();

-- RLS
ALTER TABLE awooop_contract_revisions ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON awooop_contract_revisions
    USING (project_id = current_setting('app.project_id', TRUE)
           OR current_user = 'awooop_platform');
```

### 4.2 awooop_run_state（含 lease + SAGA journal）

```sql
CREATE TABLE awooop_run_state (
    run_id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    project_id      VARCHAR(64) NOT NULL,
    agent_id        VARCHAR(128) NOT NULL,
    trace_id        CHAR(32),  -- W3C trace_id hex
    parent_run_id   UUID,
    status          VARCHAR(32) NOT NULL DEFAULT 'PENDING',
    migration_mode  VARCHAR(32) NOT NULL DEFAULT 'shadow',  -- shadow/canary/read_only/suggest/auto_remediate
    -- Worker lease
    lease_until     TIMESTAMPTZ,
    heartbeat_at    TIMESTAMPTZ,
    attempt_count   INT NOT NULL DEFAULT 0,
    worker_id       VARCHAR(128),
    -- Token budget
    budget_limit_tokens BIGINT,
    tokens_used     BIGINT NOT NULL DEFAULT 0,
    -- Timestamps
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    completed_at    TIMESTAMPTZ,
    -- SAGA journal（step-level）
    saga_steps      JSONB DEFAULT '[]',  -- [{step_id, tool, status, compensation_cmd, completed_at}]
    -- Metadata
    input_hash      CHAR(64),  -- SHA-256 of input envelope（for audit）
    effective_policy_revision_id UUID
) PARTITION BY RANGE (created_at);

-- Per-project RLS
ALTER TABLE awooop_run_state ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON awooop_run_state
    USING (project_id = current_setting('app.project_id', TRUE)
           OR current_user = 'awooop_platform');
```

### 4.3 awooop_budget_ledger（Token Budget Hard Kill）

```sql
CREATE TABLE awooop_budget_ledger (
    ledger_id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    project_id      VARCHAR(64) NOT NULL,
    period          DATE NOT NULL,  -- YYYY-MM-DD（月份第一天）
    provider        VARCHAR(32) NOT NULL,
    tokens_input    BIGINT NOT NULL DEFAULT 0,
    tokens_output   BIGINT NOT NULL DEFAULT 0,
    cost_usd        NUMERIC(12, 6) NOT NULL DEFAULT 0,
    hard_kill_at    NUMERIC(12, 6),  -- NULL = no limit
    hard_killed     BOOLEAN NOT NULL DEFAULT FALSE,
    last_run_id     UUID,
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE(project_id, period, provider)
);
```

### 4.4 8 群新增/擴充表清單（db-expert 發現）

| 表名 | 缺失欄位 / 缺失 Index | Phase |
|------|----------------------|-------|
| `incidents` | 加 `project_id`、`trace_id`、`awooop_run_id` | Phase 2 |
| `playbooks` | 加 `project_id`、`agent_id` | Phase 2 |
| `km_entries` | 加 `project_id`、`namespace` | Phase 2 |
| `mcp_audit_log` | 加 `trace_id`、`run_id`、`project_id`；加 index on (run_id) | Phase 2 |
| `ai_decisions` | 加 `project_id`、`run_id`、加 index on (run_id) | Phase 2 |
| `approval_records` | 加 `trace_id`、`approval_token_jti`、加 index on (jti) | Phase 2/8 |
| `telegram_events` | 加 `project_id`、`platform_subject_id` | Phase 7 |
| `ollama_health_checks` | 加 `host_tier`（gcp_a/gcp_b/local）、`project_id=__platform__` | Phase 2 |

---

## 5. 安全修補計畫（vuln-verifier 驗收）

### 5.1 PoC 確認的三個漏洞

| 漏洞 | 位置 | PoC 狀態 | 修補方案 | Phase |
|------|------|---------|---------|-------|
| Nonce 偽造（server nonce 不依賴 server_secret）| security_interceptor.py:451-490 | **PoC 確認可通過驗證** | HMAC(server_secret + nonce)，server_secret 從 K8s Secret 注入 | Phase 2 |
| Webhook replay（無 timestamp/nonce）| webhooks.py:679-728 | **PoC 確認可 replay** | 加 timestamp（±5min）+ nonce Redis NX | Phase 2 |
| requires_approval 由 LLM output 決定 | decision_manager.py（approval 鏈）| **PoC 確認可繞過** | policy contract 決定，禁止 LLM output 影響 | Phase 2 |

### 5.2 approval_token 規格

```
簽章算法：HS256
Payload:
  - jti: UUID（唯一性，Redis NX 15min TTL）
  - iss: "awooop-platform"
  - sub: "{project_id}:{run_id}"
  - aud: "awooop-approval"
  - exp: now + 15min
  - approval_type: "human" | "system"
  - decision_scope: [tool_id, ...]

驗證：
  1. 簽章驗證
  2. exp 未過期
  3. Redis NX 確認 jti 未使用（防 replay）
  4. sub 與 resume 的 run_id 吻合
  5. decision_scope 與 run 的 tool 吻合
```

### 5.3 vuln-verifier 每 Phase 驗收清單

- Phase 2：nonce 偽造失敗、webhook replay 失敗、requires_approval 無法由 LLM 決定
- Phase 4：audit log 0 secret 命中（抽樣 100 筆）
- Phase 5：agent 程式碼路徑 0 raw credential（sast）
- Phase 6：cross-tenant isolation PoC（EwoooC 無法讀 AWOOOI）
- Phase 8：approval token 無 token resume 被拒、Redis 宕機後從 PG 恢復

---

## 6. API Endpoint 完整清單（fullstack 補充）

### 6.1 現有（不動）
- `POST /v1/webhooks/telegram`
- `POST /v1/webhooks/alertmanager`
- `GET /v1/incidents/`
- `POST /v1/decisions/`

### 6.2 Phase 4 新增（Platform Shell）
- `POST /v1/platform/runs` — 建立 run（async）
- `GET /v1/platform/runs/{run_id}` — 查詢 run state
- `GET /v1/platform/runs/{run_id}/steps` — 查詢 SAGA steps
- `POST /v1/platform/runs/{run_id}/cancel` — 取消 run

### 6.3 Phase 4-5 新增（Approval）
- `POST /v1/platform/runs/{run_id}/approve` — 帶 approval_token 的 resume
- `POST /v1/platform/runs/{run_id}/reject` — 拒絕（帶理由）

### 6.4 Phase 6 新增（Tenant）
- `POST /v1/platform/projects` — 建立 project（admin only）
- `GET /v1/platform/projects/{project_id}/migration_state` — 查詢 Strangler Fig 狀態
- `POST /v1/platform/projects/{project_id}/contracts` — 建立 contract draft
- `POST /v1/platform/projects/{project_id}/contracts/{contract_id}/publish` — publish
- `POST /v1/platform/projects/{project_id}/contracts/{contract_id}/activate` — activate

### 6.5 Phase 7 新增（Channel Hub）
- `GET /v1/platform/channel_events` — 查詢 conversation events（with pagination）
- `POST /v1/platform/outbound` — 發送 outbound message（admin/test）

---

## 7. 錯誤碼字典（必補 9 個）

| Error Code | HTTP Status | 描述 | 場景 |
|------------|-------------|------|------|
| `E-SCHEMA-001` | 422 | LLM output schema validation failed | Phase 3 contract validator |
| `E-BUDGET-001` | 429 | Token budget hard kill triggered | Phase 4 budget guard |
| `E-APPROVAL-001` | 401 | approval_token missing or invalid | Phase 8 approval resume |
| `E-APPROVAL-002` | 401 | approval_token expired | Phase 8 |
| `E-APPROVAL-003` | 409 | approval_token already used (replay) | Phase 8 |
| `E-MCP-GATE-001` | 403 | MCP tool not authorized for this project | Phase 5 |
| `E-MCP-GATE-002` | 403 | MCP tool not authorized for this agent | Phase 5 |
| `E-MCP-GATE-003` | 403 | MCP write/execute tool blocked (not in auto_remediate mode) | Phase 5/8 |
| `E-TENANT-001` | 403 | Cross-tenant data access blocked | Phase 2+ |
| `E-IDEMPOTENT-001` | 200 | Duplicate event, returning existing run_id | Phase 4 |
| `E-RATE-001` | 429 | Project rate limit exceeded | Phase 2+ |
| `E-SAGA-001` | 500 | SAGA compensation failed, manual intervention required | Phase 4/ADR-119 |

---

## 8. 前端 Operator Console（frontend-designer，8 個模組）

> 實作在 Phase 8 之後（或 Phase 6 可 prototype Operator Console）
> ADR-UI-01~04 定架構，此處為工作項清單

| 模組 | 描述 | 優先順序 |
|------|------|---------|
| **Tenant Management** | project 列表、建立、migration_state 視覺化、budget 設定 | P1（Phase 6 prototype）|
| **Contract Lifecycle** | draft/publish/activate 操作、revision diff、六合約 family 篩選 | P1（Phase 6 prototype）|
| **Run Monitor** | run FSM 視覺化、shadow/canary/active 標記、trace_id drill-down | P1（Phase 4 後）|
| **Strangler Fig Dashboard** | shadow→canary gate 量化指標（divergence / latency / error rate）即時儀表板 | P1（Phase 7 後）|
| **Budget & Cost** | per-project token budget、hard kill 觸發歷史、成本趨勢（GCP Ollama vs paid provider）| P2 |
| **Audit Log Viewer** | audit log 查詢（redaction 後）、secret 命中警告、trace_id 關聯 | P2 |
| **MCP Gateway Admin** | tool registry、grants 管理、credential refs（masked）、audit | P2 |
| **Principal Directory** | platform_subject 查詢、Telegram/LINE/API user mapping | P3 |

**與現有設計系統整合**：
- 必須使用 next-intl（禁止 hardcode 中文/英文）
- 禁止 emoji，使用 Lucide/SVG icon
- 遵循 `feedback_design_system_consistency.md` 全站設計規範
- 禁止直接存取內網 IP（`feedback_frontend_internal_ip_ban.md`）

---

## 9. 重構切割計畫（11 PR，refactor-specialist）

> 每 PR 必須獨立可合併、有 rollback 能力、不依賴後 PR

| PR# | 標題 | 前置 PR | 影響範圍 | 風險 |
|-----|------|---------|---------|------|
| PR-01 | `telemetry.py:71` 硬碼 IP assert 移除 | 無 | 1 行 | 低 |
| PR-02 | `decision_manager.py:240` silence key 常數化 | 無 | 2 行 | 低 |
| PR-03 | `ollama_auto_recovery.py:230` 第二定義移除 | 無 | ~5 行 | 低 |
| PR-04 | `_provider` → `__provider`（registry.py）| 無 | ~20 行 | 低 |
| PR-05 | `mcp_bridge.py` namespace 動態化 | 無 | ~30 行 | 中 |
| PR-06 | `consensus_engine.py` CONSENSUS_PREFIX 加 project 前綴 | Phase 2 Redis 雙寫 Phase A | ~15 行 | 中 |
| PR-07 | nonce 重設計 + webhook timestamp/nonce（ADR-116）| 無 | ~100 行 | 高（安全修補）|
| PR-08 | Repository project_id filter 批次 1（incidents/playbooks/km）| Phase 1 schema | ~200 行 | 中 |
| PR-09 | Repository project_id filter 批次 2（mcp/ai_decisions/approval）| PR-08 | ~200 行 | 中 |
| PR-10 | Background loop 標記（31 個 loop，main.py）| ADR-123 | ~150 行 | 中 |
| PR-11 | AnomalyCounter per-project 改造 | PR-10 | ~80 行 | 中 |

> PR-01~05 可並行（無依賴），先做先進。
> PR-06~07 需要 Redis 雙寫 Phase A 先完成。
> PR-08~09 需要 Phase 1 schema 先完成。

---

## 10. Feature Flag / Kill-Switch Registry

| Flag 名稱 | 預設值 | 說明 | 開啟條件 |
|-----------|--------|------|---------|
| `AWOOOP_SHADOW_MODE` | OFF | 啟用 shadow run（鏡像但不回應）| Phase 4 完成後手動 flip |
| `AWOOOP_CANARY_MODE` | OFF | 啟用 canary（部分 user-visible 回應）| shadow gate 14天量化通過 |
| `AWOOOP_READ_ONLY_MODE` | OFF | read-only 查詢搬到 AwoooP | canary gate 7天量化通過 |
| `AWOOOP_SUGGEST_MODE` | OFF | AI 建議但人工決定 | read_only gate 14天通過 |
| `AWOOOP_WRITE_MODE` | OFF | 受控 write/execute tool 啟用 | suggest gate 30天通過 + rollback evidence ≥3 |
| `AWOOOP_BUDGET_HARD_KILL` | ON | token budget 超額直接終止（非只告警）| **預設 ON**（ADR-120）|
| `AWOOOP_MCP_OAUTH21` | OFF | MCP OAuth 2.1 flow（ADR-117）| Phase 5 完成後 |
| `AWOOOP_RLS_STRICT` | OFF | 嚴格 RLS 模式（禁止 awooop_platform bypass）| Phase 2 完成 + 30天 soak |
| `AWOOOP_EWOOOC_LIVE` | OFF | EwoooC tenant 切為 live（非 shadow）| Phase 6 canary 7天通過 |

---

## 11. Runbook 清單（8 份，debugger 需求）

| Runbook | 位置 | 觸發情境 | 主要步驟 |
|---------|------|---------|---------|
| **RB-01**: AwoooP Contract Publish Failure | `docs/runbooks/awooop-contract-publish-failure.md` | schema 驗證失敗、CODEOWNERS reject | 1.查 body_hash 2.查 draft 狀態 3.rollback to previous active |
| **RB-02**: Run State Stuck / Stale Lease | `docs/runbooks/awooop-run-stuck.md` | run 停在 RUNNING > 10min | 1.查 lease_until 2.手動 reaper 3.查 saga_steps 決定補償或放棄 |
| **RB-03**: Budget Hard Kill Triggered | `docs/runbooks/awooop-budget-hard-kill.md` | E-BUDGET-001 大量出現 | 1.查 budget_ledger 2.確認 hard_kill_at 閾值 3.是否 incident 爆發 4.臨時上調 or 等下月 reset |
| **RB-04**: Phase Rollback（Strangler Fig）| `docs/runbooks/awooop-phase-rollback.md` | canary 錯誤率 > threshold | 1.切回 project_migration_state 到上一個 mode 2.清 Redis canary cache 3.通知 EwoooC（如果影響到）|
| **RB-05**: Approval Token Replay 告警 | `docs/runbooks/awooop-approval-replay.md` | E-APPROVAL-003 出現 | 1.查 jti Redis key 2.確認 IP / user 3.吊銷 token 4.通知安全 |
| **RB-06**: Cross-Tenant Data Leak 告警 | `docs/runbooks/awooop-cross-tenant-leak.md` | E-TENANT-001 大量出現 | 1.立即停 canary/active mode 2.查 audit log 3.RLS 設定確認 4.PITR restore 評估 |
| **RB-07**: GCP Ollama Failover 異常 | `docs/runbooks/awooop-gcp-ollama-failover.md` | GCP-A/B 同時掛、Local fallback 也掛 | 1.確認 `platform:ollama:primary` Redis key 2.手動設定 fallback 3.確認 paid provider 緊急路由 |
| **RB-08**: SAGA Compensation 失敗 | `docs/runbooks/awooop-saga-compensation-fail.md` | E-SAGA-001 出現 | 1.查 saga_steps JSON 2.找失敗 step 3.手動執行補償指令 4.更新 run 狀態 |

---

## 12. 工具補強計畫（tool-expert）

| 工具 | 用途 | 安裝位置 | Phase |
|------|------|---------|-------|
| **PgBouncer** | AwoooP 多 worker 下 PG connection pool 防爆 | K8s sidecar 或獨立 Pod | Phase 4 之前 |
| **Sealed Secrets** | 替代 K8s Secret 明文，CI/CD 安全 | K3s cluster | Phase 2（security hardening 時）|
| **OPA / Cedar** | policy engine，授權邏輯集中化（取代散落程式碼）| 作為 sidecar 或 admission webhook | Phase 5 之前 |
| **chaostoolkit / LitmusChaos** | Strangler Fig 切換的混沌驗證（worker 崩潰、Redis 宕機、PG timeout）| CI pipeline | Phase 4 完成後 |
| **awooop-ctl** | AwoooP CLI（contract CRUD / run 查詢 / migration state 管理）| 本地 CLI + CI | Phase 6 之前 |
| **pg_partman** | PostgreSQL partition 自動管理 | K8s Pod / cron | Phase 4（run_state 上線前）|
| **pgvector（已有）** | KM 向量搜索 | 已存在，需 per-project namespace | Phase 2 |
| **OpenTelemetry Collector** | OTel pipeline（ADR-121），現在直送 SignOz 188:24318，未來需 sampling | K8s DaemonSet | Phase 4 之前 |

---

## 13. 業界對齊（web-researcher 發現）

### 13.1 $47k Agent Loop 事故教訓（Token Budget Hard Kill）

問題：alert ≠ enforcement。僅發 Prometheus alert 但 agent 仍繼續執行，一個 loop 燒了 $47k。

AwoooP 解法（ADR-120）：
- 三層 budget limit：per-run / per-project / per-tenant
- **Hard Kill**：超額 → 直接終止 run（not just log/alert）
- Redis hot counter（每次 call 減少）+ PG budget_ledger 事務（final decision）
- `AWOOOP_BUDGET_HARD_KILL` feature flag 預設 ON（唯一預設開啟的 flag）

### 13.2 Durable Execution / SAGA 補償交易（ADR-119）

業界標準（Temporal / Conductor / Azure Durable Functions）：multi-step tool chain 必須有 step-level journal + 補償機制。

AwoooP 解法：
- `saga_steps` JSONB 欄位在 `awooop_run_state`
- 每個 tool call 記錄：step_id / tool / status / compensation_cmd / completed_at
- 失敗時執行補償指令（反向操作）
- 補償失敗 → E-SAGA-001 + Runbook RB-08

### 13.3 MCP OAuth 2.1 Confused Deputy（ADR-117）

MCP spec 2025-06-18 要求：
- per-tenant dynamic client registration（RFC 7591）
- Resource Indicators（RFC 9728）：防止 token 被跨 resource server 使用
- PKCE（RFC 7636）：防止 authorization code interception

AwoooP 解法（ADR-117）：
- 每個 tenant 動態 client registration，不共用 client_id
- Resource Indicator 必須匹配 tool registry 的 target URI
- `E-MCP-GATE-001/002/003` error codes 覆蓋 Confused Deputy 情境

### 13.4 OTel GenAI Semantic Conventions（ADR-121）

官方規範（opentelemetry-specification/semantic_conventions/gen-ai）：
- span 命名：`gen_ai.{system}.{operation}`（e.g., `gen_ai.anthropic.chat`）
- token attribute：`gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens`
- model attribute：`gen_ai.request.model` / `gen_ai.response.model`

AwoooP 解法：全部 LLM call 必須 emit 以上 attribute，進 SignOz（188:24318）。

### 13.5 OWASP Agentic AI Top 10 對齊（ADR-122）

| OWASP 項目 | AwoooP 對應控制 |
|-----------|---------------|
| OAI-01 Prompt Injection | MCP Gateway result sanitization + schema validator |
| OAI-02 Insecure Tool Use | Five-gate MCP enforcement + audit |
| OAI-03 Excessive Agency | requires_approval from policy（禁 LLM 決定）+ write/execute feature flag |
| OAI-04 Supply Chain | contract publish HMAC + artifact SHA-256 |
| OAI-05 Data Leakage | audit log redaction + credential isolation |
| OAI-06 Insufficient Observability | OTel GenAI + audit sink + run trace_id |
| OAI-07 Unsafe Orchestration | SAGA journal + compensation + hard kill |
| OAI-08 Memory Vulnerabilities | contract revision immutability + RLS |
| OAI-09 Access Control Bypass | approval_token HS256 + jti replay prevention |
| OAI-10 Resource Exhaustion | Token Budget Hard Kill（ADR-120）|

---

## 14. GCP Ollama 拓撲對 AwoooP 的影響（ADR-110 整合）

### 14.1 新拓撲（ADR-110 + ADR-125，2026-05-05 修正）

```
Phase 0 bridge:
Primary  : GCP-A  http://192.168.0.110:11435   （110 nginx → GCP public IP）
Secondary: GCP-B  http://192.168.0.110:11436
Fallback : Local  http://192.168.0.111:11434
Emergency: Gemini → Nemotron → Claude           （全 Ollama 掛時，budget gated）

Target private mesh:
Primary  : GCP-A  http://10.77.114.21:11434
Secondary: GCP-B  http://10.77.114.22:11434
Fallback : Local  http://10.77.114.111:11434
```

ADR-125 修正 ADR-110 的傳輸層：公網 GCP IP / 110 nginx proxy 僅保留為
過渡與 rollback bridge。正式路徑是 WireGuard private mesh；runtime 路由由
AwoooP Inference Gateway 管理。

### 14.2 AwoooP 必須處理的影響項目

| 影響項 | 位置 | 處理方式 | Phase |
|--------|------|---------|-------|
| `ollama:current_primary` Redis key 雙寫（只支援 1 個 URL，新需要 3 層）| INV-1 | 改為 `platform:ollama:topology`（JSON：primary/secondary/fallback）| Phase 2 |
| `ollama_auto_recovery.py:230` 第二定義（P0-11）| ollama_auto_recovery.py | 移除，統一從 config 讀 | Phase 2 PR-03 |
| GCP public IP 進 INV-4（34.143.170.20, 34.21.145.224）| INV-4 | 標為 transitional only；正式改用 `10.77.114.21/22` mesh IP | Phase 0 INV-4 |
| WireGuard mesh | ADR-125 / runbook | 建立 `10.77.114.0/24` private transport；關閉 public 11434 | Phase 2 前置 |
| AwoooP Inference Gateway | ADR-125 / runbook | alert-fast / code-review / embedding / deep-rca lane 隔離，避免重模型搶告警 lane | Phase 4 |
| EwoooC Provider Proxy 走 GCP Ollama 路由 | Phase 6 | EwoooC 共用 platform Ollama topology（platform_resource）| Phase 6 |
| `telemetry.py:71` IP assert（P0-08）| telemetry.py:71 | 移除後，GCP IP 不再觸發 assert；改為 config-driven | Phase 2 PR-01 |
| budget_ledger 記錄 Ollama usage（免費 GCP 仍需 token 計數）| Phase 4 | Ollama call 也必須記錄 token 消耗（budget_ledger）| Phase 4 |
| Runbook RB-07（GCP Ollama failover 異常）| docs/runbooks/ | Phase 0 寫 Runbook，Phase 4 後實際 E2E 測試 | Phase 0 |

### 14.3 Ollama GCP 為 platform_resource（ADR-111）

GCP Ollama（bridge: 34.143.170.20 / 34.21.145.224；target mesh:
10.77.114.21 / 10.77.114.22）與 Local Ollama（192.168.0.111 / target
10.77.114.111）一律聲明為 `platform_resource`：
- 不屬於任何 tenant
- 所有 tenant（AWOOOI / EwoooC / Tsenyang / Bitan）共用，但 audit 記錄各自 project_id
- `platform:ollama:topology` Redis key 前綴為 `platform:`（非 `{project_id}:`）

### 14.4 實測限制（2026-05-05）

`scripts/ops/ollama-topology-check.sh` 實測：

- GCP-A `gemma3:4b` 約 2s，但 `size_vram=0`
- GCP-B `gemma3:4b` 約 8.5s，但 `size_vram=0`
- 111 fallback `gemma3:4b` 約 4.9s，`size_vram=8210446336`

結論：GCP-A/B 可以作為同步 `alert-fast` lane，但不可承擔 14B/32B 同步告警診斷。
重模型需由 Inference Gateway 分流到 async / 111 / GPU 節點。

---

## 15. 工作排序總表（含並行群組 + Critical Path）

### Critical Path（序列執行，不可跳）

```
Phase 0 全部 ADR/INV
  → Phase 1 Schema（PR-01/02/03/04/05 可並行先做）
  → Phase 2 Security Hardening + Redis 遷移（PR-06~11）
  → Phase 3 Contract Packages
  → Phase 4 Platform Shell（PgBouncer + OPA/pg_partman 同步準備）
  → Phase 5 MCP Gateway
  → Phase 6 EwoooC（14天 shadow gate）
  → Phase 7 Channel Hub（7天 canary gate）
  → Phase 8 Suggest + Write（30天 suggest gate）
```

### 可並行工作群組

| 群組 | 工作 | 可與哪個並行 |
|------|------|-----------|
| G-A（Phase 0 並行）| ADR-111～115 各自獨立 | 全部並行（5 份 ADR 各分配一位）|
| G-B（Phase 0 並行）| ADR-116～124 | 與 G-A 並行 |
| G-C（Phase 0 並行）| INV-1～INV-9（部分依賴 codebase 探索）| 與 G-A/G-B 並行 |
| G-D（Phase 2 並行）| PR-01/02/03/04/05（獨立小修補）| 全部並行 |
| G-E（Phase 2 並行）| Redis 雙寫 + repository 改造 + security hardening | 各自獨立，但 security hardening 優先 |
| G-F（Phase 4 並行）| PgBouncer 安裝 + pg_partman 安裝 + OPA 安裝 | 與 Phase 3 Contract Packages 並行 |
| G-G（Phase 5-6 並行）| Operator Console prototype（ADR-UI-01~04）| 與 Phase 6 EwoooC shadow 並行 |

### 完整排序表

| 順序 | 工作 | docs-only | 並行群組 | 阻擋誰 |
|------|------|-----------|---------|-------|
| 1-A | ADR-111 Bootstrap Order | ✅ | G-A | Phase 2 |
| 1-B | ADR-112 Contract Governance | ✅ | G-A | Phase 3 |
| 1-C | ADR-113 Active Revision Outbox | ✅ | G-A | Phase 1 |
| 1-D | ADR-114 Idempotency & Worker Lease | ✅ | G-A | Phase 4 |
| 1-E | ADR-115 Principal Mapping | ✅ | G-A | Phase 6、7 |
| 2-A | ADR-116 Security Hardening | ✅ | G-B | Phase 2 |
| 2-B | ADR-117 MCP OAuth 2.1 | ✅ | G-B | Phase 5 |
| 2-C | ADR-118 RLS Strategy | ✅ | G-B | Phase 1 |
| 2-D | ADR-119 Durable Execution SAGA | ✅ | G-B | Phase 4 |
| 2-E | ADR-120 Token Budget Hard Kill | ✅ | G-B | Phase 4 |
| 2-F | ADR-121 OTel GenAI | ✅ | G-B | Phase 4 |
| 2-G | ADR-122 OWASP Agentic AI | ✅ | G-B | 全 Phase |
| 2-H | ADR-123 Background Loop Migration | ✅ | G-B | Phase 2 |
| 2-I | ADR-124 Global Singleton Decomposition | ✅ | G-B | Phase 2 |
| 2-J | ADR-UI-01~04 Operator Console ADR | ✅ | G-B | Phase 6+ |
| 2-K | ADR-106 補 Quantified Gates | ✅ | G-B | Phase 8 |
| 3-A | INV-1 Redis Keys | ✅ | G-C | Phase 2 |
| 3-B | INV-2 Repository Retrofit Map | ✅ | G-C | Phase 2 |
| 3-C | INV-3 Entrypoints | ✅ | G-C | Phase 2 |
| 3-D | INV-4 Hardcoded Namespace/IP（含 GCP IP）| ✅ | G-C | Phase 2 |
| 3-E | INV-5 Migration Compatibility Matrix | ✅ | G-C | Phase 1 |
| 3-F | INV-6 Rollback Playbook Register | ✅ | G-C | Phase 4 |
| 3-G | INV-7 PR Cutting Plan | ✅ | G-C | Phase 2 |
| 3-H | INV-8 Background Loop Catalog（31 個）| ✅ | G-C | Phase 2 |
| 3-I | INV-9 Global Singleton Catalog（13 個）| ✅ | G-C | Phase 2 |
| 4 | Task 9 順序修正（Dockerfile/ConfigMap）| ❌ | — | Phase 1 |
| 5 | **Phase 1 Schema Migration**（重寫版）| ❌ | — | Phase 2~8 |
| 6-A | PR-01/02/03/04/05（並行小修補）| ❌ | G-D | Phase 2 |
| 6-B | **Phase 2 Security Hardening**（PR-07 優先）| ❌ | G-E | Phase 4 |
| 6-C | Phase 2 Redis 雙寫 + Repository（PR-06/08/09/10/11）| ❌ | G-E | Phase 4 |
| 7 | **Phase 3 Contract Packages**（packages/awooop-contracts/）| ❌ | — | Phase 4 |
| 8-A | PgBouncer + pg_partman + OPA 安裝 | ❌ | G-F | Phase 4 |
| 8-B | **Phase 4 Platform Shell + Shadow**（含 SAGA + Budget Kill）| ❌ | — | Phase 5 |
| 9 | **Phase 5 MCP Gateway**（含 OAuth 2.1）| ❌ | — | Phase 6 |
| 10-A | **Phase 6 EwoooC Shadow Onboarding**（14 天 gate）| ❌ | G-G | Phase 7 |
| 10-B | Operator Console prototype（G-G）| ❌ | G-G | Phase 7+ |
| 11 | **Phase 7 Channel Hub**（7 天 canary gate）| ❌ | — | Phase 8 |
| 12 | **Phase 8 Suggest + Controlled Write**（30 天 gate）| ❌ | — | AwoooP v1 GA |

**1-A 到 3-I 全部 docs-only，可在當前對話視窗連續完成，完成後才開新 Codex 對話進 Phase 1 code。**

---

## 16. 量化驗收門檻（完整版）

### Strangler Fig Gates

| 切換 | 量化條件 | 簽核 |
|------|---------|------|
| pre → shadow | tenant 已建 + agent contract published + audit/trace 寫入正常 | critic 確認 |
| shadow → canary | ≥14 天 + decision divergence < 5% + p95 退化 < 10% + 0 P0/P1 incident + audit 0 secret | critic + db-expert + vuln-verifier |
| canary → read_only | ≥7 天 + user-visible error rate < 0.5% + cost diff < 50% 預算 | critic + vuln-verifier |
| read_only → suggest | ≥14 天 + suggest accept rate ≥ 50% + 0 hallucination escalation | critic |
| suggest → auto_remediate | ≥30 天 + rollback evidence ≥ 3 成功 + approval token live + dry-run pass ≥ 99% | critic + db-expert + vuln-verifier |

### Phase 驗收門檻（量化補強）

| Phase | 必要量化指標 |
|-------|-----------|
| Phase 1 | migration up/down dry-run 通過；RLS cross-project 拒絕率 100%；AWOOOI 0 行為改動（regression pass rate 100%）|
| Phase 2 | INV-1 P0 key 遷移完成率 100%；vuln-verifier PoC 通過率 3/3；hardcode grep 結果 0 |
| Phase 3 | contract schema 覆蓋率 100%（6 個 family）；invalid fixture 拒絕率 100% |
| Phase 4 | shadow run 0 user-visible response；duplicate event 唯一 run rate 100%；stale reaper 1min 內回收率 100% |
| Phase 5 | credential leak test 通過率 100%；Five-gate integration test 覆蓋率 100% |
| Phase 6 | cross-tenant data access 拒絕率 100%；EwoooC shadow 14天 gate 通過 |
| Phase 7 | 首則進度訊息 ≤ 30s 達成率 ≥ 99%；duplicate retry 0 重複 run |
| Phase 8 | approval replay 拒絕率 100%；write/execute 預設 OFF 驗證通過 |

---

## 17. 關聯文件索引

- [ADR-106: AwoooP 架構](../adr/ADR-106-agent-platform-architecture.md)
- [ADR-107: 控制面儲存策略](../adr/ADR-107-awooop-control-plane-storage.md)
- [ADR-110: GCP Ollama 三層容災拓撲](../adr/ADR-110-gcp-ollama-topology.md)
- [MASTER-WORKPLAN.md](MASTER-WORKPLAN.md)（本文展開的主索引）
- [IMPLEMENTATION-ROADMAP.md](IMPLEMENTATION-ROADMAP.md)（歷史文件，舊版草稿）
- 待建：`docs/awooop/inventory/` INV-1～INV-9
- 待建：ADR-111～ADR-124（AwoooP 專用 ADR 系列）
- 待建：ADR-UI-01～ADR-UI-04（Operator Console ADR）
- 待建：`docs/runbooks/` RB-01～RB-08

---

*最後更新：2026-05-03（台北時區）*
*建立：12-Agent 聯合審查 × Codex 整合*
*下一步：Phase 0 docs-only 工作（ADR-111 起），完成後開新 Codex 對話進 Phase 1 code*