@edupia-tutor/spec-driven-docs 0.14.7 → 0.14.9

package/commands/generate-bdd.md

@@ -401,7 +401,20 @@ Sau khi hoàn thành tất cả các bước, bạn đã nạp:
 Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 
-> **Proposal của tester (input tuỳ chọn):** trước khi sinh, kiểm tra `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm các scenario mà tester đề xuất qua `/propose-scenario` ứng với AC của UC này. Đưa vào những cái PO/Dev đã chấp nhận — rồi draft của tester được xoá/lưu trữ khỏi `feedback/`. Bỏ qua nếu folder rỗng.
+> **Proposal của tester (input tuỳ chọn):** trước khi sinh, quét `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm `{UC-ID}-*.md`. Với mỗi proposal:
+> - `Status: accepted` (PO/Dev đã duyệt) → chèn scenario vào `.feature` của UC (giữ `@trace`), rồi **lưu trữ**: chuyển file sang `{paths.bdd_proposals_dir}/archived/` + đặt `Status: incorporated`, và **commit + push** spec repo để gỡ khỏi feedback chung.
+> - `Status: proposed`/`rejected` (hoặc thiếu `Status`) → **bỏ qua**, để nguyên cho PO/Dev xử lý (KHÔNG tự đoán, KHÔNG tự đưa vào).
+> Bỏ qua sạch nếu folder rỗng.
+
+---
+
+## Sub-Agent Mode — dùng state từ payload *(nếu `_agent_mode`)*
+
+*Chỉ khi Gate Step 0 phát hiện `_agent_mode: true` (đang chạy như sub-agent do orchestration spawn).* Orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec **một lần**; sub-agent KHÔNG lặp lại:
+- `active_platform` = `payload.active_platform` → **bỏ qua** Platform Selection / Service Detection.
+- `design_coverage` = `payload.design_coverage` → **bỏ qua** "Design Spec — Gate & Load"; nếu rỗng thì chỉ phủ Wireframe PRD.
+- **Bỏ qua** Guard "PRD đã duyệt" + Guard Design-Spec bên dưới (orchestrator đã kiểm).
+- Đi thẳng tới UC Decomposition + Generate cho `payload.uc_id`, dùng `design_coverage` để phủ Screen States + AC-UI.
 
 ---
 
@@ -609,6 +622,41 @@ Chỉ cần kiểm tra trạng thái đã phân giải:
 
 ---
 
+## Design Spec — Gate & Load (chỉ FE/App)
+
+*Chỉ chạy khi target platform là FE/App — spec mode: `active_platform ∈ {web, app, app-ios, app-android}`; umbrella mode: `active_module` là module FE/App (react/nextjs/vue/nuxt/angular/flutter/react-native/ios-swiftui/android-compose). Bỏ qua HOÀN TOÀN với `system` và backend/brownfield.*
+
+**1. Định vị design-spec của platform:**
+`{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
+- `app-ios`/`app-android` không có bản riêng → fallback bản `-app-`.
+
+**2. Guard — sign-off & độ tươi (cảnh báo MỀM, đồng bộ Guard PRD — không chặn cứng):**
+Đọc `| **Status** |` và `| **Built from PRD** |` từ Metadata design-spec.
+- Không tìm thấy file, HOẶC `Status ≠ approved`, HOẶC design-spec còn màn ❌ Missing, HOẶC `Built from PRD` ≠ `| **Version** |` của PRD hiện tại (design-spec **lỗi thời** so với PRD) → CHECKPOINT:
+  ```
+  ⚠️  Design Spec cho {active_platform} chưa sẵn sàng (Status: {status} / không có / còn màn thiếu Figma / lỗi thời: dựng từ PRD v{old}, PRD giờ v{new}).
+     BDD FE/App nên sinh từ design-spec đã approved & cập nhật để phủ đúng Screen States + AC-UI.
+     Khuyến nghị: hoàn tất / cập nhật design-spec (chạy lại /generate-design-spec nếu PRD đã đổi) rồi mới sinh BDD.
+     Vẫn sinh BDD bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y. Nếu Y mà KHÔNG có design-spec → bỏ qua bước 3 (chỉ phủ Wireframe PRD §4b).
+- `Status: approved` VÀ `Built from PRD` khớp PRD hiện tại → nạp design-spec, sang bước 2.5.
+
+**2.5. Sanity-scan nội dung design-spec** (lớp soi độc lập — D1; soi nhanh ngay tại chỗ đã mở file, trước khi dùng):
+Quét tìm cờ đỏ; nếu có → **cảnh báo mềm** (liệt kê + hỏi "Vẫn dùng design-spec này? (Y/N)"):
+- Màn nào thiếu state `loading`/`error`/`empty`.
+- AC-UI nào mơ hồ, không testable ("looks good" / "đẹp" / không pass-fail rõ).
+- Component còn `[NEW]` / `[TODO]` (chưa chốt với designer).
+- Còn `❌ Missing` frame (lẽ ra Status đã `draft` — approved mà vẫn Missing là bất thường).
+Bắt lỗi design-spec **ngay trước khi nó lan xuống BDD**. Chọn N → quay lại hoàn thiện design-spec; chọn Y → sang bước 3.
+
+**3. Trích coverage từ design-spec** (lưu thành `design_coverage`, dùng ở UC Decomposition + Coverage Matrix):
+- **Screen States** ≠ `default` cho mỗi màn: `loading`, `error`, `empty`, `success` (cái nào có).
+- **AC-UI behavioral**: giữ AC-UI mà cột `Verified by` là **PO/QA** và mô tả outcome quan sát được (lỗi + đường khôi phục, empty state + CTA, gesture điều hướng, có loading state). **LOẠI AC-UI visual thuần** (khớp Figma trong dung sai, tương phản WCAG, màu/pixel/animation — thường `Verified by: Designer`): Designer/QA review riêng, KHÔNG đưa vào Gherkin (giữ R3/R5/R6).
+- **Dedup**: nếu một Screen State / AC-UI đã trùng một AC nghiệp vụ của PRD → không tạo SC mới, chỉ ghi nhận đã phủ.
+
+---
+
 ## Orchestration Check
 
 *Bỏ qua section này nếu đã ở sub-agent mode (Step 0 của Gate đã kích hoạt).*
