spec-lite 1.5.1 → 1.6.0

package/README.md

@@ -45,7 +45,7 @@ BA author `.specs/main/feature/{F-XXX}-*/frd.md` trực tiếp qua interview, **
 
 Phạm vi hẹp: **chủ yếu frd.md** (+ tối đa một feature row vào prd nếu register). Reference component frd phụ thuộc (Components Used); component cần-nhưng-chưa-có ghi như *candidate* để `/spec-sad`/architect chốt boundary. **KHÔNG** tạo `crd.md`/`cdd.md` — component artifacts sinh ở integration time qua `/spec-new` cascade. Change History operation = `manual`. Nếu bỏ qua bước này, `/spec-new` vẫn tự tạo frd làm fallback.
 
-Sections: Overview · User Flows · Feature Acceptance Criteria · User Stories · Verification Rules · Scope · Dependencies
+Sections: Overview · User Flows · Feature Acceptance Criteria (end-to-end) · Non-Functional Requirements · Data & Migration *(nếu có)* · User Stories · Verification Rules · Scope · Dependencies
 
 ---
 
@@ -63,7 +63,7 @@ Scan codebase để extract main artifacts, sau đó vào Integration Pipeline.
 /spec-brownfield-feature
          │
          ▼
-/spec-tsd [F-XXX]   (tùy chọn — bootstrap tsd.md cho từng feature)
+/spec-test-design [F-XXX]   (tùy chọn — bootstrap test-design.md cho từng feature)
          │
          ▼
 (fill in NEEDS_CLARIFY khi có thêm context)
@@ -81,8 +81,8 @@ Scan module dirs, tạo `crd.md` + `cdd.md` cho từng component, điền Compon
 #### `/spec-brownfield-feature [path]`
 Scan routes/use cases/tests, tạo `frd.md` + `fdd.md` cho từng feature, điền Feature Index vào `prd.md`. Yêu cầu `component` đã chạy (fdd.md cần C-XXX IDs từ Component Index).
 
-#### `/spec-tsd [F-XXX]`
-Bootstrap `feature/{F-XXX}/tsd.md` (Test Spec Document) trực tiếp từ `frd.md` — mechanical derive Test Scenarios + Test Cases (mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → ≥1 positive + 1+ negative, mỗi FAC → Feature AC TC). Không interview, không cần integration. Dùng sau `/spec-brownfield-feature` để có test coverage tracking từ ngày 1, hoặc khi tsd drift khỏi frd cần regenerate fresh.
+#### `/spec-test-design [F-XXX]`
+Bootstrap `feature/{F-XXX}/test-design.md` (Test Design Document) trực tiếp từ `frd.md` — mechanical derive Test Scenarios + Test Cases (mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → ≥1 positive + 1+ negative, mỗi FAC → E2E TC, mỗi NFR → Non-functional TC, mỗi DM → Data & Migration TC). Không interview, không cần integration. Dùng sau `/spec-brownfield-feature` để có test coverage tracking từ ngày 1, hoặc khi test-design drift khỏi frd cần regenerate fresh.
 
 > **NEEDS_CLARIFY:** Các mục chưa rõ khi scan được đánh dấu `[NEEDS_CLARIFY]` — không block workflow, fill in dần khi có thêm context.
 
@@ -99,7 +99,7 @@ Mỗi requirement mới đều đi qua pipeline này.
           ├─────────────────┐
           ▼                 ▼
    /spec-tech         /spec-test   (song song — cả hai chỉ phụ thuộc spec.md)
-   (DEV approve)      (QC approve, cascade lên feature/*/tsd.md)
+   (DEV approve)      (QC approve, cascade lên feature/*/test-design.md)
           │                 │
           └────────┬────────┘
                   ▼
@@ -126,7 +126,7 @@ Tạo `.specs/integrations/{slug}/tech.md` sau khi `spec.md` được approve. C
 - Không có argument → hiển thị danh sách tất cả integrations
 
 #### `/spec-test [number]`
