awoooi/docs/HARD_RULES.md

AWOOOI Product Hard Rules v3.1

最後更新：2026-07-10（Asia/Taipei）

本文件只保留真正會造成安全、資料、成本、供應鏈或不可逆營運事故的硬邊界。一般品質缺口、舊 owner counter、文件缺件、UI 尚未完成或 verifier 尚未建立，都必須轉成可執行工作項，不得冒充永久 hard gate。

1. 適用範圍與優先序

本規範適用 AWOOOI 以及所有受 AWOOOI 治理的：

• 主機、VM、Kubernetes、資料庫、網路與備份。
• 產品、專案、網站、API、Worker、排程與資料管線。
• 套件、工具、模型、MCP、RAG、KM、PlayBook 與 AI Agent。
• LOG、metric、trace、alert、Telegram、incident、work item 與 release。

規範優先序：

1. ~/.codex/AGENTS.md 的 global_product_governance_v2。
2. repo GLOBAL_RULES.md 的 awoooi_product_engineering_rules_v3。
3. 本文件。
4. 其他 ADR、Runbook、snapshot 與歷史文件。

下層文件與本規範衝突時，下層規則自動失效並建立治理債工作項，不得阻擋不相依工作。

2. Source Of Truth

判定順序固定為：

1. production runtime receipt 與獨立 post-verifier。
2. Gitea main、CD run、deploy marker 與 production image readback。
3. committed machine-readable evidence。
4. snapshot、文件與 UI projection。
5. conversation。

不得以文件、UI 卡片、HTTP 200、source commit、測試通過或 deploy marker 單獨宣告 runtime closure。

3. Controlled Apply 預設開啟

low、medium、high 風險工作預設允許 AI controlled apply。AI 必須主動補齊：

1. target selector 與 canonical asset ID。
2. source-of-truth diff。
3. check-mode、dry-run 或等價 preflight。
4. bounded executor、timeout、cooldown 與 idempotency key。
5. rollback 或 compensating action。
6. independent post-verifier。
7. operation receipt 與同一 run_id correlation。
8. KM/RAG evidence writeback。
9. PlayBook trust、recurrence 與 Telegram receipt。

owner_response_received=0、owner_response_accepted=0、runtime_execution_authorized=false、runtime_write_gate=0、apply_allowed=false、read_only=true、manual_required、needs_human=true 只能描述舊證據，不得阻擋可驗證、可回滾、低爆炸半徑的 controlled apply。

4. Critical Break-Glass 邊界

只有下列操作仍是事故級硬阻擋：

• 讀取、輸出、傳送或保存 secret、token、private key、cookie、session、authorization header、runner token 或 raw secret volume。
• DROP、TRUNCATE、破壞性 migration、production restore、不可逆 prune 或 remote delete。
• reboot、node drain、不可逆 firewall/DNS/TLS/network cutover。
• credentialed exploit、外部攻擊型 active scan 或未授權 lateral movement。
• 新增付費 provider、提高成本上限或切換 production provider route。
• 未完成 replay、shadow、canary 與 rollback 的 OpenClaw/核心 Agent 替換。
• force push、refs/repo/visibility 破壞或 remote history rewrite。

break-glass 必須有事件 ID、原因、範圍、期限、執行者、rollback、post-verifier 與事後 review。不得把 critical 邊界擴張成一般人工審批。

5. GitHub 全面停用

Gitea/Gitea SSH 是唯一 source-control authority。禁止：