@@ -655,7 +703,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 - So với version PRD hiện tại.
 - Nếu **giống** → hỏi: "BDD đã sinh từ PRD v{version}. Gen lại? (Y/N)"
 - Nếu **khác** (PRD đã cập nhật):
-  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
+  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có. **Nếu `@trace.prd_version` của BDD CŨ HƠN row cũ nhất còn trong bảng** (lịch sử đã bị cắt sang `changelog/`) → không thấy đủ diff → **khuyến nghị F** (gen lại toàn bộ), đừng tin Y một phần.
   2. Hiện CHECKPOINT:
      ```
      ⚠️  Phát hiện PRD version drift
@@ -670,7 +718,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
        F — gen lại toàn bộ scenario
        N — huỷ
      ```
-  3. Tiếp tục theo lựa chọn của người dùng.
+  3. Tiếp tục theo lựa chọn của người dùng. **Nếu changelog row không nêu rõ UC/AC/BR bị đổi (mơ hồ) → khuyến nghị F** (gen lại toàn bộ) thay vì Y, để khỏi sót scenario bị ảnh hưởng (lưới an toàn — không chắc đổi ở đâu thì quét rộng).
 
 ---
 
@@ -693,7 +741,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 
 | Check | Rule |
 |-------|------|
-| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe có ≥1 SC. |
+| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe (PRD §4b) có ≥1 SC. **FE/App: mỗi Screen State (≠default) và mỗi AC-UI behavioral của design-spec (`design_coverage`) cũng phải có ≥1 SC** — dedup với AC nghiệp vụ PRD; bỏ AC-UI visual thuần. |
 | C.2 PRD Traceability | Mỗi AC và mỗi BR (gồm từng bullet logic) map tới ≥1 SC. |
 | C.3 Business Dictionary | Dùng đúng canonical term từ business-dictionary.md. |
 | C.4 Banned Terms | 0 banned term trong file — grep trước khi gen. |
@@ -742,6 +790,8 @@ Với mỗi UC trong PRD, trình bày outline SC **trước khi sinh**:
   BRs covered: {TICKET-ID}-UC1-BR1, BR2, BR3
 ```
 
+*(FE/App: nếu đã nạp design-spec (xem "Design Spec — Gate & Load"), đưa Screen State ≠default (loading/error/empty) + AC-UI behavioral của `design_coverage` vào outline — dedup với AC nghiệp vụ, đừng tạo SC trùng.)*
+
 CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào không?" → **Chờ confirm trước khi sinh.**
 
 ---
@@ -787,6 +837,20 @@ Với mỗi UC, ghi vào path đã phân giải ở trên. Dùng từ vựng cho
 # Tham chiếu nhanh các term dùng trong feature này. Chi tiết SoT: business-dictionary.md
 # <Term 1>: <định nghĩa ngắn>
 # <Term 2>: <định nghĩa ngắn>
+#
+# --- Popup/Modal Lifecycle (tùy chọn — BẮT BUỘC nếu feature là popup/modal; Pre-merge yêu cầu) ---
+# - Open trigger:   <khi nào popup hiển thị, vd: click menu sidebar>
+# - Close trigger:  <khi nào popup đóng, vd: F5 / click X / ESC / navigate away>
+# - Refresh model:  <data refresh khi nào, vd: mỗi lần open (NO CACHE) / persisted / polling>
+# - State reset:    <state nào reset khi đóng/mở lại, vd: pagination, expand, dropdown selection>
+#
+# --- Display Logic Matrix (tùy chọn — BẮT BUỘC nếu display logic phụ thuộc ≥2 chiều; Pre-merge yêu cầu) ---
+# Liệt kê đủ ma trận N×M case + map mỗi case → SC. Tên SC theo pattern `<cấu trúc>: <outcome>` (KHÔNG dùng "(Case X)").
+# | # | Dim1 | Dim2 | Format hiển thị        | SC   |
+# |---|------|------|------------------------|------|
+# | 1 | 0    | 0    | `Tên hàng`             | SC{} |
+# | 2 | 0    | 1    | `Tên hàng (đơn vị)`    | SC{} |
+# | ... | ...  | ...  | ...                    | ...  |
 
 Feature: <Feature name>
   As a <role>
@@ -834,11 +898,7 @@ Feature: <Feature name>
     Given <state>
     When <action>
     Then <expected error handling>
-```
 