-Tạo `.specs/integrations/{slug}/test.md` sau khi `spec.md` được approve. Chạy bởi **QC**, **song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Mechanical derive Test Scenarios + Test Cases từ frd.md (Flow → TS, US/AC → Functional TC, VR → positive + negative, FAC → Feature AC TC), priority deterministic. Cascade lên `feature/{F-XXX}/tsd.md` qua Changes blocks. Gate: integration phải có `features:` non-empty (component-thuần không áp dụng).
+Tạo `.specs/integrations/{slug}/test.md` sau khi `spec.md` được approve. Chạy bởi **QC**, **song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Mechanical derive Test Scenarios + Test Cases từ frd.md (Flow → TS, US/AC → Functional TC, VR → positive + negative, FAC → E2E TC, NFR → Non-functional TC, DM → Data & Migration TC), priority deterministic. Cascade lên `feature/{F-XXX}/test-design.md` qua Changes blocks. Gate: integration phải có `features:` non-empty (component-thuần không áp dụng).
 
 #### `/plan`
 Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`.
@@ -171,12 +171,12 @@ Migrate **main artifact** lỗi thời lên structure mới (mọi main type). T
 | `/spec-brownfield-init` | `.specs/main/prd.md`, `.specs/main/domain.md`, `.specs/main/sad.md` |
 | `/spec-brownfield-component` | `.specs/main/component/{C-XXX}-*/crd.md + cdd.md` |
 | `/spec-brownfield-feature` | `.specs/main/feature/{F-XXX}-*/frd.md + fdd.md` |
-| `/spec-tsd` | `.specs/main/feature/{F-XXX}-*/tsd.md` |
+| `/spec-test-design` | `.specs/main/feature/{F-XXX}-*/test-design.md` |
 | `/artifact-audit` | *(báo cáo out-dated; + stamp `template_version` cho main artifact legacy conform)* |
 | `/artifact-migrate` | *(modify in-place main artifact lỗi thời lên structure mới + set `template_version`)* |
 | `/spec-new` | `.specs/integrations/{slug}/spec.md` |
 | `/spec-tech` | `.specs/integrations/{slug}/tech.md` |
-| `/spec-test` | `.specs/integrations/{slug}/test.md`, cascade: `feature/{F-XXX}/tsd.md` |
+| `/spec-test` | `.specs/integrations/{slug}/test.md`, cascade: `feature/{F-XXX}/test-design.md` |
 | `/plan` | `.specs/integrations/{slug}/plan.md`, `todo.md` |
 | `/build` | *(implements tasks từ `plan.md`/`todo.md`)* |
 | `/review-integration` | *(findings report — không tạo file)* |

package/package.json

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

package/skills/ado-create/SKILL.md

@@ -216,7 +216,7 @@ Sau khi tất cả tickets đã được tạo, cập nhật `spec.md`:
 ### Feature: Đăng ký / Đăng nhập (F-001)
 **ADO:** [#12345 — [SDLC-TEST] Đăng ký / Đăng nhập](https://dev.azure.com/...)
 
-**Feature-level Acceptance Criteria:**
+**Feature Acceptance Criteria:**
 ```
 
 **Với User Story ticket thành công:** Thêm dòng `**ADO:**` ngay sau heading user story:

package/skills/artifact-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifact-audit
-description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so với template không (chỉ main artifacts — prd/domain/sad/frd/fdd/tsd/crd/cdd; integration artifacts ngoài scope). So `template_version` của artifact với `template_version` hiện tại đọc thẳng từ template (.claude/templates/). Versioned khớp → up-to-date, lệch → out-dated (in vX → vY). Artifact thiếu version (sinh trước versioning) → đối chiếu structure với template: khớp thì stamp version, lệch thì flag out-dated. KHÔNG tự migrate — chỉ stamp khi chắc chắn khớp + báo cáo. Nhận tùy chọn 1 hay nhiều main type làm scope (vd `frd`, `frd,crd`); không có arg → audit mọi main type.
+description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so với template không (chỉ main artifacts — prd/domain/sad/frd/fdd/test-design/crd/cdd; integration artifacts ngoài scope). So `template_version` của artifact với `template_version` hiện tại đọc thẳng từ template (.claude/templates/). Versioned khớp → up-to-date, lệch → out-dated (in vX → vY). Artifact thiếu version (sinh trước versioning) → đối chiếu structure với template: khớp thì stamp version, lệch thì flag out-dated. KHÔNG tự migrate — chỉ stamp khi chắc chắn khớp + báo cáo. Nhận tùy chọn 1 hay nhiều main type làm scope (vd `frd`, `frd,crd`); không có arg → audit mọi main type.
 ---
 
 # artifact-audit
