universal-dev-standards 5.1.0-beta.7 → 5.1.0

package/bundled/locales/zh-TW/core/health-check-standards.md

@@ -0,0 +1,144 @@
+---
+source: ../../../core/health-check-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 健康檢查標準
+
+> **語言**: [English](../../../core/health-check-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-17
+**狀態**: Trial（到期 2026-10-17）
+**適用範圍**: universal
+**來源**: XSPEC-067（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+健康檢查標準：liveness / readiness / startup 三種 probe、深度 health check、結構化 JSON 回應。
+
+業界常見錯誤：把 liveness 和 readiness 混用（健康檢查檢查外部依賴導致連鎖重啟）。本標準明確三種 probe 語意分離，定義深度 health check 的檢查範圍（僅關鍵依賴），並規範結構化 JSON 回應以便下游自動化處理。
+
+---
+
+## 核心規範
+
+- Liveness probe 不得檢查外部依賴（DB、下游 API），否則會造成連鎖重啟
+- Readiness probe 可檢查關鍵外部依賴，但僅關鍵（非全部依賴）
+- 慢啟動服務應使用 startup probe，啟動完成後交棒給 liveness
+- Health check 端點必須回傳結構化 JSON，包含 status / dependencies / timestamp
+- Health check 結果應作為 observability 的 Error signal 之一，連續 fail 觸發 incident
+
+---
+
+## 三種 Probe 類型
+
+### Liveness Probe
+
+- **目的**：服務是否還活著（process 是否卡死）
+- **建議端點**：`GET /health/live`
+- **允許檢查**：process 是否能回應 HTTP、內部 event loop 是否可用
+- **禁止檢查**：DB 連線、下游 API、消息佇列（會造成連鎖重啟）
+- **失敗行為**：重啟 pod / process
+- **參數**：failureThreshold=3，periodSeconds=10
+
+### Readiness Probe
+
+- **目的**：是否可接收流量
+- **建議端點**：`GET /health/ready`
+- **允許檢查**：自身 API 可用、DB 連線（若服務必須依賴 DB）、關鍵下游依賴、必要設定已載入
+- **禁止檢查**：非關鍵依賴（避免非關鍵故障造成服務被移出負載均衡）
+- **失敗行為**：移出負載均衡，不重啟
+- **參數**：failureThreshold=3，periodSeconds=5
+
+### Startup Probe
+
+- **目的**：啟動期專用，替代慢啟動服務的 liveness
+- **建議端點**：`GET /health/startup`
+- **檢查項目**：啟動過程所需資源（如快取預熱、index 載入）已完成
+- **失敗行為**：重啟 pod（啟動超時）
+- **完成後**：停用，改由 liveness 接手
+- **參數**：failureThreshold=30，periodSeconds=10
+
+---
+
+## 深度規則
+
+| 層級 | 使用時機 | 檢查範圍 |
+|------|---------|---------|
+| Shallow | Liveness | process 是否可回應，不碰任何外部依賴 |
+| Deep | Readiness | 自身 API 路由、DB ping（若必須）、關鍵下游 API ping |
+
+**關鍵依賴的定義**：沒有它服務就完全無法提供核心功能。
+
+---
+
+## 回應格式
+
+**Content-Type**：`application/json`
+
+| HTTP 狀態碼 | 意義 |
+|------------|------|
+| `200` | healthy — 所有關鍵依賴正常 |
+| `503` | unhealthy — 至少一個關鍵依賴失敗 |
+
+**JSON Schema**：
+
+```json
+{
+  "status": "healthy | degraded | unhealthy",
+  "timestamp": "<ISO-8601>",
+  "uptime_seconds": 12345,
+  "version": "1.0.0",
+  "dependencies": {
+    "database": {
+      "status": "healthy | unhealthy",
+      "latency_ms": 5,
+      "last_check": "<ISO-8601>"
+    },
+    "upstream_api": {
+      "status": "healthy | unhealthy",
+      "latency_ms": 20
+    }
+  }
+}
+```
+
+---
+
+## 與 Observability 整合
+
+- Health check 結果應作為 RED metric 的 Error 來源之一（Rate / Errors / Duration）
+- 連續 N 次 health check failed 應觸發 incident（對齊 incident-response）
+- probe 延遲本身應被監控（異常緩慢可能是 resource_exhaustion 徵兆）
+
+---
+
+## 情境範例
+
+**情境 1：liveness 不檢查 DB**
+- 條件：DB 暫時無法連線
+- Liveness 回傳 200 healthy（不檢查 DB），避免連鎖重啟
+
+**情境 2：readiness 因關鍵依賴失敗**
+- 條件：關鍵下游 API 不可達
+- Readiness 回傳 503，pod 移出負載均衡但不重啟
+
+**情境 3：startup 後交棒 liveness**
+- 條件：服務需 60s 預熱快取
+- 前 60s startup probe 持續回 503，預熱完成後交棒 liveness
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `HC-001` | `HEALTH_CHECK_FAILED` — 關鍵依賴失敗 |
+| `HC-002` | `HEALTH_CHECK_TIMEOUT` — probe 本身超時 |
+| `HC-003` | `INVALID_DEPENDENCY_SET` — readiness 檢查了非關鍵依賴（設計違規） |

package/bundled/locales/zh-TW/core/immutability-first.md

@@ -0,0 +1,159 @@
+---
+source: ../../../core/immutability-first.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 不可變性優先架構標準
+
+> **語言**: [English](../../../core/immutability-first.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-16
+**適用範圍**: TypeScript 介面、資料流設計、並行系統
+**Scope**: universal
+**來源**: XSPEC-044
+
+---
+
+## 目的
+
+系統級不可變性設計原則：DTO／Value Object 欄位一律 `readonly`，防止並行 Agent 環境下的競態條件。
+
+資料流介面（DTO / Value Object）的欄位一律宣告為 `readonly`，陣列欄位使用 `ReadonlyArray<T>`，物件修改透過展開語法建立新物件，防止並行 Agent 環境下的意外狀態共享與競態條件。
+
+---
+
+## 核心規範
+
+- 資料流介面（DTO / Value Object）的所有欄位必須宣告 `readonly`
+- 介面中的陣列型欄位使用 `ReadonlyArray<T>` 而非可變的 `T[]`
+- 修改物件時使用物件展開語法建立新物件，不直接賦值給 `readonly` 欄位
+- 跨並行邊界（`Promise.all` / Worker Thread）傳遞的物件必須為深層不可變
+- 介面中的嵌套物件欄位使用 `Readonly<T>` 包裝（防止淺層保護不足）
+
+---
+
+## 規則詳細說明
+
+### IMM-001：DTO 欄位 readonly（必要）
+
+資料流介面（Data Transfer Objects、Value Objects）的所有欄位必須宣告 `readonly`，防止並行 Agent 環境下的意外狀態共享與競態條件。
+
+**錯誤範例**：
+```typescript
+interface TaskResult {
+  status: TaskStatus   // ← 可被意外修改
+  cost_usd?: number
+}
+```
+
+**正確範例**：
+```typescript
+interface TaskResult {
+  readonly status: TaskStatus   // ← 型別安全保護
+  readonly cost_usd?: number
+}
+```
+
+---
+
+### IMM-002：陣列欄位 ReadonlyArray（必要）
+
+介面中的陣列型欄位使用 `ReadonlyArray<T>` 而非可變的 `T[]`，防止 `push`/`splice`/`sort` 等就地修改操作破壞共享陣列。
+
+**錯誤範例**：
+```typescript
+interface MemoryContext {
+  recentHistory: IterationRecord[]   // ← 可被 push/splice
+}
+```
+
+**正確範例**：
+```typescript
+interface MemoryContext {
+  readonly recentHistory: ReadonlyArray<IterationRecord>
+}
+```
+
+---
+
+### IMM-003：展開語法替代就地修改（必要）
+
+修改物件時使用物件展開語法建立新物件，不直接賦值給 `readonly` 欄位，保留原始物件不變，同時建立可追蹤的修改歷程。
+
+**錯誤範例**：
+```typescript
+options.sessionId = forkId   // ← 直接修改，其他持有者看到改變
+```
+
+**正確範例**：
+```typescript
+const taskOptions = { ...options, sessionId: forkId }   // ← 新物件
+```
+
+---
+
+### IMM-004：並行邊界深層不可變（必要）
+
+跨並行邊界（`Promise.all` / Worker Thread）傳遞的物件必須為深層不可變，並行執行中無法預測存取順序，可變共享物件必然產生競態條件。
+
+**正確範例**：
+```typescript
+// 每個並行任務持有自己的 options 快照
+const batchResults = await Promise.all(
+  batch.map(task => {
+    const taskOptions = { ...baseOptions, sessionId: forkId }
+    return executeOneTask(task, adapter, taskOptions, ...)
+  })
+)
+```
+
+---
+
+### IMM-005：嵌套物件 Readonly 包裝（建議）
+
+介面中的嵌套物件欄位使用 `Readonly<T>` 包裝，頂層 `readonly` 不防止嵌套物件欄位被修改（淺層保護不足）。
+
+**錯誤範例**：
+```typescript
+interface PipelineMemoryEntry {
+  readonly metadata: { score?: number }   // ← metadata.score 仍可被修改
+}
+```
+
+**正確範例**：
+```typescript
+interface PipelineMemoryEntry {
+  readonly metadata: Readonly<{ score?: number; severity?: string }>
+}
+```
+
+---
+
+## 適用時機
+
+- 設計新的 DTO / Value Object / Config 介面時
+- 跨並行邊界傳遞物件時
+- Agent 間共享狀態設計時
+- Code Review 時檢查介面是否遺漏 `readonly`
+
+---
+
+## 豁免情況
+
+- Builder Pattern 的 mutable builder 物件（在 `build()` 後回傳不可變結果）
+- 測試 fixture 的 mutable 建立步驟（建立後視為不可變）
+- 效能關鍵的熱路徑（需有明確的 benchmark 依據才可豁免）
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `IMM-E001` | `READONLY_VIOLATION` — 嘗試修改 readonly 欄位（TypeScript 編譯期捕獲） |
+| `IMM-E002` | `SHARED_MUTATION` — 跨並行邊界的就地修改導致競態條件 |
+| `IMM-E003` | `SHALLOW_READONLY` — 嵌套物件遺漏 `Readonly<T>` 包裝，淺層保護不足 |

package/bundled/locales/zh-TW/core/recovery-recipe-registry.md

@@ -0,0 +1,146 @@
+---
+source: ../../../core/recovery-recipe-registry.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 恢復食譜註冊表標準
+
+> **語言**: [English](../../../core/recovery-recipe-registry.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-16
+**適用範圍**: 所有 Agent 執行恢復邏輯
+**Scope**: universal
+**來源**: XSPEC-046（claw-code ROADMAP Phase 3 Recovery Recipes，DEC-035）
+**依賴**: failure-source-taxonomy（XSPEC-045）
+
+---
+
+## 目的
+
+恢復食譜註冊表：將分散的恢復邏輯統一為 YAML 可配置的 Recipe，以 `failureSource` 為匹配鍵。
+
+各模組（Fix Loop、Circuit Breaker、Guardian 自動修復、Staging 重試）的恢復邏輯統一為可外部化的 Recovery Recipe 格式。每個 Recipe 透過 `failureSource`（XSPEC-045）匹配觸發條件，選擇對應的恢復策略，並定義升級路徑（escalation）。無匹配 Recipe 時 fallback 到現有行為（向後相容）。
+
+---
+
+## 核心規範
+
+- 每個 Recovery Recipe 必須有唯一 ID（`RR-NNN` 格式）
+- `match.failure_source` 必須是 failure-source-taxonomy 中定義的 8 類之一
+- `escalation.on_exhaust` 必須定義，不得無限循環（如 escalation 指向自身）
+- 無匹配 Recipe 時，系統必須 fallback 到現有預設行為（不得拋出錯誤）
+- 使用者自訂 Recipe 優先於內建 Recipe（同 `failureSource` 時，使用者配置的先匹配）
+- Recipe config 格式錯誤時 fallback 到策略預設值（不中斷執行）
+
+---
+
+## 6 個內建恢復策略
+
+### `fix_loop`
+
+- **描述**：注入結構化錯誤回饋，重試任務（現有 Fix Loop）
+- **預設 config**：`max_attempts: 3`, `budget_usd: 0.50`
+- **最適合**：`compilation`, `test_failure`
+
+### `circuit_breaker`
+
+- **描述**：三態斷路器保護（XSPEC-036），連續失敗後開路避免雪崩
+- **預設 config**：`failure_threshold: 3`, `cooldown_ms: 30000`
+- **最適合**：`tool_failure`, `prompt_delivery`
+
+### `rebase_and_retry`
+
+- **描述**：先執行 git rebase 同步基底分支，再重試任務／迭代
+- **預設 config**：`max_attempts: 1`, `base_branch: "main"`
+- **最適合**：`branch_divergence`
+- **依賴**：XSPEC-047 Branch Drift Detection
+
+### `model_switch`
+
+- **描述**：切換至備用模型後重試
+- **預設 config**：`fallback_models: [...]`, `max_attempts: 2`
+- **最適合**：`model_degradation`, `prompt_delivery`
+
+### `degraded_mode`
+
+- **描述**：以降級模式繼續執行（如：跳過品質驗證、以部分結果繼續）
+- **結果狀態**：`done_with_concerns`
+- **最適合**：`resource_exhaustion`, `model_degradation`
+
+### `human_checkpoint`
+
+- **描述**：暫停執行，等待人工介入（提供失敗細節供判斷）
+- **最適合**：`policy_violation`, `branch_divergence`
+- **備註**：所有其他策略的最終升級路徑
+
+---
+
+## Recipe YAML 格式
+
+```yaml
+id: RR-NNN          # 必填，唯一識別符
+name: string        # 必填，可讀名稱
+match:              # 必填
+  failure_source: <FailureSource>   # 必填
+  severity: [critical, high, ...]   # 選填；省略表示匹配所有 severity
+strategy: <RecoveryStrategy>        # 必填
+config: {}                          # 選填；覆蓋策略預設值
+escalation:         # 必填
+  on_exhaust: <RecoveryStrategy>    # 必填；不得指向自身
+  message: string   # 選填；升級時的通知訊息
+```
+
+---
+
+## 5 個預設 Recipe
+
+| ID | 名稱 | 匹配條件 | 策略 | 升級路徑 |
+|----|------|----------|------|---------|
+| `RR-001` | Fix Loop for Compilation Errors | `compilation` | `fix_loop`（3次, $0.50） | `human_checkpoint` |
+| `RR-002` | Fix Loop for Test Failures | `test_failure` | `fix_loop`（3次, $0.50） | `human_checkpoint` |
+| `RR-003` | Model Switch for Degradation | `model_degradation` | `model_switch`（2次） | `degraded_mode` |
+| `RR-004` | Rebase for Branch Divergence | `branch_divergence` | `rebase_and_retry`（1次） | `human_checkpoint`（需人工解決衝突） |
+| `RR-005` | Degraded Mode for Resource Exhaustion | `resource_exhaustion` | `degraded_mode` | `human_checkpoint` |
+
+---
+
+## 類型定義
+
+### RecoveryStrategy
+
+```
+fix_loop | circuit_breaker | rebase_and_retry | model_switch | degraded_mode | human_checkpoint
+```
+
+### RecoveryRecipe
+
+| 欄位 | 類型 | 必填 |
+|------|------|------|
+| `id` | `string`（RR-NNN 格式） | 是 |
+| `name` | `string` | 是 |
+| `match.failure_source` | `FailureSource` | 是 |
+| `match.severity` | `string[]`（可選） | 否 |
+| `strategy` | `RecoveryStrategy` | 是 |
+| `config` | `object`（可選） | 否 |
+| `escalation.on_exhaust` | `RecoveryStrategy` | 是 |
+| `escalation.message` | `string`（可選） | 否 |
+
+---
+
+## 整合點
+
+### DevAP
+
+- `packages/core/src/types.ts` — `RecoveryRecipe` / `RecoveryStrategy` type
+- `packages/core/src/recovery-registry.ts` — Registry 實作與預設 recipe
+- `packages/core/src/orchestrator.ts` — fix loop 前查詢 Registry
+
+### VibeOps
+
+- `src/types/index.ts` — 獨立定義 `RecoveryRecipe`（AGPL 隔離）
+- `src/runner/recovery-registry.ts` — 獨立實作
+- `recovery-recipes.yaml` — 預設 recipe 配置

package/bundled/locales/zh-TW/core/retry-standards.md

@@ -0,0 +1,140 @@
+---
+source: ../../../core/retry-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 重試策略標準
+
+> **語言**: [English](../../../core/retry-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-17
+**狀態**: Trial（到期 2026-10-17）
+**適用範圍**: universal
+**來源**: XSPEC-067（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+重試策略標準：指數退避加抖動、重試上限、依 failure-source 分類的重試規則。
+
+延伸既有 circuit-breaker 與 failure-source-taxonomy，補齊 retry 層的標準化規則。避免各元件各自實作重試造成行為不一致（無上限重試、無 jitter 導致 thundering herd）。
+
+---
+
+## 核心規範
+
+- 所有重試邏輯必須使用 exponential + jitter，禁止固定間隔或無 jitter 的純指數
+- 重試必須有明確上限（`max_attempts`），禁止無限重試
+- 重試決策必須先參考 failure-source-taxonomy 分類，fail-fast 類別不得重試
+- 重試必須與 circuit-breaker 整合：OPEN 狀態下不得重試，直接 fail-fast
+- 每次重試都應透過遙測事件上報（`retry_attempted` / `retry_exhausted`）
+
+---
+
+## 退避公式
+
+**Exponential with full jitter**：
+
+```
+wait_ms = min(cap_ms, base_ms * 2^attempt) * (0.5 + random() * 0.5)
+```
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `base_ms` | `100` | 基底等待時間 |
+| `cap_ms` | `30000` | 等待時間上限 |
+| `max_attempts` | `5` | 最大重試次數 |
+| `jitter_ratio` | `0.5` | ±50% 抖動 |
+
+**理由**：
+- Exponential 隨重試次數指數退避，避免短時間大量請求
+- Jitter ±50% 避免 thundering herd（所有 client 同時重試）
+- cap_ms=30s 避免超長等待，與典型 request timeout 對齊
+
+---
+
+## 依 failure-source 的重試規則
+
+| 失敗來源 | 可重試 | max_attempts | base_ms | 備註 |
+|---------|--------|-------------|---------|------|
+| `transient_network` | ✅ | 5 | 100 | 短暫網路抖動，指數退避通常可恢復 |
+| `rate_limit` | ✅ | 3 | 1000 | 底數加大預留額度恢復時間；優先採用 Retry-After header |
+| `upstream_unavailable` | ✅ | 3 | 500 | 重試前先查 circuit-breaker |
+| `tool_failure` | ✅ | 2 | 200 | 工具層失敗通常非 transient，僅給 2 次機會 |
+| `prompt_delivery` | ✅ | 2 | 100 | 超過 2 次改走 model_switch |
+| `authentication` | ❌ | — | — | fail-fast；憑證錯誤重試不會變對 |
+| `validation` | ❌ | — | — | fail-fast；input 錯誤重試結果不變 |
+| `policy_violation` | ❌ | — | — | fail-fast；安全決策禁止繞過 |
+| `quota_exhausted` | ❌ | — | — | fail-fast；等 budget reset 或升級 tier |
+
+---
+
+## 與 circuit-breaker 整合
+
+| 規則 | 說明 |
+|------|------|
+| Rule 1 | 每次重試前檢查對應 breaker 的 state；若為 OPEN 立即回傳 `CircuitOpenError`，不消耗 `max_attempts` |
+| Rule 2 | 重試全部耗盡（`retry_exhausted`）計入 breaker 的 failure count |
+| Rule 3 | HALF_OPEN 狀態下僅允許 1 次探針重試，不套用 `max_attempts` |
+
+---
+
+## 遙測事件
+
+**`retry_attempted`**（每次重試前上傳，第 0 次原始呼叫不算）
+
+| 欄位 | 類型 |
+|------|------|
+| `operation` | `string` |
+| `attempt` | `number` |
+| `max_attempts` | `number` |
+| `failure_source` | `FailureSource \| null` |
+| `wait_ms` | `number` |
+
+**`retry_exhausted`**（達到 max_attempts 仍失敗時上傳）
+
+| 欄位 | 類型 |
+|------|------|
+| `operation` | `string` |
+| `attempts` | `number` |
+| `final_failure_source` | `FailureSource` |
+
+---
+
+## 情境範例
+
+**情境 1：指數退避計算**
+- 條件：呼叫下游 API 失敗，failure_source=transient_network，已重試 2 次
+- 第 3 次重試等待時間：`min(30000, 100 * 2^3) * [0.5..1.0] = 400~800ms`
+
+**情境 2：authentication fail-fast**
+- 條件：API 回傳 401，failure_source=authentication
+- 結果：立即 fail-fast，不進入退避，不計入 circuit-breaker failure count
+
+**情境 3：circuit OPEN 跳過重試**
+- 條件：對應 breaker 為 OPEN，cooldown 剩 15s
+- 結果：立即回傳 CircuitOpenError，不消耗 max_attempts
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `RETRY-001` | `RETRY_EXHAUSTED` — 達到 max_attempts 仍失敗 |
+| `RETRY-002` | `RETRY_SKIPPED_NON_RETRYABLE` — failure_source 屬 fail-fast 類別 |
+| `RETRY-003` | `RETRY_SKIPPED_CIRCUIT_OPEN` — breaker OPEN 狀態下跳過重試 |
+
+---
+
+## 相關標準
+
+- [circuit-breaker.md](circuit-breaker.md) — OPEN 狀態下禁止重試
+- [failure-source-taxonomy.md](failure-source-taxonomy.md) — 依 failureSource 決定 retry/fail-fast
+- [timeout-standards.md](timeout-standards.md) — 單次重試 timeout 不得超過剩餘 deadline
+- [recovery-recipe-registry.md](recovery-recipe-registry.md) — retry 耗盡後交棒給 recovery recipe

package/bundled/locales/zh-TW/core/security-decision.md

@@ -0,0 +1,120 @@
+---
+source: ../../../core/security-decision.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 安全決策標準
+
+> **語言**: [English](../../../core/security-decision.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-15
+**適用範圍**: 所有多來源安全決策仲裁場景
+**Scope**: universal
+**來源**: XSPEC-037（claude-code-book Ch.4 deny>ask>allow pipeline）
+
+---
+
+## 目的
+
+安全決策鐵律：`deny > ask > allow` 三態優先級仲裁。
+
+多來源安全決策的仲裁規則：`deny` 永遠勝出，無論來源優先級。三態語義（deny / ask / allow）比布林值更精確，支援「需使用者確認」的中間狀態。
+
+---
+
+## 核心規範
+
+- 所有安全決策仲裁必須遵循 `deny > ask > allow` 優先級，無例外
+- `deny` 的勝出不受規則來源優先級影響（低優先級的 deny 可以覆蓋高優先級的 allow）
+- `ask` 狀態在 CI / 無人值守模式下必須等同 `deny`（無法互動確認）
+- 決策結果必須記錄來源規則列表（可追蹤性）
+- `projectSettings` 來源的安全提升操作必須被拒絕（信任半徑保護）
+
+---
+
+## 三態決策類型
+
+| 決策 | 優先級 | 描述 |
+|------|--------|------|
+| `deny` | 1（最高） | 明確拒絕，立即阻止操作。任何來源的 deny 都使最終決策為 deny |
+| `ask` | 2 | 需要使用者確認才能繼續。CI 模式下等同 deny（無法互動） |
+| `allow` | 3（最低） | 允許操作繼續。所有規則都為 allow 時才能執行 |
+
+---
+
+## 仲裁規則
+
+```typescript
+function arbitrate(rules: SecurityDecisionRule[]): SecurityDecision {
+  if (rules.some(r => r.decision === "deny")) return "deny";
+  if (rules.some(r => r.decision === "ask")) return "ask";
+  return "allow";
+}
+```
+
+**不變式**：`deny` 勝出不受 `source` 優先級影響。
+
+---
+
+## 介面定義
+
+### SecurityDecision
+
+```
+deny | ask | allow
+```
+
+### SecurityDecisionRule
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `source` | `string` | 規則來源（user / project / policy / builtin） |
+| `decision` | `SecurityDecision` | 決策值 |
+| `reason` | `string`（可選） | 用於日誌和使用者說明 |
+
+### SecurityDecisionResult
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `final_decision` | `SecurityDecision` | 最終決策 |
+| `winning_rules` | `SecurityDecisionRule[]` | 觸發最終決策的規則 |
+| `all_rules` | `SecurityDecisionRule[]` | 所有評估的規則（審計用） |
+| `ci_mode_override` | `boolean` | `true` 時 ask → deny |
+
+---
+
+## 信任半徑保護
+
+`projectSettings` 在安全敏感操作中被排除（防止惡意 repo 注入）。
+
+**被阻擋的操作**：
+
+- 將 `requiresUserConfirmation` 設為 `false`
+- 記憶體路徑重定向到專案目錄外（如 `~/.ssh`）
+- 工具白名單擴充超出 `userSettings` 允許的範圍
+- 安全規則降級（deny → allow）
+
+拒絕時記錄 `warn` 等級日誌：`[WARN] projectSettings security override rejected: {operation}`
+
+---
+
+## 適用組件
+
+- DevAP Safety Hook
+- VibeOps CommandPolicy
+- VibeOps Governance Framework（SPEC-049）
+- 任何多來源規則合併的安全仲裁場景
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `SD-001` | `SECURITY_DENIED` — deny 決策，操作被阻止 |
+| `SD-002` | `SECURITY_ASK_CI` — ask 在 CI 模式下被視為 deny |
+| `SD-003` | `TRUST_RADIUS_VIOLATION` — projectSettings 嘗試安全提升，已拒絕 |