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

package/bundled/locales/zh-TW/core/skill-standard-alignment-check.md

@@ -0,0 +1,112 @@
+---
+source: ../../../core/skill-standard-alignment-check.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# Skill-Standard 對齊檢查標準
+
+> **語言**: [English](../../../core/skill-standard-alignment-check.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-17
+**狀態**: Trial（到期 2026-10-17）
+**適用範圍**: universal
+**來源**: XSPEC-070（DEC-043 Wave 1 治理 Meta 套件）
+
+---
+
+## 目的
+
+Skill 必有 Standard 作為錨點，Standard 可無 Skill；定期識別孤兒 Skill。
+
+Skill 是 UX 糖衣，Standard 是 standards-of-truth。若 Skill 無錨定 Standard，其行為就沒有明文依據，會隨作者口味飄移。本標準規範 Skill 必須指明錨定哪個 Standard，並定期識別「孤兒 Skill」（無對應 Standard），觸發補 Standard 的流程。反向允許 Standard 無 Skill（不強制每個 Standard 都造 Skill）。
+
+---
+
+## 核心規範
+
+- 所有 Skill 必須在 frontmatter 指明 `anchor_standard`（至少一個）
+- `anchor_standard` 必須指向 Trial / Active / Deprecated 狀態的標準 id
+- Skill 無 `anchor_standard` 視為 orphan，必須在下一版補上或降級為 Proposed
+- Standard 無對應 Skill 是合法的（Standard 可獨立存在，Skill 僅為 UX 加速）
+- 定期（建議季度）執行 alignment check，產出 orphan Skill 清單
+
+---
+
+## 對齊規則
+
+### Skill 必須有 Standard
+
+- **規則**：Skill 的 frontmatter 必須包含 `anchor_standard` 欄位
+- **格式**：`anchor_standard: <standard-id>` 或 `[<standard-id-1>, <standard-id-2>, ...]`
+- **強制執行**：CI / pre-release check，缺欄位視為 fail
+- **例外**：純 utility Skill（如 docs-generator）可標記 `anchor_standard: none` + 填 `utility_reason`
+
+### Standard 不必有 Skill
+
+- **規則**：Standard 是否有對應 Skill 不強制
+- **理由**：Standard 是 standards-of-truth，可被 QualityGate / Agent 直接消費；強制每 Standard 都造 Skill 會導致 Skill 庫膨脹
+- **範例**：`immutability-first` 標準無對應 Skill — 合法
+
+### 孤兒 Skill 偵測
+
+- 沒有 `anchor_standard` 的 Skill 視為 orphan
+- **偵測後行動**：
+  1. 列入季度報告
+  2. 建立對應 Standard 的 XSPEC（循 admission-criteria 流程）
+  3. 若無法建立 Standard，降 Skill 為 Proposed 直到有錨點
+
+---
+
+## 2026-04 已知孤兒 Skill 清單
+
+| Skill ID | 所需 Standard |
+|----------|--------------|
+| `slo-assistant` | slo-standards（XSPEC-063 規劃中） |
+| `runbook-assistant` | runbook-standards（XSPEC-064 規劃中） |
+| `incident-response-assistant` | incident-response-standards（XSPEC-063 規劃中） |
+| `observability-assistant` | observability-standards（XSPEC-063 規劃中） |
+| `metrics-dashboard-assistant` | metrics-dashboard-standards（XSPEC-063 規劃中） |
+| `ci-cd-assistant` | ci-cd-standards（XSPEC-066 規劃中） |
+
+清單將隨 XSPEC-063~069 實作逐步清空。
+
+---
+
+## 對齊檢查工作流程
+
+1. 掃描 `skills/**/*.md` 抽取 frontmatter `anchor_standard`
+2. 掃描 `ai/standards/*.ai.yaml` 抽取所有 `standard.id`
+3. 計算差集：Skill without anchor_standard → orphan 清單
+4. 計算反向差集：Standard without Skill → informational（非錯誤）
+5. 若 `anchor_standard` 指向不存在的 id 或已 Archived 的 id → 錯誤
+6. 輸出 `alignment-report.json` / `alignment-report.md`（含 orphan 清單、broken anchor 清單）
+
+---
+
+## 遙測事件
+
+**`alignment_check_run`**
+
+| 欄位 | 類型 |
+|------|------|
+| `total_skills` | `number` |
+| `total_standards` | `number` |
+| `orphan_skills_count` | `number` |
+| `broken_anchors_count` | `number` |
+| `standalone_standards_count` | `number` |
+| `timestamp` | `string` |
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `ALIGN-001` | `SKILL_MISSING_ANCHOR` — Skill frontmatter 缺 anchor_standard |
+| `ALIGN-002` | `BROKEN_ANCHOR` — anchor_standard 指向不存在的 standard id |
+| `ALIGN-003` | `ARCHIVED_ANCHOR` — anchor_standard 指向已 Archived 的標準 |
+| `ALIGN-004` | `UTILITY_MISSING_REASON` — utility Skill 標 anchor_standard=none 但缺 utility_reason |

package/bundled/locales/zh-TW/core/standard-admission-criteria.md

@@ -0,0 +1,104 @@
+---
+source: ../../../core/standard-admission-criteria.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 標準納入條件
+
+> **語言**: [English](../../../core/standard-admission-criteria.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-17
+**狀態**: Trial（到期 2026-10-17）
+**適用範圍**: universal
+**來源**: XSPEC-070（DEC-043 Wave 1 治理 Meta 套件）
+
+---
+
+## 目的
+
+新標準納入 UDS 的四項條件。在 DEC-043 提出 60+ 候選新標準的背景下，需要一個明文的納入檢查清單，避免標準庫膨脹（重疊、未使用）與降低品質。本標準是 UDS 的治理層 meta 標準 — 用來「決定標準的標準」。每個候選新標準必須通過四項條件才能從 Proposed 進入 Trial。
+
+---
+
+## 核心規範
+
+- **四項硬性條件**：所有候選新標準必須同時通過 Evidence / Scope / Non-overlapping / AI-executable
+- **拒絕理由必須具體**：不得以「不合適」之類籠統用詞結案，必須指出未通過的 criterion
+- **Admission ≠ Active**：通過 admission 僅代表可進 Trial，不代表直接 Active
+- **Self-applicability**：本標準也必須符合四項條件
+- **Backward compat**：既有 66 個 Active 標準不溯及既往
+
+---
+
+## 四項條件
+
+### 1. Evidence（具體場景）
+
+至少 2 個具體使用場景（非 hypothetical）：
+
+- 場景來自實際專案、Repo、論文或 DEC 記錄
+- 描述具體（可舉出檔案 / 函式 / commit）
+- 至少 1 個來自 AsiaOstrich 內部痛點或外部產業佐證
+
+**拒絕範例**：「未來可能用到」— 無具體場景
+
+### 2. Scope（明確作用域）
+
+- `meta.scope` 標示 `universal` / `partial` / `uds-specific`
+- frontmatter 列出適用的活動類型（development / deployment / testing）
+- 若為 partial 或 uds-specific，說明不通用的原因
+
+**拒絕範例**：「所有場合都適用」— 過度泛化
+
+### 3. Non-overlapping（無重大重疊）
+
+與既有 UDS 標準內容重複 < 30%：
+
+- 列出最接近的 3 個既有標準，說明差異
+- 若有 ≥ 30% 重疊，應改為擴充既有標準
+- 明確定義 `integration_points`
+
+**拒絕範例**：與 `retry-standards` 80% 內容重複 — 應合併
+
+### 4. AI-executable（AI 可消費）
+
+至少一個 DevAP QualityGate / VibeOps Agent prompt / Skill 能消費：
+
+- 定義清楚的 guidelines（每條可驗證）
+- 至少 2 個 Given-When-Then scenarios
+- 需型別時提供 interface / types 區塊
+- 明確的 `integration_points`
+
+**拒絕範例**：只有抽象原則，無任何 AI 可執行的規則
+
+---
+
+## 拒絕協議
+
+1. 拒絕理由必須指出未通過的 criterion（evidence / scope / non-overlapping / ai-executable）
+2. 拒絕記錄寫入 `cross-project/decisions/` 或 DEC 的 rejection log
+3. 候選者可依理由修正後重新申請（不永久封鎖）
+4. 若拒絕理由涉及重疊，應建議改為擴充既有標準
+
+---
+
+## 情境範例
+
+- **情境 1 — 通過**：`retry-standards` 申請。Evidence（XSPEC-067 Scenario 1-1/1-2）、Scope（universal）、Non-overlapping（與 circuit-breaker 互補）、AI-executable（9 guidelines + 3 scenarios）全通過 → 進入 Trial
+- **情境 2 — 因重疊拒絕**：`advanced-retry-with-jitter` 申請。與 `retry-standards` 重疊 > 30% → 拒絕，建議改為 Phase 2 擴充
+- **情境 3 — 因證據不足拒絕**：`universal-best-practices` 申請。僅「未來可能用到」類描述 → 拒絕，要求至少 2 個已發生案例
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `ADMISSION-001` | `MISSING_EVIDENCE` — 未提供至少 2 個具體使用場景 |
+| `ADMISSION-002` | `SCOPE_UNDEFINED` — 未定義 meta.scope 或適用活動類型 |
+| `ADMISSION-003` | `OVERLAP_EXCEEDED` — 與既有標準重疊 > 30% |
+| `ADMISSION-004` | `NOT_AI_EXECUTABLE` — 無任何 AI 可消費的規則或 scenarios |

package/bundled/locales/zh-TW/core/standard-lifecycle-management.md

@@ -0,0 +1,116 @@
+---
+source: ../../../core/standard-lifecycle-management.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 標準生命週期管理
+
+> **語言**: [English](../../../core/standard-lifecycle-management.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-17
+**狀態**: Trial（到期 2026-10-17）
+**適用範圍**: universal
+**來源**: XSPEC-070（DEC-043 Wave 1 治理 Meta 套件）
+
+---
+
+## 目的
+
+UDS 標準生命週期狀態機。既有 66 個標準無明確狀態管理：新增標準沒有試驗期、過時標準無棄用路徑、廢棄標準仍被引用。本標準建立五狀態機（Proposed / Trial / Active / Deprecated / Archived）與合法轉移規則，並規範所有 `.ai.yaml` 標準必須在 frontmatter 標示 `status` / `since` / `expires` / `supersedes`。
+
+---
+
+## 核心規範
+
+- **所有標準必有狀態**：frontmatter 必須包含 `status` 和 `since`
+- **Trial 必有期限**：`expires` 預設 since + 6 months
+- **Deprecated 必有替代**：`supersedes` 指向替代標準 id 或遷移文件
+- **禁止反向轉移**：Active → Proposed、Archived → Active 均無意義
+- **逾期自動 Archived**：Trial 到期未決則自動歸檔
+
+---
+
+## 狀態說明
+
+| 狀態 | 描述 | Skill 可引用？ |
+|------|------|--------------|
+| **Proposed** | 草案階段，未通過 admission | 不可 |
+| **Trial** | 批准但試驗中（預設 6 個月） | 可（標註 trial）|
+| **Active** | 全面採用，standard-of-truth | 可 |
+| **Deprecated** | 標記棄用，必須提供 `supersedes` | 可（Skill 應警示）|
+| **Archived** | 已移除，僅保留歷史 | 不可 |
+
+---
+
+## 合法轉移路徑
+
+```
+Proposed ──(通過 admission)──→ Trial
+Trial    ──(驗證通過)─────────→ Active
+Trial    ──(到期/拒絕)─────────→ Archived
+Active   ──(被取代)───────────→ Deprecated
+Deprecated ──(遷移完成)────────→ Archived
+```
+
+**禁止的轉移**：
+
+- Active → Proposed（無意義）
+- Archived → Active（應重新申請 admission）
+- Deprecated → Active（應重新 Trial）
+- Proposed → Active（須先 Trial）
+
+---
+
+## Frontmatter 必填欄位
+
+### 必填（所有狀態）
+
+- `status`: proposed | trial | active | deprecated | archived
+- `since`: ISO-8601（進入當前狀態的日期）
+- `version`: semver 字串
+
+### 條件必填
+
+| 欄位 | 適用時機 |
+|------|---------|
+| `expires` | `status = trial`（預設 since + 6 months）|
+| `supersedes` | `status = deprecated`（替代標準 id 或遷移文件路徑）|
+| `migration_guide` | `status = deprecated`（相對路徑，選填但強烈建議）|
+
+---
+
+## 情境範例
+
+- **情境 1 — Trial → Active**：`retry-standards` 處於 trial。2026-08-01 審視發現 DevAP Fix Loop 和 VibeOps Builder 均採用且無重大缺陷 → 轉 Active，`since=2026-08-01`，移除 `expires`
+- **情境 2 — Trial 逾期自動 Archived**：某標準 trial 期限 2026-10-17 到期未通過驗證 → 狀態轉 Archived，記錄原因
+- **情境 3 — Deprecated 帶遷移**：`legacy-retry-logic` 被 `retry-standards` 取代 → `status=deprecated, supersedes=retry-standards, migration_guide=docs/migrations/retry-v1-to-v2.md`；Skill 使用時顯示警告
+
+---
+
+## 遙測事件
+
+**`standard_state_change`**
+
+| 欄位 | 類型 |
+|------|------|
+| `standard_id` | `string` |
+| `from_state` | `proposed\|trial\|active\|deprecated\|archived` |
+| `to_state` | `proposed\|trial\|active\|deprecated\|archived` |
+| `reason` | `string` |
+| `timestamp` | `ISO-8601` |
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `LIFECYCLE-001` | `MISSING_STATUS` — frontmatter 缺 status 欄位 |
+| `LIFECYCLE-002` | `MISSING_EXPIRES` — trial 狀態缺 expires 欄位 |
+| `LIFECYCLE-003` | `MISSING_SUPERSEDES` — deprecated 狀態缺 supersedes 欄位 |
+| `LIFECYCLE-004` | `FORBIDDEN_TRANSITION` — 嘗試執行禁止的狀態轉移 |
+| `LIFECYCLE-005` | `TRIAL_EXPIRED` — trial 到期未決策 |

package/bundled/locales/zh-TW/core/test-governance.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/test-governance.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-03-24
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-04-20
 status: current
 ---
 
@@ -81,6 +81,17 @@ status: current
 | Staging | 整合和 E2E 測試 | DevOps |
 | Production | 煙霧測試和監控 | SRE |
 
+## 規則
+
+| ID | 觸發時機 | 指令 | 優先度 |
+|----|---------|------|--------|
+| enforce-completion-criteria | 完成任務或功能時 | 在將任務/功能標記為完成前，驗證所有必要的完成準則已達成 | 必須 |
+| pyramid-compliance | 規劃測試策略時 | 以 70/20/7/3 金字塔比例為指引。可接受偏差，但需有文件記錄的正當理由 | 必須 |
+| sit-isolation | 執行系統測試時 | 系統測試應對外部相依性使用 Stub，但使用真實的內部服務。使用 SIT 環境進行系統層級的驗證 | 建議 |
+| test-execution-continuity | 新增或完成測試案例時 | 測試案例必須連接到自動化執行觸發器（CI gate、build hook 或排程執行）。存在但從未執行的測試提供假信心，比沒有測試更糟。在將測試覆蓋率標記為完成前，請確認執行歷程存在。| 必須 |
+
+---
+
 ## 相關標準
 
 - [測試標準](testing-standards.md)

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

@@ -1,3 +1,11 @@
+---
+source: ../../../core/testing-standards.md
+source_version: 3.2.0
+translation_version: 3.2.0
+last_synced: 2026-04-20
+status: current
+---
+
 # 測試標準
 
 > **Language**: [English](../../../core/testing-standards.md) | 繁體中文
@@ -231,6 +239,29 @@
 e2e/[feature]/[scenario].[ext]
 ```
 
+#### E2E 前置條件範圍（e2e-precondition-scope）
+
+E2E 環境前置檢查（`globalSetup`、`beforeAll`）必須驗證**所有受測頁面與端點**的健康狀態，而非僅驗證認證入口點。
+
+**反模式** — 只驗 login：
+```ts
+// ❌ 即使功能頁回傳 500 也會通過
+await page.goto('/login');
+expect(response.status()).toBe(200);
+```
+
+**正確模式** — 明確的覆蓋清單：
+```ts
+// ✅ 驗證套件涵蓋的所有頁面
+const PAGES_UNDER_TEST = ['/login', '/dashboard', '/feature-x'];
+for (const path of PAGES_UNDER_TEST) {
+  const res = await fetch(`${BASE_URL}${path}`);
+  expect(res.status).toBeLessThan(500); // 遇到 5xx 立即失敗
+}
+```
+
+> **證據**：真實事故 — E2E `globalSetup` 只驗了 `Login.aspx`；功能頁靜默回傳 HTTP 500。整個 E2E 套件通過，提供假信心，直到正式環境崩潰才被發現。
+
 ---
 
 ## 測試替身

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

@@ -0,0 +1,117 @@
+---
+source: ../../../core/timeout-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# Timeout 標準
+
+> **語言**: [English](../../../core/timeout-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-17
+**狀態**: Trial（到期 2026-10-17）
+**適用範圍**: universal
+**來源**: XSPEC-067（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+Timeout 標準：層級預算（cascading 0.8×）、deadline propagation、與 circuit-breaker 整合。
+
+避免多層呼叫鏈中下層 timeout 大於上層（導致上層先 timeout 而下層仍在執行的資源浪費）。透過 cascading 預算規則（每層 ≤ 0.8× 上層）與 deadline propagation（傳 absolute timestamp）讓整條呼叫鏈都能精準 fail-fast。
+
+---
+
+## 核心規範
+
+- 多層呼叫的 timeout 必須逐層遞減，每下一層 ≤ 0.8 × 上層（預留 20% buffer）
+- 跨服務呼叫必須傳遞 deadline（absolute timestamp），不得只傳 relative duration
+- 收到請求後若 `now > deadline`，必須立即 fail-fast，禁止發起下游呼叫
+- Timeout 觸發必須計入對應 circuit-breaker 的 failure count
+- 禁止下層 timeout 大於上層 timeout（違反 fail-fast，等同沒設 timeout）
+
+---
+
+## Cascading 預算規則
+
+**規則**：每下一層 timeout ≤ 0.8 × 上層 timeout
+
+**範例**（Client timeout=10s，呼叫鏈 Client → Gateway → Service A → DB）：
+
+| 層級 | timeout |
+|------|---------|
+| Client | 10,000ms |
+| Gateway | 8,000ms（10000 × 0.8） |
+| Service A | 6,400ms（8000 × 0.8） |
+| DB | 5,120ms（6400 × 0.8） |
+
+**理由**：
+- 預留 20% buffer 給序列化、網路傳輸、重試等開銷
+- 避免上層先 timeout 而下層仍在執行（資源浪費）
+- 0.8 是業界經驗值（gRPC / Envoy 常用 0.7~0.85）
+
+---
+
+## Deadline Propagation
+
+| 欄位 | 值 |
+|------|-----|
+| 格式 | absolute ISO-8601 timestamp（非 relative duration） |
+| Header 名稱 | `X-Deadline` |
+
+**規則**：
+1. 發起呼叫前計算 `deadline = now + timeout`，寫入 header
+2. 收到請求後立即檢查 `now > deadline_header` → 若是則 fail-fast（回 `DEADLINE_EXCEEDED`）
+3. 向下游呼叫時 `timeout = min(cascading_budget, deadline - now)`，取兩者較小
+
+**理由**：Relative duration（如 timeout=5s）無法在多層呼叫中累積扣除；absolute timestamp 讓每一層都能精準計算剩餘時間。
+
+---
+
+## Timeout 類型
+
+| 類型 | 預設值 | 說明 |
+|------|--------|------|
+| `connect_timeout` | 5,000ms | 建立 TCP / TLS 連線的時間上限 |
+| `request_timeout` | 30,000ms | 發送請求到收到完整回應的時間上限；受 cascading 預算約束 |
+| `idle_timeout` | 60,000ms | 連線閒置多久後關閉；server 端設定 |
+| `total_deadline` | 60,000ms | 含所有重試在內的整體上限；retry × attempt_timeout 總和不得超過此值 |
+
+---
+
+## 與 circuit-breaker 整合
+
+| 規則 | 說明 |
+|------|------|
+| Rule 1 | 每次 timeout 觸發視為一次失敗，計入 breaker 的 failure count |
+| Rule 2 | 連續 timeout 達 failureThreshold 時 breaker 進入 OPEN |
+| Rule 3 | OPEN 狀態下的請求應套用極短 timeout（或直接 fail-fast） |
+
+---
+
+## 情境範例
+
+**情境 1：cascading 預算驗證**
+- Client timeout=10s，各層依序 8s → 6.4s → 5.12s
+
+**情境 2：deadline 已過期 fail-fast**
+- 條件：請求抵達 Service A 時 X-Deadline 已過期
+- 結果：立即回 DEADLINE_EXCEEDED，不呼叫 DB
+
+**情境 3：timeout 觸發 circuit breaker**
+- 條件：連續 3 次下游呼叫皆 timeout（failureThreshold=3）
+- 結果：circuit-breaker 進入 OPEN，第 4 次立即回 CircuitOpenError
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `TIMEOUT-001` | `REQUEST_TIMEOUT` — 單次請求超時 |
+| `TIMEOUT-002` | `DEADLINE_EXCEEDED` — 整體 deadline 已過，拒絕發起／處理請求 |
+| `TIMEOUT-003` | `CASCADING_BUDGET_VIOLATION` — 下層 timeout > 上層 timeout（配置錯誤） |

package/bundled/locales/zh-TW/core/token-budget.md

@@ -0,0 +1,143 @@
+---
+source: ../../../core/token-budget.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# Token 預算區間標準
+
+> **語言**: [English](../../../core/token-budget.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-15
+**適用範圍**: 所有有 token 預算限制的 Agent 執行環境
+**Scope**: universal
+**來源**: XSPEC-036（claude-code-book Ch.7 four-zone threshold model）
+
+---
+
+## 目的
+
+Token 閾值四區模型：以使用率百分比劃分四個運作區間，漸進觸發不同強度的保護策略。
+
+比「打到上限才停」更優雅，為使用者提供早期預警和自動降級機會。
+
+---
+
+## 核心規範
+
+- 所有有 token 預算限制的執行環境必須使用四區模型監控使用率
+- WARNING 區必須記錄日誌並發出可觀測事件，不得靜默
+- DANGER 區必須觸發輕量保護策略（如截斷工具結果、縮減輸出預算）
+- BLOCKING 區必須拒絕新請求，回傳 `TOKEN_BUDGET_EXCEEDED` 而非讓請求超時崩潰
+- 壓縮操作本身需保留足夠的輸出空間（否則壓縮本身也可能失敗）
+
+---
+
+## 四區模型
+
+| 區間 | 使用率範圍 | 行動 | 日誌等級 |
+|------|----------|------|---------|
+| **SAFE**（安全） | 0% – 84% | 正常執行 | — |
+| **WARNING**（警告） | 85% – 89% | 發出 `TOKEN_BUDGET_WARNING` 事件，通知 Coordinator／使用者 | `info` |
+| **DANGER**（危險） | 90% – 94% | 觸發輕量壓縮策略 | `warn` |
+| **BLOCKING**（阻塞） | 95% – 100% | 拒絕新請求，回傳 `TOKEN_BUDGET_EXCEEDED` | `error` |
+
+### WARNING 區可選行動
+
+- 降低 `model_tier`（capable → standard）
+- 提示使用者考慮分割任務
+
+### DANGER 區必要行動
+
+- 截斷超大工具結果（Tool Result Snip）
+- 縮減後續 Agent 的 `maxToolRounds`（建議降低 20%）
+
+### DANGER 區可選行動
+
+- 將重要輸出持久化到磁碟，上下文只保留摘要
+
+---
+
+## 閾值常數
+
+| 常數 | 值 |
+|------|-----|
+| `WARNING_THRESHOLD` | `0.85` |
+| `DANGER_THRESHOLD` | `0.90` |
+| `BLOCKING_THRESHOLD` | `0.95` |
+
+---
+
+## 類型定義
+
+### TokenBudgetZone
+
+```
+safe | warning | danger | blocking
+```
+
+### TokenBudgetStatus
+
+| 欄位 | 類型 |
+|------|------|
+| `current_tokens` | `number` |
+| `max_tokens` | `number` |
+| `usage_ratio` | `number` |
+| `zone` | `TokenBudgetZone` |
+
+### TokenBudgetExceededError
+
+| 欄位 | 類型 |
+|------|------|
+| `code` | `"TOKEN_BUDGET_EXCEEDED"` |
+| `current_tokens` | `number` |
+| `max_tokens` | `number` |
+| `usage_ratio` | `number` |
+| `zone` | `"blocking"` |
+
+---
+
+## 壓縮後預算常數參考
+
+| 常數 | 值 |
+|------|-----|
+| `MAX_FILES_TO_RESTORE` | `5` |
+| `TOTAL_TOKEN_BUDGET` | `50000` |
+| `MAX_TOKENS_PER_FILE` | `5000` |
+| `MAX_TOKENS_PER_SKILL` | `5000` |
+
+---
+
+## 遙測事件
+
+**`token_budget_zone_change`**
+
+| 欄位 | 類型 |
+|------|------|
+| `from_zone` | `TokenBudgetZone` |
+| `to_zone` | `TokenBudgetZone` |
+| `usage_ratio` | `number` |
+| `agent_name` | `string` |
+| `timestamp` | `string` |
+
+---
+
+## 適用場景
+
+- DevAP 任務執行（Task token 預算監控）
+- VibeOps 9-Agent Pipeline（跨 Agent 累積上下文監控）
+- VibeOps PipelineMemory Snip 觸發條件
+- 任何有 `maxTotalTokens` 限制的 Agent 執行環境
+
+---
+
+## 錯誤碼
+
+| 代碼 | 說明 |
+|------|------|
+| `TB-001` | `TOKEN_BUDGET_EXCEEDED` — 已進入 BLOCKING 區，拒絕新請求 |
+| `TB-002` | `TOKEN_BUDGET_WARNING` — 已進入 WARNING 區，建議採取行動 |
+| `TB-003` | `SNIP_FAILED` — 輕量壓縮失敗，仍在 DANGER 區 |