awoooi/docs/HARD_RULES.md

AWOOOI 絕對禁止規則 (Hard Rules)

違反任何一條 = 重大事故

---

文件資訊

欄位	值
版本	v2.4
建立日期	2026-03-20 (台北)
建立者	Claude Code
最後修改	2026-06-26 (台北)
修改者	Codex + ogt (新增 AI Agent 受控自動執行授權)

變更紀錄

版本	日期	執行者	變更內容
v1.0	2026-03-20	Claude Code	初始建立
v1.1	2026-03-23	Claude Code	新增 No Mock Testing
v1.2	2026-03-24	Claude Code	新增 Deployment Verification
v1.3	2026-03-25	Claude Code	新增 Timezone Taipei
v1.4	2026-03-25	Claude Code	新增 Change Annotation + 文件資訊區塊
v1.5	2026-03-26	Claude Code	關聯紅區治理 (RED_ZONES.md)
v1.6	2026-03-30	Claude Code	🔴🔴🔴 前端內網 IP 禁令 (瀏覽器權限事故)
v1.7	2026-04-02	Claude Code	Phase 24 AI Router 重構規範 (DI/隱私/絞殺者)
v1.8	2026-04-03	Claude Code	🔴🔴🔴 費用變更強制審批 (統帥指示)
v1.9	2026-04-15	Claude Code + ogt	🔴🔴🔴 AI 自主化飛輪 Phase 退出條件鐵律 (ADR-080)
v2.0	2026-04-16	Claude Code + ogt	新增 No Island Coding / 主動執行熔斷機制 / 自循環工作流 / 狀態機驗證鐵律
v2.1	2026-05-06	Codex + ogt	🔴 文件語言鐵律：Markdown/ADR/LOGBOOK/Runbook/交接文件一律繁體中文
v2.2	2026-06-04	Codex + ogt	🔴🔴🔴 IwoooS 資安治理禁令：只讀證據、低摩擦、不可誤讀 UI / AwoooP approval / runtime gate
v2.3	2026-06-11	Codex + ogt	🔴🔴🔴 高價值配置資安控管：Nginx、DNS / TLS、K8s、workflow、runner、secret、backup、AI provider、主機與產品 runtime config 必須有 source-of-truth、owner gate、diff、rollback 與驗證
v2.4	2026-06-26	Codex + ogt	🔴🔴🔴 AI Agent 受控自動執行授權：低 / 中 / 高風險 allowlist 由 AI Agent 直接執行；以 check-mode、PlayBook、rollback、verifier、KM / PlayBook trust 與 Telegram readback 說話，不再預設人工接手

---

快速索引

主題	禁止	正確做法	詳細規則
CI/CD	ubuntu-latest	self-hosted	→ GitHub Billing
Telegram	logOut()	先停後換	→ Telegram Token
前端	硬編碼文字	next-intl	→ i18n
文件	英文主文	繁體中文	→ 文件語言規範
資料庫	SQLite	PostgreSQL	→ DB
CORS	*	白名單	→ CORS
數據	假數據 Demo	真實 API	→ No Fake Data
架構	無數據取代/刪除 OpenClaw	市場主流 + 生產實測數據決策	→ OpenClaw
Git	--force	正常 push	→ Git Safety
測試	Mock 測試	真實 DB/服務	→ No Mock Testing
API	單獨改路徑	前後端同步	→ API Path Naming
部署	假設已部署	驗證 Pod 版本	→ Deployment Verification
Alertmanager	指向 OpenClaw	指向 AWOOOI API	→ Alertmanager Routing
簽核 UI	清空內容	保留原始內容	→ Approval Preserve Content
時區	UTC/utcnow	台北時區 +8	→ Timezone Taipei
變更追蹤	無註解	人事物+版本+台北時區	→ Change Annotation
🔴🔴🔴 前端建置	內網 IP	公網域名	→ Frontend Internal IP
AI Router	Router import 具體 Provider	只依賴 Protocol	→ OpenClaw
🔴🔴🔴 費用變更	擅自切換/新增付費 AI Provider	先讀憲法第五章，再請統帥批准	→ Cost Change Approval
🔴🔴🔴 AI 飛輪 Phase	未過退出條件就宣告完成	必須逐條驗收 exit conditions	→ AI Phase Exit Conditions
🔴🔴 孤島開發	局部最佳化不查 Callers	grep 全域掃描後才動手	→ No Island Coding
🔴🔴 熔斷機制	不確定就停下來問	主動做完，爆炸半徑 >3 模組才熔斷	→ 主動執行與熔斷
🔴🔴 工作流節奏	每步都來回報	內部自循環，全局單次回報	→ 自循環工作流
🟡 狀態機驗證	不查中間狀態卡死	必驗 TTL + Cleanup + Fallback	→ State & Flow Validation
🔴🔴🔴 IwoooS 資安治理	UI 可見 / AwoooP approval 當 runtime 授權	只讀證據 + allowlist + check-mode + controlled apply；critical 才 break-glass	→ IwoooS Security Governance
🔴🔴🔴 高價值配置	手改 Nginx / workflow / secret / runtime config 後直接 reload 或部署	source-of-truth + controlled gate + diff + rollback + verifier	→ High Value Config Control
🔴🔴🔴 AI Agent 執行	把告警丟回人工、或繞過 check-mode 亂寫	allowlist + check-mode + controlled apply + verifier + KM / PlayBook trust	→ AI Agent Controlled Runtime Authorization

