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

package/core/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}

package/core/commands/report-bug.md

@@ -27,6 +27,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/core/commands/review-code.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/core/commands/review-context.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).
 
@@ -437,10 +438,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
@@ -452,8 +455,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 |
 |-------------|-------------|-------------|
@@ -476,6 +482,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
@@ -517,10 +524,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.

package/core/commands/review-tech-docs.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/core/commands/setup-ai-first.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/core/commands/validate-traces.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/core/skills/code/SKILL.md

@@ -28,6 +28,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/core/skills/design-spec/SKILL.md

@@ -31,6 +31,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/core/skills/prd/SKILL.md

@@ -28,6 +28,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).
 
@@ -186,7 +187,7 @@ Template (cấu trúc đầu ra — single-source từ `templates/prd.template.m
 | **Domain**    | {domain}                                 |
 | **Created**   | {date}                                   |
 | **Updated**   | {date}                                   |
-| **Jira Ticket** | [{TICKET}-{N}]({ticket_url})            |
+| **Ticket**    | {TICKET}-{N}{ — nếu PO có link tracker thật, thêm bên cạnh: `{TICKET}-{N} ([Jira]({tracker_url}))`} |
 | **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
 
 ---
@@ -216,13 +217,21 @@ Template (cấu trúc đầu ra — single-source từ `templates/prd.template.m
 **Out of Scope** *(chỉ thêm khi có ranh giới cần nói rõ)*
 - {hạng mục ngoài phạm vi + lý do / chủ sở hữu}
 
+## c. Phụ thuộc liên service *(mức nghiệp vụ — KHÔNG mô tả API/event/kỹ thuật)*
+
+> Kế thừa từ Product Definition Phase 1 ("Phụ thuộc liên service"). Nếu contract do đối tác phát triển song song (xem `API Source`), ghi phụ thuộc partner vào đây.
+
+- {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
 ---
 
 # 2. Acceptance Criteria
 
-**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.}
+> Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
 
-**AC2:** {…}
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+
+**AC2:** {…} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
 ---
 
@@ -240,6 +249,8 @@ Template (cấu trúc đầu ra — single-source từ `templates/prd.template.m
 **Post-condition:**
 - {kết quả sau 1}
 
+**AC liên quan:** AC{x}, AC{y}  *(các AC mà UC này thoả — phải đúng bằng tập AC có ref BR trỏ về UC này ở §2)*
+
 **Business Rule**
 
 | ID | Business Rule | Business Logic |

package/core/skills/spec/SKILL.md

@@ -28,6 +28,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/core/skills/test/SKILL.md

@@ -28,6 +28,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/core/steps/business-language.md

@@ -0,0 +1,36 @@
+# 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).

package/core/steps/gate.md

@@ -13,6 +13,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/core/steps/review-fanout.md

@@ -6,10 +6,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
@@ -21,8 +23,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 |
 |-------------|-------------|-------------|
@@ -45,6 +50,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
@@ -86,10 +92,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.