universal-dev-standards 5.12.1 → 5.13.2

package/bundled/skills/migration-assistant/SKILL.md

@@ -65,6 +65,108 @@ Guide systematic code migration, framework upgrades, and technology modernizatio
 5. **驗證** - 執行完整測試套件、檢查回歸
 6. **清理** - 移除相容層、舊依賴
 
+## API Migration Contract Tests | API 遷移合約測試
+
+When migrating an API endpoint from one tech stack to another (PHP → .NET, Express → Spring, Python → Go), unit tests on the **new** implementation verify against the **new DTO** — they cannot catch fields that the legacy returned but the new implementation forgot. Missing fields, renamed fields, type drift, and top-level vs nested placement drift will silently survive into production and break the existing frontend that still expects the legacy shape.
+
+This is **NOT** caught by unit tests, integration tests, or code review alone. A real 2026-05-24 production incident shipped with 67/67 green tests and was discovered by the customer.
+
+當 API endpoint 從一個技術棧遷至另一個（PHP → .NET、Express → Spring 等），對**新**實作的單元測試只驗證**新 DTO**——無法捕捉「舊版有但新版漏掉」「欄位 rename」「型別漂移」「頂層 vs nested 層級漂移」等問題。這些缺陷會靜默流入生產，導致前端（仍預期舊版回應 shape）失靈。
+
+**僅靠單元測試、整合測試或 code review 無法防止**。2026-05-24 真實 PROD 事故：67/67 測試全綠流入正式環境，由客戶發現缺漏。
+
+### Mandatory rule | 強制規則
+
+Every migrated API endpoint **MUST** ship with at least one contract test that compares the new implementation's response against a fixture captured from the legacy implementation. Structural equivalence (keys, types, placement), not value equality, is verified.
+
+每個被遷移的 API endpoint **必須**至少有一份 contract test，比對新實作的 response 與從 legacy 捕獲的 fixture。驗證的是結構性等價（keys、type、層級位置），而非值等價。
+
+### Fixture capture protocol | Fixture 捕獲協議
+
+**While legacy is still running (typical migration window) | 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/
+```
+
+**When legacy is already retired but source-readable | Legacy 已退役但 source 可讀:**
+
+- Trace through legacy source code, manually construct the expected response shape
+- Document each field's origin (SQL column, computed expression, hardcoded) in a sibling `.notes.md` file
+- 從 legacy source code 推導預期 response shape；每個欄位來源（SQL 欄位 / 計算式 / hardcoded）記錄於同位置 `.notes.md`
+
+### Contract test template
+
+**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` rule: same set of keys at each level (no missing, no extra unless explicitly opted in), same primitive type per key, same placement (top-level vs nested). Values can differ (timestamps, IDs); types and structure cannot.
+
+### Field-by-field migration audit checklist
+
+Before merging any migrated endpoint:
+
+- [ ] All legacy response fields mapped to new DTO (no silent drops)
+- [ ] Naming preserved where possible (avoid `TotalX` rename that drops the "per-member" semantic)
+- [ ] Top-level vs nested placement preserved
+- [ ] Type compatibility verified (string→int conversions explicit, not coincidental)
+- [ ] Error path return codes match legacy (`509` not `506`; `404` not `400`)
+- [ ] Contract test fixture committed under `tests/fixtures/migration/`
+- [ ] Cross-link to [contract-test-assistant](../contract-test-assistant/SKILL.md) for ongoing consumer-side verification
+
+合併前必確認：
+- [ ] 所有 legacy response 欄位 mapping 至新 DTO（無 silent drop）
+- [ ] 命名儘量保留
+- [ ] 頂層 vs nested 層級保留
+- [ ] 型別相容性已明確驗證
+- [ ] Error path return code 與 legacy 一致
+- [ ] Contract test fixture 已 commit
+- [ ] Cross-link 至 contract-test-assistant 做持續消費端驗證
+
 ## Rollback Strategy | 回滾策略
 
 | Approach | When to Use | 使用時機 |
