spec-lite 1.2.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-lite",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/spec-brownfield-feature/SKILL.md

@@ -266,6 +266,10 @@ Brownfield init hoàn tất! Main artifacts:
   ├── component/       ({N} components, mỗi cái có crd.md + cdd.md)
   └── feature/         ({N} features, mỗi cái có frd.md + fdd.md)
 
+Bước tiếp theo (tùy chọn):
+  /spec-tsd [F-XXX]  → bootstrap tsd.md (Test Spec Document) cho từng feature
+                       — derive 1:1 từ frd.md, có test coverage tracking từ ngày 1.
+
 Để bắt đầu implement, dùng /spec-new để tạo integration đầu tiên.
 grep "NEEDS_CLARIFY" để tìm và fill in khi có thêm context.
 ```

package/skills/spec-test/SKILL.md

@@ -0,0 +1,365 @@
+---
+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.
+---
+
+# spec-test
+
+## Overview
+
+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).
+
+**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.
+
+**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.
+
+## When to Use
+
+- `spec.md` đã được approve → bắt đầu thiết kế verification
+- Bổ sung `test.md` cho integration đã có spec.md/tech.md nhưng chưa có test.md
+
+## 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.
+- Chỉ muốn cập nhật `test.md` đã có → edit file trực tiếp
+
+---
+
+## Process
+
+### Bước 1: Xác định integration
+
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
+- Quét `specs/integrations/*/spec.md`, tìm integration khớp với argument
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
+- Nếu tìm thấy → dùng integration đó, bắt đầu luôn
+
+**Nếu không có ARGUMENT:**
+
+Quét `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `test.md`:
+
+```
+Integrations:
+
+  [1] 001-implement-auth    — Implement Auth             spec✓ test✓
+  [2] 002-implement-todo    — Implement Todo Management  spec✓ test—
+
+Chọn số integration:
+```
+
+Nếu không có integration nào → thông báo:
+> Chưa có integration nào. Hãy chạy `/spec-new` trước.
+
+Nếu integration đã có `test.md` → hỏi trước khi tiếp tục:
+> `test.md` đã tồn tại cho integration này. Tiếp tục sẽ ghi đè. Tiếp tục không?
+
+---
+
+### Bước 1b: Gate check
+
+Đọc frontmatter của `specs/integrations/{slug}/spec.md`.
+
+**Check 1 — spec.md phải approved:**
+
+Nếu `status` **không phải** `approved`:
+
+> ⛔ `spec.md` của integration **{slug}** chưa được approve (status hiện tại: `{status}`).
+>
+> `/spec-test` cần spec.md approved vì cascade frd.md (nguồn của TC) chỉ apply sau khi approve.
+>
+> Để tiếp tục:
+> 1. Review `specs/integrations/{slug}/spec.md`
+> 2. Approve (đổi `status: draft` → `status: approved`)
+>
+> Sau đó chạy lại `/spec-test`.
+
+**Dừng hoàn toàn.**
+
+**Check 2 — features non-empty:**
+
+Đọc `features:` trong frontmatter. Nếu `[]`:
+
+> ⛔ 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`).
+>
+> Đặt verification cho integration này trong:
+> - `tech.md > Implementation Notes` — verification approach
+> - `plan.md > Verification phase` — test tasks cụ thể
+>
+> Không có gì để làm với `/spec-test`. Dừng.
+
+Nếu cả 2 check pass → tiếp tục Bước 2.
+
+---
+
+### Bước 2: Load context
+
+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/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:
+
+```
+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: 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}
+```
+
+Nếu frd.md của feature nào không tồn tại → báo lỗi và dừng (lỗi cascade từ spec.md trước đó):
+> ⛔ `specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại nhưng feature có trong `features:` của spec.md. Cascade từ spec.md có thể đã fail. Kiểm tra lại.
+
+---
+
+### Bước 3: Auto-derive draft
+
+**Nguyên tắc:** agent derive **1:1 mechanically** từ frd.md. KHÔNG sáng tạo TC ngoài frd. Phần creative (extra edge cases, exploratory testing) thuộc về QC khi review.
+
+#### 3.1 ID assignment
+
+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)`
+- 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
+- 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`
+
+#### 3.2 Derivation rules
+
+Áp dụng cho mỗi feature, sinh ra Changes block tương ứng:
+
+**A. Test Scenarios** — mỗi Flow trong `frd.md > User Flows` → 1 Test Scenario.
+
+- TS ID mới = `TS-F{NNN}-{next_seq}`
+- Flow ref: `frd.md > Flow {N}: {name}`
+- Preconditions: derive từ điểm bắt đầu của Mermaid flow
+- Postconditions: derive từ điểm kết thúc happy
+- Paths: liệt kê happy + mỗi edge case trong Mermaid
+- Test cases: list các TC ID sẽ cover TS này (cross-reference TC sinh ở bước B/D)
+
+**B. Functional Test Cases** — mỗi AC trong mỗi US → 1 Functional TC.
+
+- TC ID mới = `TC-F{NNN}-{next_seq}`
+- Type: `Functional — positive` (mặc định cho AC happy), `Functional — negative` nếu AC mô tả nhánh fail
+- Priority: derive từ US Priority (xem 3.3)
+- Covers: `US-{F_ID}-{seq}`, `AC-{F_ID}-{seq}`
+- Scenario: TS ID của Flow tương ứng (nếu AC nằm trong flow)
+- Preconditions/Steps/Expected: dịch 1:1 từ Given/When/Then của AC
+
+**C. Validation Test Cases** — mỗi VR → tối thiểu 2 TC.
+
+- 1 positive: input hợp lệ → accept
+- 1+ negative: mỗi nhánh fail là 1 TC riêng (vd VR "email format" → 1 case missing `@`, 1 case missing domain, 1 case có space). Agent infer các nhánh fail từ rule text.
+- TC ID mới = `TC-F{NNN}-{next_seq}` (chung sequence với Functional)
+- Form bảng theo template gốc
+- 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.
+
+- 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
+
+**E. Traceability Matrix** — row per frd item:
+
+- 1 row per Flow → cover by TS
+- 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)
+- 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
+
+Mọi TC đều có priority deterministic. QC override khi review (Bước 4).
+
+**TC cover US/AC** — inherit từ US Priority:
+
+| US Priority (frd) | TC Priority |
+| --- | --- |
+| Must | P0 |
+| Should | P1 |
+| Could | P2 |
+
+**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:
+
+| FAC group | TC Priority |
+| --- | --- |
+| End-to-end liên story | P0 |
+| Cross-story consistency | P1 |
+| NFR — security / data integrity | P0 |
+| NFR — performance / a11y / i18n / browser | P1 |
+| Data & migration | P0 |
+
+#### 3.4 Diff vs current tsd.md
+
+Với feature có tsd.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]`
+- TC hiện tại cover item đã bị xóa khỏi frd (orphan) → đánh dấu `[REMOVE]` + ghi lý do (vd: "AC-F001-005 không còn trong frd")
+- Item trong frd đã đổi nội dung mà TC cũ không còn match (vd AC đổi expected outcome) → đánh dấu TC cũ là `[MODIFY {field}]` với field cụ thể
+
+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.
+
+#### 3.5 Placeholders cần QC fill
+
+Agent **không suy đoán** các field sau, dùng placeholder rõ ràng để QC điền ở Bước 4:
+
+| 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ế |
+| 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 |
+
+---
+
+### Bước 4: Write — sinh draft
+
+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.
+- **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`)
+
+Hiển thị **toàn bộ draft** cho QC xem — **chưa ghi file, chưa cascade**.
+
+---
+
+### Bước 5: Review — xác nhận với user
+
+> 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)
+> 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.
+> 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).**
+
+Nếu QC yêu cầu chỉnh sửa:
+- Override priority → update draft
+- Add extra TC → assign next ID, mark `[NEW]`
+- Fill placeholder → update draft
+- Remove TC khỏi draft → bỏ block hoặc đổi marker
+
+Chỉ tiến hành Bước 6 sau khi QC confirm.
+
+---
+
+### Bước 6: Save + Auto-cascade
+
+**[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`.
+
+**[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.
+
+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` (separate lifecycle với integration test.md)
+
+- **Operation=update:**
+  - Đọc tsd.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)
+  - 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
+
+**[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
+
+**[6.4] Thông báo kết quả:**
+
+```
+✓ 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)
+
+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)
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "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. |
+| "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
+
+- Traceability Matrix có item ❌ mà không có lý do ở Gaps section → agent silent skip
+- 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
+- Cascade Summary thiếu row cho feature trong `features:` (kể cả no-op) → không minh bạch
+
+## Verification
+
+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
+- [ ] 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
+- [ ] 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
+- [ ] Fail-safe: nếu apply fail thì không ghi integration test.md
+- [ ] Mỗi feature tsd.md mới có status `draft` (separate lifecycle)

package/skills/spec-tsd/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: spec-tsd
+description: Tạo tsd.md (Test Spec 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ó tsd.md.
+---
+
+# spec-tsd
+
+## Overview
+
+Tạo `specs/main/feature/{F-XXX}-{slug}/tsd.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`/`tsd`) → 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 tsd.md để có test coverage tracking ngay từ đầu.
+- **Greenfield deferred** — feature có frd.md từ lâu nhưng tsd.md chưa được tạo (vd: test design bị defer).
+- **Ad-hoc rebuild** — tsd.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 tsd hiện tại → dùng `/spec-test` (changeset patch giữ ID stable)
+- Chỉ muốn sửa vài TC → edit `tsd.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-tsd` **regenerate IDs từ 001** mỗi lần chạy. Nếu tsd.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:
+- **tsd.md chưa tồn tại** → an toàn, không có reference, regenerate fresh.
+- **tsd.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 tsd:
+
+```
+Features có frd.md:
+
+  [1] F-001 — auth                spec✓ tsd✓
+  [2] F-002 — checkout             spec✓ tsd—
+  [3] F-003 — refund               spec✓ tsd— (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 tsd.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-tsd` cần frd làm input.
+
+**Check 2 — tsd.md đã tồn tại:**
+
+Nếu `specs/main/feature/{F-XXX}-{slug}/tsd.md` đã tồn tại:
+
+> ⚠ `tsd.md` đã tồn tại cho feature **{F-XXX} — {slug}**.
+>
+> `/spec-tsd` 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 tsd.md cũ thành `tsd.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 tsd)
+
+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
+- tsd.md hiện tại: {chưa có / sẽ overwrite — backup tại tsd.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 / Feature AC.
+- 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 | tsd 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}` | 1 Feature AC TC |
+
+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 | P0 |
+| TC cover FAC consistency | P1 |
+| TC cover FAC NFR security/data | P0 |
+| TC cover FAC NFR perf/a11y/i18n/browser | P1 |
+| TC cover FAC data & migration | P0 |
+
+#### 4.4 Traceability Matrix
+
+Row per frd item — Flow / US / Story AC / VR / FAC. 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 |
+| --- | --- |
+| Environments table | Row mặc định `dev / staging / prod-like` với data set `TBD`, mục đích `TBD` |
+| Test Data table | Row `{TBD — fixture}` cho mỗi dataset thấy cần |
+| 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 tsd.md trên đã đúng chưa? Check:
+>
+> 1. **Coverage** — Traceability Matrix có đủ row cho mỗi Flow / US / AC / VR / FAC trong frd?
+> 2. **Priority** — defaults theo bảng 4.3, có TC nào cần override?
+> 3. **Placeholders** — fill Environments / Test Data / 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}/tsd.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 đủ).
+
+Nếu overwrite — file backup `tsd.md.bak.{timestamp}` đã tạo ở Bước 2.
+
+Thông báo kết quả:
+
+```
+✓ specs/main/feature/{F-XXX}-{slug}/tsd.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 Feature AC TC
+  {nếu overwrite: backup tại tsd.md.bak.{timestamp}}
+
+Bước tiếp theo:
+  - QC: fill remaining placeholders (Environments, Test Data, 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 tsd sau cũng được" | Test coverage không tracked = không biết feature đóng được chưa. tsd làm song song với frd, không sau. |
+| "Rebuild tsd 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 tsd, đã có test code" | Test code là HOW. tsd 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 toàn `TBD` sau khi QC review xong
+- Overwrite tsd.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 Feature AC cover
+- [ ] Priority deterministic theo bảng 4.3
+- [ ] Nếu overwrite: tsd.md.bak.{timestamp} đã được tạo
+- [ ] QC đã confirm draft

package/skills-overview.md

@@ -65,13 +65,14 @@ Nếu `prd.md` chưa có → dừng, yêu cầu chạy `/spec-prd` trước.
 
 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`
+**Thứ tự bắt buộc:** `init` → `component` → `feature` → `tsd` *(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` |
 
 ### Phân chia trách nhiệm
 
@@ -143,6 +144,24 @@ Component Index và Feature Index **để placeholder** — sẽ được điề
 
 ---
 
+### `/spec-tsd [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.
+
+**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.
+
+**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).
+
+**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.
+
+**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ó.
+
+---
+
 ### Thứ tự thực hiện
 
 ```
@@ -155,6 +174,9 @@ 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)
+         │
+         ▼
 (fill in NEEDS_CLARIFY items khi có thêm context)
          │
          ▼
@@ -171,6 +193,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` |
 | `/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)* |
@@ -212,6 +235,30 @@ Context load: `spec.md` + `sad.md` + `domain.md` + `cdd.md` (cho mỗi component
 
 ---
 
+### `/spec-test [number]`
+
+Tạo `specs/integrations/{slug}/test.md` cho một integration. Chạy bởi **QC** sau khi `spec.md` đã được approve. **Song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Không có thứ tự bắt buộc giữa chúng.
+
+**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.
+
+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)*.
+
+**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)
+
+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.
+
+**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.
+
+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.
+
+---
+
 ### `/plan`
 
 Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`. Là SDD wrapper quanh `planning-and-task-breakdown`.
@@ -288,23 +335,33 @@ Di chuyển integration đã hoàn thành hoặc không còn active từ `specs/
 
 ```
         /spec-new [requirement]
-   (human review + apply cascade proposals + approve)
-                │
-        /spec-tech
-   (human review + apply cascade proposals + approve)
+   (human review + auto-cascade → frd / crd / prd / domain / sad)
                 │
-        /plan
-   (human approve)
-                │
-        /build ←──────────────┐
-                │              │
-        /review-integration   │ (nếu Critical/Important)
-                │              │
-           [approve] ──────────┘ (nếu Suggestion only)
-                │
-        /archive  (khi integration Done, dọn dẹp khỏi integrations/)
+                ▼ (spec.md approved)
+        ┌───────────────────────┬───────────────────────┐
+        │ DEV branch            │ QC branch (song song) │
+        ▼                       ▼
+   /spec-tech              /spec-test
+   (review + cascade       (review + cascade
+    → cdd / fdd / sad)      → tsd)
+        │                       │
+        └───────────┬───────────┘
+                    │ (tech.md approved — /plan KHÔNG đợi test.md)
+                    ▼
+                  /plan
+            (human approve)
+                    │
+                  /build ←──────────────┐
+                    │                    │
+            /review-integration         │ (nếu Critical/Important)
+                    │                    │
+              [approve] ─────────────────┘ (nếu Suggestion only)
+                    │
+                  /archive
 ```
 
+> **Lưu ý:** `/spec-tech` (DEV) và `/spec-test` (QC) chạy song song / độc lập — cả hai chỉ phụ thuộc `spec.md` approved. `/plan` chỉ chờ `tech.md` (test tasks tự QC manage trong test framework, không phải plan.md).
+
 ---
 
 ## Project-level review

package/templates/integrations/test-template.md

@@ -0,0 +1,166 @@
+---
+id: "{id}"
+slug: "{slug}"
+title: "{title}"
+features: []
+status: draft
+created: {YYYY-MM-DD}
+referenced_by:
+  - conventions.md > 4. Integration Artifacts > 4.7 test.md > Cấu trúc
+  - skills/spec-test/SKILL.md > Process > Bước 4: Write — sinh draft
+---
+
+## 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. -->
+
+## 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ù.
+- Risk areas (vd: data migration cần backfill verify, integration đụng auth flow → security regression).
+-->
+
+### Approach
+
+- {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.
+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).
+- 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
+  - `[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.
+
+**ID assignment:** agent đọc tsd.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)
+- 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.
+-->
+
+### 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)*
+
+**Operation:** create | update
+**Format reference:** [tsd-template.md](../../templates/main/feature/tsd-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=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:
+
+#### Test Scenarios
+
+##### TS-F001-003 [NEW]: Refund flow — happy + edge
+
+- **Flow ref:** `frd.md > Flow 3: Refund`
+- **Preconditions:** order đã thanh toán xong, refund window còn hạn
+- **Postconditions:** số tiền hoàn về phương thức thanh toán gốc
+- **Paths:**
+  - Happy: order paid → refund click → confirm → refunded
+  - Edge: order paid → refund click → past window → blocked
+- **Test cases:** `TC-F001-022`, `TC-F001-023`
+
+#### Functional Test Cases
+
+##### TC-F001-022 [NEW]: Refund order trong window
+
+| Field | Value |
+| --- | --- |
+| **Type** | Functional — positive |
+| **Priority** | P0 |
+| **Covers** | `US-F001-005`, `AC-F001-012` |
+| **Scenario** | `TS-F001-003` |
+| **Preconditions** | order paid 1h trước |
+
+**Steps:**
+
+1. Login customer
+2. Vào order detail
+3. Click "Refund"
+4. Confirm refund
+
+**Expected:**
+
+- Refund record được tạo với status `processing`
+- Email notification gửi tới customer
+
+##### TC-F001-008 [MODIFY expected]
+- Expected: 2-3 phút → 30s (sau khi tech.md tối ưu queue)
+
+##### TC-F001-015 [REMOVE]
+- Lý do: superseded by TC-F001-022 (cover same AC, scope hẹp hơn)
+
+#### Validation Test Cases
+
+| TC ID | Covers VR | Field | Input | Expected | Polarity | Op |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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
+
+##### TC-F001-040 [NEW]: E2E checkout + refund
+
+| Field | Value |
+| --- | --- |
+| **Type** | Feature AC — e2e |
+| **Priority** | P0 |
+| **Covers** | `FAC-F001-004` |
+| **Spans** | `US-F001-001`, `US-F001-005` |
+
+**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.
+
+| FRD Item | Type | Covered by | Status | Op |
+| --- | --- | --- | --- | --- |
+| `US-F001-005` | US | `TC-F001-022` | ✅ | NEW |
+| `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 |
+| Flow 3 | Flow | `TS-F001-003` | ✅ | NEW |
+-->
+
+## Out of Scope
+
+<!-- Những gì KHÔNG được test trong integration này và lý do (vd: thuộc layer khác như infra audit, NFR đã verify ở integration trước, ...) -->
+
+## Open Questions
+
+<!-- Các điểm còn mơ hồ cần clarify trước khi proceed. Xóa section nếu không có. -->
+
+## Cascade Summary
+
+<!-- Bảng tóm tắt để reviewer scan nhanh trước khi approve. Liệt kê **tất cả** feature trong `features:` — feature no-delta ghi operation `no-op`. -->
+
+| 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 |

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

@@ -27,6 +27,8 @@ Mọi thay đổi structure ở file này tự động propagate qua Changes blo
 {Mô tả các luồng thao tác của user để hoàn thành mục tiêu của feature này.}
 {Mỗi flow là một Mermaid flowchart riêng, bao gồm happy case và tất cả edge cases quan trọng.}
 
+Flow numbering **stable** — không renumber khi xóa flow. Nếu xóa Flow 1, Flow 2 giữ nguyên số (không tái sử dụng số 1).
+
 ### Flow 1: {Tên luồng chính}
 
 ```mermaid
@@ -46,19 +48,32 @@ flowchart TD
     A(["Điểm bắt đầu"]) --> B["..."]
 ```
 
-## Feature-level Acceptance Criteria
+## Feature Acceptance Criteria
 
-Criteria áp dụng cho toàn bộ feature — không gắn với story cụ thể (ví dụ: performance, security, accessibility).
-AC ID format: `AC-F{NNN}-{seq}` — đánh số tăng dần toàn feature (không reset giữa sections).
+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.
 
-- `AC-{F_ID}-001`
-  - **Given** {precondition}
+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ũ.
+
+> 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.
+
+- `FAC-{F_ID}-001`
+  - **Given** {precondition đo được}
   - **When** {action}
-  - **Then** {expected outcome}
+  - **Then** {outcome có threshold hoặc danh sách cụ thể, không vague}
 
 ## User Stories
 
-US ID format: `US-F{NNN}-{seq}` — đánh số tăng dần toàn feature.
+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.
+
+Story AC ID format: `AC-F{NNN}-{seq}` — đánh số tăng dần toàn feature (không reset giữa các story). ID **stable** — không tái sử dụng seq khi xóa, không renumber.
 
 ### US-{F_ID}-001: {Story title}
 

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

@@ -0,0 +1,220 @@
+---
+id: tsd-{feature}
+type: tsd
+status: draft
+owner: "{QC}"
+feature_id: "{Feature ID — match frd.md}"
+frd_ref: "feature/{F-XXX}-{slug}/frd.md"
+referenced_by:
+  - conventions.md > 3. Main Artifacts > 3.3 Feature level > tsd.md > Cấu trúc
+---
+
+<!--
+Canonical format cho feature/{F-XXX}-{slug}/tsd.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.
+
+TSD chỉ tồn tại ở FEATURE level — không tách tsd 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 Spec: {Feature Name}
+
+## Overview
+
+{Phạm vi tsd 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**: cover các Feature AC — e2e liên story, cross-story consistency, NFR, data & migration.
+
+### Environments
+
+| Env | Mục đích | Data set | Ghi chú |
+| --- | --- | --- | --- |
+| {dev / staging / prod-like} | {functional / E2E / load} | {seed / anonymized prod} | ... |
+
+## 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.
+
+### TC-{F_ID}-001: {Title ngắn — verb-first}
+
+| Field | Value |
+| --- | --- |
+| **Type** | Functional — positive / negative |
+| **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 section hoặc inline literal}
+
+---
+
+### TC-{F_ID}-002: ...
+
+## Validation Test Cases
+
+Derive 1:1 từ Verification Rules trong frd. 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 |
+
+## Feature AC Test Cases
+
+Cover Feature Acceptance Criteria (`FAC-*`) trong frd. Feature AC trong frd đã ở format G/W/T → TC ở đây dịch 1:1: Given → Preconditions, When → Steps, Then → Expected.
+
+### TC-{F_ID}-040: {Title — e2e liên story}
+
+| Field | Value |
+| --- | --- |
+| **Type** | Feature AC — e2e |
+| **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** | Feature AC — 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
+
+---
+
+### TC-{F_ID}-050: {Title — NFR perf}
+
+| Field | Value |
+| --- | --- |
+| **Type** | Feature AC — performance |
+| **Priority** | P0 |
+| **Covers** | `FAC-{F_ID}-003` |
+| **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%
+
+## Test Data
+
+| Data set | Mục đích | Nguồn | Refresh |
+| --- | --- | --- | --- |
+| `seed_users` | functional positive | fixture / factory | mỗi run |
+| `boundary_inputs` | validation edges | inline trong TC | n/a |
+
+## 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 | `TC-{F_ID}-040` | ✅ |
+| `FAC-{F_ID}-002` | Feature AC | `TC-{F_ID}-041` | ✅ |
+| `FAC-{F_ID}-003` | Feature AC | `TC-{F_ID}-050` | ✅ |
+| `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ì tsd 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-`, 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 tsd riêng cho component.

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

@@ -1,60 +0,0 @@
----
-id: "003-assign-todo"
-slug: "assign-todo"
-title: "Assign Todo — Test Plan"
-features: ["F-004"]
-status: draft
-created: 2026-04-21
----
-
-## Test Strategy
-
-Approach tổng quan: test pyramid distribution, environment setup, fixtures.
-
-## AC Coverage Matrix
-
-| AC ID | Primary Level | Test Case ID(s) | Status |
-|-------|--------------|-----------------|--------|
-| AC-F004-001 | Component | TC-001 | draft |
-| AC-F004-002 | Component | TC-002 | draft |
-| ... |
-
-## Verification Rules Coverage
-
-Mỗi rule trong `frd.md > Verification Rules` của feature phải có **≥ 1 positive test case** (input hợp lệ pass) và **≥ 1 negative test case** (input vi phạm rule bị reject). Nếu rule áp dụng ở nhiều layer (client + gateway, xem `fdd.md > Verification Implementation`) → cover từng layer.
-
-| Rule ID | Layer (từ FDD) | Test Case ID(s) | Status |
-|---------|----------------|-----------------|--------|
-| VR-F004-001 | service | TC-010 (pos), TC-011 (neg) | draft |
-| VR-F004-002 | gateway | TC-012 (neg) | draft |
-| ... |
-
-## Test Cases
-
-### TC-001: Non-owner không thấy assign control
-**Verifies:** AC-F004-001 (primary)
-**Level:** Component test (TodoModal)
-**Setup:**
-- Render TodoModal với prop `isOwner: false`
-**Steps:**
-1. Mở modal
-2. Query assign control
-**Expected:**
-- Assign control không có trong DOM
-**Negative variants:** —
-
-### TC-006: Happy path assign
-**Verifies:** AC-F004-006, AC-F004-007 (primary), AC-F004-008 (supporting)
-**Level:** E2E (Playwright)
-**Setup:**
-- Seed: userA, userB
-- userA login, tạo todo
-**Steps:**
-1. userA mở task detail
-2. Click assign, chọn userB
-3. Confirm
-**Expected:**
-- Modal hiển thị owner = userB
-- Refresh dashboard → card hiển thị userB
-**Verification queries:**
-- DB: `SELECT * FROM todo_history WHERE todo_id=? AND event_type='ASSIGNED'` → 1 row, payload đúng