@edupia-tutor/spec-driven-docs 0.14.2 → 0.14.4

package/commands/debug.md

@@ -19,6 +19,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/define-product.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 
@@ -412,6 +413,11 @@ AI quét dự án và ghi:
 - **Phần hệ thống / feature liên quan** — liệt kê phần hệ thống/feature bị ảnh hưởng.
 - **Rule / Logic có sẵn** — các rule từ PRD có sẵn mà feature này phải tôn trọng.
 - **Chuẩn hoá thuật ngữ** — map mọi thuật ngữ trong input PO về thuật ngữ chuẩn từ business-dictionary.md.
+  - **NEW TERM DETECTION:** nếu một thuật ngữ trong input PO lặp ≥2 lần và KHÔNG có canonical tương ứng trong business-dictionary.md → KHÔNG để trống/bịa. Ghi nó thành một câu hỏi trong **Phase 3 (Clarification Log)** để hỏi PO ngay khi còn trong buổi discovery:
+    + Thuật ngữ đó nghĩa gì trong ngữ cảnh hệ thống?
+    + English canonical term nên dùng là gì?
+    + Có bổ sung vào business-dictionary.md không?
+    Sau khi PO chốt → cập nhật business-dictionary.md (nếu đồng ý) + điền vào bảng map. *(Phase 0 chỉ phát hiện; việc hỏi dồn vào Phase 3 để không phá tính chất "không cần input PO" của Phase 0.)*
 
 ```
 | Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
@@ -541,6 +547,11 @@ Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh
 
 Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md`.
 
+> **Quy ước `slug`:** `slug` = kebab-case của tên feature (vd "Loyalty Points" → `loyalty-points`),
+> viết thường, chỉ a-z 0-9 và dấu `-`. Đây là định danh feature-package dùng xuyên suốt pipeline —
+> PRD, BDD, tech-docs, design-spec, trace của feature này đều kế thừa **nguyên văn** `slug` này
+> (`/generate-prd` đặt `prd-slug = slug`). Sinh một lần ở đây, các bước sau KHÔNG tái sinh.
+
 Điền tất cả section bằng dữ liệu thu thập qua các phase.
 
 **Cập nhật Metadata theo tiến độ (cho phép resume):**