@@ -100,11 +202,13 @@ After `/migrate` completes, the AI assistant should suggest:
 ## Reference | 參考
 
 - Core standard: [refactoring-standards.md](../../core/refactoring-standards.md)
+- Related: [contract-test-assistant](../contract-test-assistant/SKILL.md) — Strategy for ongoing contract verification post-migration
 
 ## Version History | 版本歷史
 
 | Version | Date | Changes | 變更 |
 |---------|------|---------|------|
+| 1.1.0 | 2026-05-26 | Added: API Migration Contract Tests section — mandatory fixture capture protocol, C#/TS templates, field-by-field audit checklist (XSPEC-233 / closes #112) | 新增 API 遷移合約測試章節 |
 | 1.0.0 | 2026-03-24 | Initial release | 初始版本 |
 
 

package/bundled/skills/runbook-assistant/SKILL.md

@@ -43,8 +43,16 @@ Guide runbook writing, maintenance, drill exercises, and coverage reporting.
 > - 執行 `/incident --postmortem` 從事故更新 Runbook
 > - 執行 `/checkin` 提交變更
 
+## Deploy Runbook — Mandatory Rule
+
+Any deploy runbook that includes a destructive-update pattern (stop → swap → start) **MUST** follow the [Defensive Deployment Ordering](../../core/deployment-standards.md#defensive-deployment-ordering) sequence: extract to staging → verify → only then touch the live install. Skipping the verify step has caused real production outages.
+
+任何包含 destructive-update（stop → swap → start）的部署 runbook **必須**遵循 [Defensive Deployment Ordering](../../core/deployment-standards.md#defensive-deployment-ordering) 順序：解壓到 staging → verify → 通過後才動 live install。跳過 verify 步驟已造成真實生產事故。
+
 ## Reference | 參考
 
 - Core standard: [runbook-standards.md](../../core/runbook-standards.md)
 - Related: [alerting-standards.md](../../core/alerting-standards.md)
 - Related: [postmortem-standards.md](../../core/postmortem-standards.md)
+- Related: [deployment-standards.md § Defensive Deployment Ordering](../../core/deployment-standards.md#defensive-deployment-ordering) — mandatory ordering for destructive deploys
+- Related: [packaging-standards.md § Archive Format Integrity](../../core/packaging-standards.md#archive-format-integrity) — upstream pair to defensive ordering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.12.1",
+  "version": "5.13.2",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -70,7 +70,7 @@
     "@vitest/coverage-v8": "^4.1.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "eslint": "10.3.0",
+    "eslint": "10.4.0",
     "glob": "^13.0.1",
     "globals": "17.6.0",
     "husky": "^9.1.7",

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "5.12.1",
+  "version": "5.13.2",
   "lastUpdated": "2026-05-13",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "5.12.1"
+      "version": "5.13.2"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "5.12.1",
+      "version": "5.13.2",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -1147,6 +1147,18 @@
       "skillName": null,
       "description": "Content requirements and writing guidelines for different project types"
     },
+    {
+      "id": "self-review-protocol",
+      "name": "Self-Review Protocol",
+      "nameZh": "自我審查協議",
+      "source": {
+        "human": "core/self-review-protocol.md",
+        "ai": "ai/standards/self-review-protocol.ai.yaml"
+      },
+      "category": "reference",
+      "skillName": null,
+      "description": "Mandatory self-review pass on large markdown edits (>50 lines) before commit; catches 6 categories of internal cross-reference inconsistencies (diagram/step mismatch, changelog reference errors, count drift, stale templates, wrong tool references, placeholder vs rule misalignment)"
+    },
     {
       "id": "ai-instruction-standards",
       "name": "AI Instruction File Standards",
@@ -2326,7 +2338,7 @@
       "id": "license-compliance",
       "name": "License Compliance Standards",
       "nameZh": "授權合規標準",
-      "version": "5.12.1",
+      "version": "5.13.2",
       "source": {
         "human": "core/license-compliance.md",
         "ai": "ai/standards/license-compliance.ai.yaml"