spec-lite 1.5.1 → 1.6.0

package/skills/spec-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-test
-description: Tạo test.md cho một integration bằng cách mechanical derive Test Scenarios + Test Cases từ Flows/US/AC/VR/FAC trong frd.md. Auto-cascade lên feature/{F-XXX}/tsd.md. Role QC, song song với /spec-tech (DEV) — cả hai chỉ phụ thuộc spec.md approved.
+description: Tạo test.md cho một integration bằng cách mechanical derive Test Scenarios + Test Cases từ Flows/US/AC/VR/FAC trong frd.md. Auto-cascade lên feature/{F-XXX}/test-design.md. Role QC, song song với /spec-tech (DEV) — cả hai chỉ phụ thuộc spec.md approved.
 ---
 
 # spec-test
@@ -9,15 +9,15 @@ description: Tạo test.md cho một integration bằng cách mechanical derive
 
 Tạo `test.md` cho một integration trong `.specs/integrations/{slug}/`.
 
-`test.md` là verification design ở integration level — định nghĩa **how to verify** rằng integration đáp ứng `spec.md`. Nội dung gồm Test Strategy (per integration) + Changes blocks cascade lên feature `tsd.md` (Test Spec Document).
+`test.md` là verification design ở integration level — định nghĩa **how to verify** rằng integration đáp ứng `spec.md`. Nội dung gồm Test Strategy (per integration) + Changes blocks cascade lên feature `test-design.md` (Test Design Document).
 
 **Hai artifact tách bạch:**
 - `.specs/integrations/{slug}/test.md` — integration-level, ephemeral, PR record bất biến sau approve (single-word naming như `spec.md` / `tech.md` / `plan.md`).
-- `.specs/main/feature/{F-XXX}-{slug}/tsd.md` — feature-level, persistent canonical artifact (3-letter naming như `frd.md` / `fdd.md`). TC content cuối cùng nằm ở đây.
+- `.specs/main/feature/{F-XXX}-{slug}/test-design.md` — feature-level, persistent canonical artifact (cùng nhóm main feature như `frd.md` / `fdd.md`). TC content cuối cùng nằm ở đây.
 
 **Role:** QC. Song song với `/spec-tech` (DEV role). Cả hai chỉ phụ thuộc `spec.md` approved — không có thứ tự bắt buộc giữa chúng.
 
-**Cốt lõi:** agent **mechanical derive** TC từ frd.md (mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → Validation TC positive+negative, mỗi FAC → Feature AC TC). Agent KHÔNG sáng tạo TC ngoài frd — phần đó là QC thêm tay khi review.
+**Cốt lõi:** agent **mechanical derive** TC từ frd.md (mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → Validation TC positive+negative, mỗi FAC → E2E TC, mỗi NFR → Non-functional TC, mỗi DM → Data & Migration TC). Agent KHÔNG sáng tạo TC ngoài frd — phần đó là QC thêm tay khi review.
 
 ## When to Use
 
@@ -27,7 +27,7 @@ Tạo `test.md` cho một integration trong `.specs/integrations/{slug}/`.
 ## When NOT to Use
 
 - `spec.md` chưa có hoặc chưa approve → chạy `/spec-new` trước
-- Integration có `features: []` (không touch feature nào) → `test.md` không áp dụng vì component-level `tsd.md` không tồn tại trong kit này (xem `templates/main/feature/tsd-template.md` — component contract verify gián tiếp qua feature TC + unit test trong code). Verification cho integration thuần component → đặt trong tech.md hoặc phase Verification của plan.md.
+- Integration có `features: []` (không touch feature nào) → `test.md` không áp dụng vì component-level `test-design.md` không tồn tại trong kit này (xem `templates/main/feature/test-design-template.md` — component contract verify gián tiếp qua feature TC + unit test trong code). Verification cho integration thuần component → đặt trong tech.md hoặc phase Verification của plan.md.
 - Chỉ muốn cập nhật `test.md` đã có → edit file trực tiếp
 
 ---
@@ -90,8 +90,8 @@ Nếu `status` **không phải** `approved`:
 
 > ⛔ Integration **{slug}** không touch feature nào (`features: []`).
 >
-> `/spec-test` cascade lên `feature/{F-XXX}/tsd.md` — không áp dụng cho integration thuần component.
-> Component contract được verify gián tiếp qua feature TC + unit test trong code (xem `templates/main/feature/tsd-template.md`).
+> `/spec-test` cascade lên `feature/{F-XXX}/test-design.md` — không áp dụng cho integration thuần component.
+> Component contract được verify gián tiếp qua feature TC + unit test trong code (xem `templates/main/feature/test-design-template.md`).
 >
 > Đặt verification cho integration này trong:
 > - `tech.md > Implementation Notes` — verification approach