• GitHub app、plugin、connector、MCP、gh、GitHub API、GitHub Actions、PR、issue、repo、branch、ref、mirror 與 search。
• 任何 Gitea workflow 在執行時從 github.com 或 api.github.com 解析、clone 或下載 actions/*。
• 把 .github/workflows、GitHub backup、GitHub primary switch 或 GitHub CI/CD 當作目前 truth 或待恢復目標。

Gitea workflow action 必須來自受控 Gitea action registry 或 repo-owned immutable action，並具備 digest、SBOM、provenance、更新策略、rollback 與 egress verifier。歷史 .github/workflows 一律標記 retired/do_not_use。

6. 資料與隱私

• PostgreSQL 是 production database；不得以 SQLite 冒充 production truth。
• 禁止 fake/demo/mock 資料進入 production readback。
• 不得保存 raw alert payload、credential、private topology 或可還原敏感資料的 partial/hash 值到公開 API、LOG、KM、RAG 或 Telegram。
• schema change 必須有 forward/backward compatibility、migration verifier 與 rollback/restore plan。
• backup ready 必須同時具備 expected inventory、bundle/checksum、freshness 與 sample restore dry-run。

7. Source、Release 與 Runtime Safety

• 禁止 force push、未驗證 history rewrite、remote ref delete 與 repo visibility 破壞。
• workflow、runner、Nginx、Kubernetes、DNS/TLS、database、backup 與 provider config 必須有 source diff、check、rollback 與 post-verifier。
• NEXT_PUBLIC_* 不得包含內網 IP、secret 或 private topology；公開 Web 使用正式網域。
• CD 必須驗證 source SHA、image digest/tag、GitOps revision、rollout、API health 與 user-visible smoke。
• deploy marker 只證明 release receipt，不等於 AI Loop 或資安事件 closure。

8. AI Agent 與 AISOC 完成契約

AI 自動化完成必須在同一 automation_run_id 具備：

sense -> normalize -> correlate -> decide -> check -> controlled_apply -> verify -> retry_or_rollback -> incident_close -> km_rag_writeback -> playbook_trust_writeback -> telegram_receipt

以下不得計入完成：

• metadata-only aggregate、歷史不同 run 拼接、fallback counter。
• 只有告警發送、建立 work item、產生建議或等待人工。
• 工具 installed、route HTTP 200、UI 可見或 source/test/CD green。

每個 host/service/product/site/tool/package 都必須有 asset-to-signal、asset-to-control、asset-to-executor 與 asset-to-verifier coverage。缺口由 AI 自動建立、排序與持續推進工作項。

9. UI/UX 與資訊架構

UI/UX 是持續並行的產品工作，不得因 P0 runtime 未完成而全面凍結。所有正式頁面必須：

• 第一視窗顯示狀態、範圍、下一步與可執行動作，不以長文字牆作主要操作介面。
• 使用 progressive disclosure、表格、filter、tabs、timeline、graph 與 receipts drill-down。
• desktop/mobile 無重疊、無水平溢位、無空白巨欄，且 loading/error/empty/degraded 狀態可辨識。
• 繁體中文為台灣預設；時間使用 Asia/Taipei，必要時同時保留 UTC machine timestamp。

UI 缺口通常不是 critical hard gate，但必須列入正式 backlog、完成 visual smoke 並不得被刪除或遺忘。

10. Gate 生命週期

任何新增 gate 都必須提供：

• policy_version
• risk_class
• scope
• owner_lane
• expires_at
• exit_condition
• replacement_action
• rollback_ref
• post_verifier

缺欄位、無期限、無退出條件或只回傳 0/false 的 gate 是治理債，不是有效阻擋。每次版本更新必須自動掃描並淘汰過時 gate、manual/owner/read-only copy 與不可執行 Runbook。

11. 驗證與稽核

每次變更至少保留：

• source diff 與 commit SHA。
• focused tests、typecheck/lint/schema/i18n 驗證。
• CD run 與 deploy marker。
• production API/readback。
• desktop/mobile smoke。
• 未完成 runtime gap、blocker 與下一個 ordered action。

所有證據要可由 AI Agent 消費並寫回 KM/RAG/PlayBook trust；不得只存在對話或人工截圖。

12. 已退役舊規範

以下語意自 v3.1 起全面退役：

• 未到某 Phase 就禁止 UI、feature 或平行工作。
• 任一紅燈就停止所有不相依工作。
• 低、中、高風險一律 owner review/manual handoff/read-only。
• GitHub Billing、ubuntu-latest 額度或恢復 GitHub 作為工作理由。
• UI 可見、approval counter 或人工接手作為預設終局。
• 沒有 PlayBook/verifier 就只能等待；正確做法是由 AI 補齊後 controlled apply。

歷史文件仍可作事故脈絡與 evidence，但不得恢復上述阻擋力。