-### Coverage Matrix & Pre-merge Checklist *(thêm vào cuối mỗi file)*
-
-```gherkin
 # === PRD COVERAGE (C.1 + C.2) ===
 # AC mapping:
 #   AC1 (...) → SC1, SC2
@@ -851,17 +911,25 @@ Feature: <Feature name>
 #     [x] <action 1>  → SC1
 #     [x] <action 2>  → SC2
 #     [ ] <action 3>  → MISSING ← BLOCK MERGE
+# Design Spec coverage (chỉ FE/App — C.1 mở rộng; bỏ khối này nếu không nạp design-spec):
+#   Screen "<screen>": loading → SC?, error → SC?, empty → SC?
+#   AC-UI behavioral: AC-UI3 (lỗi+khôi phục) → SC?, AC-UI4 (empty CTA) → SC?
+#     (bỏ AC-UI visual thuần: AC-UI1 khớp Figma, AC-UI5 WCAG — Designer/QA review riêng)
 
 # === PRE-MERGE CHECKLIST ===
 # - [ ] Mỗi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
 # - [ ] Coverage Matrix: 0 dòng MISSING (C.1)
+# - [ ] FE/App: mỗi Screen State (≠default) + AC-UI behavioral của design-spec có ≥1 SC (C.1 mở rộng)
 # - [ ] Mỗi AC/BR map tới ≥1 SC (C.2)
 # - [ ] 0 banned term (C.4) — grep file trước khi merge
 # - [ ] Feature ≥3 SC có NHÓM grouping theo business theme (C.5)
 # - [ ] Nếu popup/modal: khai báo Popup/Modal Lifecycle trong BUSINESS DEFINITION
 # - [ ] Nếu display logic ≥2 chiều: Display Logic Matrix trong BUSINESS DEFINITION
+
 ```
 
+*(Template `.feature` là **single-source** ở `templates/feature.template` — sửa file đó để đổi cấu trúc mọi `.feature` sinh ra. Coverage Matrix + Pre-merge Checklist nằm ở **cuối** template, thêm vào cuối mỗi file.)*
+
 ---
 
 ## Write Trace State

package/commands/generate-bdd.tmpl

@@ -6,7 +6,20 @@
 ## Context
 {{include:steps/context-loader.md}}
 
-> **Proposal của tester (input tuỳ chọn):** trước khi sinh, kiểm tra `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm các scenario mà tester đề xuất qua `/propose-scenario` ứng với AC của UC này. Đưa vào những cái PO/Dev đã chấp nhận — rồi draft của tester được xoá/lưu trữ khỏi `feedback/`. Bỏ qua nếu folder rỗng.
+> **Proposal của tester (input tuỳ chọn):** trước khi sinh, quét `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm `{UC-ID}-*.md`. Với mỗi proposal:
+> - `Status: accepted` (PO/Dev đã duyệt) → chèn scenario vào `.feature` của UC (giữ `@trace`), rồi **lưu trữ**: chuyển file sang `{paths.bdd_proposals_dir}/archived/` + đặt `Status: incorporated`, và **commit + push** spec repo để gỡ khỏi feedback chung.
+> - `Status: proposed`/`rejected` (hoặc thiếu `Status`) → **bỏ qua**, để nguyên cho PO/Dev xử lý (KHÔNG tự đoán, KHÔNG tự đưa vào).
+> Bỏ qua sạch nếu folder rỗng.
+
+---
+
+## Sub-Agent Mode — dùng state từ payload *(nếu `_agent_mode`)*
+
+*Chỉ khi Gate Step 0 phát hiện `_agent_mode: true` (đang chạy như sub-agent do orchestration spawn).* Orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec **một lần**; sub-agent KHÔNG lặp lại:
+- `active_platform` = `payload.active_platform` → **bỏ qua** Platform Selection / Service Detection.
+- `design_coverage` = `payload.design_coverage` → **bỏ qua** "Design Spec — Gate & Load"; nếu rỗng thì chỉ phủ Wireframe PRD.
+- **Bỏ qua** Guard "PRD đã duyệt" + Guard Design-Spec bên dưới (orchestrator đã kiểm).
+- Đi thẳng tới UC Decomposition + Generate cho `payload.uc_id`, dùng `design_coverage` để phủ Screen States + AC-UI.
 
 ---
 
@@ -214,6 +227,41 @@ Chỉ cần kiểm tra trạng thái đã phân giải:
 
 ---
 
