spec-lite 1.5.2 → 1.6.0

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`

package/skills-overview.md

@@ -62,14 +62,14 @@ Nhận F-XXX từ argument (hoặc chọn từ prd Feature Index) + tùy chọn
 - **Create-only**: frd.md của feature mục tiêu **chưa tồn tại**. Đã tồn tại → **dừng, redirect `/spec-new`** (thay đổi feature đã spec phải đi qua integration để delta cascade + kéo theo `/spec-tech`/`/spec-test`).
 - Feature mới **đơn lẻ** chưa có trong Index → offer **register một row vào `prd.md > Features`** rồi author.
 
-**Sections template** (7): Overview · User Flows · Feature Acceptance Criteria · User Stories · Verification Rules · Scope · Dependencies
+**Sections template**: Overview · User Flows · Feature Acceptance Criteria (end-to-end) · Non-Functional Requirements · Data & Migration *(nếu có)* · User Stories · Verification Rules · Scope · Dependencies
 
 **Phạm vi hẹp — chủ yếu `frd.md`:**
 - Reference component frd phụ thuộc (Components Used → C-XXX có sẵn).
 - Component cần-nhưng-chưa-có → ghi *candidate* + Open Question cho `/spec-sad`/architect chốt boundary.
 - Có thể register **một** feature row vào prd (side-effect lên prd).
 - **Cascade vocabulary lên `domain.md`** (pha mô tả/WHAT): glossary term + **định nghĩa shared entity** (attributes), `Owner: TBD` để `/spec-sad` gán ở pha thiết kế (HOW). BA define entity, KHÔNG carve/gán Owner.
-- **KHÔNG** tạo `crd.md`/`cdd.md` (sinh ở integration time qua `/spec-new` cascade), không tạo `fdd.md`/`tsd.md`, không đổi status feature đã có, không đụng sad.
+- **KHÔNG** tạo `crd.md`/`cdd.md` (sinh ở integration time qua `/spec-new` cascade), không tạo `fdd.md`/`test-design.md`, không đổi status feature đã có, không đụng sad.
 - Change History operation = `manual` (cả frd lẫn domain). Verification Rules dùng quy ước option-suggester của `/spec-new` (BA owns).
 
 Bỏ qua bước này cũng được — `/spec-new` sẽ tự tạo frd làm fallback khi integration đầu tiên chạm tới feature.
@@ -94,14 +94,14 @@ Bỏ qua bước này cũng được — `/spec-new` sẽ tự tạo frd làm fa
 
 Dùng khi onboarding một project đã có code vào SDD. Mục tiêu: extract main artifacts từ codebase hiện có, sau đó chuyển vào **Integration Pipeline** để implement.
 
-**Thứ tự bắt buộc:** `init` → `component` → `feature` → `tsd` *(tùy chọn — bootstrap test coverage tracking)*
+**Thứ tự bắt buộc:** `init` → `component` → `feature` → `test-design` *(tùy chọn — bootstrap test coverage tracking)*
 
 | Command | Scan | Reads | Writes |
 | --- | --- | --- | --- |
 | `/spec-brownfield-init [path]` | tech stack, README, auth, infra | attachments | `prd.md` *(no indexes)*, `domain.md` *(glossary only)*, `sad.md` |
 | `/spec-brownfield-component [path]` | module dirs, service/controller/entity files | `prd.md`, `domain.md` | `component/{C-XXX}-*/crd.md + cdd.md`; update `prd.md` Component Index; cascade Shared Entities → `domain.md` |
 | `/spec-brownfield-feature [path]` | use cases, routes, test files | `prd.md`, `domain.md`, `component/*/crd.md` | `feature/{F-XXX}-*/frd.md + fdd.md`; update `prd.md` Feature Index |
-| `/spec-tsd [F-XXX]` | — *(không scan code, derive 100% từ frd)* | `feature/{F-XXX}-*/frd.md`, `fdd.md` *(optional)* | `feature/{F-XXX}-*/tsd.md` |
+| `/spec-test-design [F-XXX]` | — *(không scan code, derive 100% từ frd)* | `feature/{F-XXX}-*/frd.md`, `fdd.md` *(optional)* | `feature/{F-XXX}-*/test-design.md` |
 
 ### Phân chia trách nhiệm
 
@@ -173,21 +173,21 @@ Component Index và Feature Index **để placeholder** — sẽ được điề
 
 ---
 
-### `/spec-tsd [F-XXX]`
+### `/spec-test-design [F-XXX]`
 
-**Mục tiêu:** Bootstrap `tsd.md` (Test Spec Document) cho một feature trực tiếp từ frd.md — mechanical derive Test Scenarios + Test Cases. KHÔNG cần integration.
+**Mục tiêu:** Bootstrap `test-design.md` (Test Design Document) cho một feature trực tiếp từ frd.md — mechanical derive Test Scenarios + Test Cases. KHÔNG cần integration.
 
 **Khi nào dùng:**
-- **Brownfield onboarding** — sau `/spec-brownfield-feature` đã sinh frd.md, chạy `/spec-tsd` cho từng feature để có test coverage tracking từ ngày 1.
-- **Greenfield deferred** — feature đã có frd.md từ lâu nhưng tsd.md chưa được tạo.
-- **Ad-hoc rebuild** — tsd drift khỏi frd, regenerate fresh.
+- **Brownfield onboarding** — sau `/spec-brownfield-feature` đã sinh frd.md, chạy `/spec-test-design` cho từng feature để có test coverage tracking từ ngày 1.
+- **Greenfield deferred** — feature đã có frd.md từ lâu nhưng test-design.md chưa được tạo.
+- **Ad-hoc rebuild** — test-design drift khỏi frd, regenerate fresh.
 
 **Khi nào KHÔNG dùng:**
-- Có integration cascade từ spec.md → frd → muốn cập nhật tsd theo changeset → dùng `/spec-test` (preserve ID stable).
+- Có integration cascade từ spec.md → frd → muốn cập nhật test-design theo changeset → dùng `/spec-test` (preserve ID stable).
 
-**Derivation:** mechanical 1:1 từ frd — mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → ≥1 positive + 1+ negative Validation TC, mỗi FAC → Feature AC TC. Priority deterministic theo US Priority + FAC group. KHÔNG interview.
+**Derivation:** mechanical 1:1 từ frd — mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → ≥1 positive + 1+ negative Validation TC, mỗi FAC → E2E TC, mỗi NFR → Non-functional TC, mỗi DM → Data & Migration TC. Priority deterministic theo US Priority + loại requirement. KHÔNG interview.
 
-**Cảnh báo overwrite:** nếu tsd.md đã tồn tại, skill hỏi confirm rõ ràng — regenerate sẽ reassign IDs từ 001 và làm vỡ test code references nếu có.
+**Cảnh báo overwrite:** nếu test-design.md đã tồn tại, skill hỏi confirm rõ ràng — regenerate sẽ reassign IDs từ 001 và làm vỡ test code references nếu có.
 
 ---
 
@@ -203,7 +203,7 @@ Component Index và Feature Index **để placeholder** — sẽ được điề
 /spec-brownfield-feature [path]
          │
          ▼
-/spec-tsd [F-XXX]   (tùy chọn — chạy cho mỗi feature để bootstrap tsd.md)
+/spec-test-design [F-XXX]   (tùy chọn — chạy cho mỗi feature để bootstrap test-design.md)
          │
          ▼
 (fill in NEEDS_CLARIFY items khi có thêm context)
@@ -225,7 +225,7 @@ Nhóm skill dọn dẹp / migrate artifacts hiện có sau khi template được
 
 ### `/artifact-audit [type]`
 
-Phát hiện **main artifact** lỗi thời so với template (xem `conventions.md` §7 Template Versioning). So `template_version` của artifact với `template_version` đọc thẳng từ template tại `.claude/templates/main/` — không manifest, không cache. **Chỉ main artifacts** (`prd`/`domain`/`sad`/`frd`/`fdd`/`tsd`/`crd`/`cdd`); integration artifacts ngoài scope.
+Phát hiện **main artifact** lỗi thời so với template (xem `conventions.md` §7 Template Versioning). So `template_version` của artifact với `template_version` đọc thẳng từ template tại `.claude/templates/main/` — không manifest, không cache. **Chỉ main artifacts** (`prd`/`domain`/`sad`/`frd`/`fdd`/`test-design`/`crd`/`cdd`); integration artifacts ngoài scope.
 
 **Scope:** argument là 1 main type (`/artifact-audit frd`) hoặc list (`frd,crd`); không có arg → audit mọi main type. Type resolve theo **filename**.
 
@@ -260,7 +260,7 @@ Sau khi main artifacts đã sẵn sàng (từ greenfield hoặc brownfield), m
 | --- | --- | --- |
 | `/spec-new [requirement]` | `prd.md`, `domain.md`, frd(s), crd(s) | `.specs/integrations/{slug}/spec.md` |
 | `/spec-tech [number]` | `sad.md`, `domain.md`, cdd(s), fdd(s), `spec.md` | `.specs/integrations/{slug}/tech.md` |
-| `/spec-test [number]` | `spec.md`, frd(s), tsd(s), `tech.md` *(optional)* | `.specs/integrations/{slug}/test.md`, `feature/{F-XXX}/tsd.md` |
+| `/spec-test [number]` | `spec.md`, frd(s), test-design(s), `tech.md` *(optional)* | `.specs/integrations/{slug}/test.md`, `feature/{F-XXX}/test-design.md` |
 | `/plan` | `spec.md`, `tech.md`, `domain.md` | `plan.md`, `todo.md` |
 | `/build` | `plan.md`, `todo.md` | *(source code)* |
 | `/review-integration` | `spec.md`, `tech.md`, `plan.md`, `todo.md`, *(source code)* | *(findings report)* |
@@ -308,21 +308,22 @@ Tạo `.specs/integrations/{slug}/test.md` cho một integration. Chạy bởi *
 
 **Luôn hiển thị danh sách tất cả integrations** trong `.specs/integrations/`, đánh dấu `✓` những cái đã có `test.md`. Nếu có argument → chọn luôn không cần hiển thị.
 
-**Gate check:** spec.md phải `approved` + `features:` non-empty. Integration có `features: []` (thuần component) → dừng vì component-level `tsd` không tồn tại trong kit này.
+**Gate check:** spec.md phải `approved` + `features:` non-empty. Integration có `features: []` (thuần component) → dừng vì component-level `test-design` không tồn tại trong kit này.
 
-Context load: `spec.md` + `frd.md` (cho mỗi feature — source của TC) + `tsd.md` (cho mỗi feature nếu tồn tại, để diff và assign next ID) + `tech.md` *(optional, hint env / data set / NFR threshold)*.
+Context load: `spec.md` + `frd.md` (cho mỗi feature — source của TC) + `test-design.md` (cho mỗi feature nếu tồn tại, để diff và assign next ID) + `tech.md` *(optional, hint env / data set / NFR threshold)*.
 
 **KHÔNG interview** — agent **mechanical derive** TC từ frd.md:
 - mỗi Flow → 1 Test Scenario (`TS-F{NNN}-{seq}`)
 - mỗi US AC → 1 Functional TC
 - mỗi VR → 1 positive + 1+ negative Validation TC
-- mỗi FAC → 1 Feature AC TC (theo nhóm e2e / consistency / NFR / data & migration)
+- mỗi FAC → 1 E2E TC (Type e2e / consistency)
+- mỗi NFR → 1 Non-functional TC; mỗi DM → 1 Data & Migration TC
 
-Priority deterministic: US Priority Must/Should/Could → P0/P1/P2 (TC cover US/AC); VR → inherit max priority của Refs; FAC e2e/security/data → P0, consistency/perf/a11y → P1.
+Priority deterministic: US Priority Must/Should/Could → P0/P1/P2 (TC cover US/AC); VR → inherit max priority của Refs; FAC e2e + NFR security + DM → P0, FAC consistency + NFR perf/a11y → P1.
 
-**Cascade Proposals** đề xuất delta cho mỗi `feature/{F-XXX}/tsd.md` qua Changes blocks với markers `[NEW]/[MODIFY {field}]/[REMOVE]`. Feature no-delta → **bỏ block hoàn toàn**, ghi `no-op` trong Cascade Summary.
+**Cascade Proposals** đề xuất delta cho mỗi `feature/{F-XXX}/test-design.md` qua Changes blocks với markers `[NEW]/[MODIFY {field}]/[REMOVE]`. Feature no-delta → **bỏ block hoàn toàn**, ghi `no-op` trong Cascade Summary.
 
-QC review: override priority defaults, fill placeholders (env / data / OOS / strategy), add extra edge cases ngoài AC/VR nếu thấy cần. Sau confirm → auto-cascade ghi tsd.md.
+QC review: override priority defaults, fill placeholders (env / data / OOS / strategy), add extra edge cases ngoài AC/VR nếu thấy cần. Sau confirm → auto-cascade ghi test-design.md.
 
 ---
 
@@ -410,7 +411,7 @@ Di chuyển integration đã hoàn thành hoặc không còn active từ `.specs
         ▼                       ▼
    /spec-tech              /spec-test
    (review + cascade       (review + cascade
-    → cdd / fdd / sad)      → tsd)
+    → cdd / fdd / sad)      → test-design)
         │                       │
         └───────────┬───────────┘
                     │ (tech.md approved — /plan KHÔNG đợi test.md)

