universal-dev-standards 5.15.1 → 5.17.0

package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md

@@ -3,7 +3,8 @@ name: dev-workflow-guide
 source: ../../../../skills/dev-workflow-guide/SKILL.md
 source_version: 1.0.0
 translation_version: 1.0.0
-last_synced: 2026-03-24
+last_synced: 2026-06-02
+source_hash: 5bf83f0db544
 status: current
 description: "[UDS] 將軟體開發階段對應到 UDS 指令與功能的指南"
 ---
@@ -19,27 +20,29 @@ description: "[UDS] 將軟體開發階段對應到 UDS 指令與功能的指南"
 ## 軟體開發階段總覽
 
 ```
-I. 規劃設計 ──► II. 測試驅動開發 ──► III. 程式碼開發 ──► IV. 品質保證
+I. Planning ──► II. Testing Design ──► III. Implementation ──► IV. Quality Gates
+   需求設計          測試驅動開發            程式碼開發              品質保證
 
-V. 版本提交 ──► VI. 文件與架構 ──► VII. 工具與標準 ──► VIII. 進階分析
+V. Release ──► VI. Documentation ──► VII. Standards ──► VIII. Advanced
+   版本提交         文件與架構              工具與標準           進階分析
 ```
 
 ### 快速對照表
 
-| 階段 | UDS 指令 | 用途 |
-|------|----------|------|
-| **I. 規劃與設計** | `/brainstorm` `/requirement` `/sdd` `/reverse` | 需求、規格、逆向工程 |
-| **II. 測試驅動開發** | `/bdd` `/atdd` `/tdd` `/coverage` `/derive` | 先寫測試再寫程式 |
-| **III. 實作** | `/refactor` `/reverse` | 撰寫與改善程式碼 |
-| **IV. 品質關卡** | `/checkin` `/review` | 提交前檢查與程式碼審查 |
-| **V. 發布與提交** | `/commit` `/changelog` `/release` | 版本、提交、發布 |
-| **VI. 文件** | `/docs` `/docgen` `/struct` | 文件與專案結構 |
-| **VII. 工具與標準** | `/discover` `/testing` `/guide` `/git` | 參考指南 |
-| **VIII. 進階分析** | `/methodology` | 跨方法論工作流程 |
+| 階段 | UDS 指令 | 目的 | 用途 |
+|------|----------|------|------|
+| **I. 規劃與設計** | `/brainstorm` `/requirement` `/sdd` `/reverse` `/api-design` `/database` | Requirements, specs, API/DB design | 需求、規格、API/DB 設計 |
+| **II. 測試驅動開發** | `/bdd` `/atdd` `/tdd` `/coverage` `/derive` `/ac-coverage` | Design tests before code | 先寫測試再寫程式 |
+| **III. 實作** | `/refactor` `/reverse` `/migrate` `/durable` | Write, improve, and migrate code | 撰寫、改善與遷移程式碼 |
+| **IV. 品質關卡** | `/checkin` `/review` `/security` `/scan` `/incident` | Quality, security, incident response | 品質、安全、事故回應 |
+| **V. 發布與提交** | `/commit` `/changelog` `/release` `/pr` `/ci-cd` | Version, commit, PR, CI/CD | 版本、提交、PR、CI/CD |
+| **VI. 文件** | `/docs` `/docgen` | Docs and project structure | 文件與專案結構 |
+| **VII. 工具與標準** | `/discover` `/guide` `/metrics` `/audit` | Reference guides, metrics, audit | 參考指南、指標、審計 |
+| **VIII. 進階分析** | `/methodology` | Cross-methodology workflows | 跨方法論工作流程 |
 
 ## 常見場景
 
-### 場景 1：新功能開發
+### 場景 1：新功能開發（Greenfield）
 
 從零開始建立新功能的推薦流程：
 
