universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-TW/core/incident-response.md

@@ -0,0 +1,111 @@
+---
+source: ../../../core/incident-response.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: b1c1a516710b
+status: current
+---
+
+# 事件回應標準
+
+> **Language**: [English](../../../core/incident-response.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/incident-response.ai.yaml`
+> **規格**: XSPEC-063（cross-project/specs/XSPEC-063-uds-sre-standards-pack.md）
+
+## 概觀
+
+本標準定義端到端的**事件回應生命週期（incident response lifecycle）**：severity
+分類、回應時間 SLA、角色與職責、溝通協定、升級路徑，以及 blameless postmortem
+要求。設計目標為降低 MTTR、確保事件期間對利害關係人的一致溝通，並透過結構化
+postmortem 推動系統性可靠性改善。
+
+本標準屬於 **SRE／運維標準包**（XSPEC-063），是與 `slo-sli`（error budget 觸發）
+與 `runbook`（可執行修復步驟）並列的事件處理成員。它與
+`virtual-organization-standards` 組合——SEV-1 事件會啟動事件 virtual organization
+（IC、Communications Lead、Operations Lead）——並餵養 XSPEC-251（Operator）所述的
+主動可靠性責任。
+
+> **範圍**：本標準定義「事件如何分類、協調、溝通與學習」。paging 工具（PagerDuty、
+> Opsgenie）、status-page 產品與 ticketing 系統屬採用者的選擇，不在本標準範圍內。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | Severity 分類（4 級 SEV 量表搭配回應 SLA） | MUST |
+| REQ-002 | Incident Commander 角色（SEV-1/2 須於 10 分鐘內指派） | MUST |
+| REQ-003 | 利害關係人溝通協定（定義節奏 + status page） | MUST |
+| REQ-004 | Blameless postmortem 要求（5 Whys、action item 追蹤） | MUST |
+| REQ-005 | On-call 輪值與交接（≥2 名工程師、書面交接） | MUST |
+| REQ-006 | 事件回顧指標（MTTD/MTTR 每月檢視） | SHOULD |
+
+### REQ-001 — Severity 分類
+
+每起事件 MUST 在宣告時以 4 級 severity 量表分類。**SEV-1**（Critical）：影響所有
+使用者的完全服務中斷或資料外洩，15 分鐘內回應、通報 C-suite。**SEV-2**（High）：
+主要功能無法使用或顯著效能劣化、影響 >25% 使用者，30 分鐘內回應。**SEV-3**
+（Medium）：次要功能無法使用或影響 <25% 使用者的劣化，4 小時內回應。**SEV-4**
+（Low）：外觀問題或極輕微影響，24 小時內回應。
+
+### REQ-002 — Incident Commander 角色
+
+每起 SEV-1 與 SEV-2 事件 MUST 在宣告後 10 分鐘內指派一名 Incident Commander（IC）。
+IC 負責協調回應 bridge、指派角色（scribe、comms lead、技術 lead）、推動時間軸、
+對修復做出 go/no-go 決策，以及啟動 postmortem。IC NOT 直接進行除錯——其唯一焦點
+是協調。
+
+### REQ-003 — 利害關係人溝通協定
+
+在 SEV-1/SEV-2 事件期間，對利害關係人的更新 MUST 依定義節奏發送：宣告後 15 分鐘內
+首次通知、直到解決前每 30 分鐘更新一次，並在任何 severity 變更或重大進展時立即
+更新。更新 MUST 包含目前狀態、已知影響、正在進行的處置，以及下次更新時間。status
+page MUST 與內部溝通同步更新。
+
+### REQ-004 — Blameless Postmortem 要求
+
+每起 SEV-1 事件 MUST 在 5 個工作天內完成 blameless postmortem；SEV-2 事件則於 10 個
+工作天內。Postmortem MUST 為 blameless——聚焦系統性成因，而非個人錯誤。必備章節：
+時間軸、影響、root cause（5 Whys）、contributing factors、附負責人與到期日的 action
+item，以及 lessons learned。Action item MUST 追蹤至完成。
+
+### REQ-005 — On-Call 輪值與交接
+
+每個 production 服務 MUST 具備文件化的 on-call 輪值，至少 2 名工程師。輪值排程 MUST
+至少提前 2 週發布。On-call 交接 MUST 包含書面摘要：進行中的事件、仍在調查的近期
+事件、已知的 flaky alert、即將到來的計畫性維護，以及任何服務健康疑慮。交接 MUST
+由接班 on-call 確認接收。
+
+### REQ-006 — 事件回顧指標
+
+團隊 SHOULD 每月追蹤並檢視事件指標：MTTD（Mean Time To Detect）、MTTR（Mean Time
+To Resolve）、各 severity 的事件頻率、重複事件（90 天內相同 root cause），以及
+postmortem action-item 完成率。這些指標 SHOULD 在與工程領導層的每月可靠性檢視中
+檢討。
+
+## 與既有標準的整合
+
+- **`runbook`**——IC 與 on-call 工程師在 mitigate 階段執行 typed runbook；SEV
+  runbook 依 `runbook` 節奏演練。
+- **`slo-sli`**——error budget 燃燒常觸發事件宣告；SLO 影響於 postmortem 中摘要。
+- **`postmortem-standards`**——REQ-004 與 blameless postmortem 模板對齊；本標準
+  設定觸發條件與時程。
+- **`virtual-organization-standards`**——SEV-1 事件實例化事件 virtual organization
+  （IC、Communications Lead、Operations Lead）。
+- **`alerting-standards`**——告警啟動偵測與 severity 評估。
+- **`execution-history`**——自動化緩解動作記錄為 execution history。
+
+## 相關規格
+
+- XSPEC-063 — UDS SRE／運維標準包（本標準來源）
+- XSPEC-251 — Operator 主動可靠性（事件上游的主動責任）
+- DEC-041 — EU AI Act 2026 合規（可稽核性需要 postmortem）
+- DEC-042 — Guardian / Governance Agent 模式（agent 驅動 runbook 執行）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~006：severity 分類、incident commander、溝通協定、blameless postmortem、on-call 輪值/交接、回顧指標（XSPEC-063） |

package/bundled/locales/zh-TW/core/license-compliance.md

@@ -0,0 +1,131 @@
+---
+source: ../../../core/license-compliance.md
+source_version: 2.1.0
+translation_version: 2.1.0
+last_synced: 2026-06-10
+source_hash: 8ac1763bd1a1
+status: current
+---
+
+# 授權合規標準
+
+> **Language**: [English](../../../core/license-compliance.md) | 繁體中文
+
+> **版本**: 2.1.0 | **狀態**: Active | **更新日期**: 2026-05-16
+> **AI 最佳化版本**: `ai/standards/license-compliance.ai.yaml`
+> **Agent Spec**: ASPEC-001 (cross-project/aspec/ASPEC-001-license-compliance-agent.md)
+
+**Scope**: universal
+
+## 概述
+
+針對 AI 增強開發的完整授權合規標準，涵蓋一般 OSS 實務（Tier 1）以及針對 AI 生成程式碼的 AI 專屬規則（Tier 2）。
+
+## Tier 1 — 一般 OSS 合規實務
+
+適用於所有專案，無論是否使用 AI。
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | 授權分類與允許清單（allowlist） | MUST |
+| REQ-002 | CI 中的自動化授權掃描 | MUST |
+| REQ-003 | SBOM 產生（CycloneDX 1.5 或 SPDX 2.3） | MUST |
+| REQ-004 | 授權署名與 NOTICES 檔案 | MUST |
+| REQ-005 | 授權違規補救（5 個工作天） | MUST |
+| REQ-006 | 採用新技術時的授權審查 | SHOULD |
+
+### 授權分級
+
+| 分級 | 授權 | 動作 |
+|------|------|------|
+| APPROVED | MIT, Apache 2.0, BSD-2/3-Clause, ISC, CC0 | 自動核准 |
+| REVIEW-REQUIRED | LGPL-2.1/3.0, MPL-2.0, CDDL | 採用前須法務審查 |
+| PROHIBITED | GPL-2.0/3.0, AGPL-3.0, SSPL-1.0, BUSL-1.1 | 立即封鎖 PR |
+
+## Tier 2 — AI 專屬規則
+
+對產生程式碼的 AI Agent（VibeOps Generator Agent 及同等者）具有約束力。
+
+| ID | 規則 | 嚴重度 |
+|----|------|--------|
+| LC-001 | 必須查詢 SPDX ID | Blocking |
+| LC-002 | 封鎖清單（blocklist）自動封鎖 | Blocking |
+| LC-003 | 允許清單（allowlist）自動核准 | Informational |
+| LC-004 | 灰名單（greylist）人工審查 | Review required |
+| LC-005 | SBOM 強制產生 | Blocking |
+| LC-006 | 著作權相似度閾值（≥0.85 封鎖） | Blocking |
+| LC-007 | PII 樣式偵測 | Review required |
+| LC-008 | EU AI Act 透明度標記 | Blocking |
+| LC-009 | 客戶政策上限 | Informational |
+
+## v2.1.0 增強（XSPEC-193 Phase 2）
+
+### ClearlyDefined API（LC-001）
+
+- 主要授權查詢來源：`https://api.clearlydefined.io/definitions/{type}/{provider}/{namespace}/{name}/{revision}`
+- 知名套件的信賴度 ≥ 0.95（score.total ≥ 80）
+- 24h TTL LRU 快取（cap=500）+ 404 negative cache
+- Token bucket：10 req/s，burst 20
+- 重試策略：5xx → exponential backoff × 3（200ms/1s/3s）；429 → batch fallback
+- DEC-064 快取金鑰隔離：`sha256(client_salt + ':' + purl)`
+
+### AST PII 分析（LC-007）
+
+- Tree-sitter 支援：TypeScript、JavaScript、Python
+- 上下文分類：
+  - `hardcoded_value` → 嚴重度升級為 `critical`
+  - `comment` → 嚴重度降級為 `info`
+  - `schema_field` → 加註，嚴重度不變
+- `// pii:ignore` pragma：抑制同一行的發現
+- 選填欄位：`PIIPattern.confidence`、`PIIPattern.ast_context`
+- tree-sitter 不可用時優雅降級（graceful fallback）為 regex
+
+### EmbeddingProvider 策略（LC-006）
+
+- `provider='onnx-minilm'`：ONNX 本機推論（all-MiniLM-L6-v2）
+- `provider='ollama-bge-m3'`：Ollama 本機 API（localhost:11434）
+- `provider='jaccard'`：Jaccard token 相似度（Phase 1 基準線，預設）
+- 記憶體內 snippet 索引（`buildSnippetIndex()`）依客戶隔離（DEC-064 salt）
+- 外部搜尋：透過 `enableExternalSearch=true` opt-in（預設=false）
+
+## 原則
+
+| ID | 原則 |
+|----|------|
+| P-1 | SPDX 優先 — 所有授權 ID 必須是 SPDX 標準 |
+| P-2 | 獨立評估者 — 與 Generator 使用不同的模型類別 |
+| P-3 | 證據導向決策 — 每個封鎖都附帶可追溯的證據 |
+| P-4 | 預設透明 — 必須有 EU AI Act Article 50 標記 |
+| P-5 | 客戶主權 — 政策可在 EULA §9 限制內客製化 |
+
+## 工具序列（XSPEC-193 §2）
+
+```
+1. dependency_reader
+2. license_lookup         ← ClearlyDefined API (v2.1.0)
+3. license_blocklist_check
+4. sbom_generator
+5. pii_pattern_detector   ← AST-enhanced (v2.1.0)
+6. copyright_similarity_check ← EmbeddingProvider (v2.1.0)
+7. eu_ai_act_classifier
+8. transparency_marker
+9. block_pr
+10. suggest_alternative
+11. escalate_to_human
+```
+
+## 相關規格
+
+- XSPEC-193 — License Compliance Agent 完整規格
+- XSPEC-066 — Wave 3 Compliance Pack（v1.0.0 基準線）
+- DEC-063 — VibeOps 法務與合規策略
+- DEC-064 — 客戶 IP 隔離（cache salt）
+- ASPEC-001 — License Compliance Agent SPEC（XSPEC-205 §REQ-2 格式）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-04-30 | 初版 — REQ-001~006 一般 OSS 實務 |
+| v2.0.0 | 2026-05-14 | 新增 Tier 2 LC-001~009 AI 專屬規則 |
+| v2.1.0 | 2026-05-16 | ClearlyDefined API + AST PII + EmbeddingProvider + ASPEC-001 參照 |

package/bundled/locales/zh-TW/core/llm-output-validation.md

@@ -0,0 +1,192 @@
+---
+source: ../../../core/llm-output-validation.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 8b7fc8543760
+status: current
+---
+
+# LLM 輸出驗證標準
+
+> **Language**: [English](../../../core/llm-output-validation.md) | 繁體中文
+
+> 標準 ID：`llm-output-validation`
+> 版本：v1.0.0
+> 最後更新：2026-05-05
+
+---
+
+## 為什麼需要 LLM 輸出驗證？
+
+LLM 輸出具有**不確定性**：同一個 prompt 在不同時間、不同模型版本下可能產生格式不一致的輸出。如果不加以驗證，這些輸出可能在下游管線中造成靜默失敗（silent failure）——不是報錯，而是用了一個錯誤的預設值或 `undefined`。
+
+LLM 輸出驗證包含三個層次：
+
+| 層次 | 問題 | 工具 |
+|------|------|------|
+| 結構驗證 | 輸出格式是否正確？ | JSON Schema、Zod、Pydantic |
+| 語意驗證 | 宣稱的事實是否有根據？ | NLI probe、Grounding check |
+| 行為驗證 | Agent 是否正確拒絕越界請求？ | 紅隊語料庫、拒絕評估 |
+
+---
+
+## 一、Schema Contract Test（結構驗證）
+
+### 核心概念
+
+每個 AI Agent 應宣告一份 `output-schema.json`（JSON Schema 格式），並提供對應的 contract test。
+
+**Contract test 的目的**：
+- 確認 schema 本身是合法的 JSON Schema
+- 確認 valid fixtures 通過驗證
+- 確認 invalid fixtures（缺少必填欄位、型別錯誤、enum 違規）被拒絕
+
+### 推薦目錄結構
+
+```
+agents/<agent-name>/
+  output-schema.json       ← JSON Schema 定義
+  __tests__/
+    contract.test.ts       ← Contract test suite
+  __fixtures__/
+    valid.json             ← 真實 LLM 輸出 golden fixture
+    invalid-missing-id.json ← 缺少必填欄位的 fixture
+```
+
+### TypeScript 範例（使用 Ajv）
+
+```typescript
+import Ajv from "ajv"
+import schema from "../output-schema.json"
+import validFixture from "../__fixtures__/valid.json"
+
+const ajv = new Ajv({ strict: false })
+const validate = ajv.compile(schema)
+
+// 測試 1：Schema 本身是合法的 JSON Schema
+it("schema is valid JSON Schema", () => {
+  expect(ajv.validateSchema(schema)).toBe(true)
+})
+
+// 測試 2：Valid fixture 通過驗證
+it("valid fixture passes schema", () => {
+  expect(validate(validFixture)).toBe(true)
+})
+
+// 測試 3：空 object 被拒絕
+it("empty object is rejected", () => {
+  expect(validate({})).toBe(false)
+})
+
+// 測試 4：缺少 source_agent 被拒絕
+it("object missing source_agent is rejected", () => {
+  const { source_agent, ...without } = validFixture
+  expect(validate(without)).toBe(false)
+})
+```
+
+### Python 範例（使用 Pydantic）
+
+```python
+from pydantic import ValidationError
+from your_module import AgentOutput
+
+# 測試 valid fixture
+valid_data = { "version": "1.0.0", "source_agent": "planner", ... }
+output = AgentOutput(**valid_data)  # 不拋出 exception
+
+# 測試 invalid fixture
+try:
+    AgentOutput(version="bad-format", source_agent="planner")
+    assert False, "Should have raised"
+except ValidationError:
+    pass  # 預期行為
+```
+
+---
+
+## 二、幻覺偵測（Semantic Validation）
+
+### 什麼是幻覺？
+
+LLM 產生「聽起來正確但實際上沒有根據」的內容。例如：
+- 虛構的 API 文件 URL
+- 不存在的資料庫欄位名稱
+- 未在 context 中出現的 dependency 版本
+
+### 偵測策略
+
+| 策略 | 適用場景 | 自動化程度 |
+|------|---------|-----------|
+| **Schema 結構化輸出** | Agent 輸出 JSON，enum 限制可能值 | 高（自動） |
+| **Grounding Check** | RAG 系統，回答需引用 context | 中（需 NLI 模型） |
+| **信心度標記** | Agent 在輸出中包含 `confidence` 分數 | 中（需 prompt 設計） |
+| **紅隊語料庫** | 主動測試越界請求的拒絕行為 | 高（自動） |
+
+### 幻覺率目標
+
+| Agent 類型 | Schema 合規率 | 事實幻覺率 |
+|-----------|-------------|----------|
+| 結構化 JSON Agent | ≥ 99% | ≤ 5% |
+| RAG Agent | ≥ 95% | ≤ 5% |
+| 對話 Agent | ≥ 90% | ≤ 10% |
+
+---
+
+## 三、Prompt 回歸測試
+
+### 何時需要跑 Prompt 回歸測試？
+
+- 修改任何 `agents/*/prompt.md`
+- 模型版本升級（相同 prompt，不同 model）
+- Schema 新增 required field
+
+### 回歸測試流程
+
+```bash
+# 1. 修改前：用 temperature=0 記錄 golden output
+ai-agent run planner --input fixtures/planner-input.json --temp 0 > golden.json
+
+# 2. 修改後：重跑並比對
+ai-agent run planner --input fixtures/planner-input.json --temp 0 > after.json
+
+# 3. 用 contract test 驗證 after.json 仍符合 schema
+npx vitest run agents/__tests__/contract.test.ts
+```
+
+---
+
+## 四、品質閘門（Quality Gates）
+
+| 閘門 | 閾值 | 強制程度 |
+|------|------|---------|
+| Schema 合規（CI） | 100% | Block merge |
+| 空 object 拒絕（CI）| 100% | Block merge |
+| Prompt 修改後回歸（CI）| schema 合規維持 | Block merge |
+| 幻覺率（pre-release）| ≤ 5% | Advisory |
+
+---
+
+## 五、工具推薦
+
+| 工具 | 語言 | 用途 |
+|------|------|------|
+| [Ajv](https://ajv.js.org/) | TypeScript/JS | JSON Schema contract test |
+| [Zod](https://zod.dev/) | TypeScript | Runtime type validation |
+| [Pydantic](https://docs.pydantic.dev/) | Python | Schema + type validation |
+| [DeepEval](https://deepeval.com/) | Python | LLM 幻覺率、faithfulness 評分 |
+| [Ragas](https://docs.ragas.io/) | Python | RAG grounded answer rate |
+
+---
+
+## 參考標準
+
+- NIST AI RMF (AI 100-1, 2023) — AI 風險管理框架
+- OWASP Top 10 for LLM Applications v1.1 — LLM01: Prompt Injection
+- ISO/IEC 42001:2023 — AI 管理系統
+- [UDS `security-testing.ai.yaml`](../../../core/security-testing.md) — SAST + DAST 整合
+- [UDS `adversarial-test.ai.yaml`](../../../core/adversarial-test.md) — Prompt injection 紅隊標準
+
+
+**Scope**: universal

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

@@ -1,19 +1,102 @@
 ---
 source: ../../../core/logging-standards.md
-source_version: 1.2.0
-translation_version: 1.2.0
-last_synced: 2026-01-24
+source_version: 1.4.0
+translation_version: 1.4.0
+last_synced: 2026-07-08
+source_hash: 732277ef939f
 status: current
 ---
 
 # 日誌標準
 
-> 版本: 1.2.0 | 最後更新: 2026-01-24
+> **語言**: [English](../../../core/logging-standards.md) | 繁體中文
+
+**版本**: 1.4.0
+**最後更新**: 2026-06-17
+**適用性**: 所有軟體專案
+**範圍**: 通用 (Universal)
+**業界標準**: RFC 5424、OpenTelemetry、W3C Trace Context
+**參考**: [opentelemetry.io](https://opentelemetry.io/)
 
 ## 概述
 
 本文件定義日誌標準，確保所有環境中的應用程式日誌具有一致性、結構化且可操作。
 
+## 強制事件 (Mandatory Events)
+
+> **結案** UDS issue [#108](https://github.com/AsiaOstrich/universal-dev-standards/issues/108)（XSPEC-234）。本標準其餘部分定義**如何**寫一條 log（等級／欄位／PII 遮罩／輪替）；本章定義**何時必須寫**——把「規範上合格但實質沉默」的 logging 排除在外。
+
+遵守所有格式規則卻**在關鍵時刻從不觸發**的 logging 比沒有還糟：它在事故當下給人虛假的安全感。以下事件是**必須**寫 log 的 canonical 時機，每個宣告 `when`／`must_log`／`must_NOT_log`／`level`／`rationale`。
+
+### 為何需要（真實事故）
+
+某 PHP→.NET 遷移耗 2 天診斷「send failed、沒 log」，因為**四層皆沉默**：
+
+1. **負載平衡器將 backend 標 DOWN**（503）——health probe 逾時；backend 只記 probe 噪音，零業務事件。
+2. **Framework 驗證 reject**（如 ModelState／DTO 501）——在任何 handler 執行前就返回，**payload 完全未 log**。
+3. **Auth 失敗**只記「Account or password error」——**無 uid、無 source IP** → 無法調查。
+4. **背景 worker 還活著但 log 檔 0 bytes**——無機制偵測沉默。
+
+這些都無法靠格式規則捕捉，強制事件補上此缺口。
+
+### 類目（9 個 canonical 事件）
+
+| id | when 時機 | level | 核心必填欄位（`must_log`）| `must_NOT_log` |
+|----|-----------|-------|---------------------------|----------------|
+| `application_startup` | process boot 後，**接受請求前** | INFO | app_name, version, git_sha, environment, hostname, pid, listening_endpoints | secrets、完整連線字串 |
+| `request_received` | HTTP middleware 首次看到 request | INFO / DEBUG | method, path, source_ip, request_id | request body、auth headers |
+| `validation_failure` | schema / ModelState / DTO 驗證 reject | WARN | request_id, path, missing_fields[], payload_shape（僅 keys）| 欄位**值**、PII |
+| `authentication_failure` | login / token 驗證失敗 | WARN | uid（嘗試）, source_ip, failure_reason | password、token value |
+| `outbound_call_start` | 對外 HTTP/RPC call 發起 | INFO | target_url（host+path）, request_id propagated, timeout_ms | credentials、bearer tokens |
+| `outbound_call_complete` | 外部 call 返回或失敗 | INFO / WARN / ERROR | status_code **或** failure_phase（dns/tcp/tls/http）, elapsed_ms, retries | 含 PII 的 response body |
+| `business_event` | state-changing 業務操作完成 | INFO | operation_name, actor, target ids, outcome | 完整 record payload、PII |
+| `heartbeat` | 長期背景服務，≥ 1 次 / 60 秒 | INFO | service_name, queue_depth, items_processed_since_last_heartbeat | — |
+| `shutdown` | process 退出（graceful 或 fatal）| INFO / ERROR | app_name, signal/reason, uptime_seconds, pending_work_count | — |
+
+每個事件的 `rationale` 對應真實失效模式：`validation_failure` ⇒ 事故 #2（payload 未記）；`authentication_failure` 欄位要求 ⇒ 事故 #3（無 uid/IP）；`heartbeat` + 沉默偵測 ⇒ 事故 #4（0-byte log）；`application_startup`/`shutdown` ⇒ 生命週期盲區；`outbound_call_*` ⇒「send failed」卻無 call 痕跡。
+
+### 場景
+
+#### Scenario：驗證失敗時必須有 log
+
+- **GIVEN** API endpoint 收到缺 `[Required]` 欄位的 payload
+- **WHEN** framework 在 handler 執行前自動 reject（如 400/501）
+- **THEN** 必須寫一條 WARN log，含 `request_id`、`path`、`missing_fields[]`、`payload_shape`（僅 keys）
+- **AND** post-mortem 可直接從 log 重現失敗原因
+
+#### Scenario：背景服務必須 heartbeat
+
+- **GIVEN** worker process 啟動
+- **WHEN** 60 秒內無 INFO/WARN/ERROR 寫入
+- **THEN** 必須寫一條 `heartbeat` log，含當前 queue depth 與累計處理量
+- **AND** 若連續 ≥ 2× 心跳間隔（≥ 120 秒）無 heartbeat，silence detector 必須 alert
+
+### Compliant startup log 範例
+
+```json
+{
+  "timestamp": "2026-06-17T08:00:00.000Z",
+  "level": "INFO",
+  "message": "application_startup",
+  "event": "application_startup",
+  "app_name": "payment-service",
+  "version": "2.3.1",
+  "git_sha": "a1b2c3d",
+  "environment": "production",
+  "hostname": "pod-abc123",
+  "pid": 4711,
+  "listening_endpoints": ["0.0.0.0:8080", "0.0.0.0:9090/metrics"]
+}
+```
+
+### Follow-on 規則
+
+1. **Access log 分離**——health probe／liveness 流量不應污染業務事件 log。將 probe 導向獨立 sink／檔案，避免淹沒或輪替掉業務事件（見事故 #1）。
+2. **Log 沉默偵測 SLA**——服務應於 N 分鐘無事件時 alert，N ≤ 2× `heartbeat` 間隔。缺少預期 log 本身就是可告警條件（見下方「Absence of Expected Logs」告警模式）。
+3. **OPS-facing log 可發現性**——回給 client 的錯誤回應應帶 `request_id`，讓支援能將使用者回報的失敗對應到 backend log，免於來回詢問 log 存取。
+
+> **Cross-ref**：`heartbeat`／沉默偵測與[日誌檔案輪替政策](#日誌檔案輪替政策)互補（0-byte／靜默丟棄的 log 是同一盲區的兩個方向），並與 migration-assistant 的背景作業／副作用完整性互補（這些事件即可觀測的「已執行」證據）。
+
 ## 日誌等級
 
 ### 標準日誌等級
@@ -417,6 +500,117 @@ tracestate: vendor=value
 | WARN | 90 天 |
 | ERROR/FATAL | 1 年 |
 
+---
+
+## 日誌檔案輪替政策
+
+### 輪替政策——必須同時設定兩者
+
+基於檔案的 log sink 設定**必須**包含以下**兩種**觸發器：
+
+1. **時間輪替**（`rollingInterval: Day` 或等效設定）——用於按時間分區
+2. **大小輪替**，且 `rollOnFileSizeLimit: true`（或等效設定）——用於處理流量突增
+
+> **為何強制要求：** 大多數日誌函式庫預設有靜默的大小上限。當檔案達到上限，後續的日誌寫入會被**靜默丟棄**——沒有警告、沒有錯誤。應用程式繼續運行，而半天的日誌就此消失。同時明確設定兩種觸發器可避免這個陷阱。
+
+### 生產環境的預設上限是危險的
+
+| 函式庫 | 預設大小上限 | 達到上限時的行為 |
+|---|---|---|
+| Serilog File sink (.NET) | 1 GB | **靜默停止寫入**（`RollOnFileSizeLimit = false` 為預設值） |
+| log4j RollingFileAppender | 除非設定否則無限制 | 相同——不輪替 = 丟棄 |
+| Python `RotatingFileHandler` | 除非設定 `maxBytes` 否則無限制 | 無限制增長 |
+| Winston `winston-daily-rotate-file` | 除非設定 `maxSize` 否則無限制 | 相同——不輪替 = 丟棄 |
+
+若未明確設定基於大小的輪替，即等同接受上述其中一種失敗模式。
+
+### 建議的起始值
+
+| 參數 | 值 | 理由 |
+|---|---|---|
+| `fileSizeLimitBytes` | 100 MB | 平衡：小到可用編輯器開啟，大到不會過度輪替 |
+| `rollOnFileSizeLimit` | `true` | 達到上限時，建立 `*-001.txt`、`*-002.txt`；**不要**丟棄 |
+| `retainedFileCountLimit` | ≥ N×7，N = 每日最大預期輪替次數 | 避免過早刪除時間窗口內的日誌 |
+
+### 各語言設定範例
+
+**.NET / Serilog** (`appsettings.json`):
+
+```json
+{
+  "Serilog": {
+    "WriteTo": [{
+      "Name": "File",
+      "Args": {
+        "path": "logs/app-.txt",
+        "rollingInterval": "Day",
+        "fileSizeLimitBytes": 104857600,
+        "rollOnFileSizeLimit": true,
+        "retainedFileCountLimit": 90
+      }
+    }]
+  }
+}
+```
+
+**Python** (`logging.handlers`):
+
+```python
+from logging.handlers import RotatingFileHandler
+
+handler = RotatingFileHandler(
+    filename="logs/app.log",
+    maxBytes=104857600,   # 100 MB
+    backupCount=90        # ~3 個月的輪替，假設低基數
+)
+# 若需要時間+大小的組合輪替，可搭配 TimedRotatingFileHandler 與大小檢查
+# 或使用第三方函式庫如 concurrent-log-handler。
+```
+
+**Java / log4j2** (`log4j2.xml`):
+
+```xml
+<RollingFile name="App" fileName="logs/app.log"
+             filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
+  <PatternLayout pattern="%d %-5p %c{1.} - %m%n"/>
+  <Policies>
+    <TimeBasedTriggeringPolicy interval="1"/>
+    <SizeBasedTriggeringPolicy size="100 MB"/>
+  </Policies>
+  <DefaultRolloverStrategy max="90"/>
+</RollingFile>
+```
+
+**Node / Winston** (`winston-daily-rotate-file`):
+
+```javascript
+import DailyRotateFile from "winston-daily-rotate-file";
+
+new DailyRotateFile({
+  filename: "logs/app-%DATE%.log",
+  datePattern: "YYYY-MM-DD",
+  maxSize: "100m",
+  maxFiles: "90d"
+});
+```
+
+### 操作 SOP——調查根因，勿只提高上限
+
+若日誌檔案大小在預期的每日結束時達到 `fileSizeLimitBytes` 的 ≥ 90%，**在提高上限前先調查原因**。常見根本原因：
+
+- 嘈雜的重試迴圈將每次嘗試以 INFO 記錄，而非 WARN 摘要
+- 在正式環境中意外啟用了不受限制的 debug 日誌
+- 一個上游失敗造成 stack trace 洪流
+- 健康探針 / sidecar 污染了業務日誌
+
+提高上限只是掩蓋了底層的噪音問題，並將下次中斷推遲。
+
+### 失敗模式參考（真實事故）
+
+一個正式 .NET Worker 只使用 `rollingInterval: Day`（未設定大小限制，Serilog 預設 1 GB 上限），在 07:31 達到上限，靜默丟棄所有日誌條目直到 13:00+，操作員才注意到 tail 停滯。連續五個每日檔案顯示 `~1,073,741,8XX bytes`（= 1 GiB，Serilog 預設值）。半天的正式診斷資料就此消失。若設定 `fileSizeLimitBytes` + `rollOnFileSizeLimit: true`，就會輪替至 `worker-YYYYMMDD_001.txt` 並保留這些事件。
+
+---
+
 ## 快速參考卡
 
 ### 日誌等級選擇
@@ -445,6 +639,14 @@ tracestate: vendor=value
 - [ ] 永不記錄信用卡
 - [ ] 已設定保留政策
 
+### 輪替清單
+
+- [ ] 已設定時間輪替（`rollingInterval: Day` 或等效設定）
+- [ ] 已設定大小輪替，且 `rollOnFileSizeLimit: true`（或等效設定）
+- [ ] `fileSizeLimitBytes` 已明確設定（預設上限是危險的）
+- [ ] `retainedFileCountLimit` ≥ N×7 以涵蓋時間窗口內的輪替
+- [ ] 已定義 90% 大小 SOP：調查噪音根因，勿只提高上限
+
 ---
 
 **相關標準：**
@@ -457,6 +659,8 @@ tracestate: vendor=value
 
 | 版本 | 日期 | 變更 |
 |-----|------|------|
+| 1.4.0 | 2026-06-17 | 新增：強制事件類目——9 個 canonical「何時必須寫 log」事件（when/must_log/must_NOT_log/level/rationale）、驗證失敗 + heartbeat 場景、compliant startup 範例、follow-on 規則（access log 分離、沉默偵測 SLA、request_id 可發現性）（XSPEC-234 / 關閉 issue #108） |
+| 1.3.0 | 2026-05-26 | 新增：日誌檔案輪替政策——強制雙觸發器（時間 + 大小）輪替及危險預設警告、.NET/Python/Java/Node 各語言設定範例、操作 SOP（XSPEC-232 / 關閉 issue #111） |
 | 1.2.0 | 2026-01-24 | 新增：OpenTelemetry 語義慣例、可觀測性三支柱整合、基於日誌的告警、進階關聯模式 |
 | 1.1.0 | 2026-01-05 | 新增：參考標準章節，包含 OWASP、RFC 5424、OpenTelemetry 和 12 Factor App |
 | 1.0.0 | 2025-12-30 | 初始日誌標準 |