awoooi/docs/awooop/MASTER-WORKPLAN.md

AwoooP Master Workplan（P0 防爆版）

狀態：規劃凍結基準 日期：2026-05-03 主要 ADR：ADR-106（架構）、ADR-107（控制面儲存） 取代：本檔取代 IMPLEMENTATION-ROADMAP.md 作為 AwoooP 主索引；舊 roadmap 仍保留為一階草稿，僅供歷史對照 整合基準：docs/awooop/AWOOOI-AWOOOP-AI-AUTONOMOUS-FLYWHEEL-INTEGRATION-PLAN.md

---

0. 為什麼有這份文件

12 位 Agent（critic / vuln-verifier / debugger / db-expert / planner / fullstack-engineer / refactor-specialist / migration-engineer / onboarder / tool-expert / web-researcher / frontend-designer）對舊版 Plan 1 與 ADR-106 做完獨立審查後，發現至少 12 個 P0 問題；後續再補了 12 個會在實作後咬人的設計缺口。

2026-05-06 補充：AwoooP 不再被視為獨立產品線，而是 AI 自動化飛輪的人機協作控制台、治理層、稽核層與操作層。完整 owner、wave、risk register 與驗收方式以整合基準文件為準。

結論：直接進 Phase 1 SQL migration 會立刻爆。 必須先補足 5 份 ADR、4 份 Inventory，把 Strangler Fig 的「資料載體、雙寫遷移、邊界硬攔截、可重放、可審計」全部寫死，再下 code。

---

1. 共識：實作前必須先完成的修補

#	問題	風險等級	必補在
1	Redis key 直接改名無雙寫期 → 費用計數歸零、Telegram 409、silence 失效、Ollama failover 雙寫不到	🔴🔴🔴	Phase 2 之前
2	Migration SQL 表名錯（incident_records / mcp_audit_snapshots）、無 rollback、ORM 1.x vs 2.x	🔴🔴🔴	Phase 1 重寫
3	project_id / tenant_id 在 codebase 0 命中，30+ 業務表無此欄	🔴🔴🔴	Phase 1 + Phase 2
4	project_migration_state 表缺失，Strangler Fig 無資料載體	🔴🔴	Phase 1
5	AWOOOI 雙重身份 Bootstrap Paradox（cron/job/healthcheck 全無 project_id）	🔴🔴	Phase 0 補 ADR-111
6	EwoooC 接入零技術路徑，需要 Provider Proxy Adapter 設計	🔴🔴	Phase 0 補 ADR-115
7	Strangler shadow→canary→active 無量化 gate 條件	🔴🔴	Phase 0 寫進 ADR-106 補章
8	Layer 3 redaction 零實作（helper 有但無 enforcement point）	🔴🔴🔴	Phase 5
9	_provider 屬性是 public，可繞過 audit	🔴🔴	Phase 5
10	WAITING_APPROVAL resume 不驗 caller identity，無 approval_token 簽章	🔴🔴	Phase 4 + Phase 8
11	Redis approval state 單點，無 PG sync	🔴	Phase 2 + Phase 8
12	Task 9（K8s ConfigMap）順序倒置，agent prompt 全回 None	🔴🔴🔴	Phase 1 之前先順序修正
13	Audit log 本身會洩密，redaction 必須做在 audit sink 前	🔴🔴	Phase 5
14	sanitization_service.py 已存在 helper，但 MCP Gateway / AgentToolExecutor 沒強制使用	🔴🔴	Phase 5
15	Redis working memory（SCAN incident:*）需要 project 邊界	🔴🔴	Phase 2
16	Contract publish 權限與簽章未定義（誰可 publish/activate）	🔴	Phase 0 補 ADR-112
17	Active revision 切換無 transactional outbox，worker 可能吃舊 policy	🔴	Phase 0 補 ADR-113
18	Run/Channel idempotency 缺 key derivation 規則與 unique index	🔴	Phase 0 補 ADR-114
19	Async worker 缺 lease / heartbeat / stale reaper	🔴	Phase 4
20	高流量表（run_state / channel_event / mcp_audit / agent_audit）partition 與 retention 需 Phase 1 就決定	🟠	Phase 1
21	Observability metrics label cardinality 規則：run_id/trace_id/session_id 禁止進 metrics	🟠	Phase 4
22	Telegram/LINE/Slack/API/Internal 缺 canonical principal mapping	🟠	Phase 0 補 ADR-115
23	EwoooC Provider Proxy 不能只改 OLLAMA_API_BASE，必須補 envelope + audit 入口	🔴	Phase 0 補 ADR-115
24	所有 entrypoint（cron / job / webhook / CLI / healthcheck）需 inventory 並標 requires_project_id	🔴	Phase 0 Inventory