@@ -47,15 +50,15 @@ V. 版本提交 ──► VI. 文件與架構 ──► VII. 工具與標準 ─
 /brainstorm → /requirement → /sdd → /derive → /tdd → /checkin → /commit
 ```
 
-| 步驟 | 指令 | 做什麼 |
-|------|------|--------|
-| 1 | `/brainstorm` | 探索想法與方法 |
-| 2 | `/requirement` | 撰寫使用者故事（INVEST 準則） |
-| 3 | `/sdd` | 建立規格文件 |
-| 4 | `/derive` | 從規格產生測試骨架 |
-| 5 | `/tdd` | 用紅綠重構循環實作 |
-| 6 | `/checkin` | 驗證品質關卡 |
-| 7 | `/commit` | 建立規範化提交 |
+| 步驟 | 指令 | 做什麼 | 做什麼 |
+|------|------|--------|--------|
+| 1 | `/brainstorm` | Explore ideas and approaches | 探索想法與方法 |
+| 2 | `/requirement` | Write user stories (INVEST criteria) | 撰寫使用者故事 |
+| 3 | `/sdd` | Create specification document | 建立規格文件 |
+| 4 | `/derive` | Generate test skeletons from spec | 從規格產生測試骨架 |
+| 5 | `/tdd` | Implement with Red-Green-Refactor | 用紅綠重構循環實作 |
+| 6 | `/checkin` | Verify quality gates | 驗證品質關卡 |
+| 7 | `/commit` | Create conventional commit | 建立規範化提交 |
 
 ### 場景 2：修復錯誤
 
@@ -65,13 +68,13 @@ V. 版本提交 ──► VI. 文件與架構 ──► VII. 工具與標準 ─
 /discover → /reverse → /tdd → /checkin → /commit
 ```
 
-| 步驟 | 指令 | 做什麼 |
-|------|------|--------|
-| 1 | `/discover` | 評估受影響區域健康度 |
-| 2 | `/reverse` | 理解現有程式碼結構 |
-| 3 | `/tdd` | 先寫失敗測試，再修復 |
-| 4 | `/checkin` | 驗證品質關卡 |
-| 5 | `/commit` | 建立規範化提交 |
+| 步驟 | 指令 | 做什麼 | 做什麼 |
+|------|------|--------|--------|
+| 1 | `/discover` | Assess affected area health | 評估受影響區域健康度 |
+| 2 | `/reverse` | Understand existing code structure | 理解現有程式碼結構 |
+| 3 | `/tdd` | Write failing test, then fix | 先寫失敗測試，再修復 |
+| 4 | `/checkin` | Verify quality gates | 驗證品質關卡 |
+| 5 | `/commit` | Create conventional commit | 建立規範化提交 |
 
 ### 場景 3：重構
 
@@ -81,41 +84,75 @@ V. 版本提交 ──► VI. 文件與架構 ──► VII. 工具與標準 ─
 /discover → /reverse → /coverage → /refactor → /checkin → /commit
 ```
 
-| 步驟 | 指令 | 做什麼 |
-|------|------|--------|
-| 1 | `/discover` | 評估專案健康度與風險 |
-| 2 | `/reverse` | 記錄目前行為 |
-| 3 | `/coverage` | 確保測試安全網存在 |
-| 4 | `/refactor` | 套用重構策略 |
-| 5 | `/checkin` | 驗證品質關卡 |
-| 6 | `/commit` | 建立規範化提交 |
+| 步驟 | 指令 | 做什麼 | 做什麼 |
+|------|------|--------|--------|
+| 1 | `/discover` | Assess project health and risks | 評估專案健康度與風險 |
+| 2 | `/reverse` | Document current behavior | 記錄目前行為 |
+| 3 | `/coverage` | Ensure test safety net exists | 確保測試安全網存在 |
+| 4 | `/refactor` | Apply refactoring strategies | 套用重構策略 |
+| 5 | `/checkin` | Verify quality gates | 驗證品質關卡 |
+| 6 | `/commit` | Create conventional commit | 建立規範化提交 |
+
+### 場景 4：安全審查
+
+安全審查與漏洞修復的推薦流程：
+
+```
+/scan → /security → /checkin → /commit
+```
+
+| 步驟 | 指令 | 做什麼 | 做什麼 |
+|------|------|--------|--------|
+| 1 | `/scan` | Run automated security scans (deps, secrets) | 執行自動化安全掃描 |
+| 2 | `/security` | Deep security review (OWASP) | 深入安全審查 |
+| 3 | `/checkin` | Verify quality gates | 驗證品質關卡 |
+| 4 | `/commit` | Create conventional commit | 建立規範化提交 |
+
+### 場景 5：API 設計與實作
+
+API 設計與實作的推薦流程：
+
+```
+/brainstorm → /api-design → /sdd → /derive → /tdd → /pr
+```
+
+| 步驟 | 指令 | 做什麼 | 做什麼 |
+|------|------|--------|--------|
+| 1 | `/brainstorm` | Explore API approaches | 探索 API 方案 |
+| 2 | `/api-design` | Design endpoints and schemas | 設計端點與 schema |
+| 3 | `/sdd` | Create specification document | 建立規格文件 |
+| 4 | `/derive` | Generate test skeletons | 產生測試骨架 |
+| 5 | `/tdd` | Implement with tests | 搭配測試實作 |
+| 6 | `/pr` | Create pull request | 建立 Pull Request |
 
 ## 使用方式
 
 ```bash