@@ -650,8 +661,13 @@ Next     : {lệnh gợi ý kèm ví dụ tham số}
 *(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
 
 
+Ví dụ footer cho lệnh này:
+
 ```
-/define-product Hoàn tất ✅
-File: {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
-Next: /generate-prd {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
+---
+Status   : ✅ Complete
+Output Artifacts:
+  created {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md (product definition, Phase 1-7)
+Pipeline : [Discovery ◀ bạn ở đây] → PRD → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+Next     : /generate-prd {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
 ```

package/commands/define-product.tmpl

@@ -18,6 +18,11 @@ AI quét dự án và ghi:
 - **Phần hệ thống / feature liên quan** — liệt kê phần hệ thống/feature bị ảnh hưởng.
 - **Rule / Logic có sẵn** — các rule từ PRD có sẵn mà feature này phải tôn trọng.
 - **Chuẩn hoá thuật ngữ** — map mọi thuật ngữ trong input PO về thuật ngữ chuẩn từ business-dictionary.md.
+  - **NEW TERM DETECTION:** nếu một thuật ngữ trong input PO lặp ≥2 lần và KHÔNG có canonical tương ứng trong business-dictionary.md → KHÔNG để trống/bịa. Ghi nó thành một câu hỏi trong **Phase 3 (Clarification Log)** để hỏi PO ngay khi còn trong buổi discovery:
+    + Thuật ngữ đó nghĩa gì trong ngữ cảnh hệ thống?
+    + English canonical term nên dùng là gì?
+    + Có bổ sung vào business-dictionary.md không?
+    Sau khi PO chốt → cập nhật business-dictionary.md (nếu đồng ý) + điền vào bảng map. *(Phase 0 chỉ phát hiện; việc hỏi dồn vào Phase 3 để không phá tính chất "không cần input PO" của Phase 0.)*
 
 ```
 | Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
@@ -147,6 +152,11 @@ Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh
 
 Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md`.
 
+> **Quy ước `slug`:** `slug` = kebab-case của tên feature (vd "Loyalty Points" → `loyalty-points`),
+> viết thường, chỉ a-z 0-9 và dấu `-`. Đây là định danh feature-package dùng xuyên suốt pipeline —
+> PRD, BDD, tech-docs, design-spec, trace của feature này đều kế thừa **nguyên văn** `slug` này
+> (`/generate-prd` đặt `prd-slug = slug`). Sinh một lần ở đây, các bước sau KHÔNG tái sinh.
+
 Điền tất cả section bằng dữ liệu thu thập qua các phase.
 
 **Cập nhật Metadata theo tiến độ (cho phép resume):**
@@ -156,8 +166,13 @@ Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/prod
 
 {{include:steps/report-footer.md}}
 
+Ví dụ footer cho lệnh này:
+
 ```
-/define-product Hoàn tất ✅
-File: {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
-Next: /generate-prd {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
+---
+Status   : ✅ Complete
+Output Artifacts:
+  created {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md (product definition, Phase 1-7)
+Pipeline : [Discovery ◀ bạn ở đây] → PRD → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+Next     : /generate-prd {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
 ```

package/commands/dev-gen-test.md

@@ -22,6 +22,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/dev-run-test.md

@@ -22,6 +22,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/dev-smoke-test.md

@@ -18,6 +18,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/fix-bug.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/generate-bdd.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/generate-code.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/generate-design-spec.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/generate-prd.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 
@@ -402,9 +403,23 @@ 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.
 
 
-*Context bổ sung cho lệnh này: Đọc toàn bộ file product-definition. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, dữ liệu Phase 1-7, và bảng **Chuẩn hoá thuật ngữ** (Terminology Map ở Phase 0 — các cặp `thuật ngữ PO → thuật ngữ chuẩn`). Lưu bản đồ này để áp dụng ở bước Quy tắc thuật ngữ. **Nếu Phase 7 (Validation Report) còn `Xung đột phát hiện` / `Mục còn thiếu` khác "None" → diễn đạt lại mỗi mục thành một câu hỏi theo format `Q… — [AI DRAFT]` của section "Giả định AI" (nêu rõ độ vênh + cần PO chốt điều gì), thay vì dán thô. AI không tự quyết thay PO.***
+*Context bổ sung cho lệnh này: Đọc toàn bộ file product-definition. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, **tên PO** (field `PO` ở Metadata), dữ liệu Phase 1-7, và bảng **Chuẩn hoá thuật ngữ** (Terminology Map ở Phase 0 — các cặp `thuật ngữ PO → thuật ngữ chuẩn`). Lưu bản đồ này để áp dụng ở bước Quy tắc thuật ngữ. **Nếu Phase 7 (Validation Report) còn `Xung đột phát hiện` / `Mục còn thiếu` khác "None" → diễn đạt lại mỗi mục thành một câu hỏi theo format `Q… — [AI DRAFT]` của section "Giả định AI" (nêu rõ độ vênh + cần PO chốt điều gì), thay vì dán thô. AI không tự quyết thay PO.***
 
-CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domain: {domain}). Tiếp tục? (Y/N)"
+**Phân giải PO** (đọc trước, hỏi sau): lấy `PO` từ Metadata của product-definition. Nếu đã có giá trị → dùng luôn, KHÔNG hỏi lại. Nếu trống/thiếu → hỏi PO ngay ở CHECKPOINT dưới. Điền giá trị này vào field `PO` của PRD Metadata.
+
+**Phân giải `slug`** (kế thừa, KHÔNG tái sinh): lấy `slug` từ tên file product-definition — đoạn sau `{TICKET-ID}-` (vd `LOYAL29-loyalty-points.md` → `slug = loyalty-points`). Đặt `prd-slug = slug` này cho feature-package PRD, để folder `{specs_dir}/{domain}/{prd-slug}/` khớp 1-1 với product-definition. KHÔNG tự bịa slug mới — nếu tên file không theo dạng `{TICKET-ID}-{slug}.md`, dừng và hỏi người dùng.
+
+**Guard — discovery phải hoàn tất:** đọc `Status` và `Completed Phase` từ Metadata của product-definition.
+- Nếu `Status: completed` (Completed Phase = 7) → tiếp tục bình thường.
+- Nếu `Status: in-progress` (Completed Phase < 7) → **DỪNG**, KHÔNG sinh PRD, báo:
+  ```
+  ❌ Product-definition chưa hoàn tất (Status: in-progress, Completed Phase: {N}/7).
+     /generate-prd cần discovery đủ Phase 1-7 (BR, Business Logic, AC, Validation Report).
+     Chạy lại /define-product {file} để resume từ Phase {N+1}, rồi mới sinh PRD.
+  ```
+  PRD là artifact ký duyệt — không sinh từ nguồn discovery chưa chốt.
+
+CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domain: {domain}), PO: **{tên PO — hoặc hỏi nếu product-definition để trống}**. Nguồn: discovery hoàn tất (Phase 7/7). Tiếp tục? (Y/N)"
 
 ---
 