@@ -9,7 +9,7 @@ description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so v
 
 Trả lời một câu hỏi: **main artifact nào trong `.specs/main/` đã lỗi thời so với template mới nhất?**
 
-> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `tsd`, `crd`, `cdd` — đều nằm dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt` dưới `.specs/integrations/`) **không** thuộc scope của skill này — chúng là ephemeral và immutable sau khi `done`, không audit/migrate theo version.
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `test-design`, `crd`, `cdd` — đều nằm dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt` dưới `.specs/integrations/`) **không** thuộc scope của skill này — chúng là ephemeral và immutable sau khi `done`, không audit/migrate theo version.
 
 Cơ chế (xem `conventions.md` §7 Template Versioning):
 - **Nguồn sự thật** = `template_version` trong frontmatter template đang cài (`.claude/templates/...`). Đọc thẳng lúc chạy — không manifest, không cache.
@@ -43,7 +43,7 @@ Type của main artifact resolve theo **filename**. Mỗi type map tới đúng
 | `sad.md` | sad | `main/sad-template.md` |
 | `frd.md` | frd | `main/feature/frd-template.md` |
 | `fdd.md` | fdd | `main/feature/fdd-template.md` |
-| `tsd.md` | tsd | `main/feature/tsd-template.md` |
+| `test-design.md` | test-design | `main/feature/test-design-template.md` |
 | `crd.md` | crd | `main/component/crd-template.md` |
 | `cdd.md` | cdd | `main/component/cdd-template.md` |
 

package/skills/artifact-migrate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifact-migrate
-description: Migrate MAIN artifact trong .specs/main/ lên structure template mới nhất (chỉ main artifacts — prd/domain/sad/frd/fdd/tsd/crd/cdd; integration artifacts ngoài scope). Tự chạy /artifact-audit (classify-only, scoped) để phát hiện out-dated, rồi áp delta từ block `migrations` của template — add section thiếu, remove section deprecated, update format section (vd ASCII→Mermaid) — set template_version = current. Tương tác: confirm add/remove/update, hỏi carry-over khi rename, section nội dung mới thì interview hoặc NEEDS_CLARIFY (không bịa). Single-artifact, KHÔNG cascade. Nhận tùy chọn 1 main artifact (path); không có arg → quét mọi main artifact, migrate từng cái có confirm + skip.
+description: Migrate MAIN artifact trong .specs/main/ lên structure template mới nhất (chỉ main artifacts — prd/domain/sad/frd/fdd/test-design/crd/cdd; integration artifacts ngoài scope). Tự chạy /artifact-audit (classify-only, scoped) để phát hiện out-dated, rồi áp delta từ block `migrations` của template — add section thiếu, remove section deprecated, update format section (vd ASCII→Mermaid) — set template_version = current. Tương tác: confirm add/remove/update, hỏi carry-over khi rename, section nội dung mới thì interview hoặc NEEDS_CLARIFY (không bịa). Single-artifact, KHÔNG cascade. Nhận tùy chọn 1 main artifact (path); không có arg → quét mọi main artifact, migrate từng cái có confirm + skip.
 ---
 
 # artifact-migrate
@@ -9,7 +9,7 @@ description: Migrate MAIN artifact trong .specs/main/ lên structure template m
 
 Đưa một main artifact (hoặc toàn bộ main artifacts) **lỗi thời** lên đúng structure của template mới nhất, rồi cập nhật `template_version`. Đây là vế **fix** đối xứng với `/artifact-audit` (vế **detect**).
 
-> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `tsd`, `crd`, `cdd` — đều dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — ephemeral + immutable sau `done`, không migrate theo version.
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `test-design`, `crd`, `cdd` — đều dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — ephemeral + immutable sau `done`, không migrate theo version.
 
 Cơ chế (xem `conventions.md` §7 Template Versioning):
 - **Required section hiện tại** = body `##` headings của template (deterministic theo level; `###` = instance).
@@ -34,7 +34,7 @@ Cơ chế (xem `conventions.md` §7 Template Versioning):
 
 Resolve type của main artifact theo **filename** (giống `/artifact-audit`). Mỗi type map tới đúng một template tại `.claude/templates/...`:
 