+## Design Spec — Gate & Load (chỉ FE/App)
+
+*Chỉ chạy khi target platform là FE/App — spec mode: `active_platform ∈ {web, app, app-ios, app-android}`; umbrella mode: `active_module` là module FE/App (react/nextjs/vue/nuxt/angular/flutter/react-native/ios-swiftui/android-compose). Bỏ qua HOÀN TOÀN với `system` và backend/brownfield.*
+
+**1. Định vị design-spec của platform:**
+`{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
+- `app-ios`/`app-android` không có bản riêng → fallback bản `-app-`.
+
+**2. Guard — sign-off & độ tươi (cảnh báo MỀM, đồng bộ Guard PRD — không chặn cứng):**
+Đọc `| **Status** |` và `| **Built from PRD** |` từ Metadata design-spec.
+- Không tìm thấy file, HOẶC `Status ≠ approved`, HOẶC design-spec còn màn ❌ Missing, HOẶC `Built from PRD` ≠ `| **Version** |` của PRD hiện tại (design-spec **lỗi thời** so với PRD) → CHECKPOINT:
+  ```
+  ⚠️  Design Spec cho {active_platform} chưa sẵn sàng (Status: {status} / không có / còn màn thiếu Figma / lỗi thời: dựng từ PRD v{old}, PRD giờ v{new}).
+     BDD FE/App nên sinh từ design-spec đã approved & cập nhật để phủ đúng Screen States + AC-UI.
+     Khuyến nghị: hoàn tất / cập nhật design-spec (chạy lại /generate-design-spec nếu PRD đã đổi) rồi mới sinh BDD.
+     Vẫn sinh BDD bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y. Nếu Y mà KHÔNG có design-spec → bỏ qua bước 3 (chỉ phủ Wireframe PRD §4b).
+- `Status: approved` VÀ `Built from PRD` khớp PRD hiện tại → nạp design-spec, sang bước 2.5.
+
+**2.5. Sanity-scan nội dung design-spec** (lớp soi độc lập — D1; soi nhanh ngay tại chỗ đã mở file, trước khi dùng):
+Quét tìm cờ đỏ; nếu có → **cảnh báo mềm** (liệt kê + hỏi "Vẫn dùng design-spec này? (Y/N)"):
+- Màn nào thiếu state `loading`/`error`/`empty`.
+- AC-UI nào mơ hồ, không testable ("looks good" / "đẹp" / không pass-fail rõ).
+- Component còn `[NEW]` / `[TODO]` (chưa chốt với designer).
+- Còn `❌ Missing` frame (lẽ ra Status đã `draft` — approved mà vẫn Missing là bất thường).
+Bắt lỗi design-spec **ngay trước khi nó lan xuống BDD**. Chọn N → quay lại hoàn thiện design-spec; chọn Y → sang bước 3.
+
+**3. Trích coverage từ design-spec** (lưu thành `design_coverage`, dùng ở UC Decomposition + Coverage Matrix):
+- **Screen States** ≠ `default` cho mỗi màn: `loading`, `error`, `empty`, `success` (cái nào có).
+- **AC-UI behavioral**: giữ AC-UI mà cột `Verified by` là **PO/QA** và mô tả outcome quan sát được (lỗi + đường khôi phục, empty state + CTA, gesture điều hướng, có loading state). **LOẠI AC-UI visual thuần** (khớp Figma trong dung sai, tương phản WCAG, màu/pixel/animation — thường `Verified by: Designer`): Designer/QA review riêng, KHÔNG đưa vào Gherkin (giữ R3/R5/R6).
+- **Dedup**: nếu một Screen State / AC-UI đã trùng một AC nghiệp vụ của PRD → không tạo SC mới, chỉ ghi nhận đã phủ.
+
+---
+
 ## Orchestration Check
 
 *Bỏ qua section này nếu đã ở sub-agent mode (Step 0 của Gate đã kích hoạt).*
@@ -260,7 +308,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 - So với version PRD hiện tại.
 - Nếu **giống** → hỏi: "BDD đã sinh từ PRD v{version}. Gen lại? (Y/N)"
 - Nếu **khác** (PRD đã cập nhật):
-  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
+  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có. **Nếu `@trace.prd_version` của BDD CŨ HƠN row cũ nhất còn trong bảng** (lịch sử đã bị cắt sang `changelog/`) → không thấy đủ diff → **khuyến nghị F** (gen lại toàn bộ), đừng tin Y một phần.
   2. Hiện CHECKPOINT:
      ```
      ⚠️  Phát hiện PRD version drift
@@ -275,7 +323,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
        F — gen lại toàn bộ scenario
        N — huỷ
      ```
-  3. Tiếp tục theo lựa chọn của người dùng.
+  3. Tiếp tục theo lựa chọn của người dùng. **Nếu changelog row không nêu rõ UC/AC/BR bị đổi (mơ hồ) → khuyến nghị F** (gen lại toàn bộ) thay vì Y, để khỏi sót scenario bị ảnh hưởng (lưới an toàn — không chắc đổi ở đâu thì quét rộng).
 
 ---
 
@@ -298,7 +346,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 
 | Check | Rule |
 |-------|------|
-| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe có ≥1 SC. |
+| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe (PRD §4b) có ≥1 SC. **FE/App: mỗi Screen State (≠default) và mỗi AC-UI behavioral của design-spec (`design_coverage`) cũng phải có ≥1 SC** — dedup với AC nghiệp vụ PRD; bỏ AC-UI visual thuần. |
 | C.2 PRD Traceability | Mỗi AC và mỗi BR (gồm từng bullet logic) map tới ≥1 SC. |
 | C.3 Business Dictionary | Dùng đúng canonical term từ business-dictionary.md. |
 | C.4 Banned Terms | 0 banned term trong file — grep trước khi gen. |
@@ -347,6 +395,8 @@ Với mỗi UC trong PRD, trình bày outline SC **trước khi sinh**:
   BRs covered: {TICKET-ID}-UC1-BR1, BR2, BR3
 ```
 
+*(FE/App: nếu đã nạp design-spec (xem "Design Spec — Gate & Load"), đưa Screen State ≠default (loading/error/empty) + AC-UI behavioral của `design_coverage` vào outline — dedup với AC nghiệp vụ, đừng tạo SC trùng.)*
+
 CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào không?" → **Chờ confirm trước khi sinh.**
 
 ---
@@ -360,112 +410,10 @@ CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào kh
 Với mỗi UC, ghi vào path đã phân giải ở trên. Dùng từ vựng cho active platform (từ Platform Selection hoặc Service Detection).
 
 ```gherkin
