# AWOOOI Product Engineering and AI Automation Rules v3

本規範以 `~/.codex/AGENTS.md` 的 `global_product_governance_v2` 為全產品上位規範，並補充 AWOOOI / AwoooP / IWOOOS 的產品實作要求。舊版 Phase、manual gate 或 blanket read-only 規則若衝突，均由本版取代。

## 1. North Star

AWOOOI 的完成目標是 production AI DevSecOps / AISOC runtime closure：所有受管主機、服務、產品、網站、工具、套件、資料與告警，都能由 AI Agent 感知、關聯、決策、受控執行、獨立驗證、失敗回滾/重試，並寫回 KM/RAG/MCP/PlayBook。

文件、snapshot、UI card、source、test、build、CD 或 metadata receipt 都只是證據層，不能單獨宣稱 AI 自動化完成。

## 2. Source Truth and Completion

真相優先序：production runtime receipt > Gitea main/CD/deploy marker > committed machine-readable evidence > snapshot/document > conversation。

每個工作項分開追蹤：

- `source_ready`
- `tests_ready`
- `gitea_cd_ready`
- `production_deployed`
- `runtime_loop_closed`
- `visible_ui_verified`

整體完成度必須同時呈現 program progress、asset coverage 與 latest production runtime closure。不得把歷史 aggregate、hardcoded percentage 或 fallback receipt 算進當前 run 完成。

## 3. Risk and Controlled Apply

Low/medium/high 均預設 AI controlled apply；critical 才 break-glass。每個動作必須有 target selector、truth diff、risk decision、check-mode、idempotency key、bounded executor、independent verifier、rollback/no-write terminal、durable learning writeback。

以下舊狀態只作 evidence，不得作一般終局：

```text
owner_review_required
manual_required
needs_human
read_only
runtime_execution_authorized=false
runtime_write_gate=0
apply_allowed=false
```

只有明文秘密、不可逆資料破壞、reboot/node drain、不可逆網路切換、攻擊型掃描、成本/provider 變更、未經 replay/shadow/canary 的核心替換、force push/ref/visibility 破壞、raw secret volume 屬 critical。

## 4. AI Loop Contract

所有可執行事件共用同一 `trace_id/run_id/work_item_id/incident_id`：

1. Sensor: LOG/metric/trace/alert/audit/change/freshness/backup receipt
2. Normalizer: canonical asset ID、taxonomy、severity、fingerprint、cluster
3. Correlator: primary cause、secondary noise、related changes、confidence
4. Planner: candidate、PlayBook、target selector、expected outcome
5. Policy: risk、allowlist、blast radius、cost、critical classifier
6. Check: dry-run/check-mode/diff/precondition
7. Execute: single-writer、idempotent、batch/canary/cooldown
8. Verify: independent service/route/metric/data/security postconditions
9. Recover: bounded retry、rollback、dead-letter、precise blocker
10. Learn: durable DB receipt、KM/RAG/MCP/PlayBook acknowledgement、trust update

缺節點時自動建立 coverage work item；不得轉成無期限人工接手。

## 5. Complete Asset Graph

資產圖譜至少包含：

- 主機/VM：99、110、111、112、120、121、188 及後續 discovered assets
- 平台服務：Gitea、runner、Harbor、Registry、K3s、Docker/containerd、Nginx/TLS/DNS、PostgreSQL、Redis、object storage、backup/restore
- 可觀測與安全：Prometheus、Alertmanager、Sentry、SigNoz、Langfuse、Wazuh/IWOOOS、Telegram、audit
- AI：OpenClaw、Hermes、NemoTron、Ollama、providers、MCP servers/tools、RAG indexes、KM、PlayBooks
- 產品/網站/API/admin routes：以 product governance matrix 與 public surface registry 每日 reconciliation
- 套件/映像/模型/規則：SBOM、版本、來源、支援期限、CVE/配置漂移、升級 replay/canary/rollback

每個資產需有 canonical ID、產品/專案/網站/服務/工具/套件標籤、owner lane、source/runtime identity、signals、freshness、executor、verifier、backup/restore 與 learning targets。

