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

package/commands/refine-prd.md

@@ -416,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
@@ -427,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
@@ -442,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 |
 |-------------|-------------|-------------|
@@ -466,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
@@ -507,6 +554,8 @@ 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 findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
@@ -571,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ó:
 
@@ -600,6 +662,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}"
 generated_at: "{ISO datetime}"
 status: "pending_review"
 
@@ -612,6 +675,11 @@ 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}"
+    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
@@ -641,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
@@ -802,6 +878,7 @@ Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau
 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
@@ -824,7 +901,7 @@ 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 `## Changelog` ở cuối PRD:
+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} |
    ```
@@ -839,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}

package/commands/refine-prd.tmpl

@@ -23,6 +23,11 @@ Nếu `$ARGUMENTS` không chứa `--resume` → tiếp tục luồng review bìn
 
 ---
 
+## Ngôn ngữ nghiệp vụ *(áp khi viết/áp fix — gồm cả Resume Mode Phase 2)*
+{{include:steps/business-language.md}}
+
+---
+
 ## Quy trình Review
 {{include:steps/review-fanout.md}}
 
@@ -32,6 +37,19 @@ Nếu `$ARGUMENTS` không chứa `--resume` → tiếp tục luồng review bìn
 
 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ó:
 
@@ -61,6 +79,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}"
 generated_at: "{ISO datetime}"
 status: "pending_review"
 
@@ -73,6 +92,11 @@ 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}"
+    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
@@ -102,6 +126,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
 
 {{include:steps/report-footer.md}}
@@ -163,6 +195,7 @@ Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau
 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
@@ -185,7 +218,7 @@ 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 `## Changelog` ở cuối PRD:
+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} |
    ```
@@ -200,6 +233,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}

package/commands/review-context.md

@@ -410,6 +410,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 — Fix Mode & Resume Mode)*
+# 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).
+
+
 ---
 
 ## Phát hiện Review Mode
@@ -438,10 +479,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
@@ -453,8 +496,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 |
 |-------------|-------------|-------------|
@@ -477,6 +523,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
@@ -518,6 +565,8 @@ 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 findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
@@ -581,6 +630,19 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
 - **Check do orchestrator chạy (không fan out):** `P0` (umbrella routing) và `P3` (xung đột cross-PRD) cần config / context của PRD khác — orchestrator tự chạy chúng **trước** fan-out và thêm kết quả vào `ALL_FINDINGS`.
 - Vòng lặp completeness-critic (Phase 2) đảm bảo file findings đầy đủ trong một lần chạy — chạy lại `/review-context` sẽ lòi ra **0 finding mới**. Map mỗi dimension vào field `check_id` của schema dưới đây.
 
+**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), để **cổng review bắt đủ lỗi ngay lần đầu** (cổng cuối trước khi sinh BDD — sót ở đây thì test sai theo).
+- `CHANGED_SCOPE` — theo full/delta 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 file findings của target (tên suy ở "Phát hiện Review Mode"):
+   - **Không tồn tại** (lần đầu) → **FULL**: KHÔNG truyền `CHANGED_SCOPE`.
+   - **Tồn tại** + có `--full` → **FULL**: bỏ qua findings cũ.
+   - **Tồn tại** + KHÔNG `--full` → so `source_version` trong findings cũ với version target hiện tại (PRD: Metadata `Version`; BDD: `@trace.bdd_version`):
+     - **Bằng nhau** (target chưa đổi từ lần review trước) → DỪNG, báo: `"Target 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** → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của finding đã xử lý (status `accepted`/`modified`/`applied_automatically`) trong findings cũ } ∪ { UC có trong target hiện tại nhưng chưa từng xuất hiện ở findings cũ }.
+
 ---
 
 ## PRD Review Mode
@@ -591,33 +653,35 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
 
 Khi `setup.mode = umbrella`, PRD phải có metadata routing đúng để context-loader Bước 1.5 có thể đưa output sinh ra tới đúng service submodule. Chạy các check này **trước P1–P5**:
 
-**P0.1 — `@trace.domain` có mặt**
-- Đọc block frontmatter của PRD (các dòng bắt đầu bằng `@trace.` ở đầu file)
-- Nếu `@trace.domain` **vắng mặt** → finding **critical**:
-  - `finding`: "`@trace.domain` đang thiếu. Umbrella routing của team dev phụ thuộc field này để đưa BDD và code output tới đúng service submodule."
-  - `suggestion`: "Thêm `@trace.domain: {domain}` vào frontmatter của PRD. Dùng một trong các domain key được định nghĩa trong section services của `project-context.yaml` của umbrella."
+> **Nguồn đọc:** PRD mang Domain/Status ở **bảng Metadata** (`| **Domain** | … |`, `| **Status** | … |`) — **KHÔNG** phải frontmatter `@trace.*` (cái đó dành cho file `.feature`/tech-docs do máy đọc). Routing umbrella dựa trên Domain (bảng) + path, đúng như context-loader Bước 1.5 và `generate-bdd` (đọc `| **Status** |`).
+
+**P0.1 — Row `Domain` có mặt trong Metadata**
+- Đọc bảng Metadata của PRD, lấy row `| **Domain** |`.
+- Nếu **vắng mặt / để trống** → finding **critical**:
+  - `finding`: "Row `Domain` trong bảng Metadata đang thiếu. Umbrella routing của team dev phụ thuộc Domain (+ path) để đưa BDD và code output tới đúng service submodule."
+  - `suggestion`: "Thêm `| **Domain** | {domain} |` vào bảng Metadata. Dùng một trong các domain key được định nghĩa trong section services của `project-context.yaml` của umbrella."
   - `auto_fixable: false` — PO phải confirm tên domain đúng
 
