universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-TW/core/ai-response-navigation.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/ai-response-navigation.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-03-25
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-06-10
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../core/ai-response-navigation.md) | 繁體中文 | [简体中文](../../zh-CN/core/ai-response-navigation.md)
 
-**版本**: 1.0.0
-**最後更新**: 2026-03-25
+**版本**: 1.1.0
+**最後更新**: 2026-06-10
 **適用範圍**: 所有使用 AI 輔助開發的專案
 **範圍**: universal
 **產業標準**: 無（新興 AI 工具實踐）
@@ -77,6 +77,30 @@ status: current
 
 當下一步建議對應到已知的斜線命令時，使用 `` `/command` `` 格式引用，讓使用者可以直接複製執行。沒有對應命令的步驟使用自然語言描述。
 
+### 規則 6：模型級別標注（選用）
+
+當某個下一步選項明確對應到特定的複雜度等級時，可**選擇性**附加模型級別提示。此標注**嚴格為選用**——既有技能無需回頭修改；新增或修訂技能時建議帶入。
+
+**標注方式**：在選項描述後加上 `〔模型：Fast〕`、`〔模型：Standard〕` 或 `〔模型：Capable〕`。
+
+**等級判斷依據**：參考 [model-selection](model-selection.md) 標準的複雜度信號：
+- `Fast` — 修改單一檔案、spec 完全明確、無需設計判斷
+- `Standard` — 2-5 個檔案、需要模組間理解
+- `Capable` — 5+ 個檔案、架構決策、跨系統正確性
+
+等級名稱**與廠商無關**——各工具或平台自行將等級映射到可用的模型。
+
+**英文標注對照**：`〔model: Fast〕` / `〔model: Standard〕` / `〔model: Capable〕`
+
+**示例**（任務完成，含模型標注）：
+
+```markdown
+> **建議下一步：**
+> - 執行 `/derive bdd` 推導 BDD 場景 `〔模型：Fast〕` — 格式轉換工作
+> - 執行 `/checkin` 進行品質關卡驗證 ⭐ **推薦** `〔模型：Standard〕` — 需要模組間判斷
+> - 執行 `/sdd` 整合架構設計 `〔模型：Capable〕` — 跨系統影響分析
+```
+
 ---
 
 ## 情境模板
@@ -217,7 +241,7 @@ AI 需要使用者做出選擇或提供資訊時使用。
 > **建議下一步：**
 > - 執行 `/test` 為新功能撰寫測試
 > - 執行 `/commit` 提交變更 ⭐ **推薦** — 變更已完整且通過驗證
