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

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/packaging-standards.md

@@ -0,0 +1,224 @@
+---
+source: ../../../core/packaging-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-15
+status: current
+---
+
+# 打包標準
+
+> **語言**: [English](../../../core/packaging-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-15
+**適用性**: 使用 UDS/DevAP 工具鏈的專案
+**範圍**: 通用 (Universal)
+
+---
+
+## 目的
+
+本標準定義一套基於 Recipe 的打包框架，讓使用者專案可在 `.devap/packaging.yaml` 中宣告打包目標（target）。UDS 負責提供 Recipe 定義與內建 Recipe 函式庫；DevAP 則在 pipeline 中執行編排。
+
+框架的關注點分離如下：
+- **使用者專案**：宣告「打包什麼」（targets + 設定覆蓋）
+- **UDS**：定義「如何打包」（Recipe 結構 + 內建 Recipes）
+- **DevAP**：執行「何時打包」（在 Review 與 Deploy 之間的 pipeline 階段）
+
+---
+
+## 核心原則
+
+| 原則 | 說明 |
+|------|------|
+| **Recipe-based** | 每個打包目標都參照一個具名 Recipe；不在 pipeline YAML 中撰寫臨時腳本 |
+| **宣告式 targets** | 專案在 `.devap/packaging.yaml` 中宣告 targets；DevAP 負責解析與執行 |
+| **可客製化** | 四個客製化層允許設定覆蓋、Hook 注入、自訂 Recipe 及 Escape Hatch |
+| **整合至 Pipeline** | 打包作為獨立階段運行於 VibeOps pipeline 的 Review 與 Deploy 之間 |
+
+---
+
+## Recipe 結構
+
+Recipe 是定義如何打包專案的 YAML 檔案，欄位定義如下：
+
+```yaml
+# Recipe: <name>.yaml
+name: <string>            # 必填 — 唯一識別符（kebab-case）
+description: <string>     # 選填 — 人類可讀描述
+requires:                 # 選填 — 執行前必須存在的檔案
+  - <file-path>
+steps:                    # 必填 — 有序的建置/打包步驟清單
+  - run: <shell-command>
+    description: <string> # 選填 — 步驟描述
+config:                   # 選填 — 預設設定值（可被使用者專案覆蓋）
+  <key>: <value>
+hooks:                    # 選填 — 生命週期 hooks（~ 表示不執行）
+  preBuild: ~
+  postBuild: ~
+  prePublish: ~
+  postPublish: ~
+```
+
+### 必填與選填欄位
+
+| 欄位 | 必填 | 說明 |
+|------|------|------|
+| `name` | 是 | 唯一識別符，kebab-case 格式 |
+| `steps` | 是 | 至少需要一個步驟 |
+| `description` | 否 | 人類可讀描述 |
+| `requires` | 否 | 前置條件檔案檢查 |
+| `config` | 否 | 預設設定值；所有 key 均可被使用者專案覆蓋 |
+| `hooks` | 否 | 生命週期 hook 插入點；`~` 表示不執行 |
+
+### 步驟變數
+
+設定值與執行時期情境可在 `run` 指令中使用 `{variable}` 占位符：
+
+| 變數 | 來源 | 範例 |
+|------|------|------|
+| `{registry}` | `config.registry` | `ghcr.io` |
+| `{name}` | `package.json#name` 或 `config.name` | `my-app` |
+| `{version}` | `package.json#version` 或 `config.version` | `1.2.3` |
+| `{platforms}` | `config.platforms` | `linux/amd64,linux/arm64` |
+| `{output_dir}` | `config.output_dir` | `dist/installers` |
+
+---
+
+## 內建 Recipes
+
+UDS 隨附四個內建 Recipe，位於 `recipes/` 目錄：
+
+| Recipe | 檔案 | 使用場景 |
+|--------|------|----------|
+| `npm-library` | `recipes/npm-library.yaml` | 不含執行入口的 npm 套件 |
+| `npm-cli` | `recipes/npm-cli.yaml` | 含 `bin` 欄位的 npm 套件（CLI 工具） |
+| `docker-service` | `recipes/docker-service.yaml` | Docker 容器映像建置與推送 |
+| `windows-installer` | `recipes/windows-installer.yaml` | Windows 安裝程式（.msi / .exe）透過使用者腳本 |
+
+### 選擇 Recipe 的決策流程
+
+```
+產出物是 npm 套件嗎？
+├── 是 → package.json 是否含有 "bin" 欄位？
+│         ├── 是 → npm-cli
+│         └── 否 → npm-library
+└── 否 → 產出物是容器映像嗎？
+          ├── 是 → docker-service
+          └── 否 → 產出物是 Windows 安裝程式嗎？
+                    ├── 是 → windows-installer
+                    └── 否 → 撰寫自訂 Recipe（參見客製化層）
+```
+
+---
+
+## 客製化層
+
+需要偏離內建 Recipe 預設值的專案，應使用最低適用層：
+
+| 層級 | 機制 | 使用時機 |
+|------|------|----------|
+| **L1 — 設定覆蓋** | `.devap/packaging.yaml` 中的 `config:` 區塊 | 更改預設值（registry URL、tag、輸出目錄）|
+| **L2 — Hook 注入** | `.devap/packaging.yaml` 中的 `hooks:` 區塊 | 在建置或發佈前後執行額外指令 |
+| **L3 — 自訂 Recipe** | 專案 `.devap/recipes/` 中的新 `.yaml` 檔案 | 完全不同的建置流程；內建 Recipe 不適用 |
+| **L4 — Escape Hatch** | target 定義中以 `script:` 取代 `recipe:` | 原始 shell 腳本，無適合的 Recipe 抽象 |
+
+### L1 範例 — 設定覆蓋
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: publish-npm
+    recipe: npm-library
+    config:
+      registry: https://npm.pkg.github.com
+      access: restricted
+      tag: beta
+```
+
+### L2 範例 — Hook 注入
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: docker-push
+    recipe: docker-service
+    hooks:
+      postPush: |
+        curl -X POST https://hooks.example.com/deploy-notify \
+          -d "{\"version\": \"{version}\"}"
+```
+
+### L3 範例 — 自訂 Recipe
+
+```yaml
+# .devap/recipes/electron-app.yaml
+name: electron-app
+description: 建置 Electron 桌面應用程式
+requires:
+  - package.json
+  - electron-builder.yml
+steps:
+  - run: npm run build
+  - run: npx electron-builder --publish never
+config:
+  output_dir: dist
+```
+
+### L4 範例 — Escape Hatch
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: legacy-bundle
+    script: |
+      ./scripts/legacy-bundle.sh
+      mv output/ dist/bundle/
+```
+
+---
+
+## 打包驗收標準
+
+當以下**所有**條件均滿足時，打包執行視為**成功**：
+
+| 標準 | 閾值 | 備註 |
+|------|------|------|
+| 所有 `requires` 檔案存在 | 100% | 在任何步驟執行前檢查 |
+| 所有步驟以 exit code 0 結束 | 100% | 任何非零 exit 使執行失敗 |
+| `postBuild` 產出物存在 | 存在於預期路徑 | 建置步驟後由 DevAP 驗證 |
+| Hook 指令以 exit code 0 結束 | 100% | Hook 失敗會傳播為步驟失敗 |
+| 已發佈產出物可被取回 | HTTP 200 / registry 查詢成功 | 由 DevAP 在發佈後進行 smoke check |
+
+### 失敗處理
+
+| 失敗類型 | 行動 | 可重試？ |
+|----------|------|----------|
+| `requires` 檔案缺失 | 立即失敗，回報缺失路徑 | 否 |
+| 步驟非零 exit | 立即失敗，若已定義則執行 `postBuild` hook | 可設定（預設：否）|
+| Hook 非零 exit | 立即失敗 | 否 |
+| 發佈無法連線 | 以指數退避重試最多 3 次 | 是（3×）|
+
+---
+
+## 相關標準
+
+- [部署標準](deployment-standards.md) — 打包後的部署階段
+- [Pipeline 整合標準](pipeline-integration-standards.md) — CI/CD pipeline 設定
+- [Check-in 標準](checkin-standards.md) — 打包前的品質關卡
+- [版本控制標準](versioning.md) — 套件產出物使用的版本號
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-04-15 | 初始發行 — XSPEC-034 Phase 1 |
+
+---
+
+## 授權
+
+本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。

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