universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-TW/core/policy-as-code-testing.md

@@ -0,0 +1,203 @@
+---
+source: ../../../core/policy-as-code-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 80f3b5726ad3
+status: current
+---
+
+# Policy as Code 測試標準
+
+> **Language**: [English](../../../core/policy-as-code-testing.md) | 繁體中文
+
+> 標準 ID：`policy-as-code-testing`
+> 版本：v1.0.0
+> 最後更新：2026-05-05
+
+---
+
+## 為什麼需要測試 Policy as Code？
+
+OPA（Open Policy Agent）的 Rego policy 控制 AI Agent 能否執行生產環境操作。**未測試的 policy = 靜默的安全漏洞。**
+
+Policy as Code 的特殊風險：
+1. **邊界條件難以推理**：`reversible: false` + `target_env: "prod"` 組合是否觸發？
+2. **型別錯誤只在執行時爆發**：`array.concat()` 用在 set 型別 → 靜默失效
+3. **Fail-Open 風險**：評估失敗若回傳 `allow: true`，攻擊者可觸發未定義路徑
+4. **Policy 改動回歸**：新增一條 rule 可能意外放行原本被擋的案例
+
+---
+
+## 一、OPA 測試框架
+
+### 測試規則格式
+
+```rego
+# 檔案命名：<policy_module>_test.rego
+# Package：<policy_package>_test
+package governance.guardian.forbidden_patterns_test
+
+import future.keywords.if
+
+# 正向測試：規則應觸發（assert rule fires）
+test_drop_database_is_forbidden if {
+    data.governance.guardian.forbidden_patterns.has_forbidden_pattern with input as {
+        "plan": [{"command_type": "sql", "command": "DROP DATABASE prod_main", "reversible": false}]
+    }
+}
+
+# 負向測試：規則不應觸發（assert rule does NOT fire）
+test_safe_select_is_not_forbidden if {
+    not data.governance.guardian.forbidden_patterns.has_forbidden_pattern with input as {
+        "plan": [{"command_type": "sql", "command": "SELECT * FROM users LIMIT 10", "reversible": true}]
+    }
+}
+```
+
+### 執行方式
+
+```bash
+# OPA 已安裝時
+opa test src/guardian/policies/ -v
+
+# 透過 Docker（不需安裝 OPA）
+docker run --rm \
+  -v "$(pwd)/src/guardian/policies:/policies:ro" \
+  openpolicyagent/opa:latest-static \
+  test /policies -v
+```
+
+---
+
+## 二、每個 Policy Module 的最低測試要求
+
+| 類型 | 最少案例 | 說明 |
+|------|---------|------|
+| ALLOW cases | 2 | 應該通過的正常操作 |
+| DENY cases | 3 | 應該被攔截的危險操作 |
+| Boundary cases | 1 | 邊界條件（如 reversible=true vs. false）|
+| Integration（main policy）| 2 | 整合 main.rego 的允許 + 拒絕路徑 |
+
+---
+
+## 三、Policy Module 設計原則
+
+### 3.1 Fail-Closed 預設
+
+```rego
+# main.rego 必須包含以下預設
+default allow = false
+
+allow if {
+    not data.governance.guardian.forbidden_patterns.has_forbidden_pattern
+    not data.governance.guardian.env_policy.prod_violation
+    not data.governance.guardian.logic_constraints.has_logic_violation
+}
+```
+
+任何 `undefined` 評估結果都應回傳 DENY，不能回傳 ALLOW。
+
+### 3.2 使用 Set（不要 array.concat）
+
+OPA ≥ 0.40 的型別系統嚴格區分 array 和 set。`violations` partial rule 是 set 型別，**不可用 `array.concat()`**。
+
+```rego
+# ✅ 正確：partial set rule 集合 violations
+deny_reasons[r] if { r := data.governance.guardian.forbidden_patterns.violations[_] }
+deny_reasons[r] if { r := data.governance.guardian.env_policy.violations[_] }
+deny_reasons[r] if { r := data.governance.guardian.logic_constraints.violations[_] }
+
+# ❌ 錯誤：array.concat 用在 set 上 → rego_type_error
+# deny_reasons := array.concat(violations1, violations2)
+```
+
+### 3.3 禁止解析自由文字欄位
+
+Policy 決策**不得依賴** `intent`、`description`、`annotation` 等使用者可控文字欄位。
+
+```rego
+# ❌ 危險：解析 intent 欄位 → Prompt Injection 攻擊面（OWASP LLM01）
+allow if { contains(input.intent, "EMERGENCY") }
+
+# ✅ 安全：只使用結構化欄位
+allow if {
+    input.target_env != "prod"
+    every step in input.plan { step.reversible == true }
+}
+```
+
+### 3.4 一個 Module 管一個關注點
+
+```
+policies/
+  forbidden_patterns.rego      ← 禁止指令模式
+  forbidden_patterns_test.rego
+  env_policy.rego              ← 環境特定規則（prod 保護）
+  env_policy_test.rego
+  logic_constraints.rego       ← 邏輯一致性（stop+start 用 restart）
+  logic_constraints_test.rego
+  risk_gate.rego               ← 風險分數閾值
+  risk_gate_test.rego
+  main.rego                    ← 整合所有 module，Fail-Closed
+  main_test.rego               ← 整合測試
+```
+
+---
+
+## 四、CI 整合
+
+### GitHub Actions 步驟
+
+```yaml
+- name: Test OPA Rego Policies
+  run: |
+    docker run --rm \
+      -v "${{ github.workspace }}/src/guardian/policies:/policies:ro" \
+      openpolicyagent/opa:latest-static \
+      test /policies -v
+```
+
+### npm script
+
+```json
+{
+  "test:policy": "docker run --rm -v \"$(pwd)/src/guardian/policies:/policies:ro\" openpolicyagent/opa:latest-static test /policies -v"
+}
+```
+
+---
+
+## 五、品質閘門
+
+| 閘門 | 閾值 | 強制程度 |
+|------|------|---------|
+| OPA 測試通過率（CI） | 100%（所有 test_ rule 通過）| Block merge |
+| Root policy Fail-Closed | `default allow = false` 存在 | Block merge |
+| 每個 policy module 有 _test.rego | 每個 .rego 有對應測試 | Advisory |
+
+---
+
+## 六、反模式（Anti-patterns）
+
+| 反模式 | 問題 | 正確做法 |
+|--------|------|---------|
+| `array.concat()` 用在 violations（set 型）| OPA 型別錯誤 | 改用 partial set rule |
+| Root policy 缺少 `default allow = false` | Fail-Open 漏洞 | 加入 default |
+| Intent 欄位參與安全決策 | Prompt Injection 攻擊面 | 只用結構化欄位 |
+| 只測試 DENY（無 ALLOW 測試）| 無法偵測過度限制 | 加入 ALLOW 案例 |
+| _test.rego 只在本機跑，不在 CI | policy 改動無安全網 | CI 加 `opa test` step |
+
+---
+
+## 參考標準
+
+- [OPA Testing Guide](https://www.openpolicyagent.org/docs/latest/policy-testing/)
+- NIST SP 800-204C — Attribute-based Access Control
+- [UDS `secure-op.ai.yaml`](../../../core/secure-op.md) — AI Agent 安全操作六大支柱
+- [UDS `adversarial-test.ai.yaml`](../../../core/adversarial-test.md) — 對抗性測試（OWASP LLM01）
+- [UDS `container-security.ai.yaml`](../../../core/container-security.md) — 容器安全（OPA Sidecar 部署）
+
+---
+
+**Scope**: universal

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

@@ -0,0 +1,88 @@
+---
+source: ../../../core/prd-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: 3addb642ee83
+status: current
+---
+
+# 產品需求文件（PRD）標準
+
+> **Language**: [English](../../../core/prd-standards.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/prd-standards.ai.yaml`
+> **規格**: XSPEC-069（cross-project/specs/XSPEC-069-uds-product-layer-pack.md）
+
+## 概觀
+
+本標準定義**產品需求文件（PRD）**的結構、內容要求與生命週期治理。涵蓋五大必備
+PRD 段落、從 PRD 需求銜接至可追溯 user story，以及 kickoff 後變更的修訂政策。確保
+產品意圖能以可量化成功標準清楚傳達給工程、設計與利害關係人。
+
+本標準屬於**產品層標準包**（XSPEC-069）。PRD 是工程需求的*上游*：PRD → user story
+→ requirement。它銜接 `requirement-engineering`（需求的工程視角），並消費
+`product-metrics-standards` 作為成功指標。
+
+> **範圍**：本標準定義 *PRD 產物*（段落、追溯性、修訂政策）。這是 UDS 的產品層邊緣
+> （依 XSPEC-070 `standard-admission-criteria`）——需求的工程視角仍留在
+> `requirement-engineering`。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | PRD 五大段落（問題、persona、成功指標、範圍、限制） | MUST |
+| REQ-002 | PRD → user story 銜接（INVEST、可追溯至成功指標） | MUST |
+| REQ-003 | 修訂政策（kickoff 後的正式變更流程） | MUST |
+
+### REQ-001 — PRD 五大段落
+
+每份 PRD MUST 依序包含五段落：(1) **Problem Statement**——以可觀察詞語描述使用者
+痛點／機會，並盡量附量化資料；(2) **Target User / Persona**——誰受影響，引用具名
+persona（≥1 主要、≥1 次要）含角色、情境與目標；(3) **Success Metrics**——2~4 個可
+量化結果，各含現況 baseline、目標值與量測方法；(4) **Scope In / Out**——明確列出
+包含與排除（排除項可引用未來 PRD）；(5) **Constraints**——技術、法規、時間、預算或
+相依性限制。
+
+### REQ-002 — PRD 至 User Story 銜接
+
+每個 PRD 需求 MUST 拆解為一個以上 user story，遵循 `requirement-engineering` 的
+INVEST 原則。每個由 PRD 衍生的 story MUST 可追溯至至少一個 PRD 成功指標；無法連結
+的 story MUST 在進 backlog 前標記供 PM 審視。追溯連結（PRD 段落 ID → user story ID
+→ 成功指標）MUST 維護於 backlog 工具或 PRD 中的矩陣。
+
+### REQ-003 — 修訂政策
+
+開發 kickoff 會議後請求的 PRD 變更 MUST 遵循正式流程：(1) 以理由與影響評估記錄
+提案變更；(2) 取得 PM、Tech Lead 與 Design Lead 的簽核；(3) 評估範圍影響——新增
+範圍須將對應項目移出範圍或調整時程；(4) 更新版本歷史，含日期、作者、變更摘要與
+核准者。kickoff 後修改卻無版本歷史的 PRD 視為不合規。輕微編輯變更（錯字、排版）
+豁免簽核。
+
+## 反樣態
+
+- PRD 無可量化成功指標（僅質性目標，如「改善 UX」）。
+- 範圍蔓延而無變更紀錄：sprint 中途新增需求且未記錄核准。
+- 解法優先（solution-first）的 PRD：在確立使用者問題前先描述實作細節。
+- 無明確的 out-of-scope 段落，導致開發期間的邊界爭議。
+- 開發開始後才定義成功指標，使其無法驗證。
+
+## 與既有標準的整合
+
+- **`requirement-engineering`**——PRD 需求拆解為 INVEST user story。
+- **`product-metrics-standards`**——PRD 成功指標取自指標階層。
+- **`user-story-mapping`**——PRD 範圍實現為 story map 與 MVP 切片。
+- **`acceptance-criteria-traceability`**——story 帶有可追溯回 PRD 指標的 AC。
+
+## 相關規格
+
+- XSPEC-069 — UDS 產品層標準包（本標準來源）
+- XSPEC-070 — 治理 meta 標準（`standard-admission-criteria` 邊緣審視）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~003：五大段落、PRD→story 銜接、修訂政策（XSPEC-069） |

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

@@ -3,7 +3,7 @@ source: ../../../core/privacy-standards.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-04-10
-status: current
+status: stale
 ---
 
 # 隱私標準

package/bundled/locales/zh-TW/core/product-metrics-standards.md

@@ -0,0 +1,96 @@
+---
+source: ../../../core/product-metrics-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: e37a44aefd92
+status: current
+---
+
+# 產品指標框架標準
+
+> **Language**: [English](../../../core/product-metrics-standards.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/product-metrics-standards.ai.yaml`
+> **規格**: XSPEC-069（cross-project/specs/XSPEC-069-uds-product-layer-pack.md）
+
+## 概觀
+
+本標準定義團隊如何**選擇、結構化與治理產品指標**。涵蓋框架選用矩陣（成長型用
+AARRR、體驗型用 HEART、平台型用自訂北極星）、北極星準則、三層指標階層（北極星 →
+L1 driver → L2 diagnostic），以及拒絕與營收／留存脫鉤指標的反虛榮（anti-vanity）
+規則。使團隊圍繞能驅動有意義產品決策的指標對齊，而非活動追蹤。
+
+本標準屬於**產品層標準包**（XSPEC-069）。其追蹤要求連接 SRE 可觀測性基本元件
+（`observability-standards`、`slo-sli`）。
+
+> **範圍**：本標準定義*指標選擇與治理*。具體分析工具（Amplitude/Mixpanel）屬採用者
+> 的選擇。服務層級可靠性指標置於 `slo-sli`；此處為產品結果視角。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | 框架選用矩陣（AARRR / HEART / 自訂北極星） | MUST |
+| REQ-002 | 北極星準則（leading、可量測、actionable、可解釋） | MUST |
+| REQ-003 | 指標階層（最多三層） | MUST |
+| REQ-004 | 反虛榮規則 | MUST |
+
+### REQ-001 — 框架選用矩陣
+
+團隊 MUST 依產品類型選擇主要指標框架：**成長型產品**（消費 app、市集、病毒式產品）
+→ **AARRR**（Acquisition、Activation、Retention、Referral、Revenue）；**體驗型
+產品**（生產力工具、B2B SaaS）→ **HEART**（Happiness、Engagement、Adoption、
+Retention、Task Success）；**平台型產品**（開發者平台、API）→ 反映平台價值的
+**自訂北極星**，並視情況以 AARRR 或 HEART 元件補充。框架選用 MUST 記載於 PRD 或
+產品策略文件。
+
+### REQ-002 — 北極星準則
+
+每個產品 MUST 定義恰好一個北極星指標，滿足全部四項準則：(1) **Leading
+indicator**——預測未來業務健康而非量測過去結果；(2) **可量測且可追蹤**——可由可得
+資料以既定頻率（週／月）計算；(3) **團隊可施力**——產品團隊有直接槓桿可影響；
+(4) **一句話可解釋**。北極星 MUST 於每年產品規劃週期審視並再確認。
+
+### REQ-003 — 指標階層
+
+團隊 MUST 將指標結構化為至多三層階層。**Level 1（北極星）**：一個代表整體產品價值
+的指標。**Level 2（L1 driver）**：3~5 個直接影響北極星的指標，各具文件化的因果
+假設。**Level 3（L2 diagnostic）**：解釋 L1 driver 變動的 per-feature／per-team
+指標（每個 driver 最多 3 個）。超過三層的指標為 PROHIBITED——代表量測碎片化而非
+聚焦。
+
+### REQ-004 — 反虛榮規則
+
+團隊 MUST 在將任何指標加入官方儀表板前套用反虛榮測試。若某指標可在營收與留存持平
+或下降時上升，即測試失敗；此類指標 MUST NOT 出現於官方產品審視或作為功能成功標準。
+常見失敗：總註冊用戶（無活躍篩選）、原始 pageview（無 session 品質篩選）、總 API
+呼叫（無唯一活躍客戶篩選）、媒體提及、無 activation 的下載數。當虛榮指標於營運監控
+有用時，MUST 明確標示為「operational indicator, not success metric」。
+
+## 反樣態
+
+- 將虛榮指標（總註冊、原始 pageview）作為主要成功指標追蹤。
+- 未定義北極星——團隊各自最佳化不同局部指標，造成失準。
+- 團隊指標衝突，一隊的最佳化損害另一隊的指標。
+- 指標階層深於三層——複雜而無洞見。
+- 每季變更北極星，妨礙年對年趨勢分析。
+
+## 與既有標準的整合
+
+- **`prd-standards`**——PRD 成功指標取自此階層。
+- **`observability-standards` / `slo-sli`**——產品指標的*追蹤*複用 SRE 指標／可觀測
+  性基本元件；可靠性 SLO 仍留在 `slo-sli`。
+- **`user-story-mapping`**——story 驗收條件對應北極星 driver。
+
+## 相關規格
+
+- XSPEC-069 — UDS 產品層標準包（本標準來源）
+- XSPEC-063 — SRE 標準包（`observability-standards`、`slo-sli`）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~004：框架矩陣、北極星準則、指標階層、反虛榮規則（XSPEC-069） |

package/bundled/locales/zh-TW/core/project-context-memory.md

@@ -3,7 +3,7 @@ source: ../../../core/project-context-memory.md
 source_version: 1.1.0
 translation_version: 1.1.0
 last_synced: 2026-03-24
-status: current
+status: stale
 ---
 
 # 專案情境記憶標準

package/bundled/locales/zh-TW/core/prompt-regression.md

@@ -0,0 +1,88 @@
+---
+source: ../../../core/prompt-regression.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 25070d0b8a98
+status: current
+---
+
+# Prompt 回歸測試標準
+
+> **語言**: [English](../../../core/prompt-regression.md) | 繁體中文
+
+---
+
+## 概述
+
+AI 代理的 prompt 即程式碼。未預期的變更會悄悄降低代理行為品質，卻不會觸發型別錯誤或單元測試失敗。Prompt 回歸測試利用 SHA-256 黃金校驗和（golden checksum）偵測任何修改，強制開發者明確確認並記錄每次 prompt 變更。
+
+## 為什麼要使用校驗和
+
+- 僅有 diff 不能阻擋 CI 流程——校驗和可以
+- Prompt 是大型 Markdown 檔案；細微的編輯（空白字元、標點符號）都可能改變模型行為
+- 校驗和更新 + 說明註解會建立每次 prompt 變更原因的稽核軌跡
+
+## 實作方式
+
+### 1. 計算初始校驗和
+
+```bash
+for f in agents/*/prompt.md; do
+  echo -n "$f: "
+  sha256sum "$f" | cut -d' ' -f1
+done
+```
+
+### 2. 黃金校驗和測試（Vitest）
+
+```typescript
+// SPDX-License-Identifier: AGPL-3.0-only
+import { createHash } from "crypto"
+import { readFileSync } from "fs"
+import { join } from "path"
+import { describe, it, expect } from "vitest"
+
+// 僅在 prompt 變更為刻意行為時才更新這些值。
+// 在同一行加上說明 WHY prompt 發生變更的註解。
+const GOLDEN_CHECKSUMS: Record<string, string> = {
+  architect: "98017d39b0e48cda88b796687d21e0f884c810805e534453a23b7ad935e4a5ef",
+  builder:   "5c2acda3e48dae771c61f55d3a5b0d5ac7383870054ef71e757714e367c50031",
+  // ... 所有代理
+}
+
+describe("Agent prompt regression (XSPEC-162)", () => {
+  for (const [agent, expected] of Object.entries(GOLDEN_CHECKSUMS)) {
+    it(`agents/${agent}/prompt.md checksum matches golden`, () => {
+      const filePath = join(__dirname, "..", "..", "agents", agent, "prompt.md")
+      const content = readFileSync(filePath)
+      const actual = createHash("sha256").update(content).digest("hex")
+      expect(actual, `Prompt for '${agent}' changed unexpectedly. If intentional, update GOLDEN_CHECKSUMS with a comment.`).toBe(expected)
+    })
+  }
+})
+```
+
+### 3. CI 整合
+
+校驗和測試作為標準 `npm run test:coverage` 閘門的一部分執行（已透過 XSPEC-156 強制執行）。不需要額外的 CI 步驟。
+
+### 4. 更新校驗和
+
+當 prompt 變更為刻意行為時：
+
+```typescript
+// 之前：
+architect: "98017d39...",  // updated 2026-05-05: added Guardian policy XSPEC-160 reference
+```
+
+說明註解是必填的。在程式碼審查時，應拒絕未附說明註解即更新校驗和的 PR。
+
+## 相關標準
+
+- [LLM 輸出驗證](../../../core/llm-output-validation.md) — schema 層級驗證
+- [對抗性測試](../../../core/adversarial-test.md) — 紅隊語料庫
+- [測試標準](../../../core/testing-standards.md) — 整體測試金字塔
+
+
+**Scope**: universal

package/bundled/locales/zh-TW/core/property-based-testing.md

@@ -0,0 +1,87 @@
+---
+source: ../../../core/property-based-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 13f5eba04aef
+status: current
+---
+
+# Property-Based Testing 標準
+
+> **Language**: [English](../../../core/property-based-testing.md) | 繁體中文
+
+## 概述
+
+基於範例的測試只能驗證開發者想得到的案例。Property-based testing 反轉了這個思路：你定義一個不變量（「分數永遠介於 0 到 100 之間」），框架會產生數百個輸入來嘗試推翻它。當找到失敗的輸入時，框架會將其縮減（shrink）為最小反例。
+
+## 使用時機
+
+| 使用 Property 測試 | 使用範例測試 |
+|-------------------|------------------|
+| 純數學函式 | 複雜業務邏輯 |
+| 解析器 / 序列化器 | 整合路徑 |
+| 分數截斷 / 四捨五入 | UI 行為 |
+| 雜湊 / 編碼 | 資料庫操作 |
+| 安全驗證器 | 外部 API 呼叫 |
+
+## 工具：fast-check（TypeScript）
+
+```bash
+npm install --save-dev fast-check
+```
+
+```typescript
+import fc from "fast-check"
+import { describe, it, expect } from "vitest"
+import { classifyTokenZone, TOKEN_BUDGET } from "../types/index.js"
+
+describe("classifyTokenZone property: result is always a valid zone", () => {
+  it("for any ratio in [0, 2], returns a valid TokenBudgetZone", () => {
+    fc.assert(
+      fc.property(
+        fc.float({ min: 0, max: 2, noNaN: true }),
+        (ratio) => {
+          const zone = classifyTokenZone(ratio)
+          return ["safe", "warning", "danger", "blocking"].includes(zone)
+        }
+      ),
+      { numRuns: 1000 }
+    )
+  })
+})
+```
+
+## Guardian scoreReviewable 屬性
+
+需要測試的關鍵不變量：
+
+| 屬性 | 說明 |
+|----------|-------------|
+| **範圍截斷** | `score` 永遠在 `[0, 100]` 範圍內 |
+| **確定性** | 相同輸入永遠產生相同分數 |
+| **單調性** | 對相同操作，prod > staging > dev |
+| **非負性** | `breakdown` 的值全部 >= 0 |
+
+## 反例縮減（Counterexample Shrinking）
+
+當 fast-check 找到失敗案例時，會自動縮減：
+
+```
+Original failure: { target_env: "prod", command: "rm -rf /tmp/xyz123...", ... }
+Shrunk to:        { target_env: "prod", command: "rm", ... }
+```
+
+從錯誤訊息中儲存 seed 以便重現：
+```typescript
+fc.assert(property, { seed: 1234567890 })
+```
+
+## 相關標準
+
+- [Mutation Testing 標準](mutation-testing.md) — PBT 的互補
+- [測試標準](testing-standards.md) — 整體測試金字塔
+- [Adversarial Test 標準](adversarial-test.md) — 以安全為導向的 fuzzing
+
+
+**Scope**: universal

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

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/refactoring-standards.md
-source_version: 2.1.0
-translation_version: 2.1.0
-last_synced: 2026-04-22
+source_version: 2.2.0
+translation_version: 2.2.0
+last_synced: 2026-07-01
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../core/refactoring-standards.md) | 繁體中文
 
-**版本**: 2.1.0
-**最後更新**: 2026-02-10
+**版本**: 2.2.0
+**最後更新**: 2026-07-01
 **適用性**: 所有軟體專案
 **範圍**: 通用 (Universal)
 
@@ -64,10 +64,46 @@ status: current
 
 ---
 
+## 語意重複與 Copy-Drift（語意重複）
+
+文字重複（textual duplication）指標只能抓到逐字複製，卻抓不到更危險的情況：**同一個 domain fact 在多處被重複實作**。當這些實作不是逐字相同時（改寫過的分類邏輯、同一條公式在一處對一處錯、把 total 與它彙總的 rows 分開儲存），它們會通過靜態分析，然後**各自獨立地漂移**，產生看似無關、實則同源的一叢 bug。
+
+### 反模式：Copy-Drift
+
+Copy-Drift 發生於下列任一情況：
+
+- 單一 domain fact（分類、規則、計算）被**在多個 call site 重複實作**，而非由單一共用單元計算；或
+- **derived value 被持久化**（stored aggregate、counter、denormalized 欄位）**卻無與來源綁定的強制關係**，使每條 write path 都能各自更新它。
+
+因為這些 copy 並非逐字相同，文字重複工具一個都抓不到。漂移會在稍後以不一致的形式浮現：list view 與 detail view 對不上、stored counter 因某條更新路徑的 decrement/rollback 分支被略過或被註解掉而重複計數、或同一條公式在不同模組給出不同答案。
+
+### 模式：Single Source of Truth / Derive-Don't-Duplicate
+
+- **每個 fact 只有一個單元**：把每個 domain fact 抽成**唯一**的 classifier / calculator / resolver；所有 call site 都呼叫它——不重實作、不改寫。
+- **優先 derive，不要 store**：優先在 read 時計算，而非持久化第二份 copy；永遠被 derive 的值不會漂移。
+- **若 aggregate 一定要存**，把它當成 detail rows 的 **projection**，並在**單一 choke point**（例如 `SaveChanges` interceptor，或單一共用 `recompute()` 函式）重算，讓**每一條** write path（含 async job 與 failure write-back）都走同一個重算路徑而保持一致。**絕不**讓個別 path 對 stored aggregate 做 incremental `col = col + delta` 調整；incremental 調整正是 decrement/rollback 分支被略過、counter 發生漂移的原因。
+- **用測試鎖定**：用 **golden test** 鎖定 single source of truth，並加一個 **architecture test**——若規則在別處被重新定義就 fail，讓未來的 copy 在 CI 被擋下，而非在 production 才發現。
+
+### 遷移推論——Intentional-Divergence Registry（刻意偏離登記）
+
+當新系統**刻意**偏離 legacy 行為時，必須登記——否則未來某次「修正」會靜默地把它回退掉。port 過程中常見的情況：legacy *函式*回傳 X，但 legacy *pipeline* 在下游把它調和成 Y；port 把這個調和折進單一單元，讓函式直接回傳 Y。
+
+- 把每個刻意偏離登記在 **intentional-divergence registry**（legacy 行為、new 行為、rationale、所屬 fact）。
+- 用 **golden test** 鎖定 new 行為，讓未來「修正」回 legacy 會讓 build fail。
+- 把 registry 餵給對 legacy 的任何 **differential test**，使該偏離被視為**預期**而非 regression。
+
+### 給採用者的註記
+
+- per-function 的 legacy-vs-new diffing 只產出**候選**，非裁決；每個候選都要對照**整條** legacy pipeline（下游可能已調和該差異）裁決後，才能稱為 bug。
+- 用 programmatic / token-based 方式抽取 legacy 函式本體（不要手抄），避免在調查抄寫錯誤時又重新引入抄寫錯誤。
+
+---
+
 ## 相關標準
 
 - [重構指南](guides/refactoring-guide.md) - 詳細模式與教學
-- [測試標準](testing-standards.md)
+- [測試標準](testing-standards.md) - golden test 與 architecture test 鎖定 single source of truth
+- [測試治理](test-governance.md) - 在 CI 治理語意重複與 intentional-divergence 檢查
 - [程式碼審查清單](code-review-checklist.md)
 
 ---
@@ -76,6 +112,7 @@ status: current
 
 | 版本 | 日期 | 變更 |
 |------|------|------|
+| 2.2.0 | 2026-07-01 | 新增「語意重複與 Copy-Drift」（issue #142）：Copy-Drift 反模式、Single Source of Truth / Derive-Don't-Duplicate 模式、Intentional-Divergence Registry 遷移推論。 |
 | 2.0.0 | 2026-01-29 | **重大重構**：拆分為規則（本文件）和指南（refactoring-guide.md）。 |
 | 1.0.0 | 2025-12-15 | 初始版本 |