package/templates/integrations/test-template.md

@@ -12,15 +12,15 @@ referenced_by:
 
 ## Context
 
-<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (spec.md, tech.md, frd.md, current tsd.md của các feature touched), để file self-contained. -->
+<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (spec.md, tech.md, frd.md, current test-design.md của các feature touched), để file self-contained. -->
 
 ## Test Strategy
 
 <!--
 Strategy cho integration này — KHÔNG lặp lại Strategy chung của feature.
 Chỉ ghi delta hoặc nhấn mạnh phần đặc thù integration:
-- Loại test ưu tiên (functional / validation / FAC / cross-story consistency / NFR).
-- Environments / data set / fixture đặc thù.
+- Loại test ưu tiên (functional / validation / FAC e2e: journey / consistency / integrity / NFR / data & migration).
+- Yêu cầu data đặc thù integration (shape) — nguồn/refresh/env assignment thuộc execution layer, KHÔNG ở đây.
 - Risk areas (vd: data migration cần backfill verify, integration đụng auth flow → security regression).
 -->
 
@@ -28,46 +28,40 @@ Chỉ ghi delta hoặc nhấn mạnh phần đặc thù integration:
 
 - {bullet ngắn}
 
-### Environments
-
-| Env | Mục đích | Data set | Ghi chú |
-| --- | --- | --- | --- |
-| {dev / staging / prod-like} | {functional / E2E / load} | {seed / anonymized prod} | ... |
-
 ## Changes
 
 <!--