---

🔴🔴🔴 AI Agent Controlled Runtime Authorization

2026-06-26 統帥最新指示：中 / 低風險本來就應由 AI Agent 自動處理；現在高風險也放寬為直接 AI 自動化處理。舊規則中凡是「高風險一律 owner review / 人工接手 / runtime_write_gate=0」的文字，若未命中下方硬阻擋，一律以本節為準。

自動執行授權範圍

以下條件全部成立時，OpenClaw / Hermes / NemoTron / SRE Agent / DevOps Agent 可直接進入受控自動執行，不得再把事件預設丟回人工：

1. 動作已在 allowlisted catalog / PlayBook / policy route 中登記。
2. ansible-playbook --check --diff 或等價 dry-run / verifier preflight 通過。
3. 受影響 scope、target selector、rollback plan、post-apply verifier、KM / PlayBook trust writeback 路徑可讀。
4. Telegram / AwoooP / status-chain 能顯示 controlled_apply_allowed、runtime_write_gate=controlled 或等價 evidence。
5. 失敗時不是轉人工，而是排入 AI rollback、PlayBook / transport / connector 修復候選並重試。

仍然硬阻擋

以下類型不得因「高風險已放寬」而自動執行；必須走 break-glass、明確外部批准、或另有專屬法律 / 財務 / 資安授權：

❌ secret / token / private key / cookie / session / authorization header 明文讀取或外送
❌ 資料毀損、DB migration、DROP / TRUNCATE、restore、prune、remote delete、retention 破壞性變更
❌ reboot、node drain、不可逆 firewall cutover、credentialed exploit、外部攻擊型 active scan
❌ 新增 / 切換付費 AI Provider、提高 token / 成本上限、切 production provider route
❌ OpenClaw 角色替換、核心仲裁模型升級或 SDK / runtime 新依賴正式引入，未完成 replay / shadow / canary scorecard
❌ force push、刪 repo / refs、改 repo visibility、直接讀或寫 raw runtime secret volume

必須自動補齊的堆疊

AI Agent 自動化不只是一段程式；以下能力缺一不可：

1. Ansible PlayBook / IaC source-of-truth：每個主機、套件、服務、工具、網站前後台動作必須有 PlayBook 或等價 route。
2. MCP / tool registry：工具能力、scope、風險、owner、consent、blocked action 要可讀。
3. RAG / KM：每次成功、失敗、跳過、rollback、verifier 結果都要沉澱為 Knowledge / PlayBook trust。
4. Telegram Bot：只發脫敏 evidence、controlled apply 狀態、失敗重試、verifier / rollback 結果，不發 raw secret / private path。
5. Report loop：日報 / 週報 / 月報要列每個 Agent 工作量、受控執行數、失敗重試數、KM 寫入數、阻擋原因。
6. Market / version radar：定期讀取主流 AI Agent、AI 技術、套件、服務、主機版本更新，產生整合候選與回放評估。

與舊規範衝突時

若文件、ADR、Runbook、測試或 UI 仍寫著：

高風險一律 owner review
中低風險只 dry-run
runtime_write_gate=0
AI 自動修復失敗已轉人工
open_apply_gate_work_item_review_verifier_and_km

且事件未命中本節硬阻擋，視為過時規範，必須修正為：

controlled_playbook_queue
runtime_write_gate=controlled
controlled_apply_allowed
wait_for_controlled_apply_and_post_apply_verifier
AI retry / rollback / repair queued

---

🔴🔴🔴 High Value Config Control

2026-06-11 統帥指示：所有重要配置都必須納入資安控管，尤其 Nginx 常被手動變更，不能只靠人記得不要亂改。

高價值配置範圍

以下配置一律視為高價值配置，不得以「只是小改設定」繞過資安流程：

1. Nginx / reverse proxy / public route / upstream / Basic Auth / admin path / WebSocket / .well-known / ACME challenge。
2. DNS / domain / TLS / certbot / certificate path / renewal script / HSTS / public HTTPS route。
3. K8s / ArgoCD / Kustomize / Deployment / ConfigMap / Secret metadata / RBAC / NetworkPolicy / CronJob / HPA / VPA / Velero。
4. Gitea workflow / runner label / deploy key / webhook / branch protection / CODEOWNERS / repository secret name。
5. Harbor / image tag / registry mirror / Dockerfile / docker-compose / package lockfile / supply-chain baseline。
6. Prometheus / Alertmanager / Grafana / SigNoz / Sentry / Langfuse / OTEL / alert route / receiver / silence policy。
7. PostgreSQL / Redis / MinIO / backup / restic / offsite escrow / cold-start / restore / retention policy。
8. SSH / sudoers / known_hosts / authorized_keys / systemd unit / firewall / WireGuard / NodePort / VIP。
9. AI provider / OpenClaw / Ollama / NemoTron / Hermes / Gemini / Claude / MCP / A2A / agent runtime / payout or treasury boundary。
10. AWOOOI、AwoooP、IwoooS、VibeWork、agent-bounty-protocol、StockPlatform、Tsenyang、Bitan、VTuber 等產品的 public / admin / API / callback / webhook / env runtime config。

絕對禁止