---

2. Pre-flight Audit（Phase 0 擴張）

舊版 Phase 0 只凍 ADR-106/107。新版 Phase 0 還需要 5 份 ADR + 4 份 Inventory，全部 docs-only。

2.1 5 份必補 ADR（⚠️ ADR-108/109/110 已被其他 ADR 占用，AwoooP 從 ADR-111 開始）

ADR	主題	解決
ADR-111	AwoooP Bootstrap Order & Identity Paradox	#5、#24 — 定義 hard reject 啟用順序、platform_internal / requires_project_id / legacy_awoooi_default 標記、AWOOOI cron/job 過渡期豁免規則
ADR-112	Contract Governance & Publishing Workflow	#16 — 誰可 publish、誰可 activate、CODEOWNERS、簽章/HMAC、approval workflow、activation audit
ADR-113	Active Revision Invalidation & Outbox	#17 — awooop_contract_outbox 表設計、Redis pub/sub 通知、worker revision-aware cache、split-brain 防禦
ADR-114	Idempotency, Worker Lease & Run Recovery	#18、#19 — 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 Patterns	#6、#22、#23 — Telegram/LINE/Slack/API/Internal user → platform_subject 統一映射、EwoooC Provider Proxy Adapter 設計、Tsenyang/Bitan 接入模式範本

ADR-106 也需要補一節：Strangler Fig Quantified Gates，把 shadow → canary → active 的量化條件寫死（≥14 天、決策差異率 <5%、p95 退化 <10%、無 P1 incident、cost diff < 預算上限 50%）。

2.2 4 份必做 Inventory

