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

package/commands/generate-design-spec.tmpl

@@ -17,6 +17,20 @@
 
 ---
 
+## 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:
@@ -46,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.
@@ -107,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`."
 
@@ -194,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}                                                  |
@@ -421,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
@@ -432,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ờ.
 
 ---
 
@@ -458,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. |
 
 ---
 
@@ -851,7 +854,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 |
@@ -901,4 +904,5 @@ Output Artifacts:
 Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
 Next     : /refine-prd {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
            → rồi /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
+           → khi sạch critical, PO đặt | **Status** | approved | (PRD mới sinh đang draft) → /generate-bdd
 ```

package/commands/generate-prd.tmpl

@@ -157,4 +157,5 @@ Output Artifacts:
 Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
 Next     : /refine-prd {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
            → rồi /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
+           → khi sạch critical, PO đặt | **Status** | approved | (PRD mới sinh đang draft) → /generate-bdd
 ```

package/commands/generate-spec-manifest.md

@@ -595,7 +595,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-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
@@ -798,7 +799,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-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/learn.md

@@ -579,7 +579,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/map-testids.md

@@ -526,7 +526,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/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)
 
@@ -556,7 +559,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 |
@@ -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
@@ -530,7 +544,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/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/qc-design-test.md

@@ -515,7 +515,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/qc-plan.md

@@ -496,7 +496,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/qc-report.md

@@ -501,7 +501,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/qc-review.md

@@ -499,7 +499,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/qc-run-test.md

@@ -555,7 +555,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/refine-prd.md

@@ -631,7 +631,9 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
    - **Tồn tại** + có `--full` → **FULL**: bỏ qua findings cũ, không truyền `CHANGED_SCOPE` (ép quét lại toàn bộ).
    - **Tồn tại** + KHÔNG có `--full` → so `prd_version` trong findings cũ với `| **Version** |` của PRD hiện tại:
      - **Bằng nhau** (PRD chưa đổi từ lần review trước) → DỪNG, báo: `"PRD chưa đổi từ v{X} (lần review gần nhất). Không có gì để review lại — dùng --full nếu vẫn muốn quét toàn bộ."`
-     - **Khác** (đã có `--resume` bump version) → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
+     - **Khác** → kiểm tra `applied_to_version` trong findings cũ (version mà lần `--resume` gần nhất của CHÍNH lệnh này đã bump PRD tới) để biết ai gây ra thay đổi:
+       - **`applied_to_version` có mặt VÀ `==` version PRD hiện tại** → PRD đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
+       - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → PRD đã bị sửa bởi **actor khác** (lệnh `/review-context`, sửa tay…) sau lần resume này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"PRD đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
 
 **DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
 toàn bộ PRD qua đúng lăng kính của nó:
@@ -663,6 +665,7 @@ Ghi `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
 ```yaml
 prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
 prd_version: "{đọc | **Version** | từ metadata PRD lúc sinh findings — dùng để chọn full/delta lần chạy sau}"
+applied_to_version: ""   # để trống lúc phân tích; --resume sẽ ghi version PRD vừa bump tới. Lần delta sau: nếu version PRD hiện tại ≠ giá trị này → PRD bị actor khác sửa → fallback FULL (xem "Chọn full vs delta")
 generated_at: "{ISO datetime}"
 status: "pending_review"
 
@@ -684,14 +687,19 @@ findings:
     # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
     # false = cần human đọc kỹ và ghi quyết định trước khi accept
     # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
+    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 4 lăng kính
+    #   là phán đoán QA/DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
+    #   quick-accept cho Board, KHÔNG để máy tự áp.
     status: "pending"
-    # Lifecycle finding-level:
+    applied_via: ""
+    # Vòng đời finding-level (CHUNG với /review-context — Review Board đọc cả hai loại file nên enum phải khớp):
     #   pending          → finding mới, chưa được review
     #   accepted         → reviewer chấp nhận suggestion gốc → Resume sẽ apply
     #   modified         → reviewer đã sửa suggestion trong Review Board → Resume dùng suggestion đã sửa
     #   rejected         → reviewer bác bỏ, không apply
-    #   needs_discussion → hai suggestion xung đột, cần con người quyết định trước khi --resume
-    #   applied          → đã được Resume Mode apply vào PRD
+    #   needs_discussion → hai suggestion xung đột, CHẶN --resume (bỏ qua + cảnh báo) tới khi con người quyết
+    #   deferred         → cố ý hoãn (không chặn), bỏ qua lượt này, xem lại sau
+    #   applied          → đã áp vào PRD; applied_via ghi cách áp: "resume" (qua --resume) — /review-context còn dùng "fix" (qua --fix)
 
 summary:
   total_findings: {N}
@@ -781,7 +789,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 |
@@ -834,7 +842,7 @@ Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → T
            Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
 Next     : Mở trong Review Board (chuột phải vào file) → Cập nhật PRD
            → /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
-           → /generate-bdd {prd-file}
+           → khi sạch critical, PO đặt | **Status** | approved | → /generate-bdd {prd-file}
 ```
 
 Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau footer:
@@ -884,7 +892,7 @@ Với mỗi finding được chấp nhận, theo thứ tự severity (critical
 ### Phase 2.5 — Cập nhật file findings
 
 Với mỗi finding đã áp dụng (status là `accepted` hoặc `modified`):
-- Đặt `status: "applied"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
+- Đặt `status: "applied"` + `applied_via: "resume"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
 
 Cập nhật `status: "applied"` ở **root level** của file findings (không phải `summary.status`).
 # Lifecycle file-level: pending_review → applied | partially_applied
@@ -901,10 +909,22 @@ 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
 
@@ -918,7 +938,7 @@ Changes  :
 
 💡 Vừa áp {N} phương án (gồm bản PO tự sửa) → chạy lại /refine-prd {prd-file}
    (delta tự động) để lòi edge case mà các phương án vừa áp có thể tạo ra.
-⚠️  BDD có thể đã lỗi thời. Chạy:
+⚠️  Status đã reset về draft (sửa rồi phải duyệt lại). BDD có thể đã lỗi thời. Chạy:
     /review-context {prd-file}   ← kiểm tra chất lượng PRD trước
-    → /generate-bdd {prd-file}
+    → PO đặt | **Status** | approved | khi hài lòng → /generate-bdd {prd-file}
 ```

package/commands/refine-prd.tmpl

@@ -48,7 +48,9 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
    - **Tồn tại** + có `--full` → **FULL**: bỏ qua findings cũ, không truyền `CHANGED_SCOPE` (ép quét lại toàn bộ).
    - **Tồn tại** + KHÔNG có `--full` → so `prd_version` trong findings cũ với `| **Version** |` của PRD hiện tại:
      - **Bằng nhau** (PRD chưa đổi từ lần review trước) → DỪNG, báo: `"PRD chưa đổi từ v{X} (lần review gần nhất). Không có gì để review lại — dùng --full nếu vẫn muốn quét toàn bộ."`
-     - **Khác** (đã có `--resume` bump version) → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
+     - **Khác** → kiểm tra `applied_to_version` trong findings cũ (version mà lần `--resume` gần nhất của CHÍNH lệnh này đã bump PRD tới) để biết ai gây ra thay đổi:
+       - **`applied_to_version` có mặt VÀ `==` version PRD hiện tại** → PRD đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
+       - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → PRD đã bị sửa bởi **actor khác** (lệnh `/review-context`, sửa tay…) sau lần resume này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"PRD đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
 
 **DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
 toàn bộ PRD qua đúng lăng kính của nó:
@@ -80,6 +82,7 @@ Ghi `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
 ```yaml
 prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
 prd_version: "{đọc | **Version** | từ metadata PRD lúc sinh findings — dùng để chọn full/delta lần chạy sau}"
+applied_to_version: ""   # để trống lúc phân tích; --resume sẽ ghi version PRD vừa bump tới. Lần delta sau: nếu version PRD hiện tại ≠ giá trị này → PRD bị actor khác sửa → fallback FULL (xem "Chọn full vs delta")
 generated_at: "{ISO datetime}"
 status: "pending_review"
 
@@ -101,14 +104,19 @@ findings:
     # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
     # false = cần human đọc kỹ và ghi quyết định trước khi accept
     # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
+    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 4 lăng kính
+    #   là phán đoán QA/DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
+    #   quick-accept cho Board, KHÔNG để máy tự áp.
     status: "pending"
-    # Lifecycle finding-level:
+    applied_via: ""
+    # Vòng đời finding-level (CHUNG với /review-context — Review Board đọc cả hai loại file nên enum phải khớp):
     #   pending          → finding mới, chưa được review
     #   accepted         → reviewer chấp nhận suggestion gốc → Resume sẽ apply
     #   modified         → reviewer đã sửa suggestion trong Review Board → Resume dùng suggestion đã sửa
     #   rejected         → reviewer bác bỏ, không apply
-    #   needs_discussion → hai suggestion xung đột, cần con người quyết định trước khi --resume
-    #   applied          → đã được Resume Mode apply vào PRD
+    #   needs_discussion → hai suggestion xung đột, CHẶN --resume (bỏ qua + cảnh báo) tới khi con người quyết
+    #   deferred         → cố ý hoãn (không chặn), bỏ qua lượt này, xem lại sau
+    #   applied          → đã áp vào PRD; applied_via ghi cách áp: "resume" (qua --resume) — /review-context còn dùng "fix" (qua --fix)
 
 summary:
   total_findings: {N}
@@ -151,7 +159,7 @@ Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → T
            Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
 Next     : Mở trong Review Board (chuột phải vào file) → Cập nhật PRD
            → /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
-           → /generate-bdd {prd-file}
+           → khi sạch critical, PO đặt | **Status** | approved | → /generate-bdd {prd-file}
 ```
 
 Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau footer:
@@ -201,7 +209,7 @@ Với mỗi finding được chấp nhận, theo thứ tự severity (critical
 ### Phase 2.5 — Cập nhật file findings
 
 Với mỗi finding đã áp dụng (status là `accepted` hoặc `modified`):
-- Đặt `status: "applied"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
+- Đặt `status: "applied"` + `applied_via: "resume"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
 
 Cập nhật `status: "applied"` ở **root level** của file findings (không phải `summary.status`).
 # Lifecycle file-level: pending_review → applied | partially_applied
@@ -218,10 +226,22 @@ 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
 
@@ -235,7 +255,7 @@ Changes  :
 
 💡 Vừa áp {N} phương án (gồm bản PO tự sửa) → chạy lại /refine-prd {prd-file}
    (delta tự động) để lòi edge case mà các phương án vừa áp có thể tạo ra.
-⚠️  BDD có thể đã lỗi thời. Chạy:
+⚠️  Status đã reset về draft (sửa rồi phải duyệt lại). BDD có thể đã lỗi thời. Chạy:
     /review-context {prd-file}   ← kiểm tra chất lượng PRD trước
-    → /generate-bdd {prd-file}
+    → PO đặt | **Status** | approved | khi hài lòng → /generate-bdd {prd-file}
 ```

package/commands/report-bug.md

@@ -566,7 +566,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/review-code.md

@@ -515,7 +515,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 |