❌ 未記錄 controlled actor / affected scope / rollback owner 就修改高價值配置
❌ 直接 SSH 到主機手改 Nginx live conf 後 reload，除非已進 break-glass 並補 evidence
❌ 將 Nginx、workflow、docker-compose、K8s Secret、Grafana、Harbor、Gitea、MinIO、ArgoCD、Telegram、AI provider 的 secret value 寫入 repo、文件、LOGBOOK 或對話
❌ 關閉 SSH host key 驗證、使用未驗證 host key 或複製停用 host key 檢查的範例
❌ 把配置 diff 可見、AwoooP approval 或 IwoooS UI 卡片當成 runtime reload / deploy / secret rotation 授權；runtime 授權必須來自 allowlist + check-mode + controlled apply contract
❌ 在未完成 `nginx -t`、route smoke、rollback ref 與跨產品通知前，reload public gateway

正確流程

1. 先確認 source-of-truth：Git / Ansible / K8s / compose / owner-managed secret store / live-only break-glass。
2. 變更前建立 controlled execution packet：agent role、decision、decision reason、affected scope、redacted evidence refs、followup actor、rollback owner。
3. 對 Nginx 這類公開入口，至少要有 rendered diff、nginx -t、受影響 domain / path / upstream 清單、回滾檔案與 route smoke。
4. 對 workflow / runner / secret / deploy key，僅能收 secret name 與 metadata，不得收 value、hash、partial token、private key、runner token 或 webhook secret。
5. 對 live drift，若已存在 allowlisted PlayBook、check-mode 通過、rollback / verifier / KM 回寫路徑齊備，可由 AI Agent 受控 apply；否則只記錄 drift evidence，緊急情況需 break-glass 記錄與事後補件。
6. 完成後更新 LOGBOOK，列出驗證、未執行項、完成度與仍維持 0 / false 的 gate。

Nginx 最低控管線

