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

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.**
 
 ---
@@ -851,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)

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.**
 
 ---
@@ -456,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.
 
 ---
 

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
 ```

package/commands/generate-prd.md

@@ -752,11 +752,14 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 
 # Change Log
 
-### v1.0 — {mô tả} ({date})
+> Hiện tại: **v1.0** ({date}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET}-{N}-{slug}.changelog.md) *(file kho chỉ tạo khi changelog vượt 5 version)*
 
-| Mục | Thay đổi |
-|-----|----------|
-| — | Bản đầu — sinh từ product-definition. |
+<!-- Bảng phẳng, MỘT dòng/version, MỚI NHẤT TRÊN CÙNG. Chỉ giữ tối đa 5 version gần nhất ở đây;
+     cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
+
+| Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
+|---------|------|---------------------------------|
+| 1.0 | {date} | Bản đầu — sinh từ product-definition. |
 
 ---
 

package/commands/generate-tech-docs.md

@@ -113,6 +113,7 @@ Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp t
    Rồi: /review-context --resume {feature-file}  ← áp dụng các finding được chấp nhận còn lại
    Rồi chạy lại: /generate-tech-docs {feature-file}
    ```
+4. **Đồng thời** đọc `# @trace.status:` của `.feature` (tín hiệu duyệt chuẩn — B3): nếu ≠ `approved` → cảnh báo MỀM (đồng bộ qc-analyze/generate-code): "BDD chưa duyệt (@trace.status: {status}) — tech-docs sinh từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)". *(Nếu `approved` thì BDD đã sign-off; finding-gate ở trên vẫn chạy để chặn critical sót.)*
 
 ## Context
 # Context Loader — Nạp toàn bộ context dự án

package/commands/generate-tech-docs.tmpl

@@ -25,6 +25,7 @@
    Rồi: /review-context --resume {feature-file}  ← áp dụng các finding được chấp nhận còn lại
    Rồi chạy lại: /generate-tech-docs {feature-file}
    ```
+4. **Đồng thời** đọc `# @trace.status:` của `.feature` (tín hiệu duyệt chuẩn — B3): nếu ≠ `approved` → cảnh báo MỀM (đồng bộ qc-analyze/generate-code): "BDD chưa duyệt (@trace.status: {status}) — tech-docs sinh từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)". *(Nếu `approved` thì BDD đã sign-off; finding-gate ở trên vẫn chạy để chặn critical sót.)*
 
 ## Context
 {{include:steps/context-loader.md}}

package/commands/propose-scenario.md

@@ -466,7 +466,10 @@ Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_p
 
 Ghi vào `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (phân giải về `{spec_source}/feedback/bdd-proposals/` ở umbrella mode; tạo dir nếu cần).
 KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
-(xem Output). Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
+(xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
+
+> **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
+> `proposed` → PO/Dev duyệt đặt `accepted` (hoặc `rejected`) → `/generate-bdd` chèn cái `accepted` vào `.feature` rồi đặt `incorporated` + lưu trữ. **Chỉ `accepted` mới được đưa vào BDD.**
 
 ## Step 5 — Handoff (để PO/Dev thực sự thấy)
 
@@ -612,7 +615,8 @@ Scenario đề xuất (DRAFT — chờ PO/Dev review):
 
 Để PO/Dev promote:
   [ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
-  [ ] Thêm scenario vào {bdd_path} (sửa, hoặc chạy lại /generate-bdd nếu PRD đổi)
+  [ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
+  [ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
   [ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
 
 Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}

package/commands/propose-scenario.tmpl

@@ -71,7 +71,10 @@ Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_p
 
 Ghi vào `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (phân giải về `{spec_source}/feedback/bdd-proposals/` ở umbrella mode; tạo dir nếu cần).
 KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
-(xem Output). Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
+(xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
+
+> **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
+> `proposed` → PO/Dev duyệt đặt `accepted` (hoặc `rejected`) → `/generate-bdd` chèn cái `accepted` vào `.feature` rồi đặt `incorporated` + lưu trữ. **Chỉ `accepted` mới được đưa vào BDD.**
 
 ## Step 5 — Handoff (để PO/Dev thực sự thấy)
 
@@ -117,7 +120,8 @@ Scenario đề xuất (DRAFT — chờ PO/Dev review):
 
 Để PO/Dev promote:
   [ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
-  [ ] Thêm scenario vào {bdd_path} (sửa, hoặc chạy lại /generate-bdd nếu PRD đổi)
+  [ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
+  [ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
   [ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
 
 Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}

package/commands/qc-analyze.md

@@ -411,6 +411,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.
 
 
+---
+
+## Guard — BDD đã duyệt chưa
+
+Đọc `# @trace.status:` từ header file `.feature` của UC target:
+- `approved` → tiếp tục bình thường.
+- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
+  ```
+  ⚠️  BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
+     Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
+     Vẫn chạy QC bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y.
+
 ---
 
 ## Role

package/commands/qc-analyze.tmpl

@@ -18,6 +18,20 @@ ported_from: ai-automation-qc-base
 
 ---
 
+## Guard — BDD đã duyệt chưa
+
+Đọc `# @trace.status:` từ header file `.feature` của UC target:
+- `approved` → tiếp tục bình thường.
+- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
+  ```
+  ⚠️  BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
+     Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
+     Vẫn chạy QC bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y.
+
+---
+
 ## Role
 
 Bạn là **QC Analyst** — stage đầu tiên của QC automation pipeline. Lấy requirement

package/commands/refine-prd.md

@@ -909,10 +909,21 @@ Cập nhật `status: "applied"` ở **root level** của file findings (không
    - `| **Version** | {new_version} |`
    - `| **Updated**  | {today YYYY-MM-DD} |`
    - `| **Status**   | draft |` ← reset về draft, phải được duyệt lại
-5. Thêm một row mới lên đầu `# Change Log` ở cuối PRD:
-   ```
-   | {new_version} | {today} | {tóm tắt súc tích mọi thay đổi đã áp dụng} |
-   ```
+5. Cập nhật `# Change Log` của PRD — **bảng phẳng 1 dòng/version, cửa sổ trượt 5 entry** (nếu gặp format cũ `### v{X}` block → chuẩn hoá sang bảng phẳng khi cập nhật):
+   - Thêm row mới lên **đầu** bảng:
+     ```
+     | {new_version} | {today} | {tóm tắt — KÈM UC/AC/BR bị ảnh hưởng, vd "UC2: sửa BR5; thêm AC7"} |
+     ```
+     *(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
+   - Cập nhật dòng đầu section: `> Hiện tại: **v{new_version}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
+   - **Rollover (giữ PRD gọn — đây là chuẩn chung, /review-context cũng theo):** nếu bảng `# Change Log` có **> 5 row** → chuyển **mọi row vượt 5** (cũ nhất) sang **đầu** bảng của file kho `{paths.specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md` (giữ thứ tự mới→cũ); PRD chỉ giữ **5 row gần nhất**. Tạo thư mục `changelog/` + file kho nếu chưa có, theo skeleton:
+     ```
+     # Change Log (lịch sử) — {TICKET-ID}
+     > PRD: [../{TICKET-ID}-{prd-slug}.md](../{TICKET-ID}-{prd-slug}.md) — 5 version gần nhất nằm trong PRD; đây là phần cũ hơn.
+
+     | Version | Date | Changes |
+     |---------|------|---------|
+     ```
 6. Ghi `applied_to_version: "{new_version}"` ở **root level** của findings — đóng dấu "PRD đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt được thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
 
 ### Phase 4 — Report