規則控制鏈
控制層 •
Version 1.0 •
概述
SuperPortia EGS（Engineering Governance Spec）v1.2 包含 73 條治理規則，分布在 Hooks、Scripts、LLM/CV Pipeline、Rule 檔案四個控制機制類別中。整體強制覆蓋率為 35.6%（26/73 條為確定性 Deterministic 執行）。
統計摘要
| 分類 | 數量 | 說明 |
|---|---|---|
| 總規則數 | 73 | EGS v1.2 全部規則 |
| Deterministic（確定性） | 26 | Hook 或 Script 強制執行，無法繞過 |
| Advisory（建議性） | 46 | 依賴 Agent LLM 遵從，無機械強制 |
| HITL | 1 | 需要夏哥批准才能執行 |
| Not Enforced | 1 | 已識別但尚未建立控制機制 |
| 有效覆蓋率 | 35.6% | 26 條 Deterministic / 73 條總計 |
35.6% 的確定性覆蓋率意味著：每三條規則中，只有一條會在 Agent 嘗試違規時被機械攔截。其餘 64.4% 的規則依賴 Agent 的 LLM 推理能力遵從——這是 Phase 2 治理成熟度提升的主要目標。
Top 20 關鍵規則控制鏈
以下 20 條規則因業務風險最高，被列為優先監控項目。
| # | 規則名稱 | 來源檔案 | 強制類型 | 控制機制 | 擁有者 |
|---|---|---|---|---|---|
| R-01 | Deploy Gate — 禁止不帶 --dry-run 的 wrangler deploy | hooks/deploy-gate.sh | Deterministic | PreToolUse Hook (DENY) | Ops |
| R-02 | Protect Files — 禁止直接編輯 .env, settings.json, wrangler.toml | hooks/protect-files.sh | Deterministic | PreToolUse Hook (DENY) | Ops |
| R-03 | Post-Edit Lint — 任何 Edit/Write 後自動 lint | hooks/post-edit-lint.sh | Deterministic | PostToolUse Hook | Ops |
| R-04 | Doc Quality Stop — .md 檔案寫入後必須輸出自檢 Checklist | hooks/stop-hook.sh | Deterministic | Stop Hook (BLOCK) | Ops |
| R-05 | Engine Safety Blocklist — 危險操作禁止用便宜引擎 | agents.yaml | Deterministic | Code path 覆寫為 claude | Ops |
| R-06 | WO Lease Gate — 多 Agent 不可同時 accept 同一工單 | Cloud UB Worker API | Deterministic (DRAFT) | API REJECT | Cloud UB |
| R-07 | HITL 支付/刪除/外部發布 | company-constitution.md §5 | HITL | 夏哥確認後方可執行 | 夏哥 |
| R-08 | 五鐵律 — .claude/ 設定只從 ops → ships 單向流動 | cross-ship-sync.md | Advisory | Rule 教導 + ops repo 審查 | Ops |
| R-09 | PK 核查 — Perishable Knowledge 使用前必須驗證 | tech-freshness.md | Advisory | Rule 教導 | All Agents |
| R-10 | UB 語言規定 — 所有 UB entry 必須英文 | ub-governance.md | Advisory | Rule 教導 | All Agents |
| R-11 | MTAAA 分類僅用 Controlled Vocabulary | ub-governance.md | Advisory | CV 約束 LLM | MTAAA |
| R-12 | 工單是唯一任務通道 — 無口頭承諾 | company-constitution.md §3 | Advisory | Rule 教導 | All Agents |
| R-13 | Session Handoff 必須寫 UB 入庫 | agent-intelligence-protocol.md §5b | Advisory | Rule 教導 | All Agents |
| R-14 | 日誌必須寫 60-Daily/YYYY-MM-DD.md | MEMORY.md | Advisory | Rule 教導 | 小克 |
| R-15 | Pre-Flight Check — 非瑣碎任務執行前評分 0-6 | authority-trust-boundaries.md | Advisory | Rule 教導 | Chief Eng. |
| R-16 | Research-Before-Plan — 計畫前必須驗證技術時效性 | agent-intelligence-protocol.md §6 | Advisory | Rule 教導 | All Agents |
| R-17 | GSTA 對齊 — 所有報告必須引用 Goal/Strategy | gsta-alignment.md | Advisory | Rule 教導 | All Agents |
| R-18 | Compaction Recovery — 壓縮後不得問「我們在做什麼」 | compaction-recovery-protocol.md | Advisory | Rule 教導 | All Agents |
| R-19 | Doc Compression 禁止 — 禁止只寫摘要的文件 | documentation-standards.md | Advisory + Hook | Stop Hook (BLOCK if no self-check) | All Agents |
| R-20 | Project Creation Gate — 新專案必須跑 /create skill | project-creation-gate.md | Advisory + Script | verify-project-scaffold.sh | All Agents |
控制機制分類
Hooks（15 個）
PreToolUse、PostToolUse、Stop Hook 三類，在 Agent 操作前後或結束前攔截。
| Hook 檔案 | 觸發時機 | 效果 |
|---|---|---|
| deploy-gate.sh | PreToolUse / Bash | DENY：wrangler deploy/publish 無 —dry-run |
| protect-files.sh | PreToolUse / Write+Edit | DENY：.env*, settings*.json, wrangler.toml |
| post-edit-lint.sh | PostToolUse / Edit+Write | RUN：eslint/pylint/tsc on edited file |
| stop-hook.sh | Stop | BLOCK：.md 寫入無 Doc Quality Self-Check |
| check-print-pollution.sh | PostToolUse | WARN：偵測 console.log 殘留 |
| enforce-venv-python.sh | PreToolUse / Bash | DENY：python 未在 .venv 執行 |
| ub-ingest-quality.sh | PostToolUse | WARN：UB entry 缺少必要欄位 |
| session-start.sh | Session Start | RUN：heartbeat + mailbox check |
| git-commit-format.sh | PreToolUse / Bash (git) | DENY：commit message 不符合格式 |
| changelog-gate.sh | PreToolUse / Bash (git) | DENY：commit 前 CHANGELOG.md 未更新 |
| wo-status-gate.sh | PreToolUse | CHECK：工單狀態推進合法性 |
| cross-ship-file-guard.sh | PreToolUse / Write | WARN：在非 ops repo 的 .claude/ 內直接寫入 |
| adr-naming-check.sh | PostToolUse / Write | WARN：ADR 命名不符合 0001-short-title.md 格式 |
| vault-write-guard.sh | PostToolUse / Write | CHECK：Vault note 無 frontmatter |
| engine-override.sh | PreToolUse | DENY+OVERRIDE：危險操作強制升級引擎 |
Scripts（10 個）
排程或手動執行，不在 Hook 鏈中。
| 腳本 | 用途 | 執行方式 |
|---|---|---|
| verify-project-scaffold.sh | 新專案 EGS 合規性驗證 | 手動 / 新專案建立後 |
| sync-sources.sh | Docs Site 從 Source repos 同步生成頁面 | 手動 / 每次 rule/skill 修改後 |
| sync_from_ssot.sh | SS2 從 ops repo 同步 .claude/ | 手動 / ops push 後 |
| text_batch_runner.py | MTAAA 文字類 UB entry 批次分類 | 未建置（Task #69） |
| boiler_grandpa_v2.py | MTAAA 分類排程（每 5 分鐘） | launchd 排程 |
| sre-patrol.sh | 服務健康巡邏 | launchd 排程（每 15 分鐘） |
| sre-dispatch.sh | 偵測異常後自動建立 WO | launchd 觸發 |
| tokscale | 跨 Agent Token 用量追蹤 | 手動 |
| ccusage | Claude 專屬用量追蹤 | 手動 |
| backup-vault.sh | Vault 備份（計畫中） | 計畫中（G-13） |
LLM/CV（1 個）
| 機制 | 用途 | 說明 |
|---|---|---|
| MTAAA boiler_grandpa + CV | UB entry 自動分類 | LLM（DeepSeek V3）從 Controlled Vocabulary 選擇 Topic/Type/Lifecycle。非確定性但有詞彙表約束。 |
Rule 檔案（46 條 Advisory）
.claude/rules/*.md 中的 Advisory 規則，依賴 Agent LLM 在每個 session 載入並遵從。這 46 條規則缺乏機械強制，是目前治理成熟度的主要差距來源。
強制執行差距分析
以下 Advisory 規則風險最高，建議優先轉換為 Deterministic 控制：
| 規則 | 當前類型 | 建議轉換方式 | 優先級 |
|---|---|---|---|
| R-08 五鐵律（ops wins） | Advisory | cross-ship-file-guard.sh 升級為 DENY | HIGH |
| R-10 UB 語言規定 | Advisory | ub-ingest-quality.sh 加 language check | MEDIUM |
| R-12 工單唯一通道 | Advisory | PAM 整合後自動偵測口頭任務 | LOW |
| R-13 Session Handoff | Advisory | Stop Hook 加 handoff existence check | HIGH |
| R-16 Research-Before-Plan | Advisory | PK timestamp 追蹤 + Hook 提示 | MEDIUM |
| R-17 GSTA 對齊 | Advisory | Stop Hook 加 GSTA mention check | LOW |
合規審計證據來源
每條規則的執行是否生效，可從以下來源取得證據：
| 證據來源 | 涵蓋規則類型 | 查詢方式 |
|---|---|---|
| Hook 執行日誌 | Deterministic (Hooks) | ~/.claude/logs/hooks/YYYY-MM-DD.log |
| UB entry 標籤 | Advisory (ingestion) | search_brain("tag:decision") |
| Git commit history | Deploy Gate / Changelog Gate | git log --all --oneline |
| Cloud UB WO 狀態流 | WO Lease Gate | list_work_orders() |
| MTAAA 分類記錄 | LLM/CV | search_brain("MTAAA classified") |
| tokscale / ccusage | Cost Awareness | tokscale models / npx ccusage session |
| boiler_grandpa 執行日誌 | MTAAA Auto-classify | ~/Documents/superportia-ub-pipeline/logs/ |
| Vault note frontmatter | Vault Write Guard | obsidian search type: 查詢 |