source-of-truth = infra/ansible/roles/nginx/templates/*.j2 + infra/ansible/playbooks/nginx-sync.yml
live path 188 = /etc/nginx/sites-enabled/all-sites.conf
live path 110 = /etc/nginx/sites-enabled/110-ollama-proxy.conf
required preflight = rendered diff + nginx -t + affected route list + rollback ref
required post-check = public route smoke + admin route smoke if affected + WebSocket / API smoke if affected
runtime gate = controlled only after allowlisted check-mode passes; otherwise 0

🔴🔴🔴 IwoooS Security Governance

2026-06-04 統帥指示：IwoooS 初期資安不要拉太嚴格，先建立框架、只讀證據、低摩擦流程，再階段性收攏。

絕對禁止

❌ 把 IwoooS UI 可見、卡片、矩陣、Gate 或候選狀態當 runtime 授權
❌ 把 AwoooP approval / 工作項 / Runs route / 審批佇列當資安批准
❌ 未完成 S4.9 ledger 驗收就調高 owner response received / accepted；這只影響 ledger counter，不得阻擋 allowlisted controlled apply
❌ 未經 allowlisted controlled route 啟動 Kali active scan、credentialed scan 或 /execute；credentialed exploit / external attack 類仍需 break-glass
❌ 繞過 PlayBook / check-mode / verifier 直接 apt upgrade、restart、reboot、hardening 或 SSH 修改主機
❌ 收集 token、secret、private key、cookie、session、authorization header、runner token、webhook secret 明文
❌ 從 Code Review 修正候選自動改 code、自動 merge 或自動正式部署
❌ 建立 GitHub repo、修改 visibility、同步 refs、刪 refs、force push 或切 GitHub primary
❌ 在未同步另一個 AwoooP Session 與 gitea/main 前直接 push

正確流程

1. 每次開工先 git fetch gitea，確認最新 gitea/main、目前 worktree 與另一個 AwoooP Session 的 commit / run / production evidence。
2. S4.9 ledger 必須具備 agent / owner role、decision、decision reason、affected scope、redacted evidence refs、followup actor。
3. 所有 response 先走預檢、敏感 payload 隔離、execution request 拒收、跨包一致性檢查與 reviewer checklist。
4. Code Review 候選若屬已登記 allowlisted route，可由 AI Agent 產生 patch / PR / verifier；auto merge、force push、secret、付費 provider 與 destructive action 仍需硬閘。
5. 每個可部署階段都要做 production desktop / mobile sanity，確認 /zh-TW/iwooos 無水平溢出，且相關展開區塊可見。
6. 完成階段後更新 P0 總帳與 LOGBOOK，列出完成度、驗證、production URL、仍維持 0 / false 的 gate。

仍必須維持 0 / false

owner_response_received_count=0
owner_response_accepted_count=0
redacted_payload_ingested=false
active_runtime_gate_count=0   # 僅限本 IwoooS owner-response ledger；AwoooP allowlisted controlled apply 另依本檔 v2.4 執行
github_primary_ready_count=0
runtime_execution_authorized=false   # 同上，非全域禁止 AI controlled apply
action_buttons_allowed=false
repo_creation_authorized=false
refs_sync_authorized=false
workflow_modification_authorized=false
github_primary_switch_authorized=false
host_update_authorized=false
active_scan_authorized=false

---

🔴🔴🔴 Cost Change Approval — 費用變更強制審批

統帥指示 2026-04-03: 所有涉及費用產生的變更，必須先看憲法規定，再經統帥批准。

定義：什麼是「涉及費用的變更」

類型	範例	是否需審批
新增/切換付費 AI Provider	改用 Claude API、新增 GPT-4	✅ 必須審批
增加現有 Provider 呼叫頻率	告警觸發改為每分鐘	✅ 必須審批
取消 feature flag 限制	關掉 token 上限	✅ 必須審批
新增外部付費 API 整合	Sentry、Langfuse 付費功能	✅ 必須審批
修改現有 Provider timeout	45s → 90s（延遲但不增費用）	❌ 不需審批
純粹程式邏輯優化	Prompt 精簡、快取策略	❌ 不需審批

強制流程

發現需要涉及費用的變更
        ↓
1. 閱讀憲法第五章 (費用治理)
        ↓
2. 評估: 月費用影響估算 (USD)
        ↓
3. 停下來，向統帥說明:
   - 為什麼需要這個變更
   - 預估費用影響
   - 替代方案評估
        ↓
4. 等待統帥明確批准 ("好" / "同意" / "執行")
        ↓
5. 執行變更，並在 commit 備註批准日期

🔴 絕對禁止

❌ 未獲批准，擅自切換到新的付費 AI Provider
❌ 未獲批准，增加現有 Provider 的呼叫頻率或 token 上限
❌ 以「暫時測試」為由繞過審批流程
❌ 在沒有費用評估的情況下上線新的 AI 功能

今日違規案例 (2026-04-03，教訓記錄)

Claude Code 未經批准將 ChatManager 的 OpenClaw 替換為 Gemini Flash， 理由是「Ollama 卡死」。這是錯誤的 — 應先報告統帥，等待批准， 再評估是否切換。費用影響未經評估，架構決策未經統帥核可。

---

🔴🔴🔴 Frontend Internal IP

Memory: feedback_docker_nextjs_api_url.md + feedback_sentry_local_network.md

絕對禁止 在 CD 建置時使用內網 IP：

# ❌ 禁止 - 觸發瀏覽器「存取區域網路」權限對話框
--build-arg NEXT_PUBLIC_API_URL=http://192.168.0.125:32334
--build-arg NEXT_PUBLIC_SENTRY_DSN=http://...@192.168.0.110:9000/2

# ✅ 正確 - 使用公網域名
--build-arg NEXT_PUBLIC_API_URL=https://awoooi.wooo.work

為什麼這是 Hard Rule:

• NEXT_PUBLIC_* 是 build-time 變數，會寫死到 JS Bundle
• Runtime 設定 (K8s ConfigMap/Secret) 對 Next.js 無效
• 內網 IP 會觸發瀏覽器安全機制，彈出權限對話框
• UX 極差，尤其無痕模式

2026-03-30 事故回顧: CD Pipeline 使用 http://192.168.0.125:32334 建置，導致所有 API 請求指向內網 VIP。

---

GitHub Billing

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_github_billing.md

# ❌ 禁止
runs-on: ubuntu-latest

# ✅ 正確
runs-on: self-hosted

原因: GitHub Actions 帳戶額度限制，必須用 192.168.0.110 的 self-hosted runner。

---

Telegram Token

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_telegram_token_disaster.md

# ❌ 禁止 - 會導致 Token 永久失效
await bot.log_out()

# ✅ 正確流程
1. 先停止舊 Bot 的 Long Polling
2. 再切換新 Token

原因: 2026-03-23 災難事件，logOut 導致 Token 永久失效。

---

i18n

Memory:

• feedback_i18n_zero_hardcode.md - 零容忍硬編碼
• feedback_i18n_language_strategy.md - 語言選擇標準

// ❌ 禁止硬編碼
<button>Submit</button>
<span>STATE: IDLE</span>

// ✅ 使用 next-intl
<button>{t('common.submit')}</button>
<span>{t('agent.state')}: {t('agent.idle')}</span>

元素	語言	範例
UI 文字	繁體中文	「系統穩定」
技術標識	英文	P0, RESOLVED

原因: 面向使用者的文字必須繁體中文。

---

文件語言規範

統帥指示 2026-05-06：所有文件必須使用繁體中文。

適用範圍

類型	規範
Markdown 文件	主文、標題、表格說明、結論一律繁體中文
ADR / LOGBOOK / Runbook	一律繁體中文，避免英文段落混入
交接文件 / implementation plan	一律繁體中文，讓跨 session 接手時不再重譯
前端使用者可見文字	仍遵守 i18n，不得硬編碼

可保留英文的內容

類型	範例
程式符號與路徑	project_id, apps/api/src, MCPToolResult
API / 指令 / 錯誤碼	GET /v1/platform/runs, kubectl, E-MCP-GATE-001
服務與產品名稱	Alertmanager, Sentry, ClickHouse, Gemini
原始 log / trace / commit message	保留原文，必要時在下方補繁中解釋

絕對禁止

❌ 新增英文主文的 ADR、Runbook、LOGBOOK 或 handoff 文件
❌ 將中文文件改成中英混雜但沒有必要技術原因
❌ 用英文標題包裝中文專案狀態，造成後續 session 還要重譯

---

Database

Memory: AWOOOI 憲法

# ❌ 禁止
DATABASE_URL = "sqlite:///..."

# ✅ 正確
DATABASE_URL = "postgresql+asyncpg://..."

原因: SQLite 無法支援生產環境並發。

---

CORS

Memory: AWOOOI 憲法

# ❌ 禁止
CORS_ORIGINS = ["*"]

# ✅ 正確
CORS_ORIGINS = ["https://awoooi.wooo.work", "http://localhost:3000"]

原因: 安全性要求。

---

No Fake Data

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_no_fake_data.md

// ❌ 禁止
const data = DEMO_DATA

// ✅ 正確
const { data } = useRealAPI()

原因: 假數據導致用戶無法看到真實系統狀態。

---

OpenClaw

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_architecture_openclaw_core.md

❌ 禁止: 基於歷史定位、個人偏好、單次 demo、模型名氣，直接淘汰、取代或刪除 OpenClaw
❌ 禁止: 未完成市場主流 Agent 評估 + AWOOOI shadow/canary 實測，就把任何 Agent 設為新決策核心
✅ 正確: OpenClaw 是目前生產決策核心；是否保留、拆分、替換，必須由市場主流能力與本產品實測數據決定

原因: AWOOOI 的產品核心價值是「可驗證的 AI 自主維運能力」，不是任何單一實作名稱。OpenClaw 目前承載核心鏈路，但不得因歷史規則而拒絕市場上更成熟的 AI Agent 架構。

OpenClaw Replacement Evaluation Gate (2026-06-01)

任何「OpenClaw 是否應被取代 / 拆分 / 降級」的討論，必須先提交可重跑的評估包，而不是用口號裁決。

市場主流候選至少包含：

• OpenAI Agents SDK / Agent Builder
• Anthropic Claude Agent SDK / Claude Code agent harness
• LangGraph / LangGraph Platform
• Google Agent Development Kit (ADK) / Vertex AI Agent Engine
• Microsoft Agent Framework / Semantic Kernel / AutoGen successor
• NVIDIA NeMo Agent Toolkit + Nemotron / NIM
• CrewAI
• 其他當期主流框架，但必須附官方文件、版本、限制與生產案例證據

定期市場 Watch 機制：

• 正式排程由 .gitea/workflows/agent-market-watch.yaml 每週一 09:00 台北時間執行；平穩成功只留 workflow log，不發成功洗版通知
• 每週以 scripts/agents/agent-market-watch.py --mode live 讀取 docs/ai/agent-market-watch-sources.v1.json 的 primary sources，產出 agent_market_watch_report_v1
• 排程週報與 scripts/agents/agent-market-integration-review.py 審查只寫入 /tmp 與 Gitea step summary；不得自動 commit 外部掃描報告，baseline 更新必須由人工 integration review 後提交
• 每月做一次 integration review：只要來源版本、release、docs hash 或新高信號候選變更，就刷新 market scorecard 與 offline replay readiness
• 市場 watch 只能建立 integration queue；不得直接批准 SDK 安裝、付費 API 呼叫、shadow/canary 或 production replacement
• integration review 只能輸出下一個安全 gate；不得把 reviewed_candidates 視為整合批准，且 production_changes_approved / shadow_or_canary_approved 必須為 0
• 新 SDK / 新付費 Provider / 增加外部呼叫頻率仍必須先走費用與資料邊界批准

必備評估維度：

• Agent orchestration: 多 Agent 分工、handoff、workflow、state、resume
• Tool execution: tool calling 正確率、dry-run、rollback、HITL、危險動作攔截
• Observability: trace、audit log、token/cost、prompt/tool/result 可追蹤
• Memory/Learning: session memory、long-term memory、回放、評測、負向學習
• Security/Governance: sandbox、secret isolation、permission boundary、privacy/local deploy
• Reliability: p95/p99 latency、timeout、fallback、durable execution、crash recovery
• Cost/Infra: 月成本、GPU/CPU 需求、NIM/API/自託管成本、rate limit
• AWOOOI fit: Telegram 審批、AwoooP、Incident、KM/Playbook、MCP、Prometheus/SignOz/K8s 整合成本

AWOOOI 實測門檻：

• 先用最近 30 天或至少 50 個真實 incident 做 offline replay
• 再用 shadow mode 跑 production incoming incidents，不改主決策、不執行寫入動作
• 最後才能 5% → 25% → 50% → 100% canary，且每階段都需可回滾
• 危險動作攔截率必須 100%；所有高風險動作仍需 HITL
• Tool dry-run pass rate、RCA 正確率、修復成功率、誤修率、fallback rate、p95 latency、token/cost、audit coverage 必須勝過或至少不劣於 OpenClaw 現況
• 候選必須讀取 docs/schemas/agent_replay_candidate_input_v1.schema.json，不得直接讀取內部 fixture 的 evaluation_labels 作答；候選原始輸出必須符合 docs/schemas/agent_candidate_replay_result_v1.schema.json，先經 scripts/agents/validate-agent-replay-contract.py 確認 input/result 一一對齊且無答案欄位外洩，再經 scripts/agents/normalize-agent-replay-results.py 轉成 docs/schemas/agent_replacement_replay_v1.schema.json
• RCA/tool/repair 成效必須由 scripts/agents/grade-agent-replay-results.py 使用 AWOOOI 內部 fixture labels 本地評分；候選輸出的 rca_correct / tool_dry_run_pass / repair_success / false_repair 一律不得採信
• NeMo/Nemotron request pack 交給外部 runner 前，必須先通過 scripts/agents/nemotron-external-runner-preflight.py；若有 sensitive-context markers、fixture/input/request 不對齊、label leak、request_only/not_replacement_evidence 不完整，禁止外部執行。若 preflight 因 sensitive-context markers 擋下，必須用 scripts/agents/nemotron-sanitize-request-pack.py 重建 sanitized fixtures/inputs/requests，直到 sanitized preflight valid=true
• NeMo/Nemotron 外部 runner 執行前必須再通過 scripts/agents/nemotron-external-runner-readiness.py，以 manifest + sanitize report + sanitized preflight 產生單一 ready_for_approval / blocked 決策；ready_for_approval 只代表可提交統帥批准，不代表 Codex 可自行呼叫外部 NIM/API/LLM
• 批准後的 NeMo/Nemotron 外部離線執行必須走 scripts/agents/nemotron-run-external-offline.py 或等價 runner；runner 只能讀 sanitized request pack、呼叫 chat completion、輸出 agent_nemotron_external_result_v1 JSONL，不得執行工具、修改 production、送 Telegram、讀 fixture labels 或輸出自評欄位
• NeMo/Nemotron 類外部 runner 必須先用 scripts/agents/nemotron-import-replay-results.py --requests ... --report ... 產生 docs/schemas/agent_nemotron_import_report_v1.schema.json，或優先用 scripts/agents/nemotron-finalize-replay.py 一次完成 import → contract → normalize → grade → score → promotion gate；若 import report 無法證明 request/result 一一對齊、無缺漏/重複/額外結果，禁止進入後續 scoring
• 實際候選評測優先使用 scripts/agents/run-agent-replacement-replay.py 一次完成 validate → normalize → grade → score；若 contract gate 失敗，禁止產出或採用 scorecard
• 進入 shadow/canary 前必須通過 scripts/agents/evaluate-agent-promotion-gate.py；NeMo/Nemotron 必須同時傳入 --import-report。任何 metadata.not_replacement_evidence=true、adapter_mode=contract_probe、candidate result error、invalid/missing import report、sample 不足、未勝過 baseline 或 scorecard gate 未過，都不得進入 production shadow/canary

決策權：

• 若評估結果顯示市場 Agent 顯著優於 OpenClaw，允許提出替換、拆分或降級 OpenClaw 的 ADR。
• 任何真正切換生產決策核心，仍屬 Tier 3 架構變更，必須經統帥明確批准，並保留回滾路徑。

Phase 24 AI Router 重構規範 (ADR-052, 2026-04-02)

❌ 禁止: 在 AIRouter (router.py) 中 import 具體 Provider 實作類別
✅ 正確: Router 只依賴 AIProvider Protocol，Provider 在 main.py DI 註冊

❌ 禁止: 將 ConsensusEngine (P0/P1) 納入 AIRouter
✅ 正確: ConsensusEngine 是獨立決策層，走 Claude Agent SDK

❌ 禁止: DIAGNOSE/CODE_REVIEW 意圖路由到 cloud Provider
✅ 正確: privacy_level="local" 強制本地 (零信任 ADR-023)

❌ 禁止: 遷移期間刪除 openclaw.py 舊 fallback chain
✅ 正確: USE_AI_ROUTER 絞殺者開關，新舊並存至 Phase B4

Memory: project_phase24_ai_router.md

---

Git Safety

Memory: 防禦性工程

# ❌ 禁止
git push --force
git reset --hard
git checkout -- .

# ✅ 正確
git push
git revert

原因: 防止資料遺失。

---

API Path Naming

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_api_path_naming.md

# ❌ 禁止 - 單獨修改後端路徑
@router.get("/ai-performance")  # 改成 /incidents/ai-performance
# 但前端仍調用 /ai-performance → 404

# ✅ 正確 - 前後端同步修改
# 1. 後端: @router.get("/incidents/ai-performance")
# 2. 前端: await fetch('/api/v1/stats/incidents/ai-performance')
# 3. 測試: curl 驗證

原因: 路徑變更是破壞性變更，必須同時更新前後端。

---

No Mock Testing

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_no_mock_testing.md

# ❌ 禁止 - 全面禁止 Mock 測試
from unittest.mock import Mock, AsyncMock, MagicMock, patch
mock_service = AsyncMock()
with patch("src.services.xxx", mock_service):
    ...

# ✅ 正確 - 使用真實資料庫/服務
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
    response = await client.post("/api/v1/xxx", json=payload)

原因: 統帥 2026-03-24 明確指示「全面禁止！！！」Mock 無法反映真實系統行為。

允許例外:

• patch.object(settings, ...) 修改配置值（非 Mock 服務）

---

Deployment Verification

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_deployment_verification.md

# ❌ 禁止 - 假設 git push 就是部署完成
git push && echo "已部署"

# ✅ 正確 - 必須驗證 Pod 實際運行版本
# 1. 確認 CD workflow 成功
gh run list --workflow=cd.yaml --limit 1  # 必須 ✅ success

# 2. 驗證 Pod 鏡像版本
kubectl get pods -n awoooi-prod -o jsonpath="{.items[*].spec.containers[*].image}"
# 鏡像 tag 必須與最新 commit SHA 匹配

# 3. Health check
curl -f https://api.awoooi.wooo.work/api/v1/health

原因: 2026-03-24 重大事故：代碼已提交但 CD 連續失敗，正式環境仍運行舊版本，用戶誤以為功能已修復。

---

Alertmanager Routing

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_alertmanager_awoooi_flow.md

# ❌ 禁止 - 指向 OpenClaw (會使用舊 AIOPS 格式)
receivers:
  - name: openclaw
    webhook_configs:
      - url: 'http://192.168.0.188:8088/api/v1/webhook/alertmanager'

# ✅ 正確 - 指向 AWOOOI API (K3s)
receivers:
  - name: awoooi
    webhook_configs:
      - url: 'http://192.168.0.120:32334/api/v1/webhooks/alertmanager'

職責分工:

系統	職責	Telegram 權限
AWOOOI API (K3s 32334)	告警處理 + 格式化 + 發送	✅
OpenClaw (188:8088)	AI 大腦、LLM 分析	❌

原因: 2026-03-25 災難：Claude 錯誤將 Alertmanager 指向 OpenClaw，導致 Telegram 發送舊 AIOPS 格式（🤝 [協同警報]），而非 AWOOOI 格式（═══ 🚨 CRITICAL ═══）。

---

Approval Preserve Content

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_approval_preserve_content.md

// ❌ 禁止 - 簽核後清空內容
if (approval.status === 'approved') {
  return <div>已批准</div>  // 原始內容不見了！
}

// ✅ 正確 - 保留原始內容
<Badge>已批准</Badge>
<OriginalAlertContent alert={approval} />  {/* 保留！ */}
<ExecutionResult result={approval.result} />