-# ============================================================
-# @trace.id: {TICKET-ID}-UC{N}
-# @trace.title: <Feature name>
-# @trace.revision: 1  ← field tĩnh; dùng @trace.bdd_version để theo dõi version (tăng bởi /review-context --fix hoặc --resume)
-# @trace.domain: <domain>
-# @trace.platform: {active_platform — web | app | system | (bỏ trong umbrella mode)}
-# @trace.service: {active_service — bỏ trong spec repo mode}
-# @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
-# @trace.status: draft
-# @trace.author: AI-generated
-# @trace.created_at: {YYYY-MM-DD}
-# @trace.prd: {TICKET-ID}
-# @trace.prd_version: {đọc từ metadata PRD "| **Version** |"}
-# @trace.bdd_version: {1.0 nếu gen mới; tăng 0.1 khi gen lại — vd 1.0 → 1.1}
-# @trace.business_rules: {TICKET-ID}-UC{N}-BR1, {TICKET-ID}-UC{N}-BR2
-# @trace.dataset: {domain}.testdata.yaml
-# ============================================================
-
-# === CONTEXT ===
-# Actor:     <vai trò thực hiện hành động, vd: Consumer, Staff, System>
-# Screens:   <các màn liên quan, vd: Cart → Confirm Order → Order Detail>
-# Entities:  <business entity, vd: Order, OrderItem, Consumer>
-# Pre-state: <state dùng chung trước khi vào các scenario>
-
-# === SCOPE ===
-# In:  <UC này phủ gì>
-# Out: <cái gì KHÔNG thuộc UC này — link tới UC/feature khác (R10)>
-
-# === BUSINESS DEFINITION ===
-# Tham chiếu nhanh các term dùng trong feature này. Chi tiết SoT: business-dictionary.md
-# <Term 1>: <định nghĩa ngắn>
-# <Term 2>: <định nghĩa ngắn>
-
-Feature: <Feature name>
-  As a <role>
-  I want to <action>
-  So that <business value>
-
-  Background:
-    Given <precondition dùng chung — dùng alias từ dataset, không phải ID kỹ thuật>
-
-  # ==========================================================
-  # NHÓM 1: <Business theme> (<BR refs>)
-  # ==========================================================
-
-  # Side-effects: <liệt kê ngắn các Then side-effect cần verify>
-  # @trace.scenario: {TICKET-ID}-UC{N}-SC1
-  # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
-  @happy
-  Scenario: <mô tả business outcome — dùng động từ chính xác: create/receive/assign/block>
-    Given <input state — alias từ dataset>
-    When <single action>
-    Then <main observable outcome>
-      And <side-effect 1 khai báo trong header>
-
-  # Side-effects: <...>
-  # @trace.scenario: {TICKET-ID}-UC{N}-SC2
-  # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
-  @happy @alternative
-  Scenario: <cùng theme NHÓM 1 nhưng path khác — vd: giá trị enum khác>
-    Given <state>
-    When <action>
-    Then <outcome>
-
-  # ==========================================================
-  # NHÓM 2: <Business theme 2> (<BR refs>)
-  # ==========================================================
-
-  # Side-effects: <...>
-  # @trace.scenario: {TICKET-ID}-UC{N}-SC3
-  # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR2
-  @edge
-  Scenario: <scenario boundary / error>
-    Given <state>
-    When <action>
-    Then <expected error handling>
+{{include:templates/feature.template}}
 ```
 
-### Coverage Matrix & Pre-merge Checklist *(thêm vào cuối mỗi file)*
-
-```gherkin
-# === PRD COVERAGE (C.1 + C.2) ===
-# AC mapping:
-#   AC1 (...) → SC1, SC2
-#   AC2 (...) → SC3
-# BR mapping (mỗi bullet PHẢI có ≥1 SC — C.2):
-#   {TICKET-ID}-UC{N}-BR1 (...) → SC1, SC2
-#   {TICKET-ID}-UC{N}-BR2 (...) → SC3
-# Wireframe mapping (mỗi component/action ≥1 SC — C.1):
-#   Screen "<screen name>":
-#     [x] <action 1>  → SC1
-#     [x] <action 2>  → SC2
-#     [ ] <action 3>  → MISSING ← BLOCK MERGE
-
-# === PRE-MERGE CHECKLIST ===
-# - [ ] Mỗi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
-# - [ ] Coverage Matrix: 0 dòng MISSING (C.1)
-# - [ ] Mỗi AC/BR map tới ≥1 SC (C.2)
-# - [ ] 0 banned term (C.4) — grep file trước khi merge
-# - [ ] Feature ≥3 SC có NHÓM grouping theo business theme (C.5)
-# - [ ] Nếu popup/modal: khai báo Popup/Modal Lifecycle trong BUSINESS DEFINITION
-# - [ ] Nếu display logic ≥2 chiều: Display Logic Matrix trong BUSINESS DEFINITION
-```
+*(Template `.feature` là **single-source** ở `templates/feature.template` — sửa file đó để đổi cấu trúc mọi `.feature` sinh ra. Coverage Matrix + Pre-merge Checklist nằm ở **cuối** template, thêm vào cuối mỗi file.)*
 
 ---
 

package/commands/generate-code.md

@@ -422,7 +422,24 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 1. Chỉ file `.feature` đã giới hạn scope
 2. Tech-doc tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (nếu tồn tại)
 3. CLAUDE.md §architecture + §coding_standards
-4. **(chỉ FE/App)** Design Spec tại `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (nếu tồn tại) — nguồn của màn hình, component inventory, và link Figma frame từng-màn.
+4. **(chỉ FE/App)** Design Spec — nạp qua **Guard** bên dưới (gate approved/độ-tươi + sanity), là nguồn của màn hình, component inventory, và link Figma frame từng-màn.
+
+---
+
+## Guard — BDD & Design Spec đã sẵn sàng chưa *(cảnh báo MỀM — đồng bộ generate-bdd)*
+
+**BDD (mọi platform) — DS1:** đọc `# @trace.status:` từ header `.feature` target.
+- `approved` → tiếp tục. Khác `approved` → CHECKPOINT mềm:
+  ```
+  ⚠️  BDD {UC-ID} đang @trace.status: {status} (chưa duyệt). Code sinh từ BDD chưa chốt có thể phải làm lại.
+     Vẫn sinh code bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y.
+
+**Design Spec (chỉ FE/App — `@trace.platform` = web/app) — DS2:** định vị `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{@trace.platform}-{slug}.md`, đọc `| **Status** |` + `| **Built from PRD** |`:
+- Không có file, HOẶC `Status ≠ approved`, HOẶC còn màn ❌ Missing, HOẶC `Built from PRD` ≠ `| **Version** |` PRD hiện tại (lỗi thời) → CHECKPOINT mềm (liệt kê lý do + "Vẫn dùng design-spec này? (Y/N)"). Nếu Y mà KHÔNG có design-spec → sinh UI từ BDD + Wireframe PRD (thiếu chi tiết visual).
+- **Sanity-scan** (như generate-bdd bước 2.5): màn thiếu state loading/error/empty, AC-UI không testable, component `[NEW]`/`[TODO]` chưa chốt, còn ❌ Missing frame → cảnh báo trong cùng CHECKPOINT.
+- `Status: approved` VÀ `Built from PRD` khớp PRD hiện tại VÀ sạch cờ đỏ → dùng làm nguồn màn hình / component / Figma.
 
 ---
 

package/commands/generate-code.tmpl

@@ -27,7 +27,24 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 1. Chỉ file `.feature` đã giới hạn scope
 2. Tech-doc tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (nếu tồn tại)
 3. CLAUDE.md §architecture + §coding_standards
-4. **(chỉ FE/App)** Design Spec tại `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (nếu tồn tại) — nguồn của màn hình, component inventory, và link Figma frame từng-màn.
+4. **(chỉ FE/App)** Design Spec — nạp qua **Guard** bên dưới (gate approved/độ-tươi + sanity), là nguồn của màn hình, component inventory, và link Figma frame từng-màn.
+
+---
+
+## Guard — BDD & Design Spec đã sẵn sàng chưa *(cảnh báo MỀM — đồng bộ generate-bdd)*
+
+**BDD (mọi platform) — DS1:** đọc `# @trace.status:` từ header `.feature` target.
+- `approved` → tiếp tục. Khác `approved` → CHECKPOINT mềm:
+  ```
+  ⚠️  BDD {UC-ID} đang @trace.status: {status} (chưa duyệt). Code sinh từ BDD chưa chốt có thể phải làm lại.
+     Vẫn sinh code bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y.
+
+**Design Spec (chỉ FE/App — `@trace.platform` = web/app) — DS2:** định vị `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{@trace.platform}-{slug}.md`, đọc `| **Status** |` + `| **Built from PRD** |`:
+- Không có file, HOẶC `Status ≠ approved`, HOẶC còn màn ❌ Missing, HOẶC `Built from PRD` ≠ `| **Version** |` PRD hiện tại (lỗi thời) → CHECKPOINT mềm (liệt kê lý do + "Vẫn dùng design-spec này? (Y/N)"). Nếu Y mà KHÔNG có design-spec → sinh UI từ BDD + Wireframe PRD (thiếu chi tiết visual).
+- **Sanity-scan** (như generate-bdd bước 2.5): màn thiếu state loading/error/empty, AC-UI không testable, component `[NEW]`/`[TODO]` chưa chốt, còn ❌ Missing frame → cảnh báo trong cùng CHECKPOINT.
+- `Status: approved` VÀ `Built from PRD` khớp PRD hiện tại VÀ sạch cờ đỏ → dùng làm nguồn màn hình / component / Figma.
 
 ---
 

package/commands/generate-design-spec.md

@@ -455,6 +455,30 @@ Dùng `active_module` và `platform_type` suy ra từ context loading:
 
 ---
 
+## Version Check (PRD drift)
+
+Trước khi sinh, kiểm tra design-spec đã tồn tại cho platform này:
+`{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
+Đọc `| **Version** |` hiện tại của PRD từ Metadata (vd `1.3`).
+
+- **Không tồn tại** → sinh mới; ghi `| **Built from PRD** | v{prd_version hiện tại} |`.
+- **Tồn tại** → đọc row `| **Built from PRD** |` của nó, so với `| **Version** |` PRD hiện tại:
+  - **Bằng nhau** → hỏi: "Design Spec đã dựng từ PRD v{x}. Sinh lại? (Y/N)".
+  - **Khác** (PRD đã đổi) → CHECKPOINT drift:
+    ```
+    ⚠️  Phát hiện PRD version drift
+    Design Spec dựng từ PRD v{old}; PRD giờ ở v{new}.
+    Thay đổi kể từ v{old} (đọc # Change Log của PRD):
+      {changelog rows}
+    Options:
+      Y — cập nhật phần ảnh hưởng (màn / flow đổi)
+      F — sinh lại toàn bộ
+      N — huỷ
+    ```
+- Khi sinh / sinh lại → cập nhật `| **Built from PRD** | v{prd_version hiện tại} |`, bump `| **Version** |` Design Spec, **reset `| **Status** | draft |`** (design đổi → sign-off lại), thêm row Changelog.
+
+---
+
 ## Screen Discovery
 
 Từ Section 4 của PRD (User Flow + Wireframe), trích xuất mọi tên screen / page / modal được nhắc tới.
@@ -516,8 +540,8 @@ Nếu một màn chưa có design, gõ  none  cho màn đó.
 
 **Gate bắt buộc (không abort — sinh ra draft):**
 - Nếu **bất kỳ** màn nào ❌ Missing → spec được sinh dưới dạng **draft** với các màn đó
-  được gắn cờ, nhưng `Status` vẫn là `draft` và **sign-off / `/generate-bdd` bị chặn** cho tới khi
-  mọi màn có link frame đọc được, đã fetch. Ghi `missing_frames = [screens]`.
+  được gắn cờ, `Status` giữ `draft` cho tới khi mọi màn có link frame đọc được, đã fetch.
+  `/generate-bdd` FE/App sẽ **cảnh báo mềm** (đồng bộ Guard PRD) nếu sinh BDD khi design-spec chưa `approved`. Ghi `missing_frames = [screens]`.
 - Thêm một AI Assumption cho mỗi màn thiếu: "Không có Figma frame đọc được cho {screen} — spec
   của màn này chỉ là text và không được sign off cho tới khi thêm link `node-id`."
 
@@ -603,6 +627,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}](../{TICKET-ID}-{prd-slug}.md)                   |
+| **Built from PRD** | v{prd_version — `\| **Version** \|` của PRD lúc sinh; dùng phát hiện drift} |
 | **Figma**          | {figma_url — link file feature} ({linked}/{N} frame đã link)  |
 | **Author**         | {tên PO hoặc "AI-assisted"}                                   |
 | **Created**        | {YYYY-MM-DD}                                                  |
