spec-lite 1.5.2 → 1.7.0

package/templates/main/feature/frd-template.md

@@ -4,10 +4,15 @@ type: frd
 status: draft
 owner: "{BA}"
 feature_id: "{Feature ID từ PRD Feature Index}"
-template_version: 1
+template_version: 2
 migrations:
   - to: 1
     note: "baseline"
+  - to: 2
+    note: "Tách FAC theo type/execution-mode: FAC rescope còn end-to-end (journey + consistency + integrity); tách entries loại NFR → section 'Non-Functional Requirements' và loại data/migration → section 'Data & Migration', cả hai required-emptyable (heading luôn hiện, để trống nếu không có). NFR-F* tham chiếu NFR-* của PRD nếu có thể. Test case downstream giữ prefix TC-F*."
+    add: ["Non-Functional Requirements", "Data & Migration"]
+    update:
+      - { section: "Feature Acceptance Criteria", change: "rescope còn end-to-end (e2e liên story + cross-story consistency + integrity); tách entries loại NFR → section 'Non-Functional Requirements' (required-emptyable), loại data/migration → section 'Data & Migration' (required-emptyable); relocate tương tác, e2e/consistency giữ nguyên" }
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.3 Feature level > frd.md > Cấu trúc
   - skills/spec-frd/SKILL.md > Process > Bước 5: Write — sinh draft
@@ -55,25 +60,55 @@ flowchart TD
 
 ## Feature Acceptance Criteria
 
-Criteria áp dụng cho **toàn bộ feature** — phần Story AC không cover được. Mọi Feature AC phải test được pass/fail.
+Criteria **end-to-end** áp cho toàn feature mà Story AC lẻ không cover được — verify sự **kết nối giữa các phần** (emergent), không phải behavior từng story. Mọi Feature AC phải test được pass/fail.
 
-Thường gồm 4 nhóm:
-- **End-to-end liên story** — full happy path đi qua nhiều story.
-- **Cross-story consistency** — UI/behavior đồng nhất giữa các màn trong feature.
-- **Non-functional** — performance, accessibility, browser support, i18n, security.
-- **Data & migration** — backfill, schema migration, không mất data cũ.
+Gồm 3 shape (đều functional, scope rộng — trục phân chia + lý do xem `terms/001-frd-fac-pillars.md`; nền tảng type/scope xem `terms/002-functional-test-vs-e2e-test.md`):
+- **Journey (liên story)** — full happy path đi *tuần tự* qua nhiều story trong 1 session; verify state persist + không đứt giữa các bước.
+- **Consistency (đa màn)** — UI/behavior đồng nhất khi *so* nhiều màn trong feature với nhau.
+- **Integrity (bất biến liên story)** — business invariant phải đúng khi *kết hợp* nhiều story, **không nhất thiết theo trình tự** (vd: xóa account → cascade xóa mọi order ở mọi module; tổng/đối soát khớp sau nhiều thao tác). Verify *trạng thái nhất quán cuối cùng*, không phải hành trình tuần tự — đây là nhà cho cross-story functional rule mà journey/consistency không ôm.
 
+> NFR (performance, a11y, security, browser, i18n) và Data & Migration **KHÔNG** thuộc đây — chúng có section riêng bên dưới (khác type / execution-mode).
 > Out of scope: release readiness (runbook/rollout/legal sign-off) và success metric/KPI post-release — đặt ở artifact khác (`tech.md`, `sad.md`, hoặc PMO checklist).
 
 Feature AC ID format: `FAC-F{NNN}-{seq}` — counter **độc lập** với Story AC (`AC-F{NNN}-{seq}`). ID **stable** — không tái sử dụng seq khi xóa, không renumber.
 
-Format: **Given/When/Then bắt buộc** — kể cả NFR / consistency. **Then phải đo được**: ngưỡng cụ thể HOẶC danh sách item so sánh.
+Format: **Given/When/Then bắt buộc** — kể cả consistency. **Then phải đo được**: ngưỡng cụ thể HOẶC danh sách item so sánh.
 
 - `FAC-{F_ID}-001`
   - **Given** {precondition đo được}
   - **When** {action}
   - **Then** {outcome có threshold hoặc danh sách cụ thể, không vague}
 