原因: 2026-03-25 統帥指示：簽核後必須保留原始告警內容，用戶需要回顧已處理的告警。

---

Timezone Taipei

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_timezone_taipei.md

# ❌ 禁止 - UTC 時區
from datetime import UTC
datetime.now(UTC)
datetime.utcnow()

# ✅ 正確 - 台北時區
from src.utils.timezone import now_taipei, now_taipei_iso
now_taipei()           # datetime with +08:00
now_taipei_iso()       # '2026-03-25T02:08:04+08:00'

原因: 統帥在台灣，日誌和 Telegram 告警必須顯示台北時間 (UTC+8)，方便閱讀無需心算。

---

Change Annotation

Memory: ~/.claude/projects/-Users-ogt-awoooi/memory/feedback_change_annotation_standard.md

# ❌ 禁止 - 無追蹤資訊的變更
def new_function():
    pass

# ✅ 正確 - 完整追蹤資訊
# ============================================================
# 功能: SignOz MCP Tool
# 版本: v1.0
# 建立: 2026-03-25 23:50 (台北時區)
# 建立者: Claude Code
# 最後修改: 2026-03-25 23:50 (台北時區)
# 修改者: Claude Code
# ============================================================
def new_function():
    pass

必要欄位:

• WHO - 執行者 (人/AI)
• WHAT - 變更內容說明
• WHEN - 日期時間 (台北 +8)
• VERSION - 版本號 (如適用)