-test.md = changeset patch áp lên feature tsd.md(s). Mỗi block dưới đây tương ứng 1 feature bị touched.
+test.md = changeset patch áp lên feature test-design.md(s). Mỗi block dưới đây tương ứng 1 feature bị touched.
 Lặp block cho mỗi feature trong `features:` frontmatter mà có delta TC.
 
 **Khi nào BỎ block của 1 feature:**
-- Diff giữa frd hiện tại và tsd.md hiện tại của feature đó = empty (frd không thêm/đổi item nào mà tsd chưa cover).
+- Diff giữa frd hiện tại và test-design.md hiện tại của feature đó = empty (frd không thêm/đổi item nào mà test-design chưa cover).
 - Bỏ block hoàn toàn, ghi `no-op` cho feature đó trong Cascade Summary để minh bạch.
 
 **Operation:**
-- `create` — feature/{F-XXX}/tsd.md chưa tồn tại. Nội dung đầy đủ theo template gốc, mọi TS/TC implicit [NEW] (không cần marker).
-- `update` — feature/{F-XXX}/tsd.md đã tồn tại. Chỉ liệt kê TS/TC bị ảnh hưởng. Mỗi item có marker:
-  - `[NEW]` — TS/TC chưa có trong tsd hiện tại
+- `create` — feature/{F-XXX}/test-design.md chưa tồn tại. Nội dung đầy đủ theo template gốc, mọi TS/TC implicit [NEW] (không cần marker).
+- `update` — feature/{F-XXX}/test-design.md đã tồn tại. Chỉ liệt kê TS/TC bị ảnh hưởng. Mỗi item có marker:
+  - `[NEW]` — TS/TC chưa có trong test-design hiện tại
   - `[MODIFY {field}]` — TS/TC đã có, đang đổi field cụ thể (ví dụ `[MODIFY steps]`, `[MODIFY expected]`, `[MODIFY priority]`, `[MODIFY covers]`)
   - `[REMOVE]` — TS/TC đã có, sẽ bị xóa (ID retire — không tái sử dụng)
 