+## Non-Functional Requirements
+
+<!-- Required-emptyable: GIỮ heading; để trống (không bullet) nếu feature không có NFR riêng ngoài bar chung của PRD. -->
+
+NFR áp cho feature — **non-functional type** (performance, accessibility, security, browser support, i18n). Khác Feature AC ở chỗ verify *chất lượng dưới điều kiện*, không phải *làm đúng việc*.
+
+> **Security — phân biệt rõ type:** access-control / authz rules ("role X không được thấy/làm Y") là **functional** → đặt ở Story AC hoặc Verification Rules, KHÔNG vào đây. Chỉ phần **non-functional** của security (pentest, vulnerability scan, security posture / hardening — verify bằng scanner, không phải walk UI) mới là NFR.
+
+Quan hệ với PRD: mỗi NFR **tham chiếu `NFR-*` của PRD nếu có thể** (refine/siết bar chung cho feature này); nếu là yêu cầu **đặc thù-feature** mà PRD không có → đứng độc lập (không ref).
+
+NFR ID format: `NFR-F{NNN}-{seq}` — counter độc lập. ID **stable** — không tái sử dụng seq khi xóa, không renumber. Format **Given/When/Then bắt buộc**, **Then đo được** (ngưỡng cụ thể).
+
+- `NFR-{F_ID}-001` *(refines `NFR-P01` — nếu có)*
+  - **Given** {điều kiện đo được — vd: 100 RPS sustained 5 phút}
+  - **When** {action}
+  - **Then** {ngưỡng cụ thể — vd: p95 ≤ 500ms, error rate ≤ 0.1%}
+
+## Data & Migration
+
+<!-- Required-emptyable: GIỮ heading; để trống (không bullet) nếu feature không đụng migration / backfill data cũ. -->
+
+Yêu cầu về **dữ liệu cũ qua nâng cấp** — backfill, schema migration, không mất/hỏng data hiện hữu. Functional-type nhưng execution-mode riêng (chạy migration trên dataset, không phải UI flow).
+
+DM ID format: `DM-F{NNN}-{seq}` — counter độc lập. ID **stable** — không tái sử dụng seq khi xóa, không renumber. Format **Given/When/Then bắt buộc**, **Then đo được** (đếm bản ghi / so khớp cụ thể).
+
+- `DM-{F_ID}-001`
+  - **Given** {dataset cũ đo được — vd: 10.000 bản ghi địa chỉ format cũ}
+  - **When** {chạy migration}
+  - **Then** {kết quả đo được — vd: 10.000/10.000 đọc được, 0 bản ghi null, count khớp trước/sau}
+
 ## User Stories
 
 US ID format: `US-F{NNN}-{seq}` — đánh số tăng dần toàn feature. ID **stable** — không tái sử dụng seq khi xóa, không renumber.

package/templates/main/feature/test-design-template.md