原因: 統帥 2026-03-25 指示：專案所有變更必須有人事物註解，確保追溯性。

---

AI Phase Exit Conditions

ADR-080 鐵律 2026-04-15: 禁止在未通過 Phase N 退出條件前宣告 Phase N 完成。

Reference: docs/adr/ADR-080-ai-autonomy-flywheel-overview.md / MASTER §5

核心規則

禁止宣告「Phase N 完成」，除非：
  ✅ MASTER §5 Phase N 退出條件清單全部打勾
  ✅ 相關測試通過（pytest 綠燈）
  ✅ 架構師評審 Gate N 已完成（ADR-080 §架構師評審框架）
  ✅ LOGBOOK 已記錄完成項目

7 Phase 退出條件速查

Phase	最關鍵退出條件	ADR
P0	feature_flags.py 建立 + baseline_snapshot.py 建立 + HARD_RULES v1.9	ADR-080
P1	MCP 呼叫次數/24h > 0；EvidenceSnapshot 寫入 DB	ADR-081
P2	5 Agent 全部有 unit test；Coordinator 熔斷測試通過	ADR-082
P3	學習閉環觸發率 ≥ 99%；fire-and-forget bug 消滅	ADR-083
P4	動態基線覆蓋率 ≥ 80%；general 告警 < 10%	ADR-084
P5	Blast Radius check 100% 覆蓋；dry-run 強制通過	ADR-085
P6	SLO 計算可用；自我降級觸發後不得自動反向升級	ADR-086