-/dev-workflow                    # 顯示完整階段總覽
-/dev-workflow planning           # 取得第 I 階段指引
-/dev-workflow testing            # 取得第 II 階段指引
-/dev-workflow new-feature        # 取得新功能工作流程
-/dev-workflow bug-fix            # 取得修復錯誤工作流程
-/dev-workflow refactoring        # 取得重構工作流程
+/dev-workflow                    # Show full phase overview
+/dev-workflow planning           # Get Phase I guidance
+/dev-workflow testing            # Get Phase II guidance
+/dev-workflow new-feature        # Get new feature workflow
+/dev-workflow bug-fix            # Get bug fix workflow
+/dev-workflow refactoring        # Get refactoring workflow
 ```
 
 ### 支援的參數
 
-| 參數 | 說明 |
-|------|------|
-| `planning` | 第 I 階段：規劃與設計 |
-| `testing` | 第 II 階段：測試驅動開發 |
-| `implementation` | 第 III 階段：程式碼開發 |
-| `quality` | 第 IV 階段：品質保證 |
-| `release` | 第 V 階段：版本與提交 |
-| `docs` | 第 VI 階段：文件與架構 |
-| `standards` | 第 VII 階段：工具與標準 |
-| `advanced` | 第 VIII 階段：進階系統分析 |
-| `new-feature` | 場景：新功能開發 |
-| `bug-fix` | 場景：修復錯誤 |
-| `refactoring` | 場景：重構 |
+| 參數 | 說明 | 說明 |
+|------|------|------|
+| `planning` | Phase I: Planning & Design | 需求與設計 |
+| `testing` | Phase II: Test-Driven Development | 測試驅動開發 |
+| `implementation` | Phase III: Implementation | 程式碼開發 |
+| `quality` | Phase IV: Quality Gates | 品質保證 |
+| `release` | Phase V: Release & Commit | 版本與提交 |
+| `docs` | Phase VI: Documentation | 文件與架構 |
+| `standards` | Phase VII: Tools & Standards | 工具與標準 |
+| `advanced` | Phase VIII: Advanced Analysis | 進階系統分析 |
+| `new-feature` | Scenario: New feature workflow | 場景：新功能開發 |
+| `bug-fix` | Scenario: Bug fix workflow | 場景：修復錯誤 |
+| `refactoring` | Scenario: Refactoring workflow | 場景：重構 |
+| `security` | Scenario: Security review workflow | 場景：安全審查 |
+| `api` | Scenario: API design workflow | 場景：API 設計 |
 
 ## 工作流程行為
 
@@ -125,17 +162,41 @@ V. 版本提交 ──► VI. 文件與架構 ──► VII. 工具與標準 ─
 2. **階段參數**：顯示該階段的詳細指引，包含所有相關指令與範例
 3. **場景參數**：顯示該場景的推薦逐步工作流程
 
+此技能會從 [workflow-phases.md](./workflow-phases.md) 讀取詳細的階段資訊。
+
 ## 下一步引導
 
 `/dev-workflow` 完成後，AI 助手應根據使用者情況建議：
 
-> **工作流程已顯示。建議下一步：**
-> - 新功能開發 → 執行 `/brainstorm` 探索想法
-> - 修復錯誤 → 執行 `/discover` 評估受影響區域
-> - 重構程式碼 → 執行 `/discover` 評估健康度
-> - 遺留系統 → 執行 `/reverse` 進行系統考古
+> **工作流程已顯示。建議下一步 / Workflow displayed. Suggested next steps:**
+> - 新功能開發 → 執行 `/brainstorm` 探索想法 ⭐ **Recommended / 推薦** — New feature → Run `/brainstorm` to explore ideas
+> - 修復錯誤 → 執行 `/discover` 評估受影響區域 — Bug fix → Run `/discover` to assess affected area
+> - 重構程式碼 → 執行 `/discover` 評估健康度 — Refactoring → Run `/discover` to assess health
+> - 遺留系統 → 執行 `/reverse` 進行系統考古 — Legacy system → Run `/reverse` for system archeology
+> - 安全審查 → 執行 `/scan` 掃描漏洞 — Security review → Run `/scan` to find vulnerabilities
+> - API 開發 → 執行 `/api-design` 設計端點 — API development → Run `/api-design` to design endpoints
+> - 事故回應 → 執行 `/incident` 啟動回應流程 — Incident → Run `/incident` to start response
 
 ## 參考
 
-- 詳細階段指引：[workflow-phases.md](../../../../skills/dev-workflow-guide/workflow-phases.md)
-- 每日工作流程指南：[DAILY-WORKFLOW-GUIDE.md](../../../../adoption/DAILY-WORKFLOW-GUIDE.md)
+- [詳細階段指引](./workflow-phases.md) - 完整的逐階段參考
+- [每日工作流程指南](../../adoption/DAILY-WORKFLOW-GUIDE.md) - 完整的每日工作流程指南
+- [功能開發工作流程](../workflows/feature-dev.yaml) - 自動化功能開發工作流程
+- [整合流程工作流程](../workflows/integrated-flow.yaml) - 完整的 ATDD/SDD/BDD/TDD 工作流程
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更內容 |
+|------|------|----------|
+| 1.1.0 | 2026-03-24 | 新增 11 個指令、2 個新場景（安全審查、API 設計） |
+| 1.0.0 | 2026-03-04 | 初版：8 個開發階段、3 個場景、以階段為基礎的導覽 |
+
+---
+
+## 授權
+
+本技能以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權釋出。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/skills/knowledge-graph/SKILL.md

@@ -14,7 +14,7 @@ description: "[UDS] 透過知識圖追蹤規格／決策／程式碼的影響鏈
 
 依據[知識圖記憶標準](../../../../core/knowledge-graph-memory.md)的關係 schema，回答橫跨規格、決策與程式碼的結構性問題——*「XSPEC-205 的完整影響鏈是什麼？」*。有無圖引擎皆可運作。
 
-> **Implements**: XSPEC-237 Phase 5 — knowledge-graph skill（CodeSage opt-in）
+> **Implements**: XSPEC-237 Phase 5 — knowledge-graph skill（EngramGraph opt-in）
 
 ## 模式選擇
 
@@ -22,7 +22,7 @@ description: "[UDS] 透過知識圖追蹤規格／決策／程式碼的影響鏈
 
 | 條件 | 模式 |
 |------|------|
-| 設定了 `CODESAGE_URL`，或本機圖引擎 `/health` 有回應 | 服務模式（引擎）|
+| 設定了 `ENGRAM_URL`，或本機圖引擎 `/health` 有回應 | 服務模式（引擎）|
 | 否則 | 降級模式（Markdown）|
 
 ## 工作流程
@@ -31,7 +31,7 @@ description: "[UDS] 透過知識圖追蹤規格／決策／程式碼的影響鏈
 2. **選擇模式**——探測圖引擎（服務）否則後備（降級）。
 3. **服務模式（AC-5b）**——送出單一多跳查詢，呈現回傳的鏈（含跨域連結 code → spec → decision）：
    ```bash