-> - 執行 `/review` 進行自我審查
+> - 執行 `/code-review` 進行自我審查
 ```
 
 ### 範例 2：詢問使用者設計問題
@@ -265,6 +289,7 @@ AI 需要使用者做出選擇或提供資訊時使用。
 | R3 | 模板匹配回應類型 |
 | R4 | 1–5 個選項，依情境調整 |
 | R5 | 適用時使用 `/command` 格式 |
+| R6 | *（選用）* 等級明確時附加 `〔模型：Fast｜Standard｜Capable〕` |
 
 | 豁免 | 不豁免 |
 |------|--------|
@@ -288,6 +313,7 @@ AI 需要使用者做出選擇或提供資訊時使用。
 
 | 版本 | 日期 | 變更 |
 |------|------|------|
+| 1.1.0 | 2026-06-10 | 新增規則 R6 選用模型級別標注（`〔模型：Fast｜Standard｜Capable〕`）；與廠商無關；不強制既有技能回改 |
 | 1.0.0 | 2026-03-25 | 初始版本 |
 
 ---

package/bundled/locales/zh-TW/core/anti-sycophancy-prompting.md

@@ -189,4 +189,4 @@ LLM 的迎合性源自 RLHF 訓練目標：人類評分者傾向於給予令人
 ## 相關標準
 
 - [anti-hallucination.md](../../../core/anti-hallucination.md) — 防止幻覺；與防迎合互補
-- [agent-epistemic-calibration.md](../../../core/agent-epistemic-calibration.md) — Agent 設計中的認知謙遜（若適用）
+- [agent-epistemic-calibration.md](../../../core/anti-hallucination.md) — Agent 設計中的認知謙遜（若適用）

package/bundled/locales/zh-TW/core/api-design-standards.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/api-design-standards.md
-source_version: 1.0.0
-translation_version: 1.0.0
-last_synced: 2026-03-18
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-06-24
 status: current
 ---
 
@@ -10,7 +10,7 @@ status: current
 
 > **語言**: [English](../../../core/api-design-standards.md) | 繁體中文
 
-> 版本: 1.0.0 | 最後更新: 2026-03-18
+> 版本: 1.1.0 | 最後更新: 2026-06-24
 
 **適用範圍**: 所有軟體專案
 **範疇**: universal
@@ -173,12 +173,14 @@ https://api.example.com/v2/users
 
 ### 版本生命週期
 
-| 階段 | 持續時間 | 動作 |
-|------|----------|------|
+API 版本會經歷四種狀態。其中的**持續時間**——平行支援期與棄用通知期——是[棄用與日落標準](deprecation-standards.md#api-棄用)的單一職責；本表只定義狀態與各狀態下的 API 契約動作，使時間數字只存在於單一處。
+
+| 階段 | 狀態 | API 契約動作 |
+|------|------|------|
 | **現行** | 積極開發中 | 完整支援、新功能 |
-| **支援中** | 後繼版本發布後 6-12 個月 | 僅限錯誤修復、安全修補 |
-| **已棄用** | 3-6 個月通知期 | Sunset 標頭、遷移指南 |
-| **已終止** | 棄用期結束後 | 回傳 410 Gone 與遷移資訊 |
+| **支援中** | 與後繼版本平行維護 | 僅限錯誤修復、安全修補 |
+| **已棄用** | 已宣告退役 | `Deprecation` / `Sunset` 標頭、發布遷移指南 |
+| **已終止** | 已移除 | 回傳 `410 Gone` 與遷移資訊 |
 
 ### 棄用標頭
 
@@ -188,6 +190,85 @@ Deprecation: true
 Link: <https://api.example.com/v2/docs>; rel="successor-version"
 ```
 