@@ -413,7 +428,7 @@ CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domai
 - **Áp dụng Terminology Map từ product-definition**: với mỗi cặp `thuật ngữ PO → thuật ngữ chuẩn` trong bảng **Chuẩn hoá thuật ngữ** (Phase 0 của product-definition), dùng **thuật ngữ chuẩn** khi viết PRD. Đây là bản đồ PO đã xác nhận ở discovery — luôn ưu tiên áp dụng kể cả khi business-dictionary.md vắng mặt, để PRD nhất quán với product-definition. Nếu bảng trống/không có → bỏ qua âm thầm.
 - **Thay banned term**: thay mọi banned term bằng bản chuẩn tương đương (xem dictionary § Banned Terms).
 - **Dùng canonical term**: chỉ dùng các thuật ngữ được định nghĩa trong dictionary.
-- **NEW TERM DETECTION**: Nếu một thuật ngữ trong input PO xuất hiện ≥2 lần và KHÔNG có trong dictionary → **DỪNG** và hỏi PO:
+- **NEW TERM DETECTION (lưới an toàn — define-product lẽ ra đã bắt ở discovery Phase 3)**: Nếu vẫn còn thuật ngữ trong input PO xuất hiện ≥2 lần và KHÔNG có trong dictionary → **DỪNG** và hỏi PO:
   - Thuật ngữ đó nghĩa là gì trong ngữ cảnh hệ thống?
   - English canonical term nên dùng là gì?
   - Có cần bổ sung vào business-dictionary.md không?
@@ -510,6 +525,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 | **Version**   | 1.0                                      |
 | **Status**    | draft                                    |
 | **Author**    | AI-assisted                              |
+| **PO**        | {tên PO}                                 |
 | **Domain**    | {domain}                                 |
 | **Created**   | {date}                                   |
 | **Updated**   | {date}                                   |