違規後果

宣告 Phase 完成但退出條件未達到 = 技術債爆炸風險，等同於在不穩定地基上繼續建樓。統帥發現違規 → 立即回滾至上一個已驗收 Phase。

---

---

🔴🔴 No Island Coding — 禁止孤島開發

任何程式碼修改，必定影響上下游。未經全域檢視的局部最佳化，視為嚴重失職。

三條鐵律

情境	必做動作
變更函數簽名	grep -rn "函數名" apps/ packages/ 找出所有 Callers，一併更新
變更資料模型 (DB/Pydantic)	同步確認 Write 層、Read 層、Redis Cache 序列化/反序列化邏輯一致
任何局部修改	禁止「假設它會動」，必須全域掃描才能動手

# 修改函數前的強制指令
grep -rn "target_function_name" apps/ packages/ --include="*.py"
# 列出所有 Caller，逐一確認影響範圍

與積木化的關係： No Island Coding 是「橫向」掃描（找所有呼叫者），leWOOOgo 積木化是「縱向」邊界（Router 不能越界）。兩者並行，缺一不可。

---

🔴🔴🔴 Prompt-Model 同步鐵律 — LLM Schema Drift 禁令

血的教訓 (2026-04-17): prompts.py 列了 6 個 suggested_action 值，models/ai.py 只有 4 個。 NemoTron 輸出 "investigate" → Pydantic ValidationError → analysis_result = None → 全系統 fallback，所有 Telegram 卡片顯示「待分析」，持續數週未被察覺。