@@ -109,7 +109,7 @@ Load các file sau:
 
 - `.specs/integrations/{slug}/spec.md` — đọc toàn bộ + frontmatter (`features`)
 - `.specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature trong frontmatter `features` (source của TC — bắt buộc tồn tại vì cascade từ spec.md đã apply)
-- `.specs/main/feature/{F-XXX}-{slug}/tsd.md` — cho mỗi feature trong frontmatter `features` (nếu tồn tại — cần để diff và assign next ID)
+- `.specs/main/feature/{F-XXX}-{slug}/test-design.md` — cho mỗi feature trong frontmatter `features` (nếu tồn tại — cần để diff và assign next ID)
 - `.specs/integrations/{slug}/tech.md` — đọc nếu tồn tại (optional, dùng để hint environment / data set / NFR perf threshold)
 
 Tóm tắt context:
@@ -119,8 +119,8 @@ TÔI HIỂU:
 - Integration: {title}
 - Features touched: {từ frontmatter — F-XXX, ...}
 - Mỗi feature có trong frd.md:
-  - F-XXX: {N} Flows, {M} US ({K} AC), {P} VR, {Q} FAC
-- tsd.md hiện tại:
+  - F-XXX: {N} Flows, {M} US ({K} AC), {P} VR, {Q} FAC, {R} NFR, {S} DM
+- test-design.md hiện tại:
   - F-XXX: tồn tại — max(TS)=NNN, max(TC)=MMM   (cho operation=update)
   - F-YYY: chưa tồn tại                          (cho operation=create)
 - tech.md: {tồn tại / chưa — nếu có thì có hint gì cho env/data/perf}
@@ -139,11 +139,11 @@ Nếu frd.md của feature nào không tồn tại → báo lỗi và dừng (l
 
 Với mỗi feature trong `features:`:
 
-- Đọc `feature/{F-XXX}/tsd.md` hiện tại (nếu có) để lấy `max(TS-F{NNN}-seq)` và `max(TC-F{NNN}-seq)`
+- Đọc `feature/{F-XXX}/test-design.md` hiện tại (nếu có) để lấy `max(TS-F{NNN}-seq)` và `max(TC-F{NNN}-seq)`
 - ID mới = `max(seq) + 1`, format 3 chữ số
-- TC dùng **chung sequence** cho Functional / Validation / Feature AC — không reset theo loại
+- TC dùng **chung sequence** cho Functional / Validation / E2E / Non-functional / Data & Migration — không reset theo loại, không đẻ prefix riêng
 - ID **stable** — không tái sử dụng khi [REMOVE], không renumber khi [MODIFY]
-- Operation=create (tsd.md chưa tồn tại) → bắt đầu từ `001`
+- Operation=create (test-design.md chưa tồn tại) → bắt đầu từ `001`
 
 #### 3.2 Derivation rules
 
@@ -176,14 +176,13 @@ Với mỗi feature trong `features:`:
 - Covers: `VR-{F_ID}-{seq}`
 - Priority: P1 mặc định (xem 3.3)
 
-**D. Feature AC Test Cases** — mỗi FAC → 1 Feature AC TC.
+**D. E2E Test Cases** — mỗi `FAC-*` (end-to-end) → 1 TC. Type: `E2E — journey` (tuần tự liên story) / `E2E — consistency` (đa màn) / `E2E — integrity` (bất biến liên story, không tuần tự) — đọc FAC để phân loại. Covers `FAC-{F_ID}-{seq}`. Spans: list US IDs (nếu journey/integrity). Preconditions/Steps/Expected dịch 1:1 từ G/W/T.
 
-- TC ID mới = `TC-F{NNN}-{next_seq}`
-- Type: derive từ nhóm FAC (`e2e` / `consistency` / `NFR` / `data & migration`) — đọc context FAC để phân loại
-- Priority: theo bảng ở 3.3
-- Covers: `FAC-{F_ID}-{seq}`
-- Spans: list US IDs mà FAC liên quan (nếu FAC e2e)
-- Preconditions/Steps/Expected: dịch 1:1 từ Given/When/Then của FAC
+**D2. Non-Functional Test Cases** — mỗi `NFR-*` → 1 TC. Type: `performance` / `a11y` / `security` / ... (theo NFR). Covers `NFR-{F_ID}-{seq}`. Dịch 1:1 từ G/W/T.
+
+**D3. Data & Migration Test Cases** (required-emptyable) — mỗi `DM-*` → 1 TC. Type: `data migration`. Covers `DM-{F_ID}-{seq}`. Dịch 1:1 từ G/W/T. Frd không có DM entry → giữ heading, để section trống.
+
+> Mọi TC ở D / D2 / D3 dùng **chung sequence `TC-F{NNN}-{next_seq}`** — KHÔNG đẻ prefix riêng. Priority theo bảng ở 3.3.
 
 **E. Traceability Matrix** — row per frd item:
 
@@ -191,7 +190,9 @@ Với mỗi feature trong `features:`:
 - 1 row per US → cover by TC (Functional)
 - 1 row per Story AC → cover by TC (Functional)
 - 1 row per VR → cover by TC (Validation, list tất cả positive + negative)
-- 1 row per FAC → cover by TC (Feature AC)
+- 1 row per FAC → cover by TC (E2E)
+- 1 row per NFR → cover by TC (Non-functional)
+- 1 row per DM → cover by TC (Data & Migration)
 - Mọi item phải có cover ✅ (vì derive 1:1). Nếu agent không thể derive một item nào → đánh dấu ❌ + ghi lý do ở Gaps section, KHÔNG silent skip.
 
 #### 3.3 Priority defaults
@@ -208,19 +209,20 @@ Mọi TC đều có priority deterministic. QC override khi review (Bước 4).
 
 **TC cover VR** — inherit max priority của các US trong `Refs` column của VR. Nếu Refs trống → P1 default.
 
-**TC cover FAC** — theo nhóm FAC:
+**TC cover FAC / NFR / DM** — theo loại + section nguồn:
 
-| FAC group | TC Priority |
+| Loại | TC Priority |
 | --- | --- |
-| End-to-end liên story | P0 |
-| Cross-story consistency | P1 |
-| NFR — security / data integrity | P0 |
+| FAC — end-to-end (journey) | P0 |
+| FAC — integrity | P0 |
+| FAC — consistency | P1 |
+| NFR — security | P0 |
 | NFR — performance / a11y / i18n / browser | P1 |
 | Data & migration | P0 |
 
-#### 3.4 Diff vs current tsd.md
+#### 3.4 Diff vs current test-design.md
 
-Với feature có tsd.md hiện tại (operation=update):
+Với feature có test-design.md hiện tại (operation=update):
 
 - Item đã có TC cover → KHÔNG sinh TC mới, giữ nguyên TC cũ
 - Item trong frd nhưng chưa có TC cover → sinh TC mới với marker `[NEW]`
@@ -229,7 +231,7 @@ Với feature có tsd.md hiện tại (operation=update):
 
 Agent compute diff tự động — KHÔNG hỏi user "field nào đã đổi"; đọc 2 file rồi đối chiếu.
 
-**No-delta case:** nếu diff giữa frd hiện tại và tsd.md hiện tại = empty cho 1 feature (frd không thêm/đổi item nào mà tsd chưa cover) → **bỏ Changes block của feature đó hoàn toàn**, ghi `no-op` trong Cascade Summary để minh bạch.
+**No-delta case:** nếu diff giữa frd hiện tại và test-design.md hiện tại = empty cho 1 feature (frd không thêm/đổi item nào mà test-design chưa cover) → **bỏ Changes block của feature đó hoàn toàn**, ghi `no-op` trong Cascade Summary để minh bạch.
 
 #### 3.5 Placeholders cần QC fill
 
@@ -237,8 +239,7 @@ Agent **không suy đoán** các field sau, dùng placeholder rõ ràng để QC
 
 | Field | Placeholder | Vì sao agent không tự fill |
 | --- | --- | --- |
-| Environments table | Row mặc định: `dev / staging / prod-like` với `data set: TBD`, `mục đích: TBD` | Phụ thuộc setup CI/CD và availability — QC owns |
-| Test Data table | Row `{TBD — fixture}` cho mỗi seed/boundary dataset agent thấy cần | QC chọn fixture source thực tế |
+| Test Data Requirements | Row `{TBD — shape}` cho mỗi seed/boundary dataset agent thấy cần | QC xác định yêu cầu data (shape); nguồn/refresh thuộc execution |
 | Out of Scope | Để trống với note `<!-- QC fill -->` | Quyết định business của QC |
 | Test Strategy > Approach | Bullet generic theo template gốc | Strategy đặc thù integration QC fill |
 
@@ -249,8 +250,8 @@ Agent **không suy đoán** các field sau, dùng placeholder rõ ràng để QC
 Tổng hợp và viết draft `test.md` theo `templates/integrations/test-template.md`:
 
 - **Context** — tóm tắt từ Bước 2
-- **Test Strategy** — placeholder + Environments table với placeholder rows
-- **Changes** — 1 block per feature *có delta*, mỗi block có operation + content theo template gốc `templates/main/feature/tsd-template.md`. Feature no-delta → bỏ block.
+- **Test Strategy** — Approach delta đặc thù integration (KHÔNG có Environments table — env assignment thuộc execution)
+- **Changes** — 1 block per feature *có delta*, mỗi block có operation + content theo template gốc `templates/main/feature/test-design-template.md`. Feature no-delta → bỏ block.
 - **Out of Scope** — empty với note QC fill
 - **Open Questions** — list các item mà agent không thể derive deterministic (vd: FAC có wording vague, VR không rõ nhánh fail nào)
 - **Cascade Summary** — table liệt kê **tất cả** feature trong `features:` (kể cả no-delta — ghi `no-op`)
@@ -263,14 +264,14 @@ Hiển thị **toàn bộ draft** cho QC xem — **chưa ghi file, chưa cascade
 
 > Draft trên đã đúng chưa? QC điểm cần check:
 >
-> 1. **Mechanical derivation** — mỗi Flow / US / AC / VR / FAC trong frd đã có TC cover chưa? (xem Traceability Matrix)
+> 1. **Mechanical derivation** — mỗi Flow / US / AC / VR / FAC / NFR / DM trong frd đã có TC cover chưa? (xem Traceability Matrix)
 > 2. **Priority defaults** — có TC nào cần override khỏi default không?
-> 3. **Placeholders** — fill Environments / Test Data / Out of Scope / Strategy Approach.
+> 3. **Placeholders** — fill Test Data Requirements / Out of Scope / Strategy Approach.
 > 4. **Extra edge cases** — ngoài AC/VR có scenario nào QC muốn thêm? (vd: exploratory, security boundary, race condition không có trong AC)
 > 5. **Changes markers** — `[NEW]/[MODIFY]/[REMOVE]` có đúng không?
 > 6. **No-delta features** — Cascade Summary có ghi `no-op` đúng cho feature không có delta không?
 >
-> **Sau khi confirm, agent sẽ auto-apply tất cả Changes blocks lên feature tsd.md(s).**
+> **Sau khi confirm, agent sẽ auto-apply tất cả Changes blocks lên feature test-design.md(s).**
 
 Nếu QC yêu cầu chỉnh sửa:
 - Override priority → update draft
@@ -286,25 +287,25 @@ Chỉ tiến hành Bước 6 sau khi QC confirm.
 
 **[6.1] Ghi `.specs/integrations/{slug}/test.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` mirror từ `spec.md`. (test.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, xem `conventions.md` §7.)
 
-**[6.2] Auto-apply mỗi Changes block** vào `feature/{F-XXX}/tsd.md` tương ứng. Thứ tự apply: theo thứ tự xuất hiện trong frontmatter `features` (deterministic, không có forward reference giữa các feature tsd.md). Bỏ qua feature có operation `no-op` trong Cascade Summary.
+**[6.2] Auto-apply mỗi Changes block** vào `feature/{F-XXX}/test-design.md` tương ứng. Thứ tự apply: theo thứ tự xuất hiện trong frontmatter `features` (deterministic, không có forward reference giữa các feature test-design.md). Bỏ qua feature có operation `no-op` trong Cascade Summary.
 
 Cho từng block:
 
 - **Operation=create:**
-  - Tạo file `.specs/main/feature/{F-XXX}-{slug}/tsd.md`
-  - Nội dung = nội dung của Changes block (theo format `templates/main/feature/tsd-template.md`)
-  - Frontmatter của tsd.md mới: status `draft` + `template_version` copy từ `tsd-template.md` (separate lifecycle với integration test.md). Chỉ stamp ở operation=create; **operation=update KHÔNG đụng** version của tsd.md hiện có.
+  - Tạo file `.specs/main/feature/{F-XXX}-{slug}/test-design.md`
+  - Nội dung = nội dung của Changes block (theo format `templates/main/feature/test-design-template.md`)
+  - Frontmatter của test-design.md mới: status `draft` + `template_version` copy từ `test-design-template.md` (separate lifecycle với integration test.md). Chỉ stamp ở operation=create; **operation=update KHÔNG đụng** version của test-design.md hiện có.
 
 - **Operation=update:**
-  - Đọc tsd.md hiện tại
+  - Đọc test-design.md hiện tại
   - Với mỗi TS/TC trong Changes block:
     - `[NEW]` → append/insert vào section tương ứng (giữ thứ tự numeric của ID)
     - `[MODIFY {field}]` → tìm TS/TC bằng ID, update field đã chỉ định, giữ nguyên field khác
-    - `[REMOVE]` → xóa TS/TC khỏi tsd.md (ID retire, không tái sử dụng)
+    - `[REMOVE]` → xóa TS/TC khỏi test-design.md (ID retire, không tái sử dụng)
   - Cập nhật Traceability Matrix: thêm row cho item mới, update row của item bị MODIFY, KHÔNG xóa row của REMOVE (đánh dấu retire)
-  - Ghi lại tsd.md
+  - Ghi lại test-design.md
 
-**[6.2.5] Append Change History entry** vào mỗi tsd.md bị touched (theo `conventions.md` §5.5). Đây là phần atomic của auto-apply — nếu fail thì rollback luôn.
+**[6.2.5] Append Change History entry** vào mỗi test-design.md bị touched (theo `conventions.md` §5.5). Đây là phần atomic của auto-apply — nếu fail thì rollback luôn.
 
 Format entry:
 
@@ -315,16 +316,16 @@ Format entry:
   - [marker] {TS/TC ID} — {mô tả ngắn 1 dòng}
 ```
 