-**P0.2 — `@trace.domain` khớp một service key**
-- Nếu `@trace.domain` có mặt, kiểm tra giá trị của nó có khớp key nào trong section `services` của project-context.yaml không
+**P0.2 — `Domain` khớp một service key**
+- Nếu Domain có mặt, kiểm tra giá trị của nó có khớp key nào trong section `services` của project-context.yaml không.
 - Nếu **không khớp** → finding **critical**:
-  - `finding`: "`@trace.domain: {value}` không khớp key nào trong config `services` của umbrella. Routing sẽ fallback về path mặc định và BDD có thể được sinh sai chỗ."
-  - `suggestion`: "Hoặc cập nhật `@trace.domain` cho khớp một service key có sẵn ({list known keys}), hoặc thêm entry mới vào `services` trong project-context.yaml cho domain `{value}`."
+  - `finding`: "Domain `{value}` không khớp key nào trong config `services` của umbrella. Routing sẽ fallback về path mặc định và BDD có thể được sinh sai chỗ."
+  - `suggestion`: "Hoặc cập nhật row Domain cho khớp một service key có sẵn ({list known keys}), hoặc thêm entry mới vào `services` trong project-context.yaml cho domain `{value}`."
   - `auto_fixable: false`
 - Nếu section `services` chưa được cấu hình (rỗng/placeholder) → finding **major**:
   - `finding`: "Section `services` của umbrella chưa được cấu hình. Không thể kiểm chứng domain routing."
   - `suggestion`: "Cập nhật section services trong `.agent/project-context.yaml` với mapping domain-to-submodule trước khi sinh BDD."
   - `auto_fixable: false`
 
-**P0.3 — Check `@trace.status`**
-- Nếu `@trace.status` vắng mặt → **minor**, `auto_fixable: true` (thêm `@trace.status: draft`)
-- Nếu `@trace.status: draft` → **major**, `auto_fixable: false`:
+**P0.3 — Check row `Status` trong Metadata**
+- Nếu row `| **Status** |` **vắng mặt** → **minor**, `auto_fixable: true` (thêm `| **Status** | draft |`)
+- Nếu `Status: draft` → **major**, `auto_fixable: false`:
   - `finding`: "PRD status là `draft`. Team dev không nên sinh BDD từ một PRD chưa được duyệt."
-  - `suggestion`: "PO/SA nên review và cập nhật status thành `approved` trước khi team dev tiếp tục."
+  - `suggestion`: "PO/SA nên review và cập nhật Status thành `approved` trước khi team dev tiếp tục."
 
 > **P0 là một gate check:** Nếu P0.1 hoặc P0.2 cho finding critical, hiển thị cảnh báo trước khi tiếp tục:
 > ```
-> ⚠️  ROUTING WARNING: phát hiện vấn đề @trace.domain.
+> ⚠️  ROUTING WARNING: phát hiện vấn đề Domain trong Metadata.
 >    BDD/code sinh từ PRD này có thể rơi vào sai service submodule.
 >    Giải quyết các finding P0 trước khi chạy /generate-bdd.
 > ```
@@ -637,6 +701,9 @@ Quét toàn bộ PRD tìm vấn đề thuật ngữ:
 3. **Business term chưa liệt kê** — các term quan trọng vắng trong dictionary:
    → Severity: **minor**. Đề xuất thêm vào `business-dictionary.md`.
 
+4. **Thuật ngữ kỹ thuật/UI lọt vào prose nghiệp vụ** — theo baseline **Business Language Guard** (re-render, UI, timeout, spinner, API/endpoint/token…), không nằm trong dictionary nhưng vẫn là từ kỹ thuật:
+   → Severity: **major**, auto-fixable. `suggestion` theo guard: diễn đạt lại (Nhóm 1) / chuyển Design Spec (Nhóm 2) / bỏ về Tech Docs (Nhóm 3).
+
 ### P2 — Ambiguity Check
 
 Quét mỗi AC và BR tìm:
@@ -661,13 +728,20 @@ hoặc định nghĩa lại field/status transition của một entity khác đi
 
 ### P4 — Structural Completeness
 