-   curl -s -X POST "$CODESAGE_URL/graph/impact-analysis" \
+   curl -s -X POST "$ENGRAM_URL/graph/impact-analysis" \
      -H 'content-type: application/json' \
      -d '{"nodeId":"XSPEC-205","maxHops":3}'
    ```
@@ -45,12 +45,12 @@ description: "[UDS] 透過知識圖追蹤規格／決策／程式碼的影響鏈
 
 ## 下一步引導
 
-- 降級模式若觸及讀取深度上限，告知使用者圖引擎（如 CodeSage）可給出完整鏈，以及如何設定 `CODESAGE_URL`。
+- 降級模式若觸及讀取深度上限，告知使用者圖引擎（如 EngramGraph）可給出完整鏈，以及如何設定 `ENGRAM_URL`。
 - 若參照的 id 找不到，標示為待修的懸空參照。
 - 主動提議為遍歷過的文件補上缺漏的 `impacts`/`impacted_by` front-matter。
 
 ## 參考
 
 - 標準：[core/knowledge-graph-memory.md](../../../../core/knowledge-graph-memory.md)
-- 引擎（opt-in）：[CodeSage](https://github.com/AsiaOstrich/CodeSage) — `@asiaostrich/codesage`
+- 引擎（opt-in）：[EngramGraph](https://github.com/AsiaOstrich/EngramGraph) — `engramgraph`
 - 詳細指南：[guide.md](guide.md)

package/bundled/locales/zh-TW/skills/knowledge-graph/guide.md

@@ -0,0 +1,74 @@
+---
+source: ../../../../skills/knowledge-graph/guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 9c86b5a2a71d
+status: current
+---
+
+# Knowledge Graph — 詳細指南
+
+[SKILL.md](SKILL.md) 的配套說明。兩種運作模式的範例與引擎 API。
+
+---
+
+## 1. 服務模式（graph 引擎）
+
+當有相容於 EngramGraph 的引擎可連線時，單次查詢即可回傳完整影響鏈。
+
+### 影響分析
+
+```bash
+curl -s -X POST "$ENGRAM_URL/graph/impact-analysis" \
+  -H 'content-type: application/json' \
+  -d '{"nodeId":"XSPEC-205","maxHops":3}'
+# => { "nodeId": "XSPEC-205",
+#      "decisions": [ {"id":"DEC-062","title":"...","via":"direct"},
+#                     {"id":"DEC-069","title":"...","via":"supersedes"} ] }
+```
+
+`via: "direct"` 表示該決策直接 IMPACTS 此 spec；`via: "supersedes"` 表示它透過 SUPERSEDES 影響鏈（≤ `maxHops`）連到此 spec。
+
+### 信心回饋（SAGE）
+
+```bash
+curl -s -X POST "$ENGRAM_URL/graph/ingest" \
+  -H 'content-type: application/json' \
+  -d '{"type":"test_fail","functionId":"src/a.ts#execute"}'
+```
+
+降低該節點的信心值；之後讀取時會優先浮現信心較高的節點。
+
+---
+
+## 2. 降級模式（僅 Markdown）
+
+不需要引擎。透過讀取檔案重建影響鏈：
+
+1. 讀取目標文件（例如 `XSPEC-205`）。
+2. 從其 front-matter（`impacts`、`impacted_by`、`supersedes`、`related`）與行內 `[[ref]]` 連結蒐集 id。
+3. 對每個 id，讀取該文件並重複此過程，直到所需的跳數深度。
+4. 依前綴分類每個 id（`XSPEC-*`/`SPEC-*` → Spec；`DEC-*`/`ADR-*` → Decision）並回報邊。
+
+```bash
+# find the documents
+grep -rl "id: XSPEC-205" --include='*.md' .
+# discover outbound references
+grep -nE "(impacts|impacted_by|supersedes|related):|\[\[(XSPEC|DEC|ADR)-" path/to/XSPEC-205.md
+```
+
+降級模式永遠正確，但受限於你讀取了多少檔案；跨領域的程式碼連結（function → spec）通常只在服務模式中可用。
+
+---
+
+## 3. 等價性
+
+兩種模式產生**相同形狀的答案**（一份相連的 Specs/Decisions 清單，附帶邊類型）。服務模式更快且更完整（可包含 code→spec→decision 的跳轉）；降級模式則是通用後備。務必告知使用者答案來自哪種模式。
+
+---
+
+## 參考
+
+- [core/knowledge-graph-memory.md](../../core/knowledge-graph-memory.md)
+- [EngramGraph](https://github.com/AsiaOstrich/EngramGraph)

package/bundled/locales/zh-TW/skills/migration-assistant/SKILL.md

@@ -2,8 +2,9 @@
 name: migration-assistant
 source: ../../../../skills/migration-assistant/SKILL.md
 source_version: 1.0.0
+source_hash: 67b6f33f825e
 translation_version: 1.0.0
-last_synced: 2026-03-24
+last_synced: 2026-06-01
 status: current
 description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
 ---
@@ -21,19 +22,19 @@ description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
 | `/migrate` | 啟動互動式遷移引導 |
 | `/migrate --assess` | 僅風險評估 |
 | `/migrate "Vue 2 to 3"` | 引導特定遷移 |
-| `/migrate --deps` | 依賴升級分析 |
+| `/migrate --deps` | 相依升級分析 |
 | `/migrate --rollback` | 規劃回滾策略 |
 
 ## 遷移類型
 
 | 類型 | 範例 | 風險 |
 |------|------|------|
-| **框架升級** | React 17→18, Vue 2→3 | 中高 |
-| **語言遷移** | JS→TS, Python 2→3 | 高 |
-| **API 版本** | REST v1→v2, GraphQL 更新 | 中 |
-| **資料庫遷移** | MySQL→PostgreSQL | 極高 |
-| **建構工具** | Webpack→Vite | 低中 |
-| **套件管理器** | npm→pnpm | 低 |
+| **框架升級** | React 17→18, Vue 2→3, Angular 15→17 | 中高 |
+| **語言遷移** | JS→TS, Python 2→3, Java 8→17 | 高 |
+| **API 版本** | REST v1→v2, GraphQL schema 更新 | 中 |
+| **資料庫遷移** | MySQL→PostgreSQL, SQL→NoSQL | 極高 |
+| **建構工具** | Webpack→Vite, Grunt→ESBuild | 低中 |
+| **套件管理器** | npm→pnpm, pip→poetry | 低 |
 
 ## 風險評估矩陣
 
@@ -46,11 +47,97 @@ description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
 ## 工作流程
 
 1. **評估** - 評估現狀、識別破壞性變更
-2. **規劃** - 建立含依賴關係的遷移清單
+2. **規劃** - 建立含相依關係的遷移清單
 3. **準備** - 設定 codemods、相容層、功能旗標
 4. **遷移** - 分階段執行遷移並測試
 5. **驗證** - 執行完整測試套件、檢查回歸
-6. **清理** - 移除相容層、舊依賴
+6. **清理** - 移除相容層、舊相依
+
+## API 遷移合約測試
+
+當 API endpoint 從一個技術棧遷至另一個（PHP → .NET、Express → Spring、Python → Go），對**新**實作的單元測試只驗證**新 DTO**——無法捕捉「舊版有但新版漏掉的欄位」。欄位缺漏、欄位 rename、型別漂移，以及頂層 vs nested 層級漂移等問題會靜默流入生產，導致仍預期舊版 shape 的既有前端失靈。
+
+**僅靠單元測試、整合測試或 code review 無法防止**。2026-05-24 真實 PROD 事故：67/67 測試全綠流入正式環境，由客戶發現缺漏。
+
+### 強制規則
+
+每個被遷移的 API endpoint **必須**至少有一份 contract test，比對新實作的 response 與從 legacy 實作捕獲的 fixture。驗證的是結構性等價（keys、type、層級位置），而非值等價。
+
+### Fixture 捕獲協議
+
+**Legacy 仍運行（典型遷移窗口）：**
+
+```bash
+# 1. Capture ≥3 representative inputs (happy path, edge case, empty result)
+curl -X POST $LEGACY_BASE/endpoint -d @input1.json \
+  > tests/fixtures/migration/endpoint/scenario1.json
+curl -X POST $LEGACY_BASE/endpoint -d @input2_empty.json \
+  > tests/fixtures/migration/endpoint/scenario2_empty.json
+curl -X POST $LEGACY_BASE/endpoint -d @input3_edge.json \
+  > tests/fixtures/migration/endpoint/scenario3_edge.json
+
+# 2. Scrub PII and volatile values (timestamps, generated IDs)
+jq 'walk(if type == "string" and test("@") then "redacted@example.com" else . end)' \
+  tests/fixtures/migration/endpoint/scenario1.json > tmp && mv tmp ...
+
+# 3. Commit fixtures
+git add tests/fixtures/migration/endpoint/
+```
+
+**Legacy 已退役但 source 可讀：**
+
+- 追蹤 legacy source code，手動建構預期的 response shape
+- 將每個欄位的來源（SQL 欄位、計算式、hardcoded）記錄於同位置的 `.notes.md` 檔案
+
+### Contract test 範本
+
+**C# / xUnit：**
+
+```csharp
+[Theory]
+[InlineData("scenario1")]
+[InlineData("scenario2_empty")]
+[InlineData("scenario3_edge")]
+public async Task Endpoint_ResponseShape_MatchesLegacyFixture(string scenario)
+{
+    var fixture = LoadFixture($"migration/endpoint/{scenario}");
+    var response = await CallNewImpl(fixture.Input);
+    // StructuralEquivalence checks keys + types + placement, ignores values
+    StructuralEquivalence.Assert(response, fixture.ExpectedShape);
+}
+```
+
+**TypeScript / Jest：**
+
+```typescript
+import { structuralEquivalence } from "./test-utils/structural-equivalence";
+
+describe.each([
+  ["scenario1"],
+  ["scenario2_empty"],
+  ["scenario3_edge"],
+])("Endpoint response shape vs legacy fixture (%s)", (scenario) => {
+  test("matches", async () => {
+    const fixture = loadFixture(`migration/endpoint/${scenario}.json`);
+    const response = await callNewImpl(fixture.input);
+    structuralEquivalence(response, fixture.expectedShape);
+  });
+});
+```
+
+`structuralEquivalence` / `StructuralEquivalence.Assert` 規則：每一層具備相同的 key 集合（不可缺漏、不可多出，除非明確 opt in）、每個 key 具相同的基本型別、相同的層級位置（頂層 vs nested）。值可以不同（timestamps、IDs）；型別與結構不可不同。
+
+### 逐欄位遷移稽核清單
+
+合併任何被遷移的 endpoint 前：
+
+- [ ] 所有 legacy response 欄位皆 mapping 至新 DTO（無 silent drop）
+- [ ] 儘量保留命名（避免將 `TotalX` rename 而丟失「per-member」語意）
+- [ ] 保留頂層 vs nested 層級位置
+- [ ] 已驗證型別相容性（string→int 轉換為明確而非巧合）
+- [ ] Error path return code 與 legacy 一致（`509` 而非 `506`；`404` 而非 `400`）
+- [ ] Contract test fixture 已 commit 至 `tests/fixtures/migration/`
+- [ ] Cross-link 至 [contract-test-assistant](../contract-test-assistant/SKILL.md) 做持續的消費端驗證
 
 ## 回滾策略
 
@@ -61,15 +148,45 @@ description: "[UDS] 引導程式碼遷移、框架升級與技術現代化"
 | **雙運行** | 關鍵系統、零停機 |
 | **分支凍結** | 一次性完整遷移 |
 
+## 使用範例
+
+```
+User: /migrate "Vue 2 to 3"
+AI: Migration Assessment: Vue 2 → Vue 3
+    Breaking changes found: 12
+    - Options API → Composition API (47 components)
+    - Filters removed (8 usages)
+    - Event bus removed (3 usages)
+    Risk: Medium-High
+    Estimated effort: 2-3 weeks
+    Recommended: Staged migration with @vue/compat
+```
+
 ## 下一步引導
 
 `/migrate` 完成後，AI 助手應建議：
 
 > **遷移分析完成。建議下一步：**
 > - 執行 `/reverse` 深入理解現有程式碼
-> - 執行 `/testing` 確保遷移後測試通過
+> - 執行 `/testing` 確保遷移後測試通過 ⭐ **推薦**
 > - 執行 `/commit` 提交遷移變更
 
 ## 參考
 
 - 核心規範：[refactoring-standards.md](../../../../core/refactoring-standards.md)
+- 相關：[contract-test-assistant](../contract-test-assistant/SKILL.md) — 遷移後持續合約驗證的策略
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.1.0 | 2026-05-26 | 新增：API 遷移合約測試章節——強制 fixture 捕獲協議、C#/TS 範本、逐欄位稽核清單（XSPEC-233 / closes #112） |
+| 1.0.0 | 2026-03-24 | 初始版本 |
+
+## AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/migrate`](../commands/migrate.md#ai-agent-behavior--ai-代理行為)
+
+## 授權
+
+CC BY 4.0