-- Operation = `create` (tsd.md mới) | `update` (tsd.md đã tồn tại).
+- Operation = `create` (test-design.md mới) | `update` (test-design.md đã tồn tại).
 - Integration link trỏ tới `test.md` (không phải `spec.md`) — đây là cascade từ test.
-- Section name = tên section trong template tsd (`Test Scenarios`, `Functional Test Cases`, `Validation Test Cases`, `Feature AC Test Cases`, `Traceability Matrix`...).
+- Section name = tên section trong template test-design (`Test Scenarios`, `Functional Test Cases`, `Validation Test Cases`, `E2E Test Cases`, `Non-Functional Test Cases`, `Data & Migration Test Cases`, `Traceability Matrix`...).
 - Mọi TS/TC có marker trong Changes block phải xuất hiện ở entry, group theo section.
 - Với operation=create từ template trống (no Changes block content) → entry body có thể là `- **All sections**: initial scaffold`.
 
 **[6.3] Atomic rollback:** Nếu apply block nào fail (vd `[MODIFY TC-F001-005]` nhưng ID không tồn tại):
 1. Rollback các block đã apply trước đó về state ban đầu
 2. **Không** ghi integration test.md
-3. Báo lỗi cụ thể cho QC fix draft hoặc feature tsd.md hiện tại
+3. Báo lỗi cụ thể cho QC fix draft hoặc feature test-design.md hiện tại
 
 **[6.4] Thông báo kết quả:**
 