@@ -0,0 +1,289 @@
+---
+id: test-design-{feature}
+type: test-design
+status: draft
+owner: "{QC}"
+feature_id: "{Feature ID — match frd.md}"
+frd_ref: "feature/{F-XXX}-{slug}/frd.md"
+template_version: 3
+migrations:
+  - to: 1
+    note: "baseline"
+  - to: 2
+    note: "Mirror frd v2 + trim execution-leakage (giữ vai WHAT). Tách 'Feature AC Test Cases' (v1) theo type/execution-mode: đổi tên → 'E2E Test Cases' (chỉ FAC end-to-end: journey/consistency/integrity), tách TC loại NFR → 'Non-Functional Test Cases' và loại data/migration → 'Data & Migration Test Cases', cả hai required-emptyable. TC giữ prefix TC-F* chung sequence."
+    add: ["E2E Test Cases", "Non-Functional Test Cases", "Data & Migration Test Cases"]
+    remove:
+      - { section: "Feature AC Test Cases", reason: "đổi tên → 'E2E Test Cases' (chỉ cover FAC end-to-end) + tách TC Type=NFR → 'Non-Functional Test Cases' (required-emptyable), Type=data/migration → 'Data & Migration Test Cases' (required-emptyable); carry-over toàn bộ TC theo field Type, không mất nội dung" }
+      - { section: "Test Strategy > Environments", reason: "env assignment/scheduling là execution concern — design chỉ cần env requirement ở per-TC Preconditions" }
+    update:
+      - { section: "Test Data", change: "đổi thành 'Test Data Requirements' — bỏ cột Nguồn (fixture/factory = provisioning) + Refresh (cadence = execution), thêm cột 'Yêu cầu data (shape)'" }
+  - to: 3
+    note: "Thêm field Autoable (YES/MAYBE/NO) cho TC — test-design là SOURCE OF TRUTH route TC vào func-auto (YES/MAYBE) vs func-manual (toàn bộ + NO); hai track chỉ đọc, không tự quyết. Phân loại theo oracle của Expected: lập trình được (giá trị/state/record/HTTP/message/route)=YES, lập trình được nhưng setup nặng=MAYBE, visual (màu/layout/icon/animation)=NO. Mọi Validation TC = YES theo định nghĩa (không cần cột riêng)."
+    update:
+      - { section: "Functional Test Cases", change: "thêm field 'Autoable' (YES/MAYBE/NO) vào mỗi TC block + rule phân loại theo oracle ở đầu section" }
+      - { section: "Validation Test Cases", change: "ghi rõ mọi VR-derived TC = Autoable=YES (uniform, không thêm cột)" }
+---
+
+<!--
+Canonical format cho feature/{F-XXX}-{slug}/test-design.md.
+Sinh từ frd.md — mỗi AC / VR / Flow phải có ít nhất 1 test case cover.
+Traceability Matrix ở cuối là source of truth để kiểm tra coverage trước khi đóng feature.
+
+Test Design chỉ tồn tại ở FEATURE level — không tách test-design riêng cho component.
+Component là internal building block; contract của component được verify gián tiếp qua TC ở đây
+và qua unit test trong code (không phải spec artifact).
+-->
+
+# Test Design: {Feature Name}
+
+## Overview
+
+{Phạm vi test-design này — feature gì, các luồng / AC / VR chính cần verify, trong 2-3 câu.}
+
+## Test Strategy
+
+### Approach
+
+- **Functional**: verify từng US / Story AC theo happy + edge.
+- **Validation**: derive 1:1 từ Verification Rules.
+- **Flow-based (E2E)**: chạy theo Mermaid flows trong frd.
+- **Feature AC (end-to-end)**: cover `FAC-*` — journey liên story + cross-story consistency.
+- **Non-functional**: cover `NFR-*` — performance / a11y / security (execution-mode riêng: load test, scanner...).
+- **Data & migration** *(nếu có)*: cover `DM-*` — chạy migration trên dataset, verify data cũ không mất/hỏng.
+
+> Yêu cầu env của mỗi test class ghi inline ở **Preconditions** từng TC (vd "env perf-test", "dataset prod-like đã load"). Gán env tier cụ thể + lịch chạy thuộc **execution layer** — không ở test-design.
+
+## Test Scenarios
+
+Mỗi scenario gắn với 1 flow trong `frd.md > User Flows`. Scenario mô tả end-to-end path; test case chi tiết liệt kê ở section bên dưới.
+
+TS ID format: `TS-F{NNN}-{seq}` — đánh số tăng dần toàn feature. ID **stable** — đã assign rồi giữ nguyên kể cả khi xóa (không tái sử dụng seq, không renumber).
+
+### TS-{F_ID}-001: {Tên — match Flow 1 trong frd}
+
+- **Flow ref:** `frd.md > Flow 1: {tên}`
+- **Preconditions:** {state trước khi chạy}
+- **Postconditions:** {state sau khi pass}
+- **Paths:**
+  - Happy: A → B → C(happy) → D → F
+  - Edge: A → B → C(edge) → E → G
+- **Test cases:** `TC-{F_ID}-001`, `TC-{F_ID}-002`, ...
+
+---
+
+### TS-{F_ID}-002: {Tên — match Flow 2 nếu có}
+
+...
+
+## Functional Test Cases
+
+Cover User Stories và Acceptance Criteria trong frd.
+
+TC ID format: `TC-F{NNN}-{seq}` — đánh số tăng dần toàn feature. ID **stable** (không tái sử dụng seq khi xóa, không renumber). Nếu xóa TC → ID đó retire, seq mới tiếp tục tăng từ max.
+
+**Autoable** — test-design là **source of truth** cho field này; cả `test-exec-func-auto` lẫn `test-exec-func-manual` **chỉ đọc**, không tự quyết. Route TC vào đâu: func-auto cover `YES/MAYBE`, func-manual cover **toàn bộ** + `NO`. Phân loại theo **oracle của Expected** (cái mà outcome được verify):
+
+- `YES` — oracle **lập trình được**: giá trị / state / record / HTTP status / error-message text / route / computed result. *(Mọi Validation TC ⇒ YES theo định nghĩa.)*
+- `MAYBE` — oracle lập trình được **nhưng** chỉ tới được qua setup nặng: multi-entity seed, cross-service integration, prior state phức tạp.
+- `NO` — oracle **visual**: màu / spacing / layout / icon-asset render / animation / "trông đúng". Hiếm có `TC-F*` — assertion visual thuần thường không thành AC nên thành exploratory (không ID) ở manual, không phải TC này.
+
+### TC-{F_ID}-001: {Title ngắn — verb-first}
+
+| Field | Value |
+| --- | --- |
+| **Type** | Functional — positive / negative |
+| **Autoable** | YES / MAYBE / NO — phân loại theo oracle (rule ở đầu section) |
+| **Priority** | P0 / P1 / P2 |
+| **Covers** | `US-{F_ID}-001`, `AC-{F_ID}-001` |
+| **Scenario** | `TS-{F_ID}-001` |
+| **Preconditions** | ... |
+
+**Steps:**
+
+1. {action}
+2. {action}
+3. {action}
+
+**Expected:**
+
+- {observable outcome 1}
+- {observable outcome 2}
+
+**Test data:** {ref Test Data Requirements hoặc inline literal}
+
+---
+
+### TC-{F_ID}-002: ...
+
+## Validation Test Cases
+
+Derive 1:1 từ Verification Rules trong frd. **Mọi Validation TC ⇒ `Autoable=YES`** (oracle input→accept/reject, logic thuần — không phụ thuộc visual); uniform nên không thêm cột. Mỗi `VR-F{NNN}-{seq}` cần ít nhất:
+- 1 positive (rule pass)
+- 1+ negative — mỗi nhánh fail là 1 case riêng (vd VR "email format" → 1 case cho missing `@`, 1 case cho missing domain, ...)
+
+Form bảng để dễ scan; case phức tạp có thể tách ra block riêng như Functional TC.
+
+| TC ID | Covers VR | Field | Input | Expected | Polarity |
+| --- | --- | --- | --- | --- | --- |
+| `TC-{F_ID}-010` | `VR-{F_ID}-001` | `email` | `"user@example.com"` | accept | positive |
+| `TC-{F_ID}-011` | `VR-{F_ID}-001` | `email` | `""` | reject — required | negative |
+| `TC-{F_ID}-012` | `VR-{F_ID}-001` | `email` | `"abc"` | reject — invalid format | negative |
+
+## E2E Test Cases
+
+Cover Feature Acceptance Criteria (`FAC-*`) trong frd — **end-to-end** (journey + consistency + integrity). FAC ở frd đã ở format G/W/T → TC dịch 1:1: Given → Preconditions, When → Steps, Then → Expected. Phân biệt shape bằng field **Type**: `E2E — journey` = tuần tự liên story / `E2E — consistency` = so khớp đa màn / `E2E — integrity` = assert business invariant sau khi kết hợp nhiều story (không nhất thiết tuần tự) (không có TC riêng cho NFR / data ở đây — xem 2 section bên dưới).
+
+### TC-{F_ID}-040: {Title — e2e journey liên story}
+
+| Field | Value |
+| --- | --- |
+| **Type** | E2E — journey |
+| **Priority** | P0 / P1 / P2 |
+| **Covers** | `FAC-{F_ID}-001` |
+| **Spans** | `US-{F_ID}-001`, `US-{F_ID}-002`, `US-{F_ID}-003` |
+| **Preconditions** | account mới chưa onboard |
+
+**Steps:**
+
+1. Đăng ký account mới
+2. Verify email qua link
+3. Hoàn thành onboarding form
+4. Thực hiện first transaction
+
+**Expected:**
+
+- Toàn bộ flow chạy trong 1 session, không cần support intervene
+- State persist đúng giữa các step (refresh không mất tiến độ)
+
+---
+
+### TC-{F_ID}-041: {Title — consistency}
+
+| Field | Value |
+| --- | --- |
+| **Type** | E2E — consistency |
+| **Priority** | P1 |
+| **Covers** | `FAC-{F_ID}-002` |
+| **Preconditions** | feature đã deploy lên test env, 3 màn Register / Profile / Admin Create accessible |
+
+**Steps:**
+
+1. Trigger empty `email` validation ở Register
+2. Trigger empty `email` validation ở Profile
+3. Trigger empty `email` validation ở Admin Create
+4. Trigger invalid format `"abc"` ở cả 3 màn
+
+**Expected:**
+
+- 3 message ở step 1-3 identical (cùng text, cùng style)
+- 3 message ở step 4 identical
+
+---
+
+## Non-Functional Test Cases
+
+<!-- Required-emptyable: GIỮ heading; để trống (không TC) nếu section Non-Functional Requirements ở frd rỗng. -->
+
+Cover `NFR-*` trong frd. **Non-functional type** — execution-mode riêng (load test / scanner / a11y audit), không phải UI walk. Type = `performance` / `a11y` / `security` / ... TC giữ prefix `TC-F*` chung sequence.
+
+### TC-{F_ID}-050: {Title — NFR perf}
+
+| Field | Value |
+| --- | --- |
+| **Type** | Non-functional — performance |
+| **Priority** | P0 |
+| **Covers** | `NFR-{F_ID}-001` |
+| **Preconditions** | env perf-test, dataset baseline đã load |
+
+**Steps:**
+
+1. Chạy load test (k6 / JMeter) profile 100 RPS sustained 5 phút lên `/login`
+2. Đọc p95 latency từ summary report
+
+**Expected:**
+
+- p95 ≤ 500ms
+- Error rate ≤ 0.1%
+
+## Data & Migration Test Cases
+
+<!-- Required-emptyable: GIỮ heading; để trống (không TC) nếu section Data & Migration ở frd rỗng. -->
+
+Cover `DM-*` trong frd. Chạy migration trên dataset prod-like rồi assert data cũ nguyên vẹn. Type = `data migration`. TC giữ prefix `TC-F*` chung sequence.
+
+### TC-{F_ID}-060: {Title — migrate data cũ}
+
+| Field | Value |
+| --- | --- |
+| **Type** | Data migration |
+| **Priority** | P0 |
+| **Covers** | `DM-{F_ID}-001` |
+| **Preconditions** | env có dataset cũ prod-like (vd: 10.000 bản ghi địa chỉ format cũ) đã load |
+
+**Steps:**
+
+1. Snapshot count + checksum dataset trước migration
+2. Chạy migration script
+3. Đọc lại toàn bộ bản ghi sau migration
+
+**Expected:**
+
+- Count sau = count trước (10.000/10.000), không bản ghi nào null
+- Mọi địa chỉ cũ đọc được đúng format mới, 0 lỗi parse
+
+## Test Data Requirements
+
+Dữ liệu mỗi test **cần** (requirement — KHÔNG phải provisioning/refresh; cách lấy data + cadence thuộc execution layer).
+
+| Data set | Mục đích | Yêu cầu data (shape / đặc điểm) |
+| --- | --- | --- |
+| `seed_users` | functional positive | user hợp lệ, đủ field bắt buộc |
+| `boundary_inputs` | validation edges | giá trị biên cho mỗi VR (rỗng, sai format, quá dài...) |
+
+## Traceability Matrix
+
+**Source of truth** để verify coverage trước khi đóng feature. Mỗi item từ frd phải xuất hiện. Gap → đánh ❌ và mô tả rõ ở phần "Gaps" bên dưới.
+
+| FRD Item | Type | Covered by | Status |
+| --- | --- | --- | --- |
+| Flow 1 | Flow | `TS-{F_ID}-001` | ✅ |
+| `US-{F_ID}-001` | US | `TC-{F_ID}-001`, `TC-{F_ID}-002` | ✅ |
+| `AC-{F_ID}-001` | Story AC | `TC-{F_ID}-001` | ✅ |
+| `VR-{F_ID}-001` | VR | `TC-{F_ID}-010`, `TC-{F_ID}-011`, `TC-{F_ID}-012` | ✅ |
+| `FAC-{F_ID}-001` | Feature AC (e2e) | `TC-{F_ID}-040` | ✅ |
+| `FAC-{F_ID}-002` | Feature AC (consistency) | `TC-{F_ID}-041` | ✅ |
+| `NFR-{F_ID}-001` | NFR | `TC-{F_ID}-050` | ✅ |
+| `DM-{F_ID}-001` | Data & Migration | `TC-{F_ID}-060` | ✅ |
+| `AC-{F_ID}-00X` | Story AC | — | ❌ chưa có TC |
+
+### Gaps
+
+{Liệt kê item ❌ kèm lý do tạm hoãn / blocker — empty nếu coverage đầy đủ.}
+
+## Out of Scope
+
+- {những gì test-design này KHÔNG cover — lý do (vd: thuộc layer khác như infra/security audit, đã verify ở môi trường khác, ...)}
+
+## Dependencies
+
+### FRD reference
+
+- `frd.md` của feature này — mọi ID (`US-`, `AC-`, `VR-`, `FAC-`, `NFR-`, `DM-`, Flow) phải match.
+
+### Components Used (input only)
+
+Tham chiếu `frd.md > Components Used` để hiểu contract của các component được feature này dùng. Behavior của component được verify **gián tiếp** qua các TC ở đây — không tách test-design riêng cho component.
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../../../integrations/{id}-{slug}/test.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