@@ -830,7 +855,7 @@ Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink
 
 ---
 
-## Quality Checklist *(kiểm tra trước khi ghi)*
+## Self-Review Gate *(cổng tự-rà — bắt buộc chạy trước khi ghi)*
 
 - [ ] Mọi màn trong Screen Inventory có Screen Spec đầy đủ ở Section 2
 - [ ] Mọi màn có tối thiểu các state: default, loading, error
@@ -841,7 +866,12 @@ Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink
 - [ ] Link cross-reference Business PRD là relative path hợp lệ
 - [ ] Mọi màn có link Figma frame node-level (`?node-id=`) — và các màn có link đã được fetch qua Figma MCP và dùng để ground spec
 - [ ] Mỗi màn ❌ Missing được gắn cờ trong spec (`> [DRAFT — no Figma frame...]`), liệt kê trong Figma Summary, và có một AI Assumption
-- [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` và Output bên dưới chặn `/generate-bdd`
+- [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` (generate-bdd FE/App cảnh báo mềm, không chặn cứng)
+
+> **Đây là CỔNG, không phải nhắc nhở:** chạy từng mục trên TRƯỚC khi ghi file. Mục nào **FAIL** → **bắt buộc**:
+> 1. ghi một dòng `⚠️ {mục thiếu — màn/section cụ thể}` vào section **"Giả định AI"** của file (đừng để lọt im lặng), VÀ
+> 2. giữ `| **Status** | draft |` (chưa đủ điều kiện để PO+Designer sign-off `approved`).
+> KHÔNG xuất design-spec như "hoàn chỉnh" khi còn mục fail chưa gắn cờ.
 
 ---
 
@@ -967,7 +997,7 @@ Next   : Chia sẻ với Designer → PO + Designer sign-off (Status: approved)
 Status : ⚠️ Warnings — {count} màn không có link Figma frame đọc được: {missing_frames ngăn cách bởi dấu phẩy}
 Output Artifacts:
   created {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0, draft)
-Next   : 🔒 Sign-off & /generate-bdd bị CHẶN cho tới khi mọi màn có link Figma node-id.
+Next   : 🔒 Khuyến nghị hoàn tất sign-off trước (đủ link Figma node-id); /generate-bdd FE/App sẽ cảnh báo nếu design-spec chưa approved.
          1. Trong Figma: chọn mỗi frame còn thiếu → chuột phải → Copy link to selection
          2. Chạy lại /generate-design-spec {prd-file} → AI fetch & ground các frame mới
 ```

package/commands/generate-design-spec.tmpl

@@ -60,6 +60,30 @@ Dùng `active_module` và `platform_type` suy ra từ context loading:
 
 ---
 
+## Version Check (PRD drift)
+
+Trước khi sinh, kiểm tra design-spec đã tồn tại cho platform này:
+`{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
+Đọc `| **Version** |` hiện tại của PRD từ Metadata (vd `1.3`).
+
+- **Không tồn tại** → sinh mới; ghi `| **Built from PRD** | v{prd_version hiện tại} |`.
+- **Tồn tại** → đọc row `| **Built from PRD** |` của nó, so với `| **Version** |` PRD hiện tại:
+  - **Bằng nhau** → hỏi: "Design Spec đã dựng từ PRD v{x}. Sinh lại? (Y/N)".
+  - **Khác** (PRD đã đổi) → CHECKPOINT drift:
+    ```
+    ⚠️  Phát hiện PRD version drift
+    Design Spec dựng từ PRD v{old}; PRD giờ ở v{new}.
+    Thay đổi kể từ v{old} (đọc # Change Log của PRD):
+      {changelog rows}
+    Options:
+      Y — cập nhật phần ảnh hưởng (màn / flow đổi)
+      F — sinh lại toàn bộ
+      N — huỷ
+    ```
+- Khi sinh / sinh lại → cập nhật `| **Built from PRD** | v{prd_version hiện tại} |`, bump `| **Version** |` Design Spec, **reset `| **Status** | draft |`** (design đổi → sign-off lại), thêm row Changelog.
+
+---
+
 ## Screen Discovery
 
 Từ Section 4 của PRD (User Flow + Wireframe), trích xuất mọi tên screen / page / modal được nhắc tới.
@@ -121,8 +145,8 @@ Nếu một màn chưa có design, gõ  none  cho màn đó.
 
 **Gate bắt buộc (không abort — sinh ra draft):**
 - Nếu **bất kỳ** màn nào ❌ Missing → spec được sinh dưới dạng **draft** với các màn đó
-  được gắn cờ, nhưng `Status` vẫn là `draft` và **sign-off / `/generate-bdd` bị chặn** cho tới khi
-  mọi màn có link frame đọc được, đã fetch. Ghi `missing_frames = [screens]`.
+  được gắn cờ, `Status` giữ `draft` cho tới khi mọi màn có link frame đọc được, đã fetch.
+  `/generate-bdd` FE/App sẽ **cảnh báo mềm** (đồng bộ Guard PRD) nếu sinh BDD khi design-spec chưa `approved`. Ghi `missing_frames = [screens]`.
 - Thêm một AI Assumption cho mỗi màn thiếu: "Không có Figma frame đọc được cho {screen} — spec
   của màn này chỉ là text và không được sign off cho tới khi thêm link `node-id`."
 
@@ -208,6 +232,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}](../{TICKET-ID}-{prd-slug}.md)                   |
+| **Built from PRD** | v{prd_version — `\| **Version** \|` của PRD lúc sinh; dùng phát hiện drift} |
 | **Figma**          | {figma_url — link file feature} ({linked}/{N} frame đã link)  |
 | **Author**         | {tên PO hoặc "AI-assisted"}                                   |
 | **Created**        | {YYYY-MM-DD}                                                  |