-**Format reference:** dùng đúng format của template gốc — KHÔNG duplicate skeleton ở đây. `templates/main/feature/tsd-template.md` là single source of truth cho format.
+**Format reference:** dùng đúng format của template gốc — KHÔNG duplicate skeleton ở đây. `templates/main/feature/test-design-template.md` là single source of truth cho format.
 
-**ID assignment:** agent đọc tsd.md hiện tại của feature để xác định next ID:
+**ID assignment:** agent đọc test-design.md hiện tại của feature để xác định next ID:
 - `TS-F{NNN}-{seq}` cho Test Scenarios
-- `TC-F{NNN}-{seq}` cho Test Cases (Functional, Validation, Feature AC dùng chung sequence — không reset theo loại)
+- `TC-F{NNN}-{seq}` cho Test Cases (Functional, Validation, E2E dùng chung sequence — không reset theo loại)
 - ID **stable** — không tái sử dụng khi [REMOVE], không renumber khi [MODIFY].
 
-**Auto-cascade:** sau khi human approve test.md, agent tự apply tất cả Changes blocks vào feature tsd.md. Integration test.md được giữ như PR record bất biến.
+**Auto-cascade:** sau khi human approve test.md, agent tự apply tất cả Changes blocks vào feature test-design.md. Integration test.md được giữ như PR record bất biến.
 -->
 
