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，但不得恢復上述阻擋力。