universal-dev-standards 5.17.0 → 6.0.0

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

@@ -167,6 +167,203 @@ Before merging any migrated endpoint:
 - [ ] Contract test fixture 已 commit
 - [ ] Cross-link 至 contract-test-assistant 做持續消費端驗證
 
+## Post-Cutover Data Reconciliation | Cutover 後生產資料對帳
+
+> **Implements**: XSPEC-284 R2 (axis ③ persisted-data semantics) / closes UDS issue [#134](https://github.com/AsiaOstrich/universal-dev-standards/issues/134).
+
+Contract tests (above) and `behavior-snapshot` catch **interface** divergence but are blind to **persisted-data semantic** divergence. Two blind spots both share:
+
+1. **You can only assert what you thought to enumerate.** The rules that actually ship broken are the *implicit, undocumented* ones — especially the semantics of a persisted field (when is it non-zero? when is it overwritten?). Nobody writes a scenario for a rule they don't know exists.
+2. **Per-request parity ≠ data-at-rest parity.** A field written by an **asynchronous** process (delivery-receipt sync, settlement job, status reconciler) against a live external provider is not a deterministic request you can replay. Its correctness only emerges in **aggregate over real production volume**, not in a single happy-path snapshot.
+
+Contract test 與 `behavior-snapshot`只能捕捉**介面**分歧，對**持久化資料語義**分歧視而不見。兩者共有兩個盲區：(1) 你只能驗證你想得到要列舉的規則——真正出包的永遠是沒人寫下來的隱含規則（某欄位何時非零、何時被覆寫）；(2) per-request parity ≠ data-at-rest parity——由**非同步**程序（DR sync、結算批次、狀態對帳器）對 live 外部供應商寫入的欄位，不是可重放的確定性請求，其正確性只在**真實生產量的聚合**中浮現。
+
+### Failure fingerprint | 事故指紋（#134）
+
+某企業 SMS 平台 PHP→.NET 重寫：每筆金額由**非同步** DR sync 覆寫（`record.Cost = gatewayDr.Cost`）。legacy 對 carrier-failure 仍計費，rewrite 寫 gateway 回報的 `0` → cutover 邊界兩側同一失敗狀態的金額分歧。**所有既有 gate 全部漏接**（response shape 相同 → contract test 過；無人 curated「失敗仍計費」場景；欄位由背景作業對 live gateway 寫入 → 不可重放）。最後靠 ops 跑生產 `SUM(cost) GROUP BY status, day` 跨邊界彙總才發現。**單日抽樣甚至誤判「失敗不計費＝正常」**——只有跨 cutover 邊界的多週聚合才揭露真相。
+
+### Mandatory rule | 強制規則
+
+When a migration loads legacy data into the **same store** as new data, the old/new boundary is a **free differential oracle**. For each business-critical persisted field you **MUST**:
+
+- Define **aggregate reconciliation invariants** comparing the distribution of **legacy-origin vs new-origin** rows along key dimensions (e.g. `SUM(money) / COUNT(*) GROUP BY status, period`).
+- Run them **on a schedule against production** and alert when divergence exceeds a declared tolerance.
+- Investigate over a **multi-week window spanning the cutover** — never a single-day sample (a sampled check can confirm a *wrong* conclusion).
+
+當 migration 將 legacy 資料載入與 new 相同的**儲存**，新舊邊界即是**免費差分神諭**。對每個 business-critical 持久化欄位**必須**：定義聚合對帳不變量（比對 legacy-origin vs new-origin 列沿關鍵維度的分佈）、對生產**排程執行**並於分歧超過宣告容差時告警、以跨 cutover 的**多週窗口**調查（切忌單日抽樣，抽樣可能坐實錯誤結論）。
+
+### Cutover-boundary reconciliation SQL template | 對帳 SQL 模板
+
+```sql
+-- Reconcile a money/state field across the migration cutover boundary.
+SELECT status,
+       SUM(CASE WHEN created < @cutover THEN 1 ELSE 0 END)                          AS legacy_rows,
+       SUM(CASE WHEN created < @cutover AND money_field > 0 THEN 1 ELSE 0 END)      AS legacy_nonzero,
+       SUM(CASE WHEN created >= @cutover THEN 1 ELSE 0 END)                         AS new_rows,
+       SUM(CASE WHEN created >= @cutover AND money_field > 0 THEN 1 ELSE 0 END)     AS new_nonzero
+FROM records GROUP BY status;
+-- Invariant: nonzero-ratio per status must not differ across the boundary beyond tolerance.
+```
+
+### Tolerance & alerting guidance | 容差與告警指引
+
+| Aspect | Guidance | 指引 |
+|--------|----------|------|
+| **Invariant type** | nonzero-ratio / `SUM` / `COUNT` / `DISTINCT` / checksum per `GROUP BY status, period` | 每維度的非零比率 / 聚合相等 / checksum |
+| **Tolerance** | Declare per field; 0% for hard accounting invariants, a small ε only for known legitimate drift (e.g. rounding) | 逐欄宣告；硬會計不變量 0%，僅已知合法漂移容許小 ε |
+| **Window** | Multi-week, spanning cutover; bucket by `period` to localise the boundary | 多週、橫跨 cutover；以 `period` 分桶定位邊界 |
+| **Schedule** | Standing post-cutover cron (daily) until boundary rows age out of active reporting | post-cutover 排程（每日）直到邊界列退出活躍報表 |
+| **Alert** | Page on divergence > tolerance; route via `observability-assistant` alert rules | 分歧超過容差即告警；經 `observability-assistant` 告警規則路由 |
+
+### Gate 0 — Implicit-rule capture for persisted business fields | 隱含規則擷取
+
+Before migrating any feature that writes a persisted business field, **explicitly answer for each such field** three questions, then lock the answer as a snapshot scenario **or** a reconciliation invariant:
+
+> 1. **When is this value SET?** 何時設值？
+> 2. **When is it OVERWRITTEN?** 何時被覆寫？（尤其非同步路徑）
+> 3. **When is it ZEROED / nulled?** 何時歸零／清空？
+
+**High-risk implicit-rule checklist** — empirically recurring fingerprints | 高風險隱含規則檢查清單（經驗反覆出現的指紋）：
+
+- [ ] **Billing / charge semantics** — charged on submit vs on delivery; refund-on-failure? | 計費語義（提交時計費 vs 送達時計費；失敗退費？）
+- [ ] **Enum / status-code mapping** — every legacy code mapped; "success set" defined identically | 列舉／狀態碼對映（每個 legacy 碼都對映；「成功集合」定義一致）
+- [ ] **Null / empty handling** — empty string vs null vs absent; default-on-missing | 空值處理（空字串 vs null vs 不存在；缺值預設）
+- [ ] **Field-name casing / serialization** — snake_case vs camelCase binding | 欄位命名大小寫／序列化（snake_case vs camelCase 綁定）
+- [ ] **Timezone** — stored UTC vs local; report boundaries | 時區（存 UTC vs local；報表邊界）
+- [ ] **Rounding / type coercion** — `"2.00"` (text) parsed as int → dropped to 0 | 四捨五入／型別強轉（`"2.00"` 文字被當 int 解析 → 掉成 0）
+
+### 3-gate positioning | 3-gate 定位表
+
+Make the boundary between gates explicit so each axis has an owner and nothing falls into the seam:
+
+| Gate | Scope | When | 範圍 / 時機 |
+|------|-------|------|------|
+| [`behavior-snapshot`](../../core/behavior-snapshot.md) | per-request, **curated** scenarios | pre-UAT CI | per-request、人工 curated 場景；pre-UAT CI |
+| Contract tests (above / #112) | response **shape** (keys / types / placement) | unit / integration | response shape（keys/型別/層級）；單元/整合 |
+| **This section (#134)** | **aggregate, data-at-rest semantics of async-written fields, over real volume** | **post-cutover, scheduled, production** | **非同步寫入欄位的聚合、靜態資料語義，跨真實量；post-cutover 排程生產** |
+
+> Cross-ref: [`behavior-snapshot`](../../core/behavior-snapshot.md) (curated golden masters), [`observability-assistant`](../observability-assistant/SKILL.md) (reconciliation schedule + alert templates).
+
+## Background Job / Side-Effect Completeness | 背景作業／副作用完整性
+
+> **Implements**: XSPEC-284 R3 (axis ⑤).
+
+Migration inventories (`/vo-inventory`, XSPEC-200 `type:background_job`) and Devil's-Advocate grep (XSPEC-201 Step 4) **annotate** cron / queue consumers / scheduled batches / webhooks / mail-send points — but annotation alone proves nothing. A background job can be listed in the manifest, exist in code, and still **never actually run** in the new system.
+
+遷移清單與副作用 grep 只是**標注**背景作業——標注本身不證明任何事。背景作業可能在 manifest 列出、程式碼存在，卻在新系統**從未真正執行**。
+
+### Mandatory rule | 強制規則
+
+For every background side-effect carried over from legacy, verify **two** things — annotation is not enough:
+
+| Check | Pre-flight | Post-cutover |
+|-------|-----------|--------------|
+| **(a) Exists** — the cron / queue consumer / webhook / mail point is implemented in the new system | source grep + registration check | — |
+| **(b) Executed** — it has actually been **triggered / run at least once**, with observable evidence (log line, heartbeat, queue-depth drain, telemetry counter) | — | observability evidence required |
+
+If either check fails, mark the feature `not_implemented` (XSPEC-199) and **block UAT / cutover** — do not treat a silent, never-fired job as "done".
+
+對每條由 legacy 帶過來的背景副作用，須驗證**兩件事**（標注不夠）：(a) **存在**——cron／queue consumer／webhook／寄信點在新系統實際實作（source grep + 註冊檢查）；(b) **已執行**——post-cutover 已被**觸發／執行至少一次**且有可觀測證據（log、heartbeat、queue depth 排空、telemetry counter）。任一不過即標 `not_implemented`（XSPEC-199）並 **block UAT／cutover**——絕不把沉默、從未觸發的作業當「完成」。
+
+> Cross-ref: structured-log mandatory events `heartbeat` / `business_event` (logging-standards) provide the observable execution evidence for check (b).
+
+## State-Machine & Temporal Parity | 狀態機與時序對等
+
+> **Implements**: XSPEC-284 R8 (axis ⑧) → split out as **XSPEC-287**.
+
+Legacy state-transition rules and temporal preconditions are **implicit**: a single-record snapshot "looks legal", and a violation only surfaces across a **sequence** of operations. So per-request functional parity and behavior-snapshot parity both miss them (same blind-spot class as "per-request ≠ data-at-rest" / "per-request ≠ concurrency"). `feature-manifest` has only a `status` field — it does **not** validate transition legality.
+
+legacy 的狀態轉移規則與時序前提多為**隱性**：單筆記錄的快照「看起來合法」，違規只在一連串操作的**轉移序列**中浮現，因此 per-request 功能對等與 behavior-snapshot 對等都抓不到（與「per-request ≠ data-at-rest」「per-request ≠ 並發」同源盲區）。`feature-manifest` 只有 `status` 欄，**不**驗證轉移合法性。
+
+### Step 1 — State-machine list source (derive, R3) | 狀態機清單來源
+
+Legacy transitions are scattered across controllers / services / DB triggers. Derive the state enumeration + legal-transition set **mechanically** via three-way cross-reference (do not rely on memory):
+
+legacy 狀態轉移散落於 controller／service／DB trigger。以**三方交叉**機械化擷取狀態列舉 + 合法轉移集（不靠人腦回憶）：
+
+| Source | Yields |
+|--------|--------|
+| **(1) enum definition** — status enum / lookup table | the full set of declared states |
+| **(2) state-update points** — grep every `status = ...` / `UPDATE ... SET status` / trigger | which transitions the code *can* perform |
+| **(3) production actual sequences** — distinct `(from_status → to_status)` pairs observed in prod history/audit | which transitions *actually* occur |
+
+> **Authority on conflict**: when the three disagree, treat **production-observed transitions as the legacy ground truth** (echoes #134 "production is the oracle"). A transition the code allows but production never produced is a latent path; a production transition the new enum forbids is a regression.
+
+> **權威性**：三者不一致時，以**生產實際出現過的轉移為 legacy 真實行為基準**（呼應 #134「以生產為準」）。程式碼允許但生產從未產生的轉移是潛在路徑；生產出現過但新 enum 禁止的轉移是回歸。
+
+### Step 2 — Legal-transition validation (oracle, R1) | 合法轉移驗證
+
+From the derived transition graph, assert the **new system forbids illegal transitions** that legacy forbade. Block when the new system **allows a transition legacy prohibited** (a rewrite routinely loosens implicit guards):
+
+依萃取出的轉移圖，斷言**新系統禁止 legacy 禁止的非法轉移**。當新系統**允許 legacy 禁止的轉移**即 block（重寫常放寬隱性護欄）：
+
+- `cancelled → pending` (reviving a cancelled order)
+- `refunded → paid` (un-refunding)
+- `shipped → draft` (backward past a point-of-no-return)
+
+**Gate timing**: pre-UAT.
+
+### Step 3 — Temporal invariant detection (oracle, R2) | 時序不變量偵測
+
+Assert temporal invariants that a single-row snapshot cannot reveal; violation → alert:
+
+斷言單筆快照無法揭露的時序不變量；違反即告警：
+
+- `created_at ≤ updated_at` (no record updated before it existed)
+- no **future timestamps** (clock skew / bad default)
+- **monotonic** status-timestamp progression (`paid_at ≤ shipped_at ≤ delivered_at`)
+- event-ordering guarantees preserved (no reordered event log)
+
+**Gate timing**: pre-UAT **and** post-cutover (shares the reconciliation schedule of axis ③ Post-Cutover Data Reconciliation above).
+
+**Gate 時機**：pre-UAT **與** post-cutover（與上方軸③ Post-Cutover 對帳共用排程）。
+
+### Step 4 — Sequence / ordering parity (R4) | 序列／順序對等
+
+Verify the new system preserves **idempotency** (a repeated operation does not produce a duplicate state change) and **critical event ordering**, so the rewrite does not introduce order-sensitive bugs:
+
+驗證新系統保留**冪等性**（重複操作不產生重複狀態變更）與**關鍵事件順序**，避免重寫引入順序敏感 bug：
+
+- [ ] Replaying the same event/message twice yields one state change, not two
+- [ ] Out-of-order delivery is rejected or reconciled, not silently applied
+- [ ] Idempotency keys / dedup windows match legacy semantics
+
+### Boundary with XSPEC-286 axis ⑥ | 與 XSPEC-286 軸⑥ 邊界
+
+**287 (this section, axis ⑧)** owns **transition legality + temporal correctness** (a domain question). **[XSPEC-286](../../core/performance-standards.md) axis ⑥** owns **concurrency race / isolation** (a performance/contention question). An overlap case — a *concurrent* operation causing an *illegal* transition — has its concurrency aspect in 286 and its transition-legality aspect here; assign the primary owner per the dominant failure mode at landing time.
+
+**287（本節，軸⑧）**負責**轉移合法性 + 時序正確性**（領域問題）；**[XSPEC-286](../../core/performance-standards.md) 軸⑥**負責**並發競態／隔離**（效能/競爭問題）。重疊案例（並發導致非法轉移）的並發面歸 286、轉移合法性面歸本節；落地時依主導失敗模式指派主責。
+
+## Error-Path Completeness | 錯誤路徑完整性
+
+> **Implements**: XSPEC-284 R9 (axis ⑨) → split out as **XSPEC-288**.
+
+The most common migration omission is "happy path migrated, error / degradation / fallback branches dropped in bulk". The happy path has an explicit requirement; error branches are scattered (try/catch layers, custom exception hierarchies, specific error codes) and silently lost. This skill owns the **migration derive + degradation parity** (R1/R3); the **systematic missing-branch gap analysis + error-response differential** (R2/R4) lives in [full-coverage-testing](../../core/full-coverage-testing.md) "Migration Error-Path Completeness".
+
+最常見的遷移遺漏是「happy path 移了、錯誤／降級／fallback 分支整批被漏」。happy path 有明確需求，錯誤分支散落（try/catch 階層、自訂例外階層、特定錯誤碼）而被靜默遺失。本 skill 負責**遷移 derive + 降級對等**（R1/R3）；**系統性遺漏分支 gap 分析 + 錯誤回應差分**（R2/R4）落在 [full-coverage-testing](../../core/full-coverage-testing.md)「Migration Error-Path Completeness」。
+
+### Step 1 — Mechanized legacy exception / error-code list (derive, R1) | 機械化例外/錯誤碼清單
+
+Enumerate the legacy error surface **mechanically** (not from recall): grep `catch`/`except`/`rescue` blocks, the custom exception/error class hierarchy, all error/status codes, and error response shapes (serializers/DTOs). This list is the error-path to-verify checklist handed to the gap analysis in full-coverage-testing.
+
+**機械化**列舉 legacy 錯誤面（不靠回憶）：grep `catch`／`except`／`rescue` 區塊、自訂例外/錯誤類階層、所有錯誤/狀態碼、錯誤回應形狀（serializer／DTO）。此清單即交給 full-coverage-testing gap 分析的錯誤路徑待驗清單。
+
+### Step 2 — Degradation / fallback parity (R3) | 降級／Fallback 對等
+
+legacy degradation modes only run on failure, so they are easy to drop. Verify the new system preserves them — fail closed on parity, not "consistent on happy path, wildly different on failure":
+
+legacy 降級模式只在失敗時執行，容易被漏。驗證新系統保留——對等上 fail closed，而非「正常路徑一致、失敗時行為迥異」：
+
+- [ ] External-service-failure **fallback** matches legacy | 外部服務失敗 fallback 與 legacy 一致
+- [ ] **Retry** policy (count / backoff / give-up) matches legacy | 重試策略（次數／backoff／放棄）與 legacy 一致
+- [ ] **Partial-result** handling matches legacy | 部分結果處理與 legacy 一致
+- [ ] **Circuit-breaker / timeout** degradation matches legacy | 斷路器／逾時降級與 legacy 一致
+
+> **Importance ranking**: rank legacy error branches by **production-actual trigger frequency** (#134 "production is the oracle"). A high-frequency prod error branch with no new-system mapping is a hard block; never-fired latent branches are still listed but lower priority.
+> **重要性分級**：依**生產實際觸發頻率**排序（#134「以生產為準」）。高頻生產錯誤分支無對映即硬 block；從未觸發的潛在分支仍列入但較低優先。
+
+> Cross-ref: [full-coverage-testing](../../core/full-coverage-testing.md) Migration Error-Path Completeness (gap report + error-response differential, R2/R4); [behavior-snapshot](../../core/behavior-snapshot.md) (error-response parity).
+
 ## Rollback Strategy | 回滾策略
 
 | Approach | When to Use | 使用時機 |
@@ -199,15 +396,44 @@ After `/migrate` completes, the AI assistant should suggest:
 > - 執行 `/testing` 確保遷移後測試通過 ⭐ **Recommended / 推薦** — Verify post-migration tests
 > - 執行 `/commit` 提交遷移變更 — Commit migration changes
 
+## Appendix — 9-Axis Completeness Matrix | 附錄：9 軸完整性矩陣
+
+> **Source**: XSPEC-284 Legacy Refactor Completeness Framework. "Ensuring nothing is missing cannot be proven by enumeration" — you can only verify what you thought to enumerate. Strategy = two legs: **(1) mechanically derive** the to-do list from real legacy artifacts (schema / routes / cron config / prod logs), and **(2) differential oracles** (shadow run / replay / cutover-boundary reconciliation) that make divergence self-report.
+>
+> 「確保沒有遺漏」無法用列舉證明——你只能驗證你想得到要列舉的東西。策略＝兩條腿：(1) 從 legacy 真實 artifact **機械化推導**待辦清單；(2) **差分神諭**讓分歧自報。
+
+Each migration declares, per axis, three things: **derive** (list source) · **detect** (oracle) · **gate timing**. Axes marked here as covered map to existing UDS standards — do not re-invent.
+
+| Axis | Derive (list source) | Detect (oracle) | Gate | Covered by |
+|------|----------------------|-----------------|------|------------|
+| ① Feature | route table / controller / menu / permissions | inventory diff (legacy vs new) | pre-flight | XSPEC-200 feature-manifest + `/vo-inventory`; XSPEC-206 |
+| ② Behavior | curated scenarios + prod-log extraction | behavior-snapshot parity | pre-UAT | XSPEC-201 behavior-snapshot; **contract tests** (this skill) |
+| ③ **Persisted semantics** | DB schema full-column semantic sign-off (Gate 0) | **cutover-boundary aggregate reconciliation** | **post-cutover** | **This skill — Post-Cutover Data Reconciliation (#134)** |
+| ④ Implicit rules | cron / queue / computed-column / middleware source scan | per-field 3 questions + non-HTTP Devil's Advocate | pre-flight | This skill Gate 0 (HTTP layer: XSPEC-201 Step 7); XSPEC-284 R4 (non-HTTP, future) |
+| ⑤ **Background side-effects** | crontab / queue config / webhook registry / mail points | **per-job "exists + has fired"** | pre-flight + **post-cutover** | **This skill — Background Job / Side-Effect Completeness** |
+| ⑥ Non-functional | legacy perf baseline + concurrency list | latency/throughput regression + isolation | pre-UAT | XSPEC-286 (split out) |
+| ⑦ Data integrity | schema type / encoding / timezone list | row count + checksum + encoding bytes + aggregate equality | post-migration + post-cutover | XSPEC-172 data-migration-testing; XSPEC-206; XSPEC-284 R6 (future) |
+| ⑧ **State machine** | legacy transition graph (enum + update-points + prod sequences) | **legal transitions + temporal invariants (`created ≤ updated`)** | pre-UAT + **post-cutover** | **This skill — State-Machine & Temporal Parity** (XSPEC-287) |
+| ⑨ **Error paths** | legacy exception hierarchy / error codes (this skill derive + degradation) | **error-path snapshot + systematic gap analysis + error-response differential** | pre-UAT + cutover before/after | **This skill — Error-Path Completeness** (R1/R3) + **full-coverage-testing** Migration Error-Path Completeness (R2/R4); XSPEC-288 |
+| **Cross-axis** | — | **shadow run** (mirror prod to both) / **replay** (replay legacy requests) | cutover before/after | XSPEC-284 R5 (generalises `/vo-snapshot` parity, future) |
+
+每軸宣告〔清單來源 derive｜oracle detect｜gate 時機〕；標為已覆蓋者對映既有 UDS 標準，**勿重複造輪子**。未宣告的軸視為**已知遺漏風險**。本框架 P0 落地＝軸③④⑤（本 skill）；軸⑥已拆 XSPEC-286（落地於 performance-standards）、**軸⑧已落地於本 skill State-Machine & Temporal Parity（XSPEC-287）**、**軸⑨已落地（XSPEC-288）＝本 skill Error-Path Completeness（R1/R3 derive + 降級）+ full-coverage-testing（R2/R4 系統性 gap 分析 + 錯誤回應差分）**。
+
 ## 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
+- Related: [behavior-snapshot](../../core/behavior-snapshot.md) — Curated golden-master parity (3-gate axis ②)
+- Related: [observability-assistant](../observability-assistant/SKILL.md) — Reconciliation schedule + alert rules for post-cutover oracle
+- Framework: XSPEC-284 Legacy Refactor Completeness Framework — 9-axis SSOT
 
 ## Version History | 版本歷史
 
 | Version | Date | Changes | 變更 |
 |---------|------|---------|------|
+| 1.4.0 | 2026-06-17 | Added: Error-Path Completeness (axis ⑨, XSPEC-288) — mechanized legacy exception/error-code derive (R1) + degradation/fallback parity checklist (R3) + production-frequency importance ranking; systematic gap analysis + error-response differential (R2/R4) delegated to full-coverage-testing; matrix row ⑨ split between this skill and full-coverage-testing | 新增錯誤路徑完整性（軸⑨，XSPEC-288）：機械化例外/錯誤碼 derive（R1）+ 降級對等清單（R3）+ 生產頻率重要性分級；系統性 gap 分析 + 錯誤回應差分（R2/R4）委由 full-coverage-testing |
+| 1.3.0 | 2026-06-17 | Added: State-Machine & Temporal Parity (axis ⑧, XSPEC-287) — three-way transition-graph derive (enum + update-points + prod sequences), legal-transition validation, temporal invariants (`created ≤ updated` / no future / monotonic), sequence/idempotency parity, boundary with XSPEC-286 axis ⑥; matrix row ⑧ now owned by this skill | 新增狀態機與時序對等（軸⑧，XSPEC-287）：三方轉移圖萃取、合法轉移驗證、時序不變量、序列/冪等對等、與 XSPEC-286 軸⑥邊界 |
+| 1.2.0 | 2026-06-17 | Added: Post-Cutover Data Reconciliation (cutover-boundary SQL + tolerance/alerting + Gate-0 implicit-rule checklist + 3-gate positioning), Background Job / Side-Effect Completeness (exists + has-fired), 9-axis Completeness Matrix appendix; cross-ref behavior-snapshot/observability-assistant (XSPEC-284 P0 R2/R3 / closes #134) | 新增 Post-Cutover 生產資料對帳、背景作業完整性驗證、9 軸完整性矩陣附錄 |
 | 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/observability-assistant/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: observability
 scope: universal
+anchor_standard: observability-standards
 description: |
   Guide observability setup, metrics design, and alerting configuration.
   Use when: new service instrumentation, SLO definition, alert design, maturity assessment.
@@ -13,6 +14,12 @@ argument-hint: "[service name or observability topic | 服務名稱或可觀測
 
 > **Language**: English | [繁體中文](../../locales/zh-TW/skills/observability-assistant/SKILL.md)
 
+**Version**: 1.0.0
+**Last Updated**: 2026-06-19
+**Applicability**: Claude Code Skills
+
+> **Core Standard**: This skill implements [Observability Standards](../../core/observability-standards.md). For the authoritative methodology (full Metrics/Traces detail, sampling, OTel integration), refer to the core standard.
+
 Guide observability implementation across the three pillars: Logs, Metrics, and Traces.
 
 引導三支柱可觀測性實作：Logs、Metrics、Traces。
@@ -37,6 +44,73 @@ Guide observability implementation across the three pillars: Logs, Metrics, and
 /observability "payment-service"      # Guide for specific service
 ```
 
+## Three Pillars Framework | 三支柱框架
+
+Each pillar gives a different lens; their power is in correlation.
+
+| Pillar | What It Captures | When to Use | Granularity |
+|--------|-----------------|-------------|-------------|
+| **Logs** | Discrete events with context | Debugging, audit trails, error details | High (per-event) |
+| **Metrics** | Numerical measurements over time | Dashboards, alerting, capacity planning | Low (aggregated) |
+| **Traces** | Request flow across services | Latency analysis, dependency mapping | Medium (per-request) |
+
+**Correlation fields**: `trace_id` links Logs ↔ Traces ↔ Metrics (via Exemplars);
+`service.name` filters all three pillars. Workflow: metric anomaly → exemplar →
+trace → `trace_id` in logs.
+
+## Golden Signals | 四大黃金信號
+
+Based on Google SRE. Every service SHOULD monitor all four before production.
+
+| Signal | Measure | Example Metric | Alert (SLO-based) |
+|--------|---------|----------------|-------------------|
+| **Latency** | P50/P95/P99 via Histogram, split success/error | `http.server.request.duration.seconds` | P99 > X ms for 5 min |
+| **Traffic** | Requests/sec, by route/method | `http.server.request.total` (rate) | drop > 50% or spike > 200% |
+| **Errors** | errors / total requests | `...request.total{status=~"5.."}` ÷ total | error rate > X% for 5 min |
+| **Saturation** | CPU/mem/pool/disk utilization | `system.cpu.utilization` (Gauge) | resource > 80% for 10 min |
+
+## Metric Types | Metric 型別
+
+| Type | Behavior | Use When |
+|------|----------|----------|
+| **Counter** | Only goes up (resets on restart) | request count, error count, bytes sent |
+| **Gauge** | Point-in-time, up/down | queue depth, active connections, memory |
+| **Histogram** | Distribution across buckets | request duration, response size |
+| **Summary** | Client-computed percentiles | legacy, no server-side aggregation |
+
+**Naming**: `<domain>.<entity>.<action>.<unit>` in `snake_case` (e.g.
+`db.client.query.duration.seconds`). **Label cardinality**: keep labels under
+~1000 unique values — never use `user_id` / `request_id` / raw `url` / `ip` as
+labels; record those in Logs or Traces instead.
+
+## Maturity Model (L0–L4) | 成熟度模型
+
+| Level | Name | Characteristics | Upgrade Action |
+|-------|------|-----------------|----------------|
+| **L0** | No Observability | only stdout/stderr; debug via SSH + `tail -f` | structured logging; centralize collection |
+| **L1** | Basic Logging | structured JSON logs, centralized, searchable | add business metrics; first dashboard |
+| **L2** | Metrics-Driven | Logs + Metrics, dashboards, threshold alerts | enable tracing; SLO-based alerting |
+| **L3** | Full Observability | three pillars + correlation + SLO alerts + Golden Signals | anomaly detection; auto-remediation |
+| **L4** | Intelligent | AIOps anomaly detection, predictive alerts, auto-remediation | maintain, optimize, share learnings |
+
+**Self-check**: find logs for one request across services (L1+) → dashboards of
+error rate & latency (L2+) → trace request ingress→DB→back (L3+) → auto-detect
+anomalies before users report (L4).
+
+## Instrumentation Checklist | 上線前檢查表
+
+Before deploying a service to production:
+
+- [ ] **Structured logging** — JSON with `trace_id` correlation
+- [ ] **HTTP/gRPC entry metrics** — request count, duration histogram, error rate per endpoint
+- [ ] **Business operation metrics** — key events tracked (orders, payments)
+- [ ] **Distributed tracing** — span propagation, sampling rate, W3C Trace Context headers
+- [ ] **Health checks** — liveness (running?) and readiness (can serve?) probes
+- [ ] **Golden Signals dashboard** — Latency, Traffic, Errors, Saturation visualized
+- [ ] **Alert rules** — at minimum SLO burn-rate alerts
+- [ ] **Log retention** — policies set per log level
+- [ ] **Sensitive data excluded** — no passwords, tokens, or PII in logs/traces
+
 ## Next Steps Guidance | 下一步引導
 
 > **可觀測性引導完成。建議下一步：**

package/bundled/skills/pr-automation-assistant/SKILL.md

@@ -7,6 +7,7 @@ description: |
   Keywords: pull request, PR, merge, review, GitHub, GitLab.
 allowed-tools: Read, Grep, Glob, Bash(git:*, gh:*)
 argument-hint: "[branch name or PR number | 分支名稱或 PR 編號]"
+status: reference
 ---
 <!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
   PR lifecycle orchestration (5-step: CREATE→REVIEW→APPROVE→MERGE→CLEANUP,
@@ -18,6 +19,9 @@ argument-hint: "[branch name or PR number | 分支名稱或 PR 編號]"
 
 # PR Automation Assistant | PR 自動化助手
 
+> ⚠️ **Status: Reference（參考用，非可執行流程）** — PR 生命週期協調（5 步驟 CREATE→REVIEW→APPROVE→MERGE→CLEANUP、>400 行 size gate、CI gate、squash/merge 策略、gh CLI 整合）已於 2026-04-28 移至 **adoption layer（XSPEC-095）**。此處保留 PR 描述模板、合併策略決策矩陣、auto-review 觸發規則供參考。
+> Lifecycle orchestration has moved to the adoption layer (XSPEC-095); this document is **reference-only**. For enforced execution, use your adoption layer's toolchain.
+
 Streamline the pull request lifecycle from creation to merge.
 
 簡化從建立到合併的 Pull Request 生命週期。
@@ -93,7 +97,7 @@ CREATE ──► REVIEW ──► APPROVE ──► MERGE ──► CLEANUP
 After `/pr` completes, the AI assistant should suggest:
 
 > **PR 操作完成。建議下一步 / PR operation complete. Suggested next steps:**
-> - 執行 `/review` 進行詳細程式碼審查 ⭐ **Recommended / 推薦** — Run detailed code review
+> - 執行 `/code-review` 進行詳細程式碼審查 ⭐ **Recommended / 推薦** — Run detailed code review
 > - 執行 `/commit` 修正審查發現的問題 — Fix issues found in review
 > - 執行 `/changelog` 更新變更日誌 — Update changelog
 > - 檢查 CI 狀態 → `gh pr checks` — Check CI status

package/bundled/skills/project-discovery/guide.md

@@ -301,9 +301,9 @@ Use `/sdd` after discovery to:
 - Write specifications for new features informed by discovery findings
 - Reference the Discovery Report for risk assessment sections
 
-### With /review (Code Review)
+### With /code-review (Code Review)
 
-The Step 0.4 snapshot is a lightweight version of `/review`. Use full `/review` when:
+The Step 0.4 snapshot is a lightweight version of `/code-review`. Use full `/code-review` when:
 - Discovery finds significant quality concerns
 - A deeper audit is needed before planning changes
 

package/bundled/skills/push/SKILL.md

@@ -227,7 +227,7 @@ After `/push` completes, the AI assistant should suggest:
 
 ## Related Standards | 相關標準
 
-- [Push Standards](.standards/push-standards.ai.yaml) — Core push safety rules
+- [Push Standards](../../.standards/push-standards.ai.yaml) — Core push safety rules
 - [Git Workflow](../../.standards/git-workflow.ai.yaml) — Branching strategy
 - [Commit Message](../../.standards/commit-message.ai.yaml) — Commit conventions
 - [PR Automation](../pr-automation-assistant/SKILL.md) — Pull Request automation

package/bundled/skills/release-standards/SKILL.md

@@ -49,11 +49,25 @@ Configure via `uds init` or `uds config --type release_mode`:
 ## Workflow | 工作流程
 
 1. **Determine version** - Decide version type based on changes (MAJOR/MINOR/PATCH)
-2. **Update version files** - Update package.json and related version references
-3. **Update CHANGELOG** - Move [Unreleased] entries to new version section
-4. **Run pre-release checks** - Verify tests, lint, and standards compliance
-5. **Create git tag** - Tag with `vX.Y.Z` format
-6. **Commit and push** - Commit version bump and push tags
+2. **Triage open issues/PRs** - `gh pr list` + `gh issue list`; classify each **bring-in vs defer** (XSPEC-265) / 掃描 issue/PR、每項二分（帶上 vs backlog）
+3. **Update version files** - Update package.json and related version references
+4. **Update CHANGELOG** - Move [Unreleased] entries to new version section
+5. **Run pre-release checks** - Verify tests, lint, standards compliance, **and issue/PR triage gate**
+6. **Create git tag** - Tag with `vX.Y.Z` format
+7. **Commit and push** - Commit version bump and push tags
+
+### Pre-release Issue/PR Triage Gate | 發版前 issue/PR triage 閘門 (XSPEC-265)
+
+Before bumping, scan open issues/PRs and make a conscious decision per item — do **not** rely on memory:
+
+| Class | Action |
+|-------|--------|
+| **Bring-in** | patch dependabot PR / release-blocking bug / fix relevant to this version's theme → merge before bump |
+| **Defer** | major PR, audit/enhancement issue, needs separate evaluation → record in signoff "deferred" + release-notes Known Issues |
+
+- Confirm `cross-project/sub-project-triage.md` snapshot is recent (≤7 days); refresh if stale.
+- Record the result in the release sign-off (Tier-1): `Pre-release issue/PR triage | PASS | N PRs / M issues: X merged / Y deferred`.
+- **Do not require emptying the backlog** — only that every item has a conscious decision + a record. 不要求清空 backlog，只要求每項有意識決策 + 留紀錄。
 
 ### Version Increment Rules | 版本遞增規則
 

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

@@ -79,7 +79,7 @@ After `/security` completes, the AI assistant should suggest:
 
 > **安全審查完成。建議下一步 / Security review complete. Suggested next steps:**
 > - 執行 `/checkin` 確認修復符合提交規範 ⭐ **Recommended / 推薦** — Verify fixes meet check-in standards
-> - 執行 `/review` 進行程式碼審查 — Run code review on security fixes
+> - 執行 `/code-review` 進行程式碼審查 — Run code review on security fixes
 > - 執行 `/commit` 提交安全修復 — Commit security fixes
 > - 檢查相依套件更新 → `npm audit` 或 `pip audit` — Check dependency updates
 

package/bundled/skills/skill-builder/SKILL.md

@@ -8,7 +8,7 @@ argument-hint: "[process description | 流程描述]"
 
 # Process-to-Skill Assistant
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/process-automation/SKILL.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/skill-builder/SKILL.md) | [简体中文](../../locales/zh-CN/skills/skill-builder/SKILL.md)
 
 Guides you from "I keep doing this manually" to a properly built Skill,
 with the right amount of process along the way.

package/bundled/skills/spec-derivation/guide.md

@@ -9,7 +9,7 @@ description: |
 
 # Forward Derivation Guide
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/forward-derivation/SKILL.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/spec-derivation/SKILL.md)
 
 **Version**: 2.0.0
 **Last Updated**: 2026-01-25
@@ -214,18 +214,17 @@ Scenario: Login shows error for invalid credentials
 # Generator: /derive-bdd v1.0.0
 # Generated at: 2026-01-19T10:00:00Z
 
-@SPEC-001
 Feature: User Authentication
   [Source] From SPEC-001 Summary
 
-  @AC-1 @happy-path
+  @SPEC-001 @AC-1 @happy-path
   Scenario: User login with valid credentials
     # [Source] From SPEC-001 AC-1
     Given a registered user with valid credentials
     When the user submits login form
     Then the user is redirected to dashboard
 
-  @AC-2 @error-handling
+  @SPEC-001 @AC-2 @error-handling
   Scenario: Login fails with invalid credentials
     # [Source] From SPEC-001 AC-2
     Given a user with invalid credentials

package/bundled/skills/spec-driven-dev/SKILL.md

@@ -194,8 +194,8 @@ is a faithful projection of the AC spine across specs.
 
 | Signal | Meaning | Gate |
 |--------|---------|------|
-| **orphan test** | `@AC AC-NNN` references an AC no spec defines / 引用不存在的 AC | 🔴 BLOCKING |
-| **uncovered** | an AC has no `@AC` reference / AC 無測試引用 | report only / 僅報告 |
+| **orphan test** | `@SPEC-NNN @AC-N` references an AC no spec defines / 引用不存在的 AC | 🔴 BLOCKING |
+| **uncovered** | an AC has no `@SPEC-NNN @AC-N` reference / AC 無測試引用 | report only / 僅報告 |
 | **not_implemented** | AC marked so in its `.ac.yaml` / `.ac.yaml` 標記 | 🔴 BLOCKING before UAT |
 | **cross-spec conflict** | same AC id defined in >1 spec / 同 AC id 跨多 spec | 🔴 BLOCKING |
 | **orphan .feature** | Gherkin `@AC-N` tag referencing a non-existent AC / @AC-N 引用不存在 | 🔴 BLOCKING |

package/bundled/skills/sweep/SKILL.md

@@ -119,7 +119,7 @@ sweep:
 After `/sweep` completes, suggest:
 
 > - Run `/checkin` to verify overall code quality before committing
-> - Run `/review` to review the cleaned-up changes
+> - Run `/code-review` to review the cleaned-up changes
 > - Run `/commit` to commit the fixes
 
 ---

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

@@ -4,6 +4,7 @@ scope: partial
 description: "[UDS] Guide through Test-Driven Development workflow"
 allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx vitest:*)
 argument-hint: "[feature or file | 功能或檔案]"
+status: reference
 ---
 <!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
   TDD flow orchestration (RED→GREEN→REFACTOR cycle, test execution gates) relocated to adoption
@@ -14,6 +15,9 @@ argument-hint: "[feature or file | 功能或檔案]"
 
 # TDD Assistant | TDD 助手
 
+> ⚠️ **Status: Reference（參考用，非可執行流程）** — TDD 流程協調（RED→GREEN→REFACTOR 循環、測試執行 gates）已於 2026-04-28 移至 **adoption layer（XSPEC-095）**。此處保留 TDD 原則、FIRST 規則、AAA 格式、語言範例、流程指南供參考。
+> Lifecycle orchestration has moved to the adoption layer (XSPEC-095); this document is **reference-only**. For enforced execution, use your adoption layer's toolchain.
+
 Guide through the Test-Driven Development workflow: Red-Green-Refactor.
 
 引導測試驅動開發（TDD）流程：紅-綠-重構。
@@ -30,6 +34,9 @@ Guide through the Test-Driven Development workflow: Red-Green-Refactor.
 
 ## Workflow | 工作流程
 
+> 📖 以下為流程的**參考結構**，非可執行步驟；自動化／強制執行請用 adoption layer 工具鏈（XSPEC-095）。
+> The steps below are a **reference structure**, not an executable workflow.
+
 ### Phase 1: RED - Write Failing Test | 紅燈 - 撰寫失敗測試
 
 - Write a test that describes the desired behavior | 撰寫描述預期行為的測試
@@ -72,7 +79,7 @@ After `/tdd` completes, the AI assistant should suggest:
 > **TDD 循環完成。建議下一步 / TDD cycle complete. Suggested next steps:**
 > - 執行 `/checkin` 通過品質關卡 ⭐ **Recommended / 推薦** — Pass quality gates
 > - 執行 `/coverage` 確認測試覆蓋率 — Check test coverage
-> - 執行 `/review` 自我審查程式碼 — Self-review code quality
+> - 執行 `/code-review` 自我審查程式碼 — Self-review code quality
 
 ## Reference | 參考
 

package/bundled/skills/testing-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing-guide
-scope: uds-specific
+scope: universal
 description: |
   Testing pyramid and test writing standards for UT/IT/ST/E2E.
   Supports ISTQB and Industry Pyramid frameworks.

package/bundled/skills/testing-guide/testing-theory.md

@@ -1,6 +1,6 @@
 # Testing Theory Knowledge Base
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/testing-guide/testing-theory.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/testing-guide/testing-theory.md) | [简体中文](../../locales/zh-CN/skills/testing-guide/testing-theory.md)
 
 **Version**: 1.0.0
 **Last Updated**: 2026-01-29

package/bundled/skills/workflows/README.md

@@ -1,6 +1,6 @@
 # UDS Workflows
 
-> **Language**: English | [繁體中文](../../locales/zh-TW/skills/workflows/README.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/workflows/README.md) | [简体中文](../../locales/zh-CN/skills/workflows/README.md)
 
 **Version**: 1.1.0
 **Last Updated**: 2026-01-21
@@ -423,7 +423,7 @@ This prevents context pollution and ensures reproducible agent behavior.
 
 - [Agents Documentation](../agents/README.md)
 - [Skills Documentation](../README.md)
-- [Methodology System](../methodology-system/SKILL.md)
+- [Methodology System](../dev-methodology/SKILL.md)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.17.0",
+  "version": "6.0.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -61,7 +61,7 @@
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
     "chalk": "^5.3.0",
-    "commander": "^14.0.0",
+    "commander": "^15.0.0",
     "js-yaml": "^4.1.0",
     "ora": "^9.4.0"
   },
@@ -70,7 +70,7 @@
     "@vitest/coverage-v8": "^4.1.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "eslint": "10.4.1",
+    "eslint": "10.5.0",
     "glob": "^13.0.1",
     "globals": "17.6.0",
     "husky": "^9.1.7",