+> 完整的棄用**流程**（分階段的 Sunset 時間線）與**依 API 分級的最短通知期間**，由[棄用與日落標準](deprecation-standards.md#api-棄用)掌管。本標準負責下方的 API 契約面：如何在程式碼中棄用版本、何謂破壞性變更、以及如何撰寫遷移指南。
+
+### 棄用 API 版本
+
+透過 SemVer 與 API 本身發出棄用訊號，再依循棄用生命週期。版本演進對應[語義化版本](versioning.md#遞增規則)：
+
+```
+v1.0.0 — 版本引入
+v1.5.0 — 宣告棄用（不晚於移除前的 N-1 minor）
+v2.0.0 — 移除版本（破壞性變更 → MAJOR 遞增）
+```
+
+標記已棄用的程式碼，讓呼叫端在移除版本前就能看到警告：
+
+```javascript
+// v1.5.0 — 加入棄用警告
+/**
+ * @deprecated Use authenticateV2() instead. Will be removed in v2.0.0
+ */
+function authenticate(username, password) {
+  console.warn('[DEPRECATED] authenticate() will be removed in v2.0.0. Use authenticateV2()');
+  return authenticateV2(username, password);
+}
+```
+
+### 向後相容性檢查清單
+
+發布前，將每項變更分類。第一份清單中的任何項目皆屬**破壞性**，需升級 MAJOR 版本（見[語義化版本](versioning.md#遞增規則)）；第二份清單中的項目向後相容，可在 MINOR 或 PATCH 版本發布。
+
+**破壞性——不升級 MAJOR 版本絕不可做：**
+- [ ] 移除公開 API 端點
+- [ ] 移除必填請求欄位
+- [ ] 新增必填請求欄位
+- [ ] 變更回應欄位的類型
+- [ ] 變更錯誤碼的含義
+- [ ] 移除消費者依賴的回應欄位
+
+**向後相容——可在 MINOR 或 PATCH 版本安全發布：**
+- [ ] 新增可選請求欄位
+- [ ] 新增回應欄位
+- [ ] 新增端點
+- [ ] 新增錯誤碼
+- [ ] 改善錯誤訊息
+- [ ] 效能改進
+
+### API 遷移指南
+
+當 MAJOR 版本帶有破壞性變更時，發布一份遷移指南，將每個舊用法對應到其替代方案：
+
+````markdown
+# 遷移指南：v1.x 到 v2.0
+
+## 破壞性變更
+
+### 1. authenticate() 已移除
+
+**Before (v1.x)**:
+```javascript
+const token = await authenticate('user', 'pass');
+```
+
+**After (v2.0)**:
+```javascript
+const token = await authenticateV2({ username: 'user', password: 'pass' });
+```
+
+### 2. API 回應格式變更
+
+**Before (v1.x)**: `{ "data": { "user": {...} } }`
+**After (v2.0)**: `{ "user": {...} }`
+
+```javascript
+// Before
+const user = response.data.user;
+// After
+const user = response.user;
+```
+````
+
 ---
 
 ## 請求/回應標準
@@ -925,6 +1006,7 @@ Content-Security-Policy: default-src 'none'
 
 | 版本 | 日期 | 變更 |
 |------|------|------|
+| 1.1.0 | 2026-06-24 | 新增：棄用 API 版本、向後相容性檢查清單、API 遷移指南（自 versioning.md 整併）；版本生命週期的所有期間數字改由 deprecation-standards 作為單一真實來源（XSPEC-298 R8、UDS #126） |
 | 1.0.0 | 2026-03-18 | 初始版本 |
 
 ---

package/bundled/locales/zh-TW/core/audit-trail.md

@@ -0,0 +1,110 @@
+---
+source: ../../../core/audit-trail.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: 7543ded62881
+status: current
+---
+
+# 稽核軌跡標準
+
+> **Language**: [English](../../../core/audit-trail.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/audit-trail.ai.yaml`
+> **規格**: XSPEC-066（cross-project/specs/XSPEC-066-uds-compliance-audit-pack.md）
+
+## 概觀
+
+本標準定義在處理敏感資料、金融交易、權限變更與合規相關操作的系統中，如何建立、
+儲存與管理**不可變稽核軌跡（immutable audit trail）**。涵蓋必備事件類型、稽核紀錄
+結構、防篡改要求、保留期、查詢／匯出能力，以及 SIEM 整合。設計目標為滿足 SOC 2、
+ISO 27001、GDPR 與金融法規要求。
+
+本標準屬於**合規與稽核標準包**（XSPEC-066）。稽核軌跡是 EU AI Act 可稽核性
+（DEC-041）與 VibeOps Governance Agent 介入紀錄（DEC-042）的核心載體，並與治理閘門
+家族——`license-compliance`（XSPEC-193）、`verification-oracle`（XSPEC-256）、
+`model-provenance`（XSPEC-255）——組合：這些閘門的裁決會寫入符合本標準的稽核軌跡。
+
+> **範圍**：本標準定義「該稽核什麼」、「紀錄結構」以及「不可變／保留／存取」規則。
+> 具體儲存引擎（S3 Object Lock、append-only DB、雜湊鏈函式庫）與 SIEM 產品屬採用者
+> 的選擇，不在本標準範圍內。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | 必備可稽核事件類型（認證、授權、資料存取、設定、金融、合規） | MUST |
+| REQ-002 | 稽核紀錄結構（必備 + 建議欄位） | MUST |
+| REQ-003 | 不可變性與防篡改（append-only + 雜湊鏈） | MUST |
+| REQ-004 | 各類別的稽核日誌保留期 | MUST |
+| REQ-005 | 查詢與匯出能力（可篩選、可匯出、查詢動作本身亦記錄） | MUST |
+| REQ-006 | SIEM 整合與告警 | SHOULD |
+
+### REQ-001 — 必備可稽核事件類型
+
+系統 MUST 無例外地為下列事件記錄稽核紀錄：(1) **認證**——登入成功／失敗、登出、
+MFA 事件、密碼變更；(2) **授權**——存取核准／拒絕、權限提升、角色變更；
+(3) **資料存取**——TIER-1 與 TIER-2 PII（見 `pii-classification`）的讀／寫／刪、
+大量資料匯出；(4) **設定變更**——系統設定、安全政策變更、使用者／角色管理；
+(5) **金融交易**——付款處理、退款、餘額變動；(6) **合規相關操作**——同意變更、
+資料刪除請求、法律保留（legal hold）。
+
+### REQ-002 — 稽核紀錄結構
+
+每筆稽核紀錄 MUST 包含：`event_id`（UUID v4）、`event_type`（列舉字串）、
+`timestamp`（含毫秒的 ISO 8601 UTC）、`actor_id`（使用者或服務帳號）、`actor_ip`
+（使用者操作時）、`resource_type`、`resource_id`、`action`、`outcome`（成功／失敗）
+與 `environment`（production／staging）。SHOULD 另含 `session_id`、用於關聯的
+`request_id`、變更操作的前後狀態，以及地理區域。
+
+### REQ-003 — 不可變性與防篡改
+
+稽核日誌 MUST 寫入 **append-only** 儲存體，防止應用層主體修改或刪除。每筆紀錄
+MUST 包含前一筆紀錄的密碼學雜湊（**鏈接**）以偵測篡改。稽核儲存體的寫入權限
+MUST 僅限稽核服務本身——任何工程師或應用服務皆不得直接寫入。日誌完整性 MUST
+可隨選驗證。
+
+### REQ-004 — 稽核日誌保留期
+
+稽核日誌 MUST 依類別至少保留：認證／授權——熱儲存 1 年、冷儲存 6 年（SOC 2 /
+ISO 27001）；金融交易——7 年（金融法規）；PII 存取——3 年；設定變更——3 年；
+其餘稽核事件——1 年。在保留期屆滿前刪除稽核紀錄為 **PROHIBITED**。接近到期的
+日誌 MUST 自動封存至冷儲存。
+
+### REQ-005 — 稽核日誌查詢與匯出能力
+
+稽核系統 MUST 支援以 `event_type`、`actor_id`、`resource_id`、時間範圍與 `outcome`
+篩選。結果 MUST 可匯出為 JSON 與 CSV。回傳 PII 的查詢 MUST 自身亦記錄為稽核事件
+（查詢的查詢）。稽核資料 MUST 在請求後 4 小時內供獲授權的合規／安全團隊存取，
+並在 24 小時內供監管機關存取。
+
+### REQ-006 — SIEM 整合與告警
+
+稽核日誌 SHOULD 即時轉送至 SIEM 系統。SIEM SHOULD 具備自動偵測規則：暴力登入樣態
+（5 分鐘內 >5 次失敗）、營業時間外的權限提升、大量 PII 匯出（1 小時內 >1000 筆）、
+以及來自新地理區域的存取。高嚴重度偵測 SHOULD 觸發 on-call 通知。
+
+## 與既有標準的整合
+
+- **`pii-classification`**——資料存取稽核以所觸及欄位的 PII 等級為依據（TIER-1／
+  TIER-2 讀取為必備稽核事件）。
+- **`logging-standards`**——稽核紀錄是凌駕一般應用日誌之上、獨立且不可變的類別；
+  `pii-classification` 的遮罩規則仍適用。
+- **`license-compliance` / `verification-oracle` / `model-provenance`**——治理閘門
+  裁決（封鎖／override）會寫入稽核軌跡。
+- **`execution-history`**——一般執行紀錄無法取代合規等級、防篡改的稽核軌跡。
+
+## 相關規格
+
+- XSPEC-066 — UDS 合規與稽核標準包（本標準來源）
+- DEC-041 — EU AI Act 2026 合規（稽核軌跡作為可稽核性載體）
+- DEC-042 — Guardian / Governance Agent 模式（介入可稽核性）
+- DEC-020 — VibeOps 商業雙授權（授權合規稽核）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~006：事件類型、紀錄結構、不可變性／防篡改、保留期、查詢／匯出、SIEM 整合（XSPEC-066） |

package/bundled/locales/zh-TW/core/behavior-snapshot.md

@@ -0,0 +1,335 @@
+---
+source: ../../../core/behavior-snapshot.md
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-06-28
+source_hash: 36a3683ae75b
+status: current
+---
+
+# 行為快照標準
+
+> **語言**: [English](../../../core/behavior-snapshot.md) | 繁體中文 | [简体中文](../../zh-CN/core/behavior-snapshot.md)
+
+**適用範圍**：需要行為一致性驗證的遷移與重構專案
+**Scope**: universal
+
+---
+
+## 概述
+
+行為快照標準定義了一種黃金檔案格式，用於記錄現有系統的 HTTP 請求/回應配對。這些快照有兩個用途：
+
+1. **遷移一致性基準線** — 驗證新系統能重現與舊系統相同的行為
+2. **重構特性化** — 在修改程式碼前鎖定現有行為（Gate 0 協議）
+
+## 參考資料
+
+| 標準/來源 | 內容 |
+|----------------|---------|
+| XSPEC-201 | 重構/遷移完整性協議 |
+| Michael Feathers: *Working Effectively with Legacy Code* | 特性化測試概念 |
+| Golden Master Testing | 記錄並重放預期輸出的模式 |
+
+---
+
+## 快照檔案格式
+
+### 位置
+
+```
+.snapshots/<feature-id>/<scenario>.json
+```
+
+### Schema
+
+```json
+{
+  "feature_id": "FM-007",
+  "scenario": "happy_path",
+  "request": {
+    "method": "POST",
+    "path": "/api/orders/123/cancel",
+    "headers": {
+      "Content-Type": "application/json"
+    },
+    "body": {
+      "reason": "customer_request"
+    }
+  },
+  "response": {
+    "status": 200,
+    "body": {
+      "success": true,
+      "order_status": "cancelled",
+      "refund_initiated": true
+    }
+  },
+  "ignore_fields": ["refund_id", "cancelled_at"]
+}
+```
+
+### 欄位參考
+
+| 欄位 | 必填 | 說明 |
+|-------|----------|-------------|
+| `feature_id` | 是 | feature-manifest.yaml 中的 `FM-NNN` |
+| `scenario` | 是 | `snake_case` 情境名稱（`happy_path`、`not_found` 等） |
+| `request.method` | 是 | HTTP 方法 |
+| `request.path` | 是 | 不含 base URL 的 URL 路徑 |
+| `request.headers` | 否 | 請求所需的標頭（不含真實認證 token） |
+| `request.body` | 否 | 請求主體（JSON） |
+| `response.status` | 是 | 預期的 HTTP 狀態碼 |
+| `response.body` | 是 | 預期的回應主體（比較用欄位） |
+| `ignore_fields` | 否 | 比較時略過的欄位（詳見下方指南） |
+
+---
+
+## 目錄結構
+
+```
+.snapshots/
+  FM-001-UserLogin/
+    happy_path.json
+    invalid_credentials.json
+    account_locked.json
+  FM-007-OrderCancellation/
+    happy_path.json
+    order_not_found.json
+    order_already_cancelled.json
+    MANUAL-refund_webhook.json     ← 手動撰寫
+```
+
+### MANUAL- 前綴
+
+以 `MANUAL-` 為前綴的檔案包含無法自動錄製的快照：
+- 由第三方觸發的 Webhook 端點
+- 需要特定、難以重現的資料庫狀態的情境
+- 背景工作 / 佇列觸發流程（非 HTTP 入口點）
+
+`MANUAL-` 檔案不納入自動重放，但計入覆蓋率報告。
+
+---
+
+## `ignore_fields` 使用指南
+
+> **核心原則 —— 忽略「值」，保留「格式」斷言。** 某欄位是非確定性的，意指它的*值*在每次執行間會改變；這**並不**代表該欄位的*形狀*可以自由變動。`ignore_fields` 的天真用法會把整個欄位排除在比較之外，連帶也停止斷言其格式 —— 於是當序列化器悄悄把 ISO-8601 時間戳改成 Unix epoch、拿掉時區、或變更 UUID 大小寫／版本時，皆無人察覺。**忽略其值，但仍斷言其格式。**
+
+### 忽略值 vs. 忽略格式
+
+| 欄位 | 天真做法：整欄忽略 | 建議做法：忽略值、斷言格式 |
+|-------|---------------------------|-------------------------------------------|
+| `created_at` | 完全不比較 | 忽略其值；但仍斷言它是 ISO-8601、且維持相同的小數秒精度與相同的時區表示 |
+| `trace_id` | 完全不比較 | 忽略其值；但仍斷言它符合 UUID 版本與標準 8-4-4-4-12 形狀 |
+| `token` | 完全不比較 | 忽略其值；但仍斷言長度、字元集與前綴 |
+
+### 非確定性欄位：忽略值、斷言格式
+
+| 欄位模式 | 忽略（值） | 仍須斷言（格式／形狀） |
+|--------------|--------------------|-------------------------------|
+| `created_at`、`updated_at`、`timestamp` | 該瞬時 | ISO-8601 vs. epoch vs. 自訂；小數秒精度（位數）；時區表示（`Z` vs `+00:00` vs 偏移量） |
+| `token`、`session_id`、`csrf_token` | 隨機位元組 | 長度、字元集、前綴 |
+| `request_id`、`trace_id`、`correlation_id` | 隨機 UUID | UUID 版本 + 標準 8-4-4-4-12 形狀與大小寫 |
+
+**時間欄範例。** 某遷移後的端點回傳 `created_at`：
+
+```text
+舊系統："2026-05-12T08:30:00Z"
+新系統："2026-05-12T08:30:00.000+00:00"
+```
+
+兩者解碼後是同一瞬時，因此整欄忽略 —— 甚至是「先 parse 成日期再比值」 —— 都會通過。但**序列化格式已漂移**：多了小數秒、且時區表示從 `Z` 變成 `+00:00`。對採字串比對、或以嚴格格式 parse 的客戶端而言，這在正式環境會壞掉。斷言格式 pattern（例如 `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$`）能抓到它；整欄忽略則會遮蔽它。
+
+### 一律比較（業務邏輯）
+
+| 欄位模式 | 原因 |
+|--------------|--------|
+| `status`、`code`、`message`、`error_code` | 核心業務結果 |
+| `order_status`、`payment_status` | 狀態機結果 |
+| `amount`、`quantity`、`price` | 計算後的業務數值 |
+| `success`、`refunded`、`cancelled` | 布林業務結果 |
+| `user_id`、`order_id`（搭配固定測試資料） | 參照完整性 |
+
+### 整欄忽略（例外 —— 須附理由）
+
+把欄位完全排除在比較之外 —— 既不比值、**也不**斷言格式 —— 是**例外**，非預設。僅在欄位格式確實未定義或無關緊要時保留此做法（例如不透明的廠商 blob），並在行內註明理由。
+
+> ⚠️ **風險**：整欄忽略會遮蔽**格式漂移**。改變精度或時區的時間戳、改變版本的 UUID、或多了／少了一個尾零的數字都會悄悄通過 —— 而這正是一致性測試本應抓到的那類 bug。
+
+**規則**：`ignore_fields` 僅用於確實不確定性的*值*。忽略其值的同時，仍須斷言該欄位的格式／形狀。用它來排除業務邏輯欄位 —— 或用它來消音非確定性欄位的格式漂移 —— 都會使一致性測試失去意義。
+
+---
+
+## 序列化格式對等
+
+只比較**反序列化後物件**的差分 oracle，會悄悄把序列化層級的差異 normalize 掉：它把兩邊的回應都 parse 成 map／物件再比較，於是任何在 parse 後消失的分歧都看不見了。要抓到序列化 bug，oracle 必須以能保留序列化形式的粒度比較 —— 要嘛比對**原始序列化字串**，要嘛明確斷言 JSON 形狀。
+
+### 比較反序列化物件會遮蔽什麼
+
+| 序列化分歧 | 比較 parse 後物件時會被遮蔽嗎？ |
+|--------------------------|------------------------------------------|
+| `1` vs `1.0`（數字格式） | 會 —— 兩者都 parse 成數字 `1` |
+| `null` vs 缺少該 key | 會 —— 兩者都讀成不存在／null |
+| `true` vs `1` vs `"true"` | 常會 —— 型別強制轉換後 |
+| key 排序 | 會 —— 物件 key 無序 |
+| 前導零／科學記號 | 會 —— parse 時被 normalize |
+| 空白與 Unicode 轉義（`\/`、`\uXXXX`） | 會 —— parse 時遺失 |
+
+### 兩種策略
+
+1. **原始字串比對** —— 比對精確的序列化字串。保真度最強；當 wire 格式屬於契約一部分時採用（公開 API、被快取的 payload、簽章過的 body）。
+2. **明確的 JSON 形狀斷言** —— 當原始比對太嚴格時（例如確實有非確定性的值），改為明確斷言形狀：
+   - **key 的存在性與順序**（當順序屬於契約時）
+   - **數字格式**：`1` vs `1.0`、前導零、科學記號
+   - **`null` vs 缺漏 key**（省略欄位不等於明確的 `null`）
+   - **布林／字串型別**：`true` vs `"true"` vs `1`
+
+### 跨語言重寫會換掉序列化器
+
+當系統以另一種語言重寫時，序列化器會換 —— 而各序列化器的**預設行為**不同。oracle 必須明確斷言這些，因為沒有其他東西會幫你抓。PHP `json_encode` ↔ C# `System.Text.Json` 常見的預設差異：
+
+| 關注點 | PHP `json_encode`（預設） | C# `System.Text.Json`（預設） |
+|---------|------------------------------|----------------------------------|
+| 數字尾零 | `(float) 1.0` 輸出 `1`；需 `JSON_PRESERVE_ZERO_FRACTION` 才保留 `1.0` | `double` `1.0` 序列化成 `1`；`decimal` 保留小數位 |
+| 日期／時間 | 無原生日期型別 —— 由應用決定（常是自訂字串或 epoch） | `DateTime`/`DateTimeOffset` → ISO-8601（round-trip "O"），例如 `2026-05-12T08:30:00+00:00` |
+| 時區 | 由應用決定 | `DateTimeOffset` 保留偏移量；`DateTime.Kind` 決定 `Z` vs 偏移量 |
+| `null` 屬性 | 以 `"k":null` 輸出 | 預設輸出；僅在 `DefaultIgnoreCondition.WhenWritingNull` 時省略 |
+| key 排序 | 插入順序（associative array） | 屬性宣告／反射順序 |
+| 斜線與 Unicode 轉義 | 預設轉義 `/` 與非 ASCII，除非設 `JSON_UNESCAPED_SLASHES` / `JSON_UNESCAPED_UNICODE` | 不轉義 `/`；非 ASCII 依所設定的 encoder 轉義 |
+
+### 斷言序列化形狀（TypeScript）
+
+```typescript
+// 超越值的對等：斷言序列化形式，而不只是 parse 後的物件。
+function assertSerializationParity(oldRaw: string, newRaw: string): void {
+  // 1. 最強：精確的序列化字串（只剝除被忽略的*值*之後）。
+  if (oldRaw === newRaw) return;
+
+  // 2. 否則在原始文字上明確斷言形狀，而非在 JSON.parse() 上：
+  //    數字格式 —— 舊的 "1.0" 不可悄悄變成新的 "1"
+  const numberShape = (s: string) => s.match(/:\s*-?\d+(\.\d+)?([eE][+-]?\d+)?/g) ?? [];
+  expect(numberShape(newRaw)).toEqual(numberShape(oldRaw));
+
+  //    null vs 缺漏 —— 明確的 "key":null 不可消失
+  expect(/"refund_id"\s*:\s*null/.test(newRaw))
+    .toBe(/"refund_id"\s*:\s*null/.test(oldRaw));
+}
+```
+
+---
+
+## 一致性檢查工具
+
+執行 `scripts/parity-check.ts` 對目標系統重放所有快照：
+
+```bash
+npx tsx scripts/parity-check.ts --url http://new-system:8080 [--snapshots .snapshots] [--env uat|staging]
+```
+
+### 輸出範例
+
+```
+🔄 Parity Check — 119 snapshots against http://new-system:8080
+
+  ✅ FM-001 / happy_path
+  ✅ FM-001 / invalid_credentials
+  ❌ [PARITY-FAIL] FM-007 / happy_path
+      body.order_status: expected "cancelled", got "pending"
+      body.refund_initiated: expected true, got false
+
+─────────────────────────────────
+Parity Results: 118/119 passed (99.2%)
+
+❌ 1 parity check(s) failed.
+[PARITY-BLOCK] UAT/production deployment blocked. Fix parity failures first.
+```
+
+### 結束碼
+
+| 代碼 | 意義 |
+|------|---------|
+| 0 | 所有快照通過 |
+| 1 | 發現失敗 + `--env uat` 或 `production` → 部署被阻擋 |
+| 2 | 發現失敗 + `--env staging` → 僅警告 |
+
+---
+
+## Gate 0：特性化測試協議（重構）
+
+在開始任何重構之前，特性化測試必須存在且通過。
+
+### 什麼是特性化測試？
+
+特性化測試記錄現有程式碼*實際的行為*——而非它*應有的行為*。它們在修改開始前鎖定可觀察的行為。若重構期間特性化測試失敗，代表行為發生了非預期的變更。
+
+```typescript
+describe('characterization: OrderService.cancelOrder', () => {
+  // @characterization
+  it('returns status cancelled and sets refund_initiated=true for valid order', async () => {
+    const result = await orderService.cancelOrder('test-order-123', 'customer_request');
+    expect(result.order_status).toBe('cancelled');
+    expect(result.refund_initiated).toBe(true);
+  });
+});
+```
+
+### Gate 0 強制執行
+
+1. **第一次重構 commit 前**：執行 `npm test -- --grep characterization`
+   - 任何失敗 → 停止。先修復現有程式碼，再進行修改。
+2. **重構期間**：每次 commit 重新執行特性化測試
+   - 任何失敗 → 立即警告行為偏移
+3. **Gate 2（完成）**：所有特性化測試通過 → 重構完成
+
+### 反模式警告
+
+> 絕不要在沒有 Gate 0 的情況下開始重構。一旦開始修改程式碼，就無法判斷測試失敗究竟是「我破壞了某些東西」還是「測試對舊行為的描述有誤」。
+
+---
+
+## 與遷移 Pipeline 整合
+
+### Gate 1 預飛行（`--variant migration`）
+
+在執行 `/vo-pipeline --variant migration` 之前：
+1. `artifacts/feature-manifest.yaml` 必須存在
+2. `.snapshots/` 必須包含每個功能至少一個快照
+
+### 一致性閘門（UAT 前）
+
+所有功能實作完成後，執行一致性檢查：
+- 要求 100% 通過率（不含 `MANUAL-` 檔案）
+- 任何失敗皆阻擋 UAT 晉升
+
+---
+
+## 反模式
+
+| 反模式 | 影響 | 正確做法 |
+|--------------|--------|------------------|
+| 過度使用 `ignore_fields` | 隱藏業務邏輯差異 | 僅忽略非確定性欄位 |
+| 跳過 MANUAL 快照 | Webhook/背景行為未測試 | UAT 前先撰寫 MANUAL 快照 |
+| 從損壞的系統錄製快照 | 基準線錯誤 | 錄製前先驗證舊系統行為 |
+| 只比較反序列化後的物件 | 序列化格式 bug（數字格式、`null` vs 缺漏 key、key 排序、型別強制轉換）在 parse 時被 normalize 掉 | 比對原始序列化字串，或明確斷言 JSON 形狀（見「序列化格式對等」） |
+| 對非確定性欄位採整欄 `ignore_fields` | 遮蔽該欄位的**格式**漂移（時間戳精度／時區、UUID 版本） | 忽略其值但仍斷言格式／形狀（見「`ignore_fields` 使用指南」） |
+| 特性化測試缺少 `@characterization` | Gate 0 找不到它們 | 一律加上 `@characterization` 標記 |
+| 未進行 Gate 0 就開始重構 | 無法偵測行為偏移 | 先跑特性化測試，始終如此 |
+
+---
+
+## 相關標準
+
+- [功能清單標準](../../../core/feature-manifest-standard.md) — 功能清單中 FM-NNN 的 schema
+- [驗收條件追蹤](../../../core/acceptance-criteria-traceability.md) — `not_implemented` AC 狀態
+- [重構標準](../../../core/refactoring-standards.md) — 特性化測試需求
+- [測試標準](../../../core/testing-standards.md) — 測試實作標準
+- [資料遷移測試](../../../core/data-migration-testing.md) — 同樣的「別只比看起來相等」原則，作用於 DB 儲存層（byte／codepoint 編碼），而非 oracle／序列化層
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|---------|------|---------|
+| 1.0.0 | 2026-05-12 | 初始版本 — 快照 schema、一致性閘門、Gate 0 特性化協議（XSPEC-201） |
+| 1.1.0 | 2026-06-28 | 比對保真度補強（XSPEC-306）— `ignore_fields` 改寫為「忽略值、斷言格式」；新增「序列化格式對等」章節（原始 vs. JSON 形狀斷言、PHP↔C# 序列化器預設）；2 條格式遮蔽反模式；與 data-migration-testing 交叉引用 |

package/bundled/locales/zh-TW/core/browser-compatibility-standards.md

@@ -4,6 +4,7 @@ source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-06-02
 source_hash: b806494266e8
+status: stale
 ---
 
 # 瀏覽器相容性標準