docs(security): add approval state transition contract [skip ci]

docs/security/SECURITY-APPROVAL-STATE-TRANSITION.md

@@ -0,0 +1,50 @@
+# 資安人工決策狀態轉移契約
+
+| 項目 | 內容 |
+|------|------|
+| 日期 | 2026-05-13 |
+| 狀態 | 草案 |
+| Schema | `docs/schemas/security_approval_state_transition_v1.schema.json` |
+| Snapshot | `docs/security/security-approval-state-transition.snapshot.json` |
+| 模式 | `approval_state_transition_only` |
+| runtime 執行授權 | `false` |
+
+## 0. 核心結論
+
+`security_approval_state_transition_v1` 是 S3.3 的人工決策狀態轉移契約。
+
+它只回答一件事：人工 reviewer 對 review packet 做出 `approve_scope`、`reject`、`defer`、`request_more_evidence` 或 `keep_blocked` 後，AwoooP 可以如何更新狀態。
+
+它不是 runner，也不是 runtime gate。任何 transition 都必須維持 `execution_authorized=false`。
+
+## 1. 決策到狀態
+
+| Decision | Next state | 初期可做 | 仍需 runtime gate |
+|----------|------------|----------|-------------------|
+| `approve_scope` | `scope_approved_waiting_runtime_gate` | 進入設計、草案、只讀 inventory、低噪音 scope 或人工 exception 文件階段 | 是 |
+| `reject` | `closed_rejected_no_action` | 記錄拒絕原因與 audit evidence | 否 |
+| `defer` | `deferred_pending_owner_timing` | 等 owner、時間窗或條件明確 | 否 |
+| `request_more_evidence` | `evidence_requested_waiting_snapshot_update` | 要求新的 redacted snapshot 或補 evidence | 否 |
+| `keep_blocked` | `blocked_by_default` | 維持 blocked reason，只允許補 disable / allowlist / audit gate 設計 | 是 |
+
+## 2. AwoooP 可做
+
+1. 根據人工決策更新 packet / gate / rollup 的只讀狀態。
+2. 將決策寫入 `security_approval_decision_record_v1`。
+3. 對 `approve_scope` 顯示 follow-up runtime gate required。
+4. 對 `request_more_evidence` 顯示需要補哪一類 redacted evidence。
+5. 對 `keep_blocked` 顯示 block candidate 仍未解除。
+
+## 3. AwoooP 不可做
+
+1. 不把 transition rule 當成執行命令。
+2. 不因為 `approve_scope` 就立即啟動 scan、Kali `/execute`、repo 建立、visibility 修改、refs sync 或 GitHub primary cutover。
+3. 不把 reject/defer/request_more_evidence 轉成 cleanup、rollback 或自動修復。
+4. 不保存 raw secret、token、cookie、private key、credential value 或 exploit payload。
+5. 不把 LOW / MEDIUM observation 變成 blocking gate。
+
+## 4. 階段定位
+
+S3.3 讓 AwoooP 對人工決策有一致狀態語義，避免「批准 scope」被誤解成「可以立刻執行」。
+
+這仍是低摩擦框架期。它讓流程更清楚，但不提高產品、部署或開發流程的資安阻力。