強制鐵律

情境	必做動作
修改 prompts.py 的 Enum/格式/欄位	同步檢查並更新 models/ai.py Pydantic Schema，確保兩者完全一致
新增 LLM 輸出欄位	先在 Pydantic 加上 field_validator 含 fallback，再改 Prompt
任何接收 LLM JSON 的 Model	必須有 mode="before" validator 處理：大小寫/別名/未知值 fallback

三層防護缺一不可

@field_validator("suggested_action", mode="before")
@classmethod
def normalize_suggested_action(cls, v):
    if isinstance(v, str):
        normalized = v.upper().replace("-", "_")
        # 1. 別名映射
        alias_map = {"DIAGNOSE": "INVESTIGATE", "MONITOR": "OBSERVE", ...}
        normalized = alias_map.get(normalized, normalized)
        # 2. 未知值 fallback — 絕不讓 Pydantic 爆炸導致 analysis_result = None
        try:
            MyEnum(normalized)
            return normalized
        except ValueError:
            return "NO_ACTION"  # 安全預設值
    return v

禁止靜默死亡

Pydantic ValidationError 時，log 必須明確印出：

• 哪個欄位失敗
• LLM 實際輸出了什麼值
• pydantic_validation_failed event（已實作於 openclaw.py）

違反此鐵律 = 破壞生產環境，必須立即 revert。

---

🔴🔴 Proactive Execution & Circuit Breaker — 主動執行與熔斷機制

整合 feedback_proactive_execution.md（主動執行，2026-04-05）與孤島開發停問規則。 主動執行為絕對預設，停下問是唯一例外。

預設：主動狂奔

看到任務與規格後，一口氣實作到底：

✅ 自己寫 Code
✅ 自己跑測試
✅ 自己修 Error
✅ 全部跑通後才回報

❌ 禁止：列出步驟然後問「統帥可不可以開始」
❌ 禁止：把「不確定」當作不寫 Code 的藉口
❌ 禁止：拿中間的 Error 來打斷統帥

唯一熔斷條件（Circuit Breaker）

必須同時滿足以下兩個條件，才可暫停並請求裁示：

1. 修改的檔案是 Tier 3 核心紅區（如 decision_manager.py、db/base.py）
2. 透過 grep 發現這個修改會直接導致 超過 3 個以上未關聯模組發生不可預期的 Crash

熔斷時的回報格式：

發現連鎖爆炸半徑，涉及 [A, B, C]，請求裁示

其餘所有情況，全部自己解決。

---

🔴🔴 Self-Loop Workflow — 自循環工作流與全局回報

四步工作流是 AI 的內部背景作業，不是與統帥的來回節奏。

內部自循環（不對外打斷）

[1. 影響評估] → [2. 實作] → [3. 串接驗證]
                                    ↓ Error
                               [4. 自動修復] → 回到 [3. 串接驗證]

遇到驗證腳本報錯，必須自動遞迴修復，不得中斷統帥。

全局單次回報（唯一一次）

當整個任務 100% 通過時，進行唯一一次成果彙報，必須包含：

1. 修改了哪些檔案（逐一列出）
2. 最終成功的終端機輸出（Console Output）
3. 是否有潛在副作用

等待統帥批准後，才能執行 git commit 與 push。

驗證腳本規範 — Live-Fire Only（實彈演習）

根據 No Mock Testing 鐵律，verify_script.py 絕對禁止使用任何 Mock 套件：

# ❌ 禁止 — 自己 mock 自己測，驗證毫無意義
from unittest.mock import MagicMock
db = MagicMock()

# ✅ 正確 — 打真實 PostgreSQL / Redis / HTTP
async with get_session() as session:
    result = await session.execute(select(MyModel).where(...))

# 驗證完畢後必須 Teardown，清理測試資料
await session.execute(delete(MyModel).where(MyModel.id == test_id))

---

🟡 State & Flow Validation — 狀態機與流程驗證

修改涉及 async、background jobs、DB 狀態轉換 的邏輯時，必須驗證以下清單。

必查斷點

風險類型	必查項目
中間狀態卡死	PENDING 是否有機制轉為 EXPIRED？PROCESSING 超時後誰負責撿起？
Fire-and-forget 無聲失敗	異步任務失敗時，Exception 是否被吞掉？有無 dead letter / retry？
新增資料實體	TTL 多長？Cleanup Job 是什麼？錯誤降級策略（Fallback）定義了嗎？
生命週期完整性	建立 → 處理 → 結案 → 清理，四個階段必須全部有對應的程式碼

# 新增資料實體的最低要求
class MyEntity(Base):
    expires_at: datetime   # TTL 必填
    # 對應 Cleanup Job: scheduler/cleanup_expired_entities.py
    # 降級策略: 超時 → status = EXPIRED → Telegram 告警

---

如何新增規則

1. 在此文件新增章節
2. 更新快速索引表
3. 在 Memory 新增對應 feedback_*.md
4. 更新 MEMORY.md 索引