@edupia-tutor/spec-driven-docs 0.14.3 → 0.14.5

package/commands/generate-prd.tmpl

@@ -10,9 +10,46 @@
 
 *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.***
 
+**Map "Phụ thuộc liên service"** (Phase 1 câu 8 của product-definition) → **§1c "Phụ thuộc liên service"** của PRD, giữ nguyên mức nghiệp vụ (cần dữ liệu/năng lực gì, từ ai, vì sao — KHÔNG thêm chi tiết API/kỹ thuật). Nếu discovery ghi "Không có" → §1c ghi "Không có".
+
+**Map "Màn hình & thành phần chính"** (Phase 2 của product-definition) → **§4b Wireframe** của PRD: mỗi màn hình thành một Screen với Components/Actions tương ứng. Đây là nguồn coverage cho `/generate-bdd` (C.1). Nếu phải **suy thêm** Screen/component mà discovery chưa nêu → đánh dấu rõ `*(AI đề xuất — PO review)*` cạnh phần đó, đừng để âm thầm thành chân lý coverage.
+
 **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.
 
-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}**. Tiếp tục? (Y/N)"
+**Phân giải link tracker (hỏi cho MỌI ticket):** `TICKET-ID` là **định danh nội bộ** PO tự đặt lúc discovery — **KHÔNG đảm bảo** là một Jira key có thật, nên **TUYỆT ĐỐI KHÔNG tự dựng URL** kiểu `{base}/browse/{TICKET-ID}` (sẽ ra link rác trỏ tới ticket không tồn tại). Field `Ticket` **luôn giữ TICKET-ID dạng plain text**; link Jira (nếu có) chỉ **đặt thêm bên cạnh**. **Luôn hỏi PO**: *"Ticket {TICKET-ID} có link tracker thật (Jira/khác) không? Nếu có, dán vào."*
+- PO **có** link → điền field `Ticket` dạng: `{TICKET-ID} ([Jira]({tracker_url}))` — plain ID đứng trước, link trong ngoặc bên cạnh.
+- PO **không** có / để trống → điền plain text `{TICKET-ID}` (KHÔNG link, KHÔNG placeholder `{...}` lủng lẳng).
+
+**Phân giải `slug`** (kế thừa, KHÔNG tái sinh): đọc `TICKET-ID` từ Metadata `Ticket` của product-definition, rồi lấy `slug` = phần tên file **sau khi strip đúng chuỗi `{TICKET-ID}-` ở đầu**. **KHÔNG tách theo dấu `-` đầu tiên** — vì TICKET-ID có thể chứa `-` (vd Jira key `LOYAL-29`): `LOYAL-29-loyalty-points.md` với TICKET-ID `LOYAL-29` → `slug = loyalty-points` (KHÔNG phải `29-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 bắt đầu bằng `{TICKET-ID}-`, 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.
+
+**Phân giải `API Source` (brownfield / greenfield / partner song song):** hỏi PO **một** câu để chốt **loại** nguồn API — PO CHỈ chốt loại, **không bao giờ gõ chi tiết contract**:
+
+> "API của feature này thuộc loại nào?
+>   1. **existing** — API đã chạy production, contract cố định
+>   2. **greenfield** — mình tự thiết kế contract mới
+>   3. **partner** — đối tác đang phát triển song song, contract chưa có"
+
+- **(1) existing** → set Metadata `API Source: existing`. Xin PO **con trỏ nguồn** contract (1 trong: file openapi/swagger, URL swagger, path service/repo BE, hoặc doc đính kèm). AI **trích as-is** vào Appendix "Existing API Contract" (ghi rõ nguồn từng row — KHÔNG bịa, KHÔNG thiết kế mới). *Người điền detail là AI từ artifact thật, KHÔNG phải PO.*
+  - Nếu con trỏ **không truy cập được** từ context hiện tại → KHÔNG fabricate: ghi block `⛔ PENDING: contract chưa trích — nguồn: {pointer}; phải trích as-is trước /generate-bdd` vào section đó, vẫn giữ `API Source: existing`. Coi phần contract của PRD chưa hoàn tất tới khi bảng đủ.
+- **(2) greenfield** → để trống `API Source`. **Xoá** Appendix "Existing API Contract" (template đã dặn). Contract sẽ được thiết kế ở `/generate-tech-docs`.
+- **(3) partner song song** → ĐI LUỒNG greenfield (`API Source` để trống, **xoá** section Existing API Contract), **KHÔNG** set `existing`. Thêm:
+  - Ghi phụ thuộc partner vào **§1c "Phụ thuộc liên service"** của PRD (mức nghiệp vụ): cần contract/năng lực gì từ partner nào, vì sao.
+  - Một mục trong "Giả định AI": *"Contract do partner {X} phát triển song song; bản tech-docs sinh sau là ĐỀ XUẤT của ta để đàm phán (qua cổng T7 cross-team sign-off), chốt khi partner confirm — có thể thay đổi."*
+  - Lý do KHÔNG dùng `existing`: `existing` làm `/review-tech-docs` **skip T7** — nhưng partner song song chính là lúc CẦN T7 để đàm phán contract.
+
+> **`API Source` là field có vòng đời:** có thể bắt đầu greenfield/partner rồi **chuyển thành `existing`** khi contract được chốt (vd partner áp contract của họ và ta phải theo). Khi đó: chạy `/refine-prd` đổi `API Source → existing` + điền Existing API Contract từ nguồn partner (trích as-is) + bump Version; `/generate-bdd` (Version drift) và `/generate-tech-docs` (reverse-document) sẽ tự realign system BDD + tech-doc theo contract mới. FE/App BDD phần lớn không vỡ nhờ luật declarative (assert outcome quan sát được, không assert shape JSON).
+
+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}**. API Source: **{existing — nguồn {pointer} | greenfield | partner song song}**. Link tracker: **{URL — hoặc 'không có, dùng plain ID'}**. Nguồn: discovery hoàn tất (Phase 7/7). Tiếp tục? (Y/N)"
 
 ---
 
@@ -21,13 +58,16 @@ 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?
   Sau khi PO confirm → cập nhật `business-dictionary.md` (nếu đồng ý) → tiếp tục sinh.
 - Nếu không có banned term và tất cả thuật ngữ đều chuẩn → tiếp tục không gián đoạn.
 
+## Ngôn ngữ nghiệp vụ
+{{include:steps/business-language.md}}
+
 ## Quy tắc Cross-Reference
 
 Bất kỳ chỗ nào nhắc tới một TICKET-ID khác trong PRD (pre-condition, BR, ghi chú, appendix) → **PHẢI** là inline link. Mỗi PRD sống trong feature-package riêng (`{paths.specs_dir}/{domain}/{prd-slug-khác}/`), nên link trỏ sang folder anh em:
@@ -42,6 +82,12 @@ Không bao giờ để TICKET-ID dạng plain text nếu file PRD tương ứng
 - **BR ID**: `{TICKET-ID}-UC{N}-BR{M}` — **M tăng liên tục trên toàn PRD** (KHÔNG reset theo từng UC).
   - Ví dụ: UC1 → BR1, BR2; UC2 → BR3, BR4 (KHÔNG phải BR1, BR2 lại từ đầu).
 
+## Traceability AC ↔ BR ↔ UC
+
+- **Giữ link AC→BR từ discovery (KHÔNG vứt khi flatten):** Product Definition Phase 6 có cột "Bắt nguồn từ BR-{N}". Khi viết AC §2, **remap** mỗi `BR-{N}` (số discovery) sang **BR ID của PRD** (`{TICKET-ID}-UC{n}-BR{m}` sau khi đã phân BR vào UC) và gắn vào cuối AC: `_(BR: {ids})_`. Mỗi AC PHẢI có ≥1 ref BR.
+- **Điền "AC liên quan" cho mỗi UC §3 (chiều ngược):** với mỗi UC, liệt kê các AC mà nó thoả.
+- **Nhất quán 2 chiều (bắt buộc):** tập "AC liên quan" của UC{n} phải **đúng bằng** tập AC có ref BR trỏ về UC{n}. Vì BR ID đã chứa số UC, hai chiều này suy ra lẫn nhau — lệch là lỗi traceability, sửa trước khi ghi.
+
 ---
 
 ## Platform Strategy — PRD là tài liệu nghiệp vụ (không technical)
@@ -49,6 +95,8 @@ Không bao giờ để TICKET-ID dạng plain text nếu file PRD tương ứng
 PRD mô tả **WHAT** (yêu cầu nghiệp vụ) — không nhét chi tiết **kỹ thuật** (API, token, endpoint, HTTP status, tên class/bảng/cột DB, query). Những thứ đó thuộc **Tech Docs**.
 PRD **được phép** có User Flow + Wireframe ở mức nghiệp vụ (§4) để BA/QC/Dev cùng hình dung; chỉ **chi tiết visual** (màu sắc, layout pixel, animation, micro-interaction) mới thuộc **Design Spec**.
 
+> **Ngoại lệ DUY NHẤT (brownfield):** khi `API Source: existing`, Appendix "Existing API Contract" ĐƯỢC PHÉP chứa chi tiết kỹ thuật (method, path, request/response shape, HTTP status, error code) — vì đó là contract **đã tồn tại**, AI chỉ **trích as-is** làm input cho trước, KHÔNG phải thiết kế mới. Ngoại lệ này CHỈ áp cho riêng section đó; AC, BR, và toàn bộ thân PRD vẫn thuần nghiệp vụ.
+
 | ✅ Viết trong PRD (nghiệp vụ) | ❌ KHÔNG viết trong PRD |
 |---|---|
 | "Đăng nhập thành công → truy cập được tính năng" | "API trả về JWT token" ← Tech Docs |
@@ -83,10 +131,14 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 - [ ] Mọi AC đều testable (pass/fail rõ ràng), không có chi tiết kỹ thuật (API/token/DB) hay visual chi tiết (màu sắc, font, animation)
 - [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
+- [ ] §1c "Phụ thuộc liên service" có mặt: kế thừa từ discovery Phase 1 câu 8 (hoặc "Không có" nếu discovery trống); case partner song song có ghi phụ thuộc partner ở đây
 - [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
 - [ ] BR ID tăng liên tục trên toàn PRD — không reset theo từng UC
+- [ ] **Traceability AC↔BR↔UC**: mỗi AC §2 có ≥1 ref `_(BR: …)_`; mỗi UC §3 có dòng "AC liên quan"; và hai chiều khớp nhau (tập "AC liên quan" của UC = tập AC có ref BR trỏ về UC đó)
 - [ ] Mọi cross-reference TICKET-ID đều là inline link `[TICKET-ID](./file.md)`
 - [ ] Không có banned term (nếu dictionary tồn tại)
+- [ ] **Ngôn ngữ nghiệp vụ**: 0 thuật ngữ kỹ thuật/UI trong prose (re-render→hiển thị lại, UI→màn, timeout→quá thời gian chờ…) — xem Business Language Guard
+- [ ] **API Source nhất quán**: nếu `existing` → bảng "Existing API Contract" đủ method/path/request/response (hoặc mang block ⛔ PENDING kèm con trỏ nguồn); nếu greenfield/partner → section "Existing API Contract" đã bị xoá hẳn (không để bảng rỗng), và case partner có dependency + assumption ghi rõ
 - [ ] User Flow có cả luồng lỗi / luồng ngoại lệ
 - [ ] Wireframe phủ tất cả màn hình liên quan tới Use Case
 - [ ] **Định dạng (readability)**: User Story / AC / các field của UC (Actor, Description, Pre/Post-condition) viết dạng bullet `- **Label:** …` — mỗi ý MỘT dòng, KHÔNG viết các dòng liền nhau (sẽ bị dồn thành 1 đoạn khi render); có một dòng trống trước và sau mỗi bảng
@@ -95,12 +147,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
 
@@ -402,6 +416,47 @@ 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.
 
 
+---
+
+## Ngôn ngữ nghiệp vụ *(áp khi viết/áp fix — gồm cả Resume Mode Phase 2)*
+# Business Language Guard — chặn thuật ngữ kỹ thuật rò vào tài liệu nghiệp vụ
+
+Tài liệu nghiệp vụ (PRD, product-definition) mô tả **WHAT** — chỉ ngôn ngữ nghiệp vụ. Guard này chạy **mỗi khi viết hoặc sửa** prose (gen mới, áp fix `--resume`, hiệu chỉnh): **quét và xử lý** các thuật ngữ kỹ thuật/UI phổ thông bên dưới **trước khi ghi**.
+
+> Guard này là **baseline framework**, chạy **song song** với Banned Terms của `business-dictionary.md` (cơ chế dictionary giữ nguyên; project vẫn bổ sung term đặc thù vào đó). Khi cả hai cùng áp, ưu tiên bản chuẩn của dictionary nếu có.
+
+## Bản đồ xử lý (3 nhóm)
+
+**Nhóm 1 — Tương tác/triển khai → DIỄN ĐẠT LẠI sang nghiệp vụ (giữ nguyên nghĩa):**
+
+| Kỹ thuật/UI | Cách nói nghiệp vụ |
+|---|---|
+| re-render / render lại / reload / refresh (màn) | "hiển thị lại {tên màn}" |
+| timeout | "quá thời gian chờ" |
+| lỗi mạng / network error | "lỗi kết nối" |
+| UI / giao diện (khi chỉ một màn) | "màn" / "màn hình" |
+| click / tap | "bấm" / "chọn" |
+| popup / modal (nếu chỉ là khái niệm hiển thị) | "hộp thoại" / "thông báo" |
+| disable / enable (nút) | "khoá" / "mở" thao tác |
+| redirect / navigate | "chuyển tới {màn}" |
+
+**Nhóm 2 — Visual thuần → CHUYỂN Design Spec (bỏ khỏi PRD, ghi nhận lại):**
+`spinner`, `loading indicator`, `animation`, `fade/slide`, màu sắc, font, layout pixel, micro-interaction → *"Chi tiết visual này thuộc Design Spec — ghi nhận để tạo Design Spec sau."*
+
+**Nhóm 3 — Backend/contract thuần → BỎ khỏi PRD (thuộc Tech Docs):**
+`API`, `endpoint`, `token/JWT`, `HTTP status`, tên class/bảng/cột DB, query, payload, header.
+*(Ngoại lệ DUY NHẤT: Appendix "Existing API Contract" khi `API Source: existing` — xem Platform Strategy.)*
+
+## Quy tắc áp dụng
+- Quét toàn bộ text sắp ghi (User Story, AC, BR, Business Logic, Scope, Edge Cases, Assumptions…).
+- Nhóm 1 → thay tại chỗ, giữ nguyên nghĩa nghiệp vụ. **Đồng bộ cách diễn đạt** với chỗ đã có sẵn trong cùng tài liệu (vd nếu "quá thời gian chờ" đã dùng ở một BR → dùng nhất quán ở mọi nơi).
+- Nhóm 2 → gỡ khỏi prose nghiệp vụ + nhắc chuyển Design Spec.
+- Nhóm 3 → gỡ khỏi PRD (trừ ngoại lệ brownfield).
+- Nếu term không có trong bản đồ nhưng rõ ràng là tên kỹ thuật/triển khai → vẫn diễn đạt lại theo tinh thần Nhóm 1, đừng để lọt.
+
+**Checklist (dùng ở Quality Checklist của lệnh):** 0 thuật ngữ kỹ thuật/UI (re-render, UI, timeout, spinner, API/endpoint/token…) trong prose nghiệp vụ — đã diễn đạt lại (Nhóm 1) / chuyển Design Spec (Nhóm 2) / bỏ về Tech Docs (Nhóm 3).
+
+
 ---
 
 ## Quy trình Review
@@ -413,10 +468,12 @@ dừng ở mức "đủ" findings, nên mỗi vòng review sau lại lòi ra v
 fan out song song theo các chiều review, rồi lặp một critic độ-đầy-đủ cho tới khi một
 vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
-Lệnh gọi cung cấp hai thứ:
+Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
   (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
+- **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
+- **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -428,8 +485,11 @@ Lệnh gọi cung cấp hai thứ:
 
 **Bao nhiêu sub-agent:** *số lượng* agent không phải là đòn bẩy độ đầy đủ — bề rộng được
 cố định bởi taxonomy DIMENSION (thêm agent vào cùng một dimension chỉ tìm lại cùng vấn đề),
-còn *độ sâu* thuộc về vòng lặp critic ở Phase 2. Chọn **độ mịn fan-out**
-theo kích thước target, tái dùng ngưỡng của `steps/spawn-agent.md`:
+còn *độ sâu* thuộc về vòng lặp critic ở Phase 2.
+
+**Nếu `GRANULARITY = per-uc`:** **bỏ qua bảng ngưỡng dưới đây**, luôn dùng độ mịn **DIMENSION × phạm vi UC** (kể cả PRD nhỏ) — đảm bảo quét sâu, không bỏ sót ngay lần đầu. (Cái giá: nhiều agent hơn cho PRD nhỏ — chấp nhận để lần đầu đầy đủ.)
+
+**Nếu `GRANULARITY = auto`** (mặc định): chọn **độ mịn fan-out** theo kích thước target, tái dùng ngưỡng của `steps/spawn-agent.md`:
 
 | Kích thước target | Độ mịn | Số agent |
 |-------------|-------------|-------------|
@@ -452,6 +512,7 @@ UC duy nhất — chính là điều ngăn bỏ sót trên các PRD lớn.
 agent). Giới hạn mỗi wave ở **`AGENT_CAP = 12`** agent và gom batch các phạm vi UC cho vừa:
 
 1. Dựng danh sách phạm vi = `[UC1, UC2, …, UCn, PRD-global]` (độ dài `UCs + 1`).
+   - **Nếu `CHANGED_SCOPE` được truyền (review delta):** danh sách phạm vi = `[các UC trong CHANGED_SCOPE] + [PRD-global]` (chỉ các UC đã đổi + global), KHÔNG phải tất cả UC. Số agent tụt theo đó.
 2. Tính số-phạm-vi-mỗi-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
    - Nếu `groups ≥ UCs + 1` → không cần batch, chạy một agent cho mỗi `DIMENSION × scope`.
    - Else chia danh sách phạm vi thành `groups` bucket liền kề kích thước xấp xỉ bằng nhau
@@ -493,10 +554,20 @@ Gom mảng findings của mọi sub-agent vào một danh sách hợp nhất `AL
 Đây là bước chống đập-chuột-chũi. Lặp cho tới khi **hai vòng liên tiếp thêm 0 finding
 mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
+> **Lưu ý delta:** kể cả khi `CHANGED_SCOPE` giới hạn Phase 1 vào các UC đã đổi, completeness-critic ở Phase 2 **vẫn đọc TOÀN bộ doc** — đây là lưới an toàn bắt các vấn đề mà một fix ở UC đã đổi có thể làm lộ ra ở chỗ khá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.
@@ -549,6 +620,19 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
 
 Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
 
+**Tham số truyền vào Quy trình Review:**
+- `GRANULARITY = per-uc` — LUÔN fan-out theo từng UC (bỏ ngưỡng cả-file), để **ngay lần đầu đã lòi phần nhiều issue**, không dồn sang lần sau.
+- `CHANGED_SCOPE` — xác định theo chế độ full/delta ngay dưới đây.
+
+**Chọn full vs delta** *(mặc định: lần đầu FULL, lần sau DELTA)*:
+1. Tách `--full` khỏi `$ARGUMENTS` nếu có.
+2. Kiểm tra `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
+   - **Không tồn tại** (lần đầu review PRD này) → **FULL**: KHÔNG truyền `CHANGED_SCOPE`.
+   - **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.
+
 **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ó:
 
@@ -567,10 +651,18 @@ 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
 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}"
 generated_at: "{ISO datetime}"
 status: "pending_review"
 
@@ -583,14 +675,32 @@ 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
+    resolution_edge_cases:   # CHỈ điền cho critical/major; minor → để [] (bỏ qua)
+      # Phân tích bậc-hai (advisory, KHÔNG chặn): nếu áp `suggestion` này thì có thể đẻ ra
+      # edge case / side-effect gì — path lỗi mới, va chạm với BR/UC khác, trạng thái biên,
+      # hệ luỵ cross-section. PO đọc để cân nhắc trước khi accept; nếu muốn xử lý → tạo finding mới.
+      - "{edge case có thể phát sinh nếu chốt phương án này}"
+    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.**
@@ -599,6 +709,14 @@ summary:
 > `uc_id` là Use Case sở hữu (hoặc `""` cho finding PRD-global). Hai field này cho phép reviewer click một
 > finding trong Review Board và nhảy thẳng tới đúng vị trí trong PRD nguồn.
 
+> **`resolution_edge_cases` — phân tích bậc-hai (chỉ critical/major).**
+> Với mỗi finding `critical`/`major`, sau khi viết `suggestion`, nghĩ tiếp: *nếu PO chốt phương án này thì
+> đẻ ra edge case / side-effect gì?* (path lỗi mới, va chạm BR/UC khác, trạng thái biên, hệ luỵ cross-section).
+> Ghi vào `resolution_edge_cases` để PO **thấy trước khi accept**. Đây là **advisory** — KHÔNG chặn, KHÔNG tự
+> tạo finding; PO đọc rồi quyết. Finding `minor` → để `[]`.
+> *(Phần phản hồi cho phương án PO **tự sửa** (`modified`) đến ở vòng sau: sau `--resume`, lần `/refine-prd`
+> kế chạy delta sẽ quét lại UC đã đổi + critic toàn-doc → tự lòi edge case mà phương án đó tạo ra.)*
+
 ## Report
 
 # Report Footer — Định dạng output chuẩn cho mọi lệnh
@@ -703,32 +821,64 @@ 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`:
+
+```
+---
+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:
+
 ```
-/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}
+⚠️  {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
 
 Với mỗi finding được chấp nhận, theo thứ tự severity (critical → major → minor):
 - Đi tới section PRD được chỉ định bởi `finding.section`.
 - Áp dụng `finding.suggestion`. Với finding `status: "modified"`, người đã sửa sẵn `finding.suggestion` trong Review Board — giá trị đã sửa đó CHÍNH LÀ bản fix cần áp dụng.
+- **Chạy Business Language Guard trên text mới TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ"): diễn đạt lại / gỡ thuật ngữ kỹ thuật-UI để fix không tự kéo theo term kỹ thuật vào PRD.
 - Không thay đổi bất kỳ section nào không được tham chiếu bởi một finding được chấp nhận.
 
 ### Phase 2.5 — Cập nhật file findings
@@ -736,7 +886,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
 
@@ -764,6 +916,8 @@ Changes  :
   - {change 1}
   - {change 2}
 
+💡 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:
     /review-context {prd-file}   ← kiểm tra chất lượng PRD trước
     → /generate-bdd {prd-file}