@@ -789,12 +805,14 @@ Next     : {lệnh gợi ý kèm ví dụ tham số}
 *(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
 
 
+Ví dụ footer cho lệnh này:
+
 ```
-/generate-prd Hoàn tất — {TICKET-ID}
 ---
-Status : ✅ Complete
+Status   : ✅ Complete
 Output Artifacts:
-  created {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  (PRD v1.0)
-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
+  created {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md (PRD v1.0)
+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
 ```

package/commands/generate-prd.tmpl

@@ -8,9 +8,23 @@
 ## Context
 {{include:steps/context-loader.md}}
 
-*Context bổ sung cho lệnh này: Đọc toàn bộ file product-definition. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, dữ liệu Phase 1-7, và bảng **Chuẩn hoá thuật ngữ** (Terminology Map ở Phase 0 — các cặp `thuật ngữ PO → thuật ngữ chuẩn`). Lưu bản đồ này để áp dụng ở bước Quy tắc thuật ngữ. **Nếu Phase 7 (Validation Report) còn `Xung đột phát hiện` / `Mục còn thiếu` khác "None" → diễn đạt lại mỗi mục thành một câu hỏi theo format `Q… — [AI DRAFT]` của section "Giả định AI" (nêu rõ độ vênh + cần PO chốt điều gì), thay vì dán thô. AI không tự quyết thay PO.***
+*Context bổ sung cho lệnh này: Đọc toàn bộ file product-definition. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, **tên PO** (field `PO` ở Metadata), dữ liệu Phase 1-7, và bảng **Chuẩn hoá thuật ngữ** (Terminology Map ở Phase 0 — các cặp `thuật ngữ PO → thuật ngữ chuẩn`). Lưu bản đồ này để áp dụng ở bước Quy tắc thuật ngữ. **Nếu Phase 7 (Validation Report) còn `Xung đột phát hiện` / `Mục còn thiếu` khác "None" → diễn đạt lại mỗi mục thành một câu hỏi theo format `Q… — [AI DRAFT]` của section "Giả định AI" (nêu rõ độ vênh + cần PO chốt điều gì), thay vì dán thô. AI không tự quyết thay PO.***
 
-CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domain: {domain}). Tiếp tục? (Y/N)"
+**Phân giải PO** (đọc trước, hỏi sau): lấy `PO` từ Metadata của product-definition. Nếu đã có giá trị → dùng luôn, KHÔNG hỏi lại. Nếu trống/thiếu → hỏi PO ngay ở CHECKPOINT dưới. Điền giá trị này vào field `PO` của PRD Metadata.
+
+**Phân giải `slug`** (kế thừa, KHÔNG tái sinh): lấy `slug` từ tên file product-definition — đoạn sau `{TICKET-ID}-` (vd `LOYAL29-loyalty-points.md` → `slug = loyalty-points`). Đặt `prd-slug = slug` này cho feature-package PRD, để folder `{specs_dir}/{domain}/{prd-slug}/` khớp 1-1 với product-definition. KHÔNG tự bịa slug mới — nếu tên file không theo dạng `{TICKET-ID}-{slug}.md`, dừng và hỏi người dùng.
+
+**Guard — discovery phải hoàn tất:** đọc `Status` và `Completed Phase` từ Metadata của product-definition.
+- Nếu `Status: completed` (Completed Phase = 7) → tiếp tục bình thường.
+- Nếu `Status: in-progress` (Completed Phase < 7) → **DỪNG**, KHÔNG sinh PRD, báo:
+  ```
+  ❌ Product-definition chưa hoàn tất (Status: in-progress, Completed Phase: {N}/7).
+     /generate-prd cần discovery đủ Phase 1-7 (BR, Business Logic, AC, Validation Report).
+     Chạy lại /define-product {file} để resume từ Phase {N+1}, rồi mới sinh PRD.
+  ```
+  PRD là artifact ký duyệt — không sinh từ nguồn discovery chưa chốt.
+
+CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domain: {domain}), PO: **{tên PO — hoặc hỏi nếu product-definition để trống}**. Nguồn: discovery hoàn tất (Phase 7/7). Tiếp tục? (Y/N)"
 
 ---
 
@@ -19,7 +33,7 @@ CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domai
 - **Áp dụng Terminology Map từ product-definition**: với mỗi cặp `thuật ngữ PO → thuật ngữ chuẩn` trong bảng **Chuẩn hoá thuật ngữ** (Phase 0 của product-definition), dùng **thuật ngữ chuẩn** khi viết PRD. Đây là bản đồ PO đã xác nhận ở discovery — luôn ưu tiên áp dụng kể cả khi business-dictionary.md vắng mặt, để PRD nhất quán với product-definition. Nếu bảng trống/không có → bỏ qua âm thầm.
 - **Thay banned term**: thay mọi banned term bằng bản chuẩn tương đương (xem dictionary § Banned Terms).
 - **Dùng canonical term**: chỉ dùng các thuật ngữ được định nghĩa trong dictionary.
-- **NEW TERM DETECTION**: Nếu một thuật ngữ trong input PO xuất hiện ≥2 lần và KHÔNG có trong dictionary → **DỪNG** và hỏi PO:
+- **NEW TERM DETECTION (lưới an toàn — define-product lẽ ra đã bắt ở discovery Phase 3)**: Nếu vẫn còn thuật ngữ trong input PO xuất hiện ≥2 lần và KHÔNG có trong dictionary → **DỪNG** và hỏi PO:
   - Thuật ngữ đó nghĩa là gì trong ngữ cảnh hệ thống?
   - English canonical term nên dùng là gì?
   - Có cần bổ sung vào business-dictionary.md không?
@@ -93,12 +107,14 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 {{include:steps/report-footer.md}}
 