@@ -332,12 +333,12 @@ Format entry:
 ✓ .specs/integrations/{slug}/test.md đã được tạo (status: approved)
 
 Auto-cascade applied:
-  ✓ feature/F-XXX-{slug}/tsd.md — {created | updated: +N TS, +M TC, modify K TC, remove L TC}
-  ✓ feature/F-YYY-{slug}/tsd.md — no-op (frd không đổi)
+  ✓ feature/F-XXX-{slug}/test-design.md — {created | updated: +N TS, +M TC, modify K TC, remove L TC}
+  ✓ feature/F-YYY-{slug}/test-design.md — no-op (frd không đổi)
 
 Bước tiếp theo:
-  - QC: review feature tsd.md đã cascade, fill remaining TBD nếu có
-  - DEV: có thể run /plan nếu chưa có plan.md (plan.md hiện chưa consume tsd.md — test tasks tự QC manage trong test framework)
+  - QC: review feature test-design.md đã cascade, fill remaining TBD nếu có
+  - DEV: có thể run /plan nếu chưa có plan.md (plan.md hiện chưa consume test-design.md — test tasks tự QC manage trong test framework)
 ```
 
 ---
@@ -348,7 +349,7 @@ Bước tiếp theo:
 | --- | --- |
 | "TC có thể nghĩ ra khi chạy test" | Không document = không có traceability. AC pass/fail không kiểm tra được nếu không có TC mapping. |
 | "VR positive đủ rồi, negative skip" | Negative case là nơi bug ẩn. Mỗi nhánh fail của VR phải có TC riêng. |
-| "Priority để default hết P1 cho nhanh" | Priority decorative thì cũng phải đúng — derive deterministic từ US Priority/FAC group. P1 hàng loạt = QC chưa nhìn frd. |
+| "Priority để default hết P1 cho nhanh" | Priority decorative thì cũng phải đúng — derive deterministic từ US Priority/loại requirement (FAC/NFR/DM). P1 hàng loạt = QC chưa nhìn frd. |
 | "Out of Scope để trống cũng được" | Mọi integration đều có thứ không test. Trống = scope creep hoặc gap không kiểm soát. |
 
 ## Red Flags
@@ -357,8 +358,8 @@ Bước tiếp theo:
 - TC có Covers trống → không trace được lên frd
 - VR có ít hơn 2 TC (1 positive + 1+ negative) → coverage thiếu
 - Priority hàng loạt giống nhau cho mọi TC → QC chưa override default
-- Test Data toàn `TBD` sau khi QC review → chưa thật sự confirm
-- Changes block có marker `[NEW]` cho TC trùng ID với TC đã có trong tsd.md hiện tại → diff bug
+- Test Data Requirements toàn `TBD` sau khi QC review → chưa thật sự confirm
+- Changes block có marker `[NEW]` cho TC trùng ID với TC đã có trong test-design.md hiện tại → diff bug
 - Cascade Summary thiếu row cho feature trong `features:` (kể cả no-op) → không minh bạch
 
 ## Verification
@@ -368,17 +369,17 @@ Trước khi QC confirm (Bước 5), kiểm tra:
 - [ ] Mỗi Flow trong frd có 1 TS tương ứng
 - [ ] Mỗi US AC có TC Functional cover
 - [ ] Mỗi VR có ≥1 positive + ≥1 negative TC
-- [ ] Mỗi FAC có TC Feature AC cover
+- [ ] Mỗi FAC có TC E2E cover; mỗi NFR có TC Non-functional; mỗi DM có TC Data & Migration
 - [ ] Traceability Matrix đầy đủ (không ❌ mà không giải thích)
 - [ ] Priority deterministic theo bảng 3.3 (default), QC override visible
 - [ ] ID assignment từ max(seq)+1, không tái sử dụng, không renumber
-- [ ] Markers `[NEW]/[MODIFY {field}]/[REMOVE]` khớp diff vs current tsd.md
+- [ ] Markers `[NEW]/[MODIFY {field}]/[REMOVE]` khớp diff vs current test-design.md
 - [ ] Feature no-delta được ghi `no-op` trong Cascade Summary, KHÔNG có Changes block
 
 Sau khi QC confirm (Bước 6):
 
 - [ ] Auto-apply theo thứ tự features trong frontmatter
-- [ ] Mỗi tsd.md bị touched có entry mới trong `## Change History` (conventions §5.5)
+- [ ] Mỗi test-design.md bị touched có entry mới trong `## Change History` (conventions §5.5)
 - [ ] Fail-safe: nếu apply fail thì không ghi integration test.md (rollback luôn Change History entries)