@@ -435,7 +460,7 @@ Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink
 
 ---
 
-## Quality Checklist *(kiểm tra trước khi ghi)*
+## Self-Review Gate *(cổng tự-rà — bắt buộc chạy trước khi ghi)*
 
 - [ ] Mọi màn trong Screen Inventory có Screen Spec đầy đủ ở Section 2
 - [ ] Mọi màn có tối thiểu các state: default, loading, error
@@ -446,7 +471,12 @@ Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink
 - [ ] Link cross-reference Business PRD là relative path hợp lệ
 - [ ] Mọi màn có link Figma frame node-level (`?node-id=`) — và các màn có link đã được fetch qua Figma MCP và dùng để ground spec
 - [ ] Mỗi màn ❌ Missing được gắn cờ trong spec (`> [DRAFT — no Figma frame...]`), liệt kê trong Figma Summary, và có một AI Assumption
-- [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` và Output bên dưới chặn `/generate-bdd`
+- [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` (generate-bdd FE/App cảnh báo mềm, không chặn cứng)
+
+> **Đây là CỔNG, không phải nhắc nhở:** chạy từng mục trên TRƯỚC khi ghi file. Mục nào **FAIL** → **bắt buộc**:
+> 1. ghi một dòng `⚠️ {mục thiếu — màn/section cụ thể}` vào section **"Giả định AI"** của file (đừng để lọt im lặng), VÀ
+> 2. giữ `| **Status** | draft |` (chưa đủ điều kiện để PO+Designer sign-off `approved`).
+> KHÔNG xuất design-spec như "hoàn chỉnh" khi còn mục fail chưa gắn cờ.
 
 ---
 
@@ -472,7 +502,7 @@ Next   : Chia sẻ với Designer → PO + Designer sign-off (Status: approved)
 Status : ⚠️ Warnings — {count} màn không có link Figma frame đọc được: {missing_frames ngăn cách bởi dấu phẩy}
 Output Artifacts:
   created {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0, draft)
-Next   : 🔒 Sign-off & /generate-bdd bị CHẶN cho tới khi mọi màn có link Figma node-id.
+Next   : 🔒 Khuyến nghị hoàn tất sign-off trước (đủ link Figma node-id); /generate-bdd FE/App sẽ cảnh báo nếu design-spec chưa approved.
          1. Trong Figma: chọn mỗi frame còn thiếu → chuột phải → Copy link to selection
          2. Chạy lại /generate-design-spec {prd-file} → AI fetch & ground các frame mới
 ```