+Ví dụ footer cho lệnh này:
+
 ```
-/generate-prd Hoàn tất — {TICKET-ID}
 ---
-Status : ✅ Complete
+Status   : ✅ Complete
 Output Artifacts:
-  created {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  (PRD v1.0)
-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
+  created {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md (PRD v1.0)
+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
 ```

package/commands/generate-spec-manifest.md

@@ -20,6 +20,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/generate-tech-docs.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/learn.md

@@ -25,6 +25,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/map-testids.md

@@ -26,6 +26,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/propose-scenario.md

@@ -26,6 +26,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/qc-analyze.md

@@ -24,6 +24,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/qc-design-test.md

@@ -24,6 +24,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/qc-plan.md

@@ -24,6 +24,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/qc-report.md

@@ -24,6 +24,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/qc-review.md

@@ -24,6 +24,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/qc-run-test.md

@@ -24,6 +24,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/commands/refine-prd.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 
@@ -92,6 +93,19 @@ Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp t
 
 *Lưu ý: Với lệnh này, target file ở Bước 1 là một file PRD (`{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder) dưới `{paths.specs_dir}/{domain}/{prd-slug}/`. Đọc toàn bộ PRD sau khi phân giải file.*
 
+### Bước 0-C — Resume mode routing *(riêng /refine-prd, chạy ngay sau Bước 0 của Gate)*
+
+Nếu `$ARGUMENTS` chứa `--resume`:
+- Tách `--resume` ra, phần còn lại là `raw_target` (file path hoặc prd-slug).
+- **Nạp minimal context:** đọc `.agent/project-context.yaml`, trích xuất `paths.refinement_dir`
+  (default: `.agent/review` nếu không có hoặc file không tồn tại).
+- Chạy **Bước 1** với `raw_target` để phân giải `prd-slug` và `target_file`.
+  Nếu `raw_target` rỗng → liệt kê các file `*.yaml` trong `{paths.refinement_dir}/` và hỏi user chọn findings file nào.
+- **Bỏ qua Bước 0-B, 2, 3** — apply findings là tác vụ cơ học, không cần model check hay load full context.
+- → Nhảy thẳng tới **Resume Mode** ở cuối lệnh này.
+
+Nếu `$ARGUMENTS` không chứa `--resume` → tiếp tục luồng review bình thường bên dưới.
+
 ## Context
 # Context Loader — Nạp toàn bộ context dự án
 
@@ -495,8 +509,16 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
 1. Spawn một sub-agent **completeness-critic** bằng Agent tool. Cho nó:
    - toàn bộ target file (`{target_file}`),
-   - danh sách `ALL_FINDINGS` hiện tại (để nó biết những gì đã được ghi nhận),
-   - cùng context gọn đó.
+   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
+     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
+     ```json
+     [
+       { "uc_id": "...", "section": "...", "finding": "..." },
+       ...
+     ]
+     ```
+     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
+   - cùng slim context (banned terms, canonical entities, layer order, domains).
    Prompt nó:
    ```
    Here is a document and a list of issues already found. Read the WHOLE document.
@@ -567,6 +589,13 @@ Suy ra tên file output từ PRD slug:
 - File PRD: `{paths.specs_dir}/payment/create-invoice/PAY01-create-invoice.md` → output: `{paths.refinement_dir}/create-invoice-findings.yaml`
 - Quy tắc: lấy tên folder cha của PRD (prd-slug), thêm hậu tố `-findings.yaml`
 
+Trước khi ghi file, xác định `recommendation` từ findings đã dedup và sắp xếp:
+- `by_severity.critical ≥ 1` → `BLOCKED`
+- `by_severity.critical = 0` và `by_severity.major ≥ 1` → `NEEDS_REVISION`
+- `by_severity.critical = 0` và `by_severity.major = 0` → `APPROVED_WITH_MINOR_CHANGES`
+
+Đảm bảo `{paths.refinement_dir}/` tồn tại — tạo thư mục nếu chưa có trước khi ghi file.
+
 Ghi `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
 
 ```yaml
@@ -583,14 +612,27 @@ findings:
     quote: "{trích đoạn nguyên văn copy CHÍNH XÁC từ PRD tại vị trí lỗi, ≤120 ký tự}"
     finding: "{mô tả gap hoặc vấn đề}"
     suggestion: "{đề xuất cải thiện cụ thể, hành động được}"
-    auto_fixable: false  # true = AI áp dụng khi --resume; false = người phải ghi quyết định trong note
-    status: "pending"    # pending | accepted | rejected | needs_discussion
+    auto_fixable: false
+    # 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.
+    status: "pending"
+    # Lifecycle finding-level:
+    #   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
 
 summary:
   total_findings: {N}
   by_severity: { critical: {N}, major: {N}, minor: {N} }
   by_lens: { QA: {N}, DEV: {N}, SA: {N}, PO: {N} }
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
+  # Rule: critical ≥ 1                       → BLOCKED
+  #       critical = 0, major ≥ 1            → NEEDS_REVISION
+  #       critical = 0, major = 0            → APPROVED_WITH_MINOR_CHANGES
 ```
 
 > **Field định vị (`quote` + `uc_id`) — bắt buộc cho source-jump của Review Board.**
@@ -703,26 +745,57 @@ Next     : {lệnh gợi ý kèm ví dụ tham số}
 *(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
 
 
+Dùng footer chuẩn với hai field bổ sung `Findings` và `Review` đặt ngay sau `Status`:
+
 ```
-/refine-prd Hoàn tất — {PRD name}
-Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
-Review: {paths.refinement_dir}/{prd-slug}-findings.yaml
-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}
+---
+Status   : {badge}
+Findings : {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
+Review   : {paths.refinement_dir}/{prd-slug}-findings.yaml
+Output Artifacts:
+  created {paths.refinement_dir}/{prd-slug}-findings.yaml (findings từ 4-lens review)
+Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           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}
 ```
 
+Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau footer:
+
+```
+⚠️  {N} finding(s) cần quyết định của bạn trước khi --resume:
+   Mở {paths.refinement_dir}/{prd-slug}-findings.yaml
+   Với mỗi finding có status "needs_discussion":
+     1. Đọc cả hai phương án trong `suggestion`
+     2. Chọn một (hoặc viết phương án khác) vào `suggestion`
+     3. Đổi `status` → "accepted"
+   Sau đó chạy: /refine-prd {prd-file} --resume
+```
+*(Bỏ warning block này nếu không có `needs_discussion` finding nào.)*
+
 ---
 
 ## Resume Mode — Áp dụng Findings & Bump Version
 
-*Kích hoạt khi `$ARGUMENTS` chứa `--resume` (gọi bởi nút "Apply to PRD" của Review Board).*
+*Được route tới từ Bước 0-C — Resume mode routing. `prd-slug` và `target_file` đã được phân giải ở Bước 1 trước khi nhảy vào đây.*
 
 ### Phase 1 — Đọc các finding được chấp nhận
 
-1. Đọc `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
-2. Gom tất cả finding có `status: "accepted"` hoặc `status: "modified"`.
-3. Nếu không có finding nào được chấp nhận → báo "No accepted findings. PRD unchanged." và dừng.
+1. Kiểm tra `{paths.refinement_dir}/{prd-slug}-findings.yaml` có tồn tại không.
+   Nếu không → báo lỗi rõ ràng và dừng:
+   ```
+   ❌ Không tìm thấy findings file tại {paths.refinement_dir}/{prd-slug}-findings.yaml
+      Hãy chạy /refine-prd {prd-file} trước để tạo findings, rồi mới --resume.
+   ```
+2. Đọc file findings.
+3. Gom tất cả finding có `status: "accepted"` hoặc `status: "modified"`.
+4. Nếu không có finding nào được chấp nhận → báo "No accepted findings. PRD unchanged." và dừng.
+5. Nếu còn finding nào có `status: "needs_discussion"` → cảnh báo (không dừng):
+   ```
+   ⚠️  {N} finding(s) chưa được giải quyết (needs_discussion) — sẽ bị bỏ qua lần apply này.
+      Giải quyết chúng trong Review Board rồi chạy lại --resume để apply.
+   ```
 
 ### Phase 2 — Áp dụng thay đổi vào PRD
 
@@ -736,7 +809,9 @@ Với mỗi finding được chấp nhận, theo thứ tự severity (critical
 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`.
 
-Cập nhật `summary.status: "applied"` trong file findings.
+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
+# partially_applied khi có finding bị rejected hoặc needs_discussion còn sót lại.
 
 ### Phase 3 — Bump version & ghi entry changelog