package/templates/main/prd-template.md

@@ -68,6 +68,8 @@ Chi tiết về vai trò và thiết kế nằm trong `.specs/main/component/{C-
 
 ## Non-Functional Requirements
 
+NFR **product-wide** (bar chung cho cả sản phẩm). Feature refine/siết bar này cho ngữ cảnh của nó trong `frd.md > Non-Functional Requirements` bằng `NFR-F{NNN}-{seq}` *(tham chiếu `NFR-*` ở đây)*; NFR đặc thù-feature mà chưa có ở đây → nếu lặp lại ở nhiều feature thì **promote** lên bảng này.
+
 | ID | Category | Requirement | Target | Priority |
 | --- | --- | --- | --- | --- |
 | NFR-P01 | Performance | {requirement} | {target đo được} | High/Medium/Low |

package/templates/test-executions/test-exec-dm-template.md

@@ -0,0 +1,83 @@
+---
+id: test-exec-dm-{F-XXX}-{NNN}-{slug}
+type: test-exec-dm
+status: draft
+owner: "{SE / DBA}"
+feature_id: "{F-XXX}"
+test_design_ref: "main/feature/{F-XXX}-{slug}/test-design.md"
+referenced_by:
+  - conventions.md > Test Execution Artifacts > test-exec-dm.md
+  - terms/003-test-exec-buckets.md
+---
+
+<!--
+Canonical format cho .specs/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/test-exec-dm.md.
+EXECUTION layer — ephemeral per test cycle, harness "migration script trên dataset prod-like", owner SE/DBA.
+Cover Data & Migration (DM) — backfill, schema migration, data cũ không mất/hỏng. Xem terms/003.
+
+KHÔNG versioned: không template_version / migrations, ngoài scope /artifact-audit + /artifact-migrate.
+Derived từ test-design.md → test-design đổi thì REGENERATE.
+
+CHỈ TẠO file này khi frd.md có `DM-F*` (test-design § Data & Migration Test Cases không rỗng).
+  Feature không đụng migration → KHÔNG tạo test-exec-dm.md.
+
+Source of truth: test-design.md > Data & Migration Test Cases.
+  - ID = TC-F{NNN}-{seq} inherit từ test-design (Covers DM-F*). KHÔNG tạo ID mới.
+  - Coverage master = test-design.md > Traceability Matrix.
+-->
+
+# Data & Migration Test Execution: {Feature Name}
+
+**Feature**: {F-XXX} | **Owner**: {owner} | **Status**: {status}
+
+---
+
+## 1. Context
+
+| **Field** | **Detail** |
+|---|---|
+| **Feature Summary** | {1–2 câu — migration/backfill scope} |
+| **DM covered** | {DM IDs — `DM-F{NNN}-001`, ...} |
+| **Source** | [test-design.md](../../../main/feature/{F-XXX}-{slug}/test-design.md) — TC IDs (Data & Migration Test Cases) + Traceability Matrix |
+| **Migration artifact** | {ref script/EF migration: `{migration-name}` hoặc path} |
+
+---
+
+## 2. Dataset & Migration Setup
+
+> Migration chạy trên dataset **prod-like** — không phải seed nhỏ. Phải snapshot trước để so khớp.
+
+| **Field** | **Detail** |
+|---|---|
+| **Dataset** | {vd: 10.000 bản ghi địa chỉ format cũ — nguồn / cách load} |
+| **Pre-condition chung** | Migration script đã review · dataset prod-like đã load vào env test |
+| **Snapshot before** | count + checksum trước migration (baseline để assert) |
+| **Rollback plan** | {cách revert nếu migration fail — backup/restore / down-migration} |
+
+---
+
+## 3. DM Execution
+
+> **Input:** test-design.md § Data & Migration Test Cases (TC ID, expected — đếm/so khớp).
+> **Test Result:** `—` (chưa chạy) | `✅ Pass` | `❌ Fail` | `⛔ Blocked` | `🔴 HOLD`
+
+| **TC ID** | **Covers** | **Pre-condition** | **Migration Command** | **Expected** | **Test Result** | **Priority** |
+|---|---|---|---|---|---|---|
+| `TC-F{NNN}-060` | `DM-F{NNN}-001` | Dataset prod-like loaded ({N} bản ghi cũ) · snapshot baseline | `{migration-command}` | count sau = count trước ({N}/{N}) · 0 null · format mới parse đúng | — | 🔴 P0 |
+
+---
+
+## 4. Exit Criteria
+
+- [ ] Mọi DM P0 TC pass — data cũ nguyên vẹn (count + checksum khớp)
+- [ ] 0 bản ghi mất / null / lỗi parse sau migration
+- [ ] Rollback đã verify chạy được (dry-run hoặc trên copy)
+- [ ] Test Result column updated đầy đủ
+
+---
+
+## 5. Change Log
+
+| **Date** | **Cycle** | **Changes** | **Author** |
+|---|---|---|---|
+| {YYYY-MM-DD} | {cycle/release} | Initial DM execution (derive từ test-design.md) | {Author} |