-`prd.md`→`main/prd-template.md` · `domain.md`→`main/domain-template.md` · `sad.md`→`main/sad-template.md` · `frd.md`→`main/feature/frd-template.md` · `fdd.md`→`main/feature/fdd-template.md` · `tsd.md`→`main/feature/tsd-template.md` · `crd.md`→`main/component/crd-template.md` · `cdd.md`→`main/component/cdd-template.md`
+`prd.md`→`main/prd-template.md` · `domain.md`→`main/domain-template.md` · `sad.md`→`main/sad-template.md` · `frd.md`→`main/feature/frd-template.md` · `fdd.md`→`main/feature/fdd-template.md` · `test-design.md`→`main/feature/test-design-template.md` · `crd.md`→`main/component/crd-template.md` · `cdd.md`→`main/component/cdd-template.md`
 
 **Chỉ main artifacts.** Integration artifacts (`spec`/`tech`/`test`/`plan`/`todo`/`techdebt`) ngoài scope → bỏ qua. File không khớp map → cũng bỏ qua.
 

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

@@ -289,7 +289,7 @@ Brownfield init hoàn tất! Main artifacts:
   └── 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
+  /spec-test-design [F-XXX]  → bootstrap test-design.md (Test Design 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.

package/skills/spec-frd/SKILL.md

@@ -9,7 +9,7 @@ description: Author MỚI frd.md (Feature Requirements Document) trực tiếp
 
 Author `.specs/main/feature/{F-XXX}-{feature-slug}/frd.md` trực tiếp qua interview — **spec-first ở feature level**, do **BA** chạy trước khi bất kỳ integration nào bắt đầu.
 
-`frd.md` là **what to build** của một feature: Overview, User Flows, Feature AC, User Stories, Verification Rules, Scope, Dependencies. Đây là baseline ổn định, **author một lần** — mọi thay đổi sau đó đi qua `/spec-new` (delta cascade).
+`frd.md` là **what to build** của một feature: Overview, User Flows, Feature AC (end-to-end), Non-Functional Requirements, Data & Migration, User Stories, Verification Rules, Scope, Dependencies. Đây là baseline ổn định, **author một lần** — mọi thay đổi sau đó đi qua `/spec-new` (delta cascade).
 
 Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (vốn reverse-engineer frd từ code). Khác biệt: `/spec-frd` author *forward* từ interview, không scan code.
 
@@ -23,7 +23,7 @@ Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (
 - ✅ Nếu feature mục tiêu là feature mới chưa có trong Index → **register một row vào `prd.md > Features`** (side-effect hợp lệ lên prd).
 - ✅ **Cascade vocabulary lên `domain.md`** (Bước 4b — pha *mô tả hệ thống*/WHAT): glossary term + **định nghĩa entity đầy đủ** (attributes). `Owner` của entity để `TBD` cho `/spec-sad` điền ở pha *thiết kế hệ thống* (HOW). BA duyệt trước khi ghi. Đây là điểm khác với phiên bản trước (`/spec-frd` từng không đụng domain) — vocabulary sinh ra ở feature-authoring time nên seed luôn, thay vì để domain rỗng tới integration đầu tiên.
 - ❌ KHÔNG tạo/sửa `crd.md`/`cdd.md` — component artifacts ra đời ở integration time qua `/spec-new` cascade.
-- ❌ KHÔNG tạo `fdd.md` (inter-component design) hay `tsd.md` (test) — để skill/role khác lo.
+- ❌ KHÔNG tạo `fdd.md` (inter-component design) hay `test-design.md` (test) — để skill/role khác lo.
 - ❌ KHÔNG carve component / quyết `Owner` của shared entity (để `/spec-sad`/`/spec-new`); KHÔNG đổi status feature đã có; KHÔNG đụng sad.
 
 ## When to Use
@@ -43,6 +43,31 @@ Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (
 
 ## Process
 
+### Pre-flight: chuẩn bị nhánh Git (chạy TRƯỚC Bước 0)
+
+Mục tiêu: không bao giờ author frd ngay trên nhánh hiện tại của user (có thể là một nhánh đang làm dở) — luôn bắt đầu từ **nhánh chính mới nhất** rồi tách một **nhánh làm việc riêng**.
+
+**Trước tiên, thông báo cho user toàn bộ việc Git skill sẽ làm** (để user biết trước, đúng tinh thần "agent làm các việc này"):
+
+> Trước khi author frd, mình sẽ:
+> 1. Pull code mới nhất từ nhánh chính (`{main}`).
+> 2. Tạo & checkout một nhánh mới tách từ `{main}` để làm việc.
+>
+> (Bạn đang ở nhánh `{current}`.)
+
+**1. Xác định nhánh chính (`{main}`).**
+- Không phải git repo → bỏ qua toàn bộ pre-flight, note cho user rồi tiếp Bước 0.
+- Có nhánh `develop` → mặc định `{main}` = `develop`. Không có `develop` nhưng có `main`/`master` → dùng nó.
+- Mơ hồ (tồn tại cả `develop` lẫn `main`, hoặc remote default khác) → **hỏi user** nhánh nào là nhánh chính. KHÔNG đoán.
+
+**2. Kiểm tra working tree sạch.** `git status` còn thay đổi chưa commit → **DỪNG**, báo user commit/stash trước. KHÔNG tự ý stash/discard.
+
+**3. Checkout + pull nhánh chính:** `git checkout {main}` rồi `git pull`. Pull fail (conflict, không có upstream…) → **DỪNG**, surface lỗi cụ thể, để user xử lý.
+
+**4. Tạo nhánh làm việc mới off `{main}`.** Cần slug để đặt tên → thực hiện **ngay sau khi xác định feature mục tiêu ở Bước 1c** (xem nhắc ở đó): đề xuất `git checkout -b spec/{F-XXX}-{slug}`, cho user sửa tên rồi tạo. Mọi việc author/cascade từ Bước 2 trở đi diễn ra trên nhánh này.
+
+---
+
 ### Bước 0: Nạp nguồn yêu cầu (tùy chọn)
 
 Giống `/spec-prd` Bước 0. Xác định có nguồn baseline cho feature không (proposal, mô tả feature, ghi chú họp, wireframe note):
@@ -106,7 +131,7 @@ Chọn feature để author frd:
 
 Kiểm tra `.specs/main/feature/{F-XXX}-*/frd.md`.
 
-- **Chưa tồn tại** → tiếp Bước 2 (author mới).
+- **Chưa tồn tại** → **tạo nhánh làm việc** (Pre-flight bước 4): `git checkout -b spec/{F-XXX}-{slug}` off `{main}` (đề xuất tên, cho user sửa), rồi tiếp Bước 2 (author mới).
 - **Đã tồn tại** → **DỪNG**, redirect `/spec-new`:
   > frd.md cho {F-XXX} đã tồn tại. Mọi thay đổi feature đã được spec phải đi qua `/spec-new` — skill đó phân tích delta, cascade lên frd/crd/prd/domain, và kéo theo việc kỹ thuật/test (`/spec-tech`, `/spec-test`).
   > Chạy: `/spec-new {F-XXX}` (hoặc `/spec-new <mô tả thay đổi>`).
@@ -155,9 +180,14 @@ Hỏi tuần tự, từng phần — không hỏi tất cả cùng lúc. Nếu B
 **Phần 3 — User Stories:**
 > Liệt kê các stories ở cấp feature: "{Persona} muốn {hành động} để {mục tiêu}". Mỗi story có priority (Must/Should/Could) và acceptance criteria (Given/When/Then).
 
-**Phần 4 — Feature Acceptance Criteria:**
-> Có criteria nào áp cho *toàn* feature mà story lẻ không cover? (e2e liên story, cross-story consistency, NFR như performance/accessibility, data & migration)
-> Mỗi cái Given/When/Then, **Then phải đo được**.
+**Phần 4 — Feature Acceptance Criteria (end-to-end):**
+> Có criteria **end-to-end** nào áp cho *toàn* feature mà story lẻ không cover? 3 shape: journey (tuần tự liên story) + consistency (đa màn) + integrity (bất biến liên story, không tuần tự — vd cascade delete, đối soát khớp). Mỗi cái Given/When/Then, **Then phải đo được**. (NFR và data/migration hỏi riêng ở Phần 4b / 4c.)
+
+**Phần 4b — Non-Functional Requirements:**
+> Feature có yêu cầu non-functional riêng không? (performance, accessibility, security, browser, i18n). Mỗi cái **tham chiếu `NFR-*` của PRD nếu có** (refine bar chung) hoặc đặc thù-feature. G/W/T, Then đo được. Không có → để section trống (required-emptyable, giữ heading).
+
+**Phần 4c — Data & Migration:**
+> Feature có đụng migration / backfill data cũ không? Nếu có: G/W/T, Then đo được (đếm bản ghi / so khớp). Không có → giữ heading, để section trống (required-emptyable).
 
 **Phần 5 — Verification Rules:**
 > Với mỗi input field trong các stories, mình sẽ suggest 2-4 phương án validation để BA chọn (xem "Verification Rules — quy ước sinh" bên dưới). BA là người quyết định.
@@ -221,7 +251,7 @@ BA quyết **định nghĩa entity** (WHAT); `Owner` để `/spec-sad` cascade b
 
 Dùng `.claude/templates/main/feature/frd-template.md` làm skeleton, điền nội dung từ interview.
 
-**ID assignment** (luôn là create — frd mới): US `US-F{NNN}-001+`, Story AC `AC-F{NNN}-001+`, Feature AC `FAC-F{NNN}-001+` (counter độc lập với Story AC), VR `VR-F{NNN}-001+`. `NNN` = số của F-XXX. Flow đánh số từ 1.
+**ID assignment** (luôn là create — frd mới): US `US-F{NNN}-001+`, Story AC `AC-F{NNN}-001+`, Feature AC `FAC-F{NNN}-001+` (counter độc lập với Story AC), NFR `NFR-F{NNN}-001+` (counter độc lập), DM `DM-F{NNN}-001+` (counter độc lập, chỉ khi có Data & Migration), VR `VR-F{NNN}-001+`. `NNN` = số của F-XXX. Flow đánh số từ 1.
 
 **Frontmatter** frd mới: theo template, `status: draft`, `owner: BA`, `feature_id: F-XXX`, `template_version` copy từ `frd-template.md` (xem `conventions.md` §7 — chỉ set lúc CREATE; thay đổi sau qua `/spec-new` không đụng version).
 
@@ -306,7 +336,7 @@ Append **một** Change History entry vào `domain.md`, operation = `manual` (au
 
 (Nếu domain.md đang là skeleton create lần đầu thì entry vẫn `manual`/`update` — file đã được `/spec-prd` scaffold với operation `create` từ trước.) Atomic với 7a: domain cascade fail → rollback cả frd. `Owner` của entity do `/spec-sad`/`/spec-new` cascade bổ sung sau (HOW phase) qua `[MODIFY Owner]`.
 
-**7c. KHÔNG đụng gì khác.** Không đổi status của các feature *đã có* (frd tồn tại ≠ integration bắt đầu; marker "→ frd.md tồn tại" derive từ file existence). Không thêm component vào Index (chỉ candidate). Không carve component / không tự quyết `Owner` của shared entity. Không tạo crd/cdd/fdd/tsd. Không đụng sad.
+**7c. KHÔNG đụng gì khác.** Không đổi status của các feature *đã có* (frd tồn tại ≠ integration bắt đầu; marker "→ frd.md tồn tại" derive từ file existence). Không thêm component vào Index (chỉ candidate). Không carve component / không tự quyết `Owner` của shared entity. Không tạo crd/cdd/fdd/test-design. Không đụng sad.
 
 **7d. Thông báo kết quả:**
 
@@ -324,7 +354,7 @@ Append **một** Change History entry vào `domain.md`, operation = `manual` (au
   - VR-F{NNN}-{seq} — {field}
 
 Bước tiếp theo:
-  - /spec-tsd F-XXX  → QC bootstrap test spec từ frd này
+  - /spec-test-design F-XXX  → QC bootstrap test design từ frd này
   - /spec-new F-XXX  → DEV bắt đầu integration (frd sẽ được consume, crd/cdd sinh qua cascade)
   {nếu có candidate hoặc entity Owner TBD} - /spec-sad → architect chốt boundary component + gán Owner cho shared entity
 ```
@@ -355,6 +385,7 @@ Bước tiếp theo:
 
 ## Verification
 
+- [ ] **Pre-flight Git**: đã thông báo plan cho user; xác định đúng nhánh chính (hỏi nếu mơ hồ); working tree sạch; đã `checkout {main}` + `pull`; tạo nhánh làm việc mới off `{main}` trước khi author
 - [ ] `prd.md` tồn tại
 - [ ] **Single-feature gate**: nguồn liên quan đúng 1 feature; nếu >1 đã DỪNG và mô tả rõ lý do tách + redirect `/spec-prd`
 - [ ] **Create-only gate**: frd.md của feature mục tiêu CHƯA tồn tại; nếu đã có đã redirect `/spec-new`
@@ -362,12 +393,14 @@ Bước tiếp theo:
 - [ ] frd.md có đủ 7 core sections (luôn create mới); `Open Questions` chứa câu hỏi clarify + component candidate còn mở, hoặc đã xóa nếu rỗng
 - [ ] Frontmatter có `template_version` copy từ `frd-template.md`
 - [ ] Mỗi User Story có persona + priority + ít nhất 1 AC Given/When/Then
-- [ ] Feature AC dùng ID `FAC-F{NNN}-{seq}` (counter độc lập với `AC-F{NNN}`), Then đo được
+- [ ] Feature AC chỉ end-to-end (journey + consistency + integrity), ID `FAC-F{NNN}-{seq}` (counter độc lập với `AC-F{NNN}`), Then đo được; authz/access-control functional → AC/VR, không phải NFR
+- [ ] Non-Functional Requirements: heading luôn có (required-emptyable); nếu có item → ID `NFR-F{NNN}-{seq}`, tham chiếu `NFR-*` PRD nếu có thể, Then đo được
+- [ ] Data & Migration (required-emptyable): ID `DM-F{NNN}-{seq}`, Then đo được; không đụng migration → giữ heading, để trống
 - [ ] Verification Rules đã confirm với BA (không tự assert); không chứa regex/code/error message; semantic type
 - [ ] ID bắt đầu từ 001 (create mới)
 - [ ] Components Used reference C-XXX có sẵn; component mới ghi candidate + surface cho /spec-sad
 - [ ] Nếu register feature mới: prd Features có row [NEW] + Change History entry; status feature đã có KHÔNG đổi
 - [ ] Domain cascade (nếu có vocabulary mới, đã BA confirm): Glossary term ghi đủ định nghĩa; Shared Entity ghi đủ definition + attributes với `Owner: TBD` (KHÔNG tự gán C-XXX); domain.md có Change History entry operation = `manual`
-- [ ] KHÔNG tạo crd/cdd/fdd/tsd; KHÔNG carve component / gán Owner entity; KHÔNG đụng sad
+- [ ] KHÔNG tạo crd/cdd/fdd/test-design; KHÔNG carve component / gán Owner entity; KHÔNG đụng sad
 - [ ] Change History entry (frd) operation = `manual` (luôn `create`)
 - [ ] User đã confirm trước khi ghi file

package/skills/spec-new/SKILL.md

@@ -27,6 +27,31 @@ Tạo `spec.md` cho một integration mới trong `.specs/integrations/{NNN}-{sl
 
 ## Process
 
+### Bước 0 · Pre-flight: chuẩn bị nhánh Git (chạy TRƯỚC Bước 1)
+
+Mục tiêu: không bao giờ tạo spec/cascade ngay trên nhánh hiện tại của user (có thể là một nhánh đang làm dở) — luôn bắt đầu từ **nhánh chính mới nhất** rồi tách một **nhánh làm việc riêng** cho integration.
+
+**Trước tiên, thông báo cho user toàn bộ việc Git skill sẽ làm** (để user biết trước, đúng tinh thần "agent làm các việc này"):
+
+> Trước khi tạo spec, mình sẽ:
+> 1. Pull code mới nhất từ nhánh chính (`{main}`).
+> 2. Tạo & checkout một nhánh mới tách từ `{main}` để làm integration này.
+>
+> (Bạn đang ở nhánh `{current}`.)
+
+**1. Xác định nhánh chính (`{main}`).**
+- Không phải git repo → bỏ qua toàn bộ pre-flight, note cho user rồi tiếp Bước 1.
+- Có nhánh `develop` → mặc định `{main}` = `develop`. Không có `develop` nhưng có `main`/`master` → dùng nó.
+- Mơ hồ (tồn tại cả `develop` lẫn `main`, hoặc remote default khác) → **hỏi user** nhánh nào là nhánh chính. KHÔNG đoán.
+
+**2. Kiểm tra working tree sạch.** `git status` còn thay đổi chưa commit → **DỪNG**, báo user commit/stash trước. KHÔNG tự ý stash/discard.
+
+**3. Checkout + pull nhánh chính:** `git checkout {main}` rồi `git pull`. Pull fail (conflict, không có upstream…) → **DỪNG**, surface lỗi cụ thể, để user xử lý.
+
+**4. Tạo nhánh làm việc mới off `{main}`.** Cần `{NNN}-{slug}` để đặt tên → thực hiện **ngay sau khi xác định slug + số thứ tự ở Bước 4** (xem nhắc ở đó): đề xuất `git checkout -b feat/{NNN}-{slug}`, cho user sửa tên rồi tạo. Mọi việc ghi spec + auto-cascade từ Bước 5/7 diễn ra trên nhánh này.
+
+---
+
 ### Bước 1: Xác định input
 
 **Nếu có ARGUMENT** → đây là raw requirement, chuyển sang Bước 2.
@@ -66,11 +91,13 @@ Sections hiện có:
 
   [1] Overview
   [2] User Flows
-  [3] Feature-level Acceptance Criteria
-  [4] User Stories
-  [5] Verification Rules
-  [6] Scope (In Scope / Out of Scope)
-  [7] Dependencies (Feature Dependencies + Components Used)
+  [3] Feature Acceptance Criteria (end-to-end)
+  [4] Non-Functional Requirements
+  [5] Data & Migration (required-emptyable)
+  [6] User Stories
+  [7] Verification Rules
+  [8] Scope (In Scope / Out of Scope)
+  [9] Dependencies (Feature Dependencies + Components Used)
   [A] All — viết lại toàn bộ từ đầu
   [S] Lên spec từ frd.md hiện tại — frd.md đã đầy đủ, không cần chỉnh
 
@@ -156,6 +183,8 @@ Xác định số thứ tự (`NNN`):
 
 Output path: `.specs/integrations/{NNN}-{slug}/spec.md`
 
+**Tạo nhánh làm việc** (Pre-flight bước 4) — giờ đã có `{NNN}-{slug}`: `git checkout -b feat/{NNN}-{slug}` off `{main}` (đề xuất tên, cho user sửa). Bỏ qua nếu không phải git repo (pre-flight đã note).
+
 ---
 
 ### Bước 5: Write — sinh draft
@@ -214,7 +243,7 @@ Template gốc là single source of truth cho format. KHÔNG duplicate skeleton
 
 Liệt kê **tất cả** features liên quan đến integration và đánh giá từng cái. Không được bỏ qua feature nào — kể cả feature `Done` vẫn phải đánh giá xem spec mới có làm thay đổi scope không.
 
-- Operation=create khi frd.md chưa tồn tại → nội dung đầy đủ tất cả 7 sections: Overview, User Flows, Feature-level AC, User Stories, Verification Rules, Scope, Dependencies.
+- Operation=create khi frd.md chưa tồn tại → nội dung đầy đủ các section: Overview, User Flows, Feature Acceptance Criteria (end-to-end), Non-Functional Requirements (required-emptyable), Data & Migration (required-emptyable), User Stories, Verification Rules, Scope, Dependencies.
 - Operation=update khi frd.md đã tồn tại → hỏi user chọn section cần update:
 
 ```
@@ -223,11 +252,13 @@ Sections hiện có:
 
   [1] Overview
   [2] User Flows
-  [3] Feature-level Acceptance Criteria
-  [4] User Stories
-  [5] Verification Rules
-  [6] Scope (In Scope / Out of Scope)
-  [7] Dependencies (Feature Dependencies + Components Used)
+  [3] Feature Acceptance Criteria (end-to-end)
+  [4] Non-Functional Requirements
+  [5] Data & Migration (required-emptyable)
+  [6] User Stories
+  [7] Verification Rules
+  [8] Scope (In Scope / Out of Scope)
+  [9] Dependencies (Feature Dependencies + Components Used)
   [A] All — viết lại toàn bộ từ đầu
 
 Chọn section cần cập nhật (có thể chọn nhiều, ví dụ: 2 3):
@@ -429,6 +460,7 @@ Bước tiếp theo:
 
 Trước khi user confirm (Bước 6), kiểm tra:
 
+- [ ] **Pre-flight Git**: đã thông báo plan cho user; xác định đúng nhánh chính (hỏi nếu mơ hồ); working tree sạch; đã `checkout {main}` + `pull`; tạo nhánh làm việc mới off `{main}` trước khi cascade
 - [ ] Problem Statement từ góc nhìn user/business, không mention tech
 - [ ] Mỗi Acceptance Criterion dùng cú pháp GIVEN / WHEN / THEN, có thể test được
 - [ ] Out of Scope có ít nhất 1 item