-- [ ] Block Metadata: Version, Author, Date, Status
-- [ ] Ít nhất 1 UC với heading `#### {TICKET-ID}-UC{N}:`
-- [ ] Mỗi UC có: Description, Actors, Preconditions, Acceptance Criteria, Business Rules
-- [ ] Có section `## Changelog`
+Đối chiếu với cấu trúc template PRD (Metadata · §1 Tổng quan · §2 AC · §3 UC · §4 UI/UX · Appendix · Change Log):
+
+- [ ] **Metadata** có: Version, Status, Author, Created, Updated, Domain, Ticket (PO nếu có)
+- [ ] **§1c "Phụ thuộc liên service"** có mặt (hoặc ghi rõ "Không có")
+- [ ] **§2 Acceptance Criteria** (global) có mặt; **mỗi AC** kết thúc bằng ref `_(BR: …)_` (≥1 BR)
+- [ ] **≥1 UC** với heading `#### {TICKET-ID}-UC{N}:`
+- [ ] Mỗi UC có: **Actor, Description, Pre-condition, Post-condition, AC liên quan**, bảng Business Rule (AC là §2 global — UC chỉ trỏ qua "AC liên quan", KHÔNG chứa AC đầy đủ)
+- [ ] **Nhất quán 2 chiều**: tập "AC liên quan" của mỗi UC = tập AC §2 có ref BR trỏ về UC đó
+- [ ] **§4 UI/UX**: có User Flow và **Wireframe** (Wireframe lái coverage BDD C.1)
+- [ ] **API Source nhất quán**: nếu Metadata `API Source: existing` → Appendix "Existing API Contract" đủ method/path/request/response (hoặc có block ⛔ PENDING + con trỏ nguồn); nếu greenfield/partner (API Source trống) → section "Existing API Contract" đã bị **xoá hẳn** (không để bảng rỗng)
+- [ ] Có section `# Change Log`
 - [ ] Không còn giá trị `{{PLACEHOLDER}}` chưa điền
 
-→ Section thiếu: **major**. AI có thể thêm skeleton khi `--resume` nếu được chấp nhận.
+→ Section/field thiếu hoặc lệch cấu trúc: **major**. AI có thể thêm skeleton khi `--resume` nếu được chấp nhận. Riêng **"Nhất quán 2 chiều"** lệch → **major**, `auto_fixable: false` (người xác nhận AC↔UC, AI không tự đoán). **API Source: existing thiếu contract** → **major**, `auto_fixable: false` (cần nguồn contract); **greenfield còn sót section "Existing API Contract" rỗng** → **minor**, `auto_fixable: true` (xoá section).
 
 ### P5 — Custom Criteria (tuỳ chọn)
 
@@ -751,6 +825,7 @@ Sau khi chạy hết các check, ghi `{paths.refinement_dir}/{slug}-review-*-fin
 
 ```yaml
 source_file: "{absolute path to reviewed file}"
+source_version: "{version target lúc sinh findings — PRD: Metadata Version; BDD: @trace.bdd_version — dùng chọn full/delta lần chạy sau}"
 generated_at: "{ISO datetime}"
 review_type: "{prd | bdd}"
 status: "pending_review"
@@ -937,9 +1012,12 @@ Với mỗi finding có `auto_fixable: true`, theo thứ tự (critical → majo
 
 | check_id | Áp dụng gì |
 |----------|--------------|
-| P0.3 (Thiếu status) | Thêm `@trace.status: draft` vào frontmatter |
+| P0.3 (Thiếu status) | Thêm row `| **Status** | draft |` vào bảng Metadata |
 | P1 (Banned term) | Thay mọi lần xuất hiện banned term bằng canonical term |
-| P4 (Structure) | Thêm skeleton section/metadata còn thiếu |
+| P1 (Thuật ngữ kỹ thuật/UI) | Diễn đạt lại theo Business Language Guard (Nhóm 1) / chuyển Design Spec (2) / bỏ về Tech Docs (3) |
+| P4 (Structure) | Thêm skeleton section/metadata còn thiếu; greenfield → xoá section "Existing API Contract" rỗng |
+
+> **Chạy Business Language Guard trên text vừa sửa TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ") — không để bản auto-fix tự kéo thuật ngữ kỹ thuật vào.
 
 **Với file BDD:**
 
@@ -1011,11 +1089,13 @@ Mở file findings trong Review Board → rồi chạy: /review-context --resume
 
 Áp dụng theo thứ tự: critical → major → minor.
 
+> **Chạy Business Language Guard trên text vừa sửa TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ") — đặc biệt với P2 (sửa câu mơ hồ) / P4 skeleton: không để bản fix tự kéo thuật ngữ kỹ thuật-UI vào PRD.
+
 **Với finding PRD:**
 | check_id | Làm gì |
 |----------|-----------|
-| P0.3 (Thiếu status) | Thêm `@trace.status: draft` vào frontmatter |
-| P1 (Banned term) | Thay mọi lần xuất hiện banned term bằng canonical term |
+| P0.3 (Thiếu status) | Thêm row `| **Status** | draft |` vào bảng Metadata |
+| P1 (Banned term) | Thay banned term bằng canonical; thuật ngữ kỹ thuật/UI → diễn đạt lại theo Business Language Guard |
 | P2 (Ambiguity) | Áp dụng fix nêu trong `suggestion` hoặc note `modified` |
 | P3 (Conflict) | Áp dụng cách giải quyết nêu trong note modified |
 | P4 (Structure) | Thêm section/metadata field còn thiếu |