-### feature/{F-XXX}-{feature-slug}/tsd.md *(lặp block cho mỗi feature trong `features:` mà có delta TC; bỏ block nếu no-delta)*
+### feature/{F-XXX}-{feature-slug}/test-design.md *(lặp block cho mỗi feature trong `features:` mà có delta TC; bỏ block nếu no-delta)*
 
 **Operation:** create | update
-**Format reference:** [tsd-template.md](../../templates/main/feature/tsd-template.md)
+**Format reference:** [test-design-template.md](../../templates/main/feature/test-design-template.md)
 
 <!--
-operation=create → nội dung đầy đủ theo tsd-template.md (Overview, Test Strategy, Test Scenarios, Functional TCs, Validation TCs, Feature AC TCs, Test Data, Traceability Matrix, Out of Scope, Dependencies).
+operation=create → nội dung đầy đủ theo test-design-template.md (Overview, Test Strategy, Test Scenarios, Functional TCs, Validation TCs, E2E TCs, Non-Functional TCs, Data & Migration TCs, Test Data Requirements, Traceability Matrix, Out of Scope, Dependencies).
 operation=update → chỉ liệt kê TS/TC bị ảnh hưởng, mỗi item có marker, và **bắt buộc update Traceability Matrix** rows tương ứng.
 
 Ví dụ operation=update:
@@ -121,13 +115,13 @@ Ví dụ operation=update:
 | `TC-F001-030` | `VR-F001-008` | `refund_reason` | `"Customer changed mind"` | accept | positive | NEW |
 | `TC-F001-031` | `VR-F001-008` | `refund_reason` | `"abc"` | reject — min length | negative | NEW |
 
-#### Feature AC Test Cases
+#### E2E Test Cases
 
 ##### TC-F001-040 [NEW]: E2E checkout + refund
 
 | Field | Value |
 | --- | --- |
-| **Type** | Feature AC — e2e |
+| **Type** | E2E — journey |
 | **Priority** | P0 |
 | **Covers** | `FAC-F001-004` |
 | **Spans** | `US-F001-001`, `US-F001-005` |
@@ -135,6 +129,32 @@ Ví dụ operation=update:
 **Steps:** ...
 **Expected:** ...
 
+#### Non-Functional Test Cases
+
+##### TC-F001-045 [NEW]: Refund endpoint chịu tải
+
+| Field | Value |
+| --- | --- |
+| **Type** | Non-functional — performance |
+| **Priority** | P1 |
+| **Covers** | `NFR-F001-002` |
+
+**Steps:** ...
+**Expected:** ...
+
+#### Data & Migration Test Cases
+
+##### TC-F001-048 [NEW]: Backfill refund_reason cho order cũ
+
+| Field | Value |
+| --- | --- |
+| **Type** | Data migration |
+| **Priority** | P0 |
+| **Covers** | `DM-F001-001` |
+
+**Steps:** ...
+**Expected:** ...
+
 #### Traceability Matrix
 
 Bổ sung row cho mọi item mới + cập nhật row cho item bị [MODIFY]. KHÔNG xóa row của [REMOVE] — đánh dấu retire.
@@ -145,6 +165,8 @@ Bổ sung row cho mọi item mới + cập nhật row cho item bị [MODIFY]. KH
 | `AC-F001-012` | Story AC | `TC-F001-022` | ✅ | NEW |
 | `VR-F001-008` | VR | `TC-F001-030`, `TC-F001-031` | ✅ | NEW |
 | `FAC-F001-004` | Feature AC | `TC-F001-040` | ✅ | NEW |
+| `NFR-F001-002` | NFR | `TC-F001-045` | ✅ | NEW |
+| `DM-F001-001` | Data & Migration | `TC-F001-048` | ✅ | NEW |
 | Flow 3 | Flow | `TS-F001-003` | ✅ | NEW |
 -->
 
@@ -162,5 +184,5 @@ Bổ sung row cho mọi item mới + cập nhật row cho item bị [MODIFY]. KH
 
 | Artifact | Operation | Summary |
 | --- | --- | --- |
-| `feature/F-XXX-{slug}/tsd.md` | create / update | {ngắn: +N TS, +M TC, modify TC-F001-008, remove TC-F001-015} |
-| `feature/F-YYY-{slug}/tsd.md` | no-op | frd không đổi, tsd hiện tại đã cover full |
+| `feature/F-XXX-{slug}/test-design.md` | create / update | {ngắn: +N TS, +M TC, modify TC-F001-008, remove TC-F001-015} |
+| `feature/F-YYY-{slug}/test-design.md` | no-op | frd không đổi, test-design hiện tại đã cover full |

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.