## 6. Logs, Alerts and Telegram

所有 LOG/metric/trace/alert 必須先進 durable registry/receipt，再供 AI Agent 使用。原始載荷需 redaction、retention、access boundary 與 provenance；不得把 Telegram 訊息當唯一資料庫。

每個 Telegram 告警必須映射：incident、run、asset、AI route、candidate、controlled queue、verifier、rollback、KM/RAG/MCP/PlayBook writeback。成功通知要降噪；失敗、stale、missing source、recurrence、notification failure 才升級。

## 7. Information Security Management

資訊安全治理採持續循環：Govern -> Identify -> Protect -> Detect -> Respond -> Recover，並對 AI 採 Govern -> Map -> Measure -> Manage。每個控制項必須有資產範圍、evidence source、freshness SLO、coverage state、gap work item、controlled response、post-verifier 與 audit receipt。

IWOOOS/Wazuh/SIEM 不得只顯示工具安裝或 UI 可見；必須證明 signal ingestion、rule coverage、triage、containment candidate、controlled response、recovery、case closure 與 recurrence prevention。

## 8. Secure Software Delivery

- Gitea/Gitea SSH 是唯一 source-control authority；GitHub freeze 包含 Gitea workflow 的 action resolution，禁止從 `github.com` / `api.github.com` 下載 `actions/*`。
- 每次 release 必須有 source SHA、focused tests、build/typecheck/i18n、Gitea CD run、deploy marker、production API/readback、desktop/mobile smoke。
- dependency/image/model 更新需 SBOM、provenance、相容性 replay、security evaluation、shadow/canary、rollback。
- 禁止 force push、未驗證 destructive migration、secret 明文或 mock/fake production evidence。

## 9. Professional UI/UX

UI/UX 與 backend/runtime 同步推進，不等待「所有 API 100% 不再變動」。所有主要頁面必須：

- 第一視窗顯示任務、狀態、next action、真實數字與 primary blocker
- 用 table、timeline、flow、chart、status badge 與 progressive disclosure 取代文字牆
- 保留完整技術 evidence，但放在可展開 detail，而非主畫面長文
- 導航 route 移除前必須有 IA ledger、替代目的地/redirect、權限與 smoke
- 使用 `next-intl`、semantic HTML、keyboard/focus、loading/error/empty/degraded states
- desktop/mobile 無重疊、無截字，並以 production screenshot/smoke 驗證

主流專業做法是可掃描、可比較、可操作的 operational cockpit；不強制單一品牌風格、裝飾動畫或延後到未定義 Phase。

## 10. Work Order and Parallelism

權威執行順序由 production priority API 的 AI automation program ledger 與 Agent99 enterprise work ledger共同投影。插入需求必須正式綁定 program work item、asset scope、priority、acceptance、runtime evidence 與 next action。

同一主線可平行推進互不衝突的 API、UI、LOG、Telegram、KM/RAG/MCP/PlayBook、verifier、backup 與 security lanes。外部 blocker 只能阻擋其依賴項，不能凍結整個產品。

## 11. Legacy Rule Retirement

所有舊 gate 必須有：`policy_version`、`risk_class`、`reason`、`owner_lane`、`created_at`、`expires_at`、`exit_condition`、`replacement_action`、`post_verifier`。缺 expiry/exit condition 的 gate 視為治理債，不能新增；與 live truth 衝突時自動建立 drift work item。

`GLOBAL_RULES.md v2.3` 中的「紅燈停止全部新功能」、「架構盲區立即暫停」、「Phase 1/2 絕對禁止 UI 打磨」、「Phase 4 才能做視覺」已正式失效。紅燈需優先處理，但不停止其他無依賴、低爆炸半徑工作。

## 12. Required Verification

最小驗證：

```text
JSON/schema validation
focused backend tests and lint
web typecheck and i18n mirror validation
Gitea CD and deploy marker readback
production API/runtime verifier
desktop/mobile smoke for changed user-facing routes
```

版本：`awoooi_product_engineering_rules_v3`

生效：`2026-07-10 Asia/Taipei`

上位規範：`global_product_governance_v2`