@edupia-tutor/spec-driven-docs 0.14.6 → 0.14.8

package/bin/index.js

@@ -266,7 +266,7 @@ if (isInit) {
         `  trace_dir:            ".trace"`,
         ``,
         `# Domain → service submodule routing.`,
-        `# Each key must match @trace.domain in your PRD files.`,
+        `# Each key must match the PRD's Domain (Metadata row) / folder path segment.`,
         `services:`,
         servicesBlock,
         ``,

package/commands/debug.md

@@ -672,7 +672,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/commands/define-product.md

@@ -670,7 +670,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/commands/dev-gen-test.md

@@ -960,7 +960,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/commands/dev-run-test.md

@@ -684,7 +684,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/commands/dev-smoke-test.md

@@ -658,7 +658,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/commands/fix-bug.md

@@ -693,7 +693,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/commands/generate-bdd.md

@@ -401,7 +401,34 @@ 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.
+
+---
+
+## Guard — PRD đã duyệt chưa
+
+Đọc `| **Status** |` từ bảng Metadata của PRD nguồn:
+- `Status: approved` → tiếp tục bình thường.
+- `Status: draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép prototype):
+  ```
+  ⚠️  PRD đang ở Status: {status} (chưa duyệt). BDD sinh từ PRD chưa chốt có thể phải làm lại.
+     Khuyến nghị: PO review xong đặt `| **Status** | approved |` rồi mới sinh BDD.
+     Vẫn sinh BDD bây giờ? (Y/N)
+  ```
+  Chỉ tiếp tục khi người dùng chọn Y.
 
 ---
 
@@ -595,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).*
@@ -641,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
@@ -656,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).
 
 ---
 
@@ -679,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. |
@@ -728,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.**
 
 ---
@@ -837,10 +901,15 @@ 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)
@@ -989,7 +1058,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/commands/generate-bdd.tmpl

@@ -6,7 +6,34 @@
 ## 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.
+
+---
+
+## Guard — PRD đã duyệt chưa
+
+Đọc `| **Status** |` từ bảng Metadata của PRD nguồn:
+- `Status: approved` → tiếp tục bình thường.
+- `Status: draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép prototype):
+  ```
+  ⚠️  PRD đang ở Status: {status} (chưa duyệt). BDD sinh từ PRD chưa chốt có thể phải làm lại.
+     Khuyến nghị: PO review xong đặt `| **Status** | approved |` rồi mới sinh BDD.
+     Vẫn sinh BDD bây giờ? (Y/N)
+  ```
+  Chỉ tiếp tục khi người dùng chọn Y.
 
 ---
 
@@ -200,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).*
@@ -246,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
@@ -261,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).
 
 ---
 
@@ -284,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. |
@@ -333,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.**
 
 ---
@@ -442,10 +506,15 @@ 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)

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.
 
 ---
 
@@ -802,7 +819,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

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

@@ -412,6 +412,20 @@ Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 ---
 
+## Guard — PRD đã duyệt chưa
+
+Đọc `| **Status** |` từ bảng Metadata của Business PRD nguồn:
+- `Status: approved` → tiếp tục bình thường.
+- `Status: draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép prototype song song):
+  ```
+  ⚠️  Business PRD đang ở Status: {status} (chưa duyệt). Design Spec dựng trên PRD chưa chốt có thể phải làm lại theo PRD.
+     Khuyến nghị: PO duyệt PRD (đặt `| **Status** | approved |`) rồi mới sinh Design Spec.
+     Vẫn sinh Design Spec bây giờ? (Y/N)
+  ```
+  Chỉ tiếp tục khi người dùng chọn Y.
+
+---
+
 ## Platform Check
 
 Dùng `active_module` và `platform_type` suy ra từ context loading:
@@ -441,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.
@@ -502,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`."
 
@@ -589,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}                                                  |
@@ -816,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
@@ -827,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ờ.
 
 ---
 
@@ -895,7 +939,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
@@ -953,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
 ```