-- [ ] Mỗi feature tsd.md mới có status `draft` (separate lifecycle)
-- [ ] Main artifact tsd.md create có `template_version` copy từ template; tsd.md update giữ nguyên version cũ. test.md (integration) KHÔNG mang `template_version`
+- [ ] Mỗi feature test-design.md mới có status `draft` (separate lifecycle)
+- [ ] Main artifact test-design.md create có `template_version` copy từ template; test-design.md update giữ nguyên version cũ. test.md (integration) KHÔNG mang `template_version`

package/skills/spec-test-design/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: spec-test-design
+description: Tạo test-design.md (Test Design Document) trực tiếp tại feature level từ frd.md — mechanical derive Test Scenarios + Test Cases. KHÔNG cần integration, không cascade. Dùng cho brownfield onboarding (sau /spec-brownfield-feature) hoặc greenfield bootstrap khi feature đã có frd.md nhưng chưa có test-design.md.
+---
+
+# spec-test-design
+
+## Overview
+
+Tạo `.specs/main/feature/{F-XXX}-{slug}/test-design.md` trực tiếp từ frd.md của feature đó — **không qua integration**, không cascade.
+
+Skill này song hành với `/spec-prd` và `/spec-sad`: skill có acronym suffix (`prd`/`sad`/`test-design`) → tạo main artifact trực tiếp. Phân biệt với `/spec-test` — skill đó tạo `test.md` integration-level và cascade qua Changes blocks.
+
+## When to Use
+
+- **Brownfield onboarding** — sau `/spec-brownfield-feature` đã sinh frd.md, cần bootstrap test-design.md để có test coverage tracking ngay từ đầu.
+- **Greenfield deferred** — feature có frd.md từ lâu nhưng test-design.md chưa được tạo (vd: test design bị defer).
+- **Ad-hoc rebuild** — test-design.md drift quá xa khỏi frd.md, muốn regenerate fresh.
+
+## When NOT to Use
+
+- Có integration mới và muốn cascade thay đổi frd lên test-design hiện tại → dùng `/spec-test` (changeset patch giữ ID stable)
+- Chỉ muốn sửa vài TC → edit `test-design.md` trực tiếp
+- Feature chưa có frd.md → chạy `/spec-brownfield-feature` (brownfield) hoặc `/spec-new` (greenfield) trước
+
+## Cảnh báo về ID stability
+
+`/spec-test-design` **regenerate IDs từ 001** mỗi lần chạy. Nếu test-design.md đã tồn tại và đang được reference (vd: test code có `// covers TC-F001-005`), rebuild sẽ làm vỡ những reference đó.
+
+Quy tắc:
+- **test-design.md chưa tồn tại** → an toàn, không có reference, regenerate fresh.
+- **test-design.md tồn tại** → skill hỏi confirm rõ ràng trước khi overwrite. Khuyến nghị: dùng `/spec-test` qua integration changeset để preserve ID stable.
+
+---
+
+## Process
+
+### Bước 1: Xác định feature
+
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là feature ID (`F-001`, `001`) hoặc slug (`F-001-auth`, `auth`)
+- Quét `.specs/main/feature/*/frd.md`, tìm feature khớp
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy feature khớp với "{argument}". Kiểm tra `.specs/main/feature/`.
+
+**Nếu không có ARGUMENT:**
+
+Quét `.specs/main/feature/`. Liệt kê **tất cả** features có `frd.md`, đánh dấu trạng thái test-design:
+
+```
+Features có frd.md:
+
+  [1] F-001 — auth                spec✓ test-design✓
+  [2] F-002 — checkout             spec✓ test-design—
+  [3] F-003 — refund               spec✓ test-design— (frd có 5 Flow, 12 US, 8 VR, 3 FAC)
+
+Chọn số feature:
+```
+
+Nếu không có feature nào có frd → thông báo:
+> Chưa có feature nào có frd.md. Hãy chạy `/spec-brownfield-feature` hoặc `/spec-new` trước.
+
+---
+
+### Bước 2: Gate check — frd.md tồn tại + warn nếu test-design.md đã có
+
+**Check 1 — frd.md tồn tại:**
+
+Nếu `.specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại → dừng:
+> ⛔ `feature/{F-XXX}-{slug}/frd.md` không tồn tại. `/spec-test-design` cần frd làm input.
+
+**Check 2 — test-design.md đã tồn tại:**
+
+Nếu `.specs/main/feature/{F-XXX}-{slug}/test-design.md` đã tồn tại:
+
+> ⚠ `test-design.md` đã tồn tại cho feature **{F-XXX} — {slug}**.
+>
+> `/spec-test-design` regenerate IDs từ 001 — nếu có test code đang reference TC-{F_ID}-NNN hoặc TS-{F_ID}-NNN, references sẽ bị vỡ.
+>
+> Khuyến nghị: dùng `/spec-test` qua integration changeset để giữ ID stable.
+>
+> Tiếp tục overwrite? (yes / no — default no)
+
+Nếu user chọn no → dừng, suggest `/spec-test`.
+Nếu user chọn yes → backup test-design.md cũ thành `test-design.md.bak.{timestamp}` rồi proceed.
+
+---
+
+### Bước 3: Load context
+
+Load các file sau:
+
+- `.specs/main/feature/{F-XXX}-{slug}/frd.md` — **bắt buộc**, source của TC
+- `.specs/main/feature/{F-XXX}-{slug}/fdd.md` — optional, đọc nếu tồn tại để hint Components Used (cho Dependencies section của test-design)
+
+Tóm tắt context:
+
+```
+TÔI HIỂU:
+- Feature: {F-XXX} — {slug}
+- Trong frd.md:
+  - {N} Flows
+  - {M} User Stories ({K} Acceptance Criteria)
+  - {P} Verification Rules
+  - {Q} Feature Acceptance Criteria
+- test-design.md hiện tại: {chưa có / sẽ overwrite — backup tại test-design.md.bak.{timestamp}}
+- fdd.md: {tồn tại — Components Used: C-XXX, C-YYY / chưa có}
+```
+
+---
+
+### Bước 4: Auto-derive draft
+
+**Nguyên tắc:** mechanical derive 1:1 từ frd.md — same algorithm như `/spec-test` (xem [skills/spec-test/SKILL.md](../spec-test/SKILL.md) Bước 3.1-3.3). Tóm lại:
+
+#### 4.1 ID assignment
+
+- IDs bắt đầu từ `001` (vì tạo mới hoặc regenerate). TS và TC cùng feature ID `F{NNN}`, TC dùng chung sequence cho Functional / Validation / E2E / Non-functional / Data & Migration — không đẻ prefix riêng.
+- ID sẽ stable kể từ thời điểm này — lần edit tiếp theo qua `/spec-test` integration phải preserve.
+
+#### 4.2 Derivation rules
+
+| frd item | test-design output |
+| --- | --- |
+| Mỗi `Flow {N}` trong User Flows | 1 Test Scenario `TS-F{NNN}-{seq}` |
+| Mỗi `AC-F{NNN}-{seq}` trong US | 1 Functional TC `TC-F{NNN}-{seq}` |
+| Mỗi `VR-F{NNN}-{seq}` | 1 positive + 1+ negative Validation TC |
+| Mỗi `FAC-F{NNN}-{seq}` (end-to-end) | 1 E2E TC (Type `E2E — journey`/`consistency`/`integrity`) |
+| Mỗi `NFR-F{NNN}-{seq}` | 1 Non-functional TC (Type `performance`/`a11y`/`security`...) |
+| Mỗi `DM-F{NNN}-{seq}` (section required-emptyable) | 1 Data & Migration TC (Type `data migration`) |
+
+Detail dịch G/W/T → Preconditions/Steps/Expected, infer negative VR branches từ rule text — xem `/spec-test` Bước 3.2.
+
+#### 4.3 Priority defaults
+
+| Source | Priority |
+| --- | --- |
+| TC cover US Must | P0 |
+| TC cover US Should | P1 |
+| TC cover US Could | P2 |
+| TC cover VR | inherit max priority của Refs (P1 default nếu Refs trống) |
+| TC cover FAC e2e (journey) | P0 |
+| TC cover FAC integrity | P0 |
+| TC cover FAC consistency | P1 |
+| TC cover NFR security | P0 |
+| TC cover NFR perf/a11y/i18n/browser | P1 |
+| TC cover DM (data & migration) | P0 |
+
+#### 4.4 Traceability Matrix
+
+Row per frd item — Flow / US / Story AC / VR / FAC / NFR / DM. Mọi item phải có cover ✅. Item không thể derive → ❌ + ghi lý do ở Gaps section.
+
+#### 4.5 Placeholders cần QC fill
+
+Agent **không suy đoán**:
+
+| Field | Placeholder |
+| --- | --- |
+| Test Data Requirements | Row `{TBD — shape}` cho mỗi dataset test cần (yêu cầu data, không phải nguồn/refresh) |
+| Out of Scope | Để trống với note `<!-- QC fill -->` |
+| Test Strategy > Approach | Bullet generic theo template gốc |
+| Overview | 2-3 câu mô tả feature scope từ frd Overview |
+
+#### 4.6 Dependencies section
+
+- **FRD reference**: path tới `frd.md` của feature này
+- **Components Used**: copy từ `frd.md > Components Used`. Nếu fdd.md tồn tại → cross-reference C-XXX để đảm bảo đúng.
+
+---
+
+### Bước 5: Review — xác nhận với QC
+
+Hiển thị draft đầy đủ — chưa ghi file.
+
+> Draft test-design.md trên đã đúng chưa? Check:
+>
+> 1. **Coverage** — Traceability Matrix có đủ row cho mỗi Flow / US / AC / VR / FAC / NFR / DM trong frd?
+> 2. **Priority** — defaults theo bảng 4.3, có TC nào cần override?
+> 3. **Placeholders** — fill Test Data Requirements / Out of Scope / Strategy Approach.
+> 4. **Extra edge cases** — ngoài AC/VR có scenario QC muốn thêm?
+>
+> Confirm để ghi file. Reject để revise.
+
+---
+
+### Bước 6: Save
+
+Ghi `.specs/main/feature/{F-XXX}-{slug}/test-design.md` với status `draft` (feature-level artifact có lifecycle riêng, không phải `approved` — QC còn fill placeholders nên status `draft` cho đến khi đầy đủ). Frontmatter lấy `template_version` từ `test-design-template.md` (xem `conventions.md` §7).
+
+Nếu overwrite — file backup `test-design.md.bak.{timestamp}` đã tạo ở Bước 2.
+
+**Change History:** Append entry vào section `## Change History` cuối test-design.md (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial scaffold qua /spec-test-design (mechanical derive từ frd.md — N TS, M Functional TC, P Validation TC, Q E2E TC, R Non-functional TC, S Data & Migration TC)
+```
+
+Nếu overwrite test-design.md cũ → entry vẫn dùng operation `create` (vì IDs regenerate fresh, không phải update), thêm note trong body: `- **Note**: overwrote previous test-design.md (backup tại test-design.md.bak.{timestamp}) — IDs regenerated từ 001`.
+
+Thông báo kết quả:
+
+```
+✓ .specs/main/feature/{F-XXX}-{slug}/test-design.md đã được tạo (status: draft)
+  Coverage: N Flows → N TS, M US/AC → M Functional TC, P VR → ~2P Validation TC, Q FAC → Q E2E TC, R NFR → R Non-functional TC, S DM → S Data & Migration TC
+  {nếu overwrite: backup tại test-design.md.bak.{timestamp}}
+
+Bước tiếp theo:
+  - QC: fill remaining placeholders (Test Data Requirements, Out of Scope, Strategy)
+  - Đổi status: draft → approved khi sẵn sàng
+  - Sau này: nếu frd thay đổi → dùng /spec-test qua integration changeset để giữ ID stable
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Có frd rồi, viết test-design sau cũng được" | Test coverage không tracked = không biết feature đóng được chưa. test-design làm song song với frd, không sau. |
+| "Rebuild test-design nhanh hơn cập nhật manual" | Đúng cho lần đầu. Lần sau khi đã có test code reference → rebuild sẽ break references. Lúc đó dùng `/spec-test`. |
+| "Brownfield không cần test-design, đã có test code" | Test code là HOW. test-design là WHAT — declarative TC list để track coverage vs frd. Hai layer khác nhau. |
+
+## Red Flags
+
+- Traceability Matrix có ❌ mà không có Gaps section giải thích
+- Priority hàng loạt P1 — chưa override theo defaults
+- Test Strategy / Test Data Requirements toàn `TBD` sau khi QC review xong
+- Overwrite test-design.md hiện có mà không cảnh báo về ID break
+
+## Verification
+
+Trước khi ghi file:
+
+- [ ] Mỗi Flow trong frd có 1 TS
+- [ ] Mỗi US AC có TC Functional cover
+- [ ] Mỗi VR có ≥1 positive + ≥1 negative TC
+- [ ] Mỗi FAC có TC E2E cover; mỗi NFR có TC Non-functional; mỗi DM có TC Data & Migration
+- [ ] Priority deterministic theo bảng 4.3
+- [ ] Nếu overwrite: test-design.md.bak.{timestamp} đã được tạo
+- [ ] QC đã confirm draft
+- [ ] Frontmatter có `template_version` copy từ `test-design-template.md`