Inventory	範圍	解決
INV-1：Redis Key Inventory	全 codebase grep redis_client.*\(["'] + r\.set/get/scan → 列出 43+ 個 key、命名空間、TTL、用途、寫入點、讀取點、是否硬碼跨檔	#1、#15
INV-2：Repository Project-id Retrofit Map	列出全部 30+ 張業務表、目前有無 project_id 欄位、所有 repository 方法、需加 filter 的查詢、需 backfill 的歷史資料	#3
INV-3：Entrypoint Inventory	列出所有 cron job / scheduler / webhook / CLI script / healthcheck / internal service call，標記 requires_project_id / platform_internal / legacy_awoooi_default	#5、#24
INV-4：Hardcoded Namespace & IP Inventory	列出所有硬碼 K8s namespace（awoooi-prod）、SSH 主機 IP、白名單，標記 tenant-scope 改造方案	配合 #3 完成多租戶啟用

Phase 0 驗收

• ADR-111～115 全部 Accepted 並進 LOGBOOK
• ADR-106 補 Quantified Gates 章節
• 4 份 Inventory 寫入 docs/awooop/inventory/
• 沒有任何 runtime code 變動
• git diff --check 通過

---

3. 修訂版 8 階段實施計畫

階段順序與舊 roadmap 相同，但每階段範圍依 §1 共識重寫。

Phase 1 — Control Plane Schema Foundation（重寫）

目標：建立 PostgreSQL contract control plane 最小可用骨架，並修正舊 SQL migration 三大 blocker。

工作項：

1. 核對真實表名：在寫 SQL 前 grep 確認 incidents（非 incident_records）、mcp_audit_log（非 mcp_audit_snapshots），全部錯名修正
2. ORM 同步現況：使用 SQLAlchemy 2.x mapped_column、補齊 Numeric/UniqueConstraint/func import
3. 每個 migration 都有 rollback SQL（down migration 強制）
4. 新增 contract control 表：
   • awooop_projects（tenant 主表，project_id PK）
   • awooop_contract_revisions（六合約共用 revision 表，append-only）
   • awooop_active_revisions（active pointer 表）
   • awooop_artifact_refs（prompt/schema/eval 的 ref + sha256）
   • awooop_project_migration_state（Strangler 階段追蹤）
   • awooop_contract_outbox（ADR-113，active revision 切換事件）
   • awooop_channel_event_dedupe（ADR-114，idempotency 唯一鍵）
   • awooop_platform_subjects（ADR-115，canonical principal）
5. 高流量表 partition 策略決定（不延後）：
   • awooop_run_state、awooop_channel_event、awooop_mcp_gateway_audit、awooop_agent_audit_log 一律按月 partition
   • 每 tenant retention policy（預設 90 天 hot + 1 年 warm）
6. project_id 對既有表的策略：暫不在現有 30+ 業務表加欄位（留給 Phase 2），先在 AwoooP 自己的表強制 project_id NOT NULL
7. immutability 測試：published revision 嘗試 UPDATE 必失敗、draft 與 active 隔離
8. Task 9 順序修正前置：Dockerfile / ConfigMap / agent_loader 預設路徑改動先於任何 agent prompt 載入點變更

驗收：

• AWOOOI 可被表示為 project_id=awoooi 且 0 行為改動
• 每個 active revision 都有 revision_id 與 body_hash
• runtime 讀取路徑看不到 mutable draft
• migration up/down 都通過 dry-run
• partition + retention 寫入 runbook

Phase 2 — Tenant Isolation & Namespace Hardening（重寫）

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

工作項：

1. Redis 三階段雙寫遷移（依 INV-1）：
   • 階段 A：dual-write 新舊 key（30 天觀察）
   • 階段 B：dual-read，新 key 為主、舊 key 為 fallback（14 天）
   • 階段 C：移除舊 key 寫入，留 audit log
   • 必含：ai_rate:total_cost:gemini（費用上限）、telegram:polling:leader（Pod 鎖）、telegram_silence:{target}（含 decision_manager.py:230 硬碼）、ollama:current_primary（含 ollama_auto_recovery.py:230 第二定義）
2. Repository project_id 改造（依 INV-2）：
   • 所有 30+ repository 方法加 project_id filter
   • K8s namespace 白名單 → tenant-aware 設定（依 INV-4）
   • SSH 主機白名單 → tenant-aware
3. Redis working memory project 邊界（#15）：
   • incident_service.py:603 的 SCAN incident:* → SCAN {project_id}:incident:*
   • 所有 SCAN/KEYS 必須帶 prefix
4. platform_resource 例外名單：Ollama failover state、global rate limit、leader election lock 等明確標記；GCP Ollama 正式路徑依 ADR-125 改為 WireGuard mesh + AwoooP Inference Gateway，110 nginx proxy 僅保留為過渡 / rollback bridge
5. 回歸測試：cross-project read/write 必拒絕；platform_resource 必允許但寫 audit
6. AWOOOI Bootstrap Paradox 修補（依 ADR-111、INV-3）：
   • 標記為 platform_internal 的 entrypoint 帶 project_id=__platform__，hard reject 例外但寫 audit
   • 標記為 legacy_awoooi_default 的舊 cron 暫時 fallback 到 project_id=awoooi，列退場時程

驗收：

• INV-1 列出的所有 P0 key 完成三階段遷移
• 30+ repository 全部加 project_id filter，cross-project test 全紅
• 無任何 hardcode tenant 字串殘留（grep awoooi-prod / 192.168 必為 0）

Phase 3 — Contract Packages & Validators

目標：六合約從散文升級為可驗證程式。

工作項：

1. 建立 packages/awooop-contracts/（此時才建立）
2. 六合約 JSON Schema + Pydantic models
3. envelope schema：platform invocation、MCP tool call、run state、channel events
4. Output schema validator middleware：LLM 回傳必先過 schema、失敗 retry 上限硬碼、失敗不外漏到 channel
5. golden fixtures（valid + invalid）
6. Contract publish governance（依 ADR-112）：
   • CODEOWNERS 對 packages/awooop-contracts/
   • publish API 簽章驗證
   • activate 動作要 approval workflow

驗收：

• 任何 schema 不符的 LLM 輸出無法到達 channel adapter
• prompt/schema ref 必含 sha256 hash
• 無權限不能 publish 或 activate

Phase 4 — Platform Shell in Shadow Mode（補 lease/idempotency/audit redaction）

目標：建立第一個 runtime shell，但只跑 shadow，不改 legacy 行為。

工作項：

1. /v1/platform/runs API（async）
2. run_id / trace_id 生成（W3C tracecontext-compatible）
3. project + agent contract revision 解析
4. EffectivePolicy 解析（不改 provider 行為）
5. Run state machine（依 ADR-114）：
   • lease_until、heartbeat_at、attempt_count 欄位
   • SKIP LOCKED 取單
   • stale run reaper（每分鐘掃 expired lease）
6. Idempotency（依 ADR-114）：
   • (project_id, channel_type, provider_event_id) unique
   • duplicate event return 既有 run
7. Audit log redaction（#13）：
   • audit sink 寫入前過 sanitization_service
   • PII / secret pattern 硬攔
8. Observability label rules（#21）：
   • metrics label 限定 project_id / agent_id / status / provider
   • run_id / trace_id / session_id 只進 logs/traces
9. mirror 選定 AWOOOI 事件到 shadow

驗收：

• shadow run 永遠 0 user-visible response、0 destructive tool call
• legacy AWOOOI 行為 0 改變
• worker crash 後 stale run 1 分鐘內被回收
• duplicate retry 不產生重複 run
• audit log 0 secret 命中（vuln-verifier 抽樣 100 筆）

Phase 5 — MCP Gateway First Slice（補 sanitization enforcement、_provider 修正、audit redaction）

目標：把 tool 授權搬到 Gateway，read-only 工具先進。

工作項：

1. Gateway 表：tool registry、grants、credential refs、audit
2. wrap 既有 read-only MCP tool
3. 強制：Project AND Agent AND Tool AND Environment AND Approval 五重交集
4. Result sanitization enforcement point（#8、#14）：
   • 所有 MCP result 必經 sanitization_service pipeline
   • 不允許 raw result 直接進 LLM context
5. _provider → __provider（#9）：
   • 雙底線真 private
   • 加 unit test：外部 reflect 取用 must fail
6. Audit log 雙層 redaction（#13）：
   • 進 LLM 前一層
   • 進 audit sink 一層
7. tool call 記錄 trace_id / run_id / credential ref / latency / status

驗收：

• agent 程式碼路徑 0 raw credential 接觸（sast 掃過）
• raw result 不可能繞過 sanitization（單元測試 + 整合測試覆蓋）
• 2026-04-18 secret leak 重演測試：kubectl describe configmap 輸出不會出現在任何 LLM context 或 audit row

Phase 6 — EwoooC Read-Only Tenant Onboarding（依 ADR-115）

目標：以實際下游 tenant 驗證 AwoooP，全 read-only。

工作項：

1. 建立 project_id=ewoooc
2. 註冊 openclaw-biz agent contract
3. Provider Proxy Adapter（#23）：
   • 不只是改 OLLAMA_API_BASE
   • Proxy 入口補 envelope（project_id / agent_id / trace_id / run_id）
   • 經過 EffectivePolicy + budget guard + audit
   • read-only / model-call 入口優先
4. EwoooC 市場情報 tools 註冊為 read-only MCP Gateway tool
5. EwoooC bot/business-analysis 事件先 mirror 到 shadow，14 天後升 canary

驗收：

• EwoooC 可跑 read-only AwoooP shadow/canary，0 接觸 AWOOOI 資料
• business-agent context 不可讀 infra-only AWOOOI context
• budget / audit 完全 project-scoped

Phase 7 — Communication Hub Increment（補 progressive feedback）

目標：標準化 channel 但不切斷既有 bot。

工作項：

1. awooop_conversation_event + awooop_outbound_message 表（partition + retention 已在 Phase 1）
2. Telegram inbound mirror 先進
3. Progressive Feedback Policy（async UX gap，#補充）：
   • WAITING_TOOL / RUNNING / WAITING_APPROVAL 必發暫態訊息
   • 用 Telegram message edit 更新（非新訊息）
4. 既有 bot handler 維持權威，直到 canary 通過量化 gate
5. adapter-level escaping、redaction、idempotency、delivery audit
6. Canonical principal mapping（依 ADR-115）：所有 channel sender 寫入 awooop_platform_subjects

驗收：

• channel adapter 0 LLM 呼叫、0 MCP 呼叫
• async run 有進度更新（≤30s 必有第一則）
• duplicate retry 不產生 duplicate run（INV-1 + Phase 4 idempotency 已就位）

Phase 8 — Suggest & Controlled Write Paths（補 approval token signing）

目標：從 read-only 升級到 propose、再到 controlled execute。

工作項：

1. AWOOOI SRE 部分流程啟用 suggest
2. Approval resume 安全強化（#10、#11）：
   • resume API 強制驗 approval_token（HMAC-signed）
   • approval state PG 為 source of truth、Redis 為 cache
   • approval 過期 / 已決 / 重放都拒絕
3. dry-run 與 rollback evidence gate
4. write/execute 預設 disabled，feature flag 控制
5. 量化 gate（依 ADR-106 補章）：
   • shadow → canary：≥14 天 + decision divergence < 5% + p95 退化 < 10%
   • canary → active：≥7 天 + 0 P1 incident + cost diff < 預算 50%

驗收：

• WAITING_APPROVAL resume 不能在沒 token 的情況下成功（vuln-verifier 寫 PoC）
• Redis 宕機時 approval 仍可從 PG 恢復
• write/execute 預設 OFF，需顯式 feature flag

---

4. 跨階段橫向工作項（Cross-Cutting）

工作項	跨哪些階段	負責
Bootstrap order discipline（ADR-111）	Phase 0、2、4、Forever	platform-runtime
Audit log redaction（雙層）	Phase 4、5	mcp-gateway + runtime
High-traffic table partition + retention	Phase 1、4、7	db-expert + sre
Observability label cardinality 規則	Phase 4 起永久	observability
Contract outbox / active revision invalidation	Phase 1 表、Phase 4 worker 用	platform-runtime
Canonical principal mapping	Phase 0 ADR、Phase 7 落地	identity
Approval token signing	Phase 4 token 簽發、Phase 8 verify	security + runtime
EwoooC Provider Proxy Adapter	Phase 0 設計、Phase 6 落地	tenant-onboarding

---

5. 工作排序總表（建議施作順序）

順序	工作	是否 docs-only	阻擋誰
1	ADR-111 Bootstrap Order	✅	Phase 2
2	ADR-112 Contract Governance	✅	Phase 3
3	ADR-113 Active Revision Outbox	✅	Phase 1
4	ADR-114 Idempotency & Worker Lease	✅	Phase 4
5	ADR-115 Principal Mapping & EwoooC Proxy	✅	Phase 6、7
6	ADR-106 補 Quantified Gates 章節	✅	Phase 8
7	INV-1 Redis Key Inventory	✅	Phase 2
8	INV-2 Repository Retrofit Map	✅	Phase 2
9	INV-3 Entrypoint Inventory	✅	Phase 2
10	INV-4 Namespace/IP Inventory	✅	Phase 2
11	Phase 1 schema migration（重寫版）	❌ runtime	Phase 2-8
12	Task 9 順序修正（Dockerfile/ConfigMap 先）	❌ runtime	Phase 1 prompt 任何更動
13	Phase 2 三階段 Redis 雙寫 + repository project_id	❌ runtime	Phase 4 起所有 tenant 行為
14	Phase 3 contract packages	❌ runtime	Phase 4 起
15	Phase 4 platform shell + shadow + idempotency + audit redaction	❌ runtime	Phase 5-8
16	Phase 5 MCP Gateway + sanitization enforcement + __provider	❌ runtime	Phase 6 read-only tool
17	Phase 6 EwoooC onboarding via Provider Proxy	❌ runtime	Phase 7
18	Phase 7 Communication Hub + progressive feedback	❌ runtime	Phase 8
19	Phase 8 suggest + approval signing + controlled write	❌ runtime	平台 v1 GA

1～10 是 docs-only，可以在當前對話視窗連續做完，全部完成才開新對話進 Phase 1 code。

---

6. 量化驗收門檻（Strangler Fig Gates）

每個 tenant × 每個 capability 切換階段都要過：

切換	必要條件
pre → shadow	tenant 已建、agent contract published、audit/trace 寫入正常
shadow → canary	≥14 天 shadow 觀察 + decision divergence < 5% + p95 latency 退化 < 10% + 0 P0/P1 incident + audit 0 secret 命中
canary → read_only	≥7 天 canary + user-visible response 錯誤率 < 0.5% + cost diff < 預算 50%
read_only → suggest	≥14 天 read_only + agent suggestion accept rate ≥50% + 0 hallucination escalation
suggest → auto_remediate	≥30 天 suggest + rollback evidence ≥3 次成功 + approval token signing live + dry-run pass rate ≥99%

每個 gate 由 12-Agent critic + db-expert + vuln-verifier 三方簽核，寫進 LOGBOOK。

---

7. 授權需求清單（已獲統帥完整授權）

類別	動作	風險
docs-only	寫 ADR-111～115、4 份 Inventory、ADR-106 補章	低
schema	新增 8 張 AwoooP 控制面表（Phase 1）	中（DB migration）
schema	30+ 業務表加 project_id 欄位 + backfill（Phase 2）	高（DB migration、要 db-expert review）
Redis	全 codebase 43+ key 三階段雙寫遷移（Phase 2）	高（影響費用、Telegram、silence、ollama failover）
code	30+ repository 加 project_id filter（Phase 2）	中（regression risk）
code	wrap MCP provider 為 Gateway（Phase 5）	中
infra	partition + retention runbook（Phase 1）	低
infra	K8s ConfigMap 預載 agent prompt（Task 9 提前）	中
security	__provider 雙底線、approval token 簽章（Phase 5、8）	中
feature flag	suggest mode、controlled write（Phase 8）	高（要 vuln-verifier PoC + dry-run evidence）

不在本授權範圍：

• 提高 paid provider 配額或啟用新雲端 provider（仍須 HARD_RULES feedback_cost_change_approval 流程）
• 任何 destructive MCP tool 上線（要 Phase 8 evidence 才開）
• Telegram/LINE/Slack webhook 直接切走（必須先 shadow → canary → 量化 gate）

---

8. Codex 工作模式建議

階段	對話	cwd
排序 1～10（docs-only）	當前對話可直接完成	/Users/ogt/awoooi
排序 11 起（runtime code）	新開 Codex 對話 + 乾淨 worktree	/Users/ogt/awoooi

實作對話 kickoff prompt 模板：

讀完：
- AGENTS.md
- docs/12-agent-game-rules.md
- docs/LOGBOOK.md 最新一篇
- docs/adr/ADR-106 / 107 / 108 / 109 / 110 / 111 / 112
- docs/awooop/MASTER-WORKPLAN.md
- docs/awooop/inventory/ INV-1 ~ INV-4

只做 Phase {N}。不擴張範圍、不改 provider 行為、不切 channel webhook、不建空目錄。
完成後輸出 [P7-COMPLETION]。

---

9. 參考

• docs/adr/ADR-106-agent-platform-architecture.md
• docs/adr/ADR-107-awooop-control-plane-storage.md
• docs/adr/ADR-105-revert-a2-ollama-primary.md
• docs/adr/ADR-111-awooop-bootstrap-order.md（待寫）
• docs/adr/ADR-112-awooop-contract-governance.md（待寫）
• docs/adr/ADR-113-awooop-active-revision-outbox.md（待寫）
• docs/adr/ADR-114-awooop-idempotency-worker-lease.md（待寫）
• docs/adr/ADR-115-awooop-principal-mapping-tenant-onboarding.md（待寫）
• docs/awooop/inventory/INV-1-redis-keys.md（待寫）
• docs/awooop/inventory/INV-2-repository-project-id-retrofit.md（待寫）
• docs/awooop/inventory/INV-3-entrypoints.md（待寫）
• docs/awooop/inventory/INV-4-hardcoded-namespace-ip.md（待寫）
• docs/12-agent-game-rules.md
• docs/LOGBOOK.md