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

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
@@ -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
@@ -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

@@ -438,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
@@ -453,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 |
 |-------------|-------------|-------------|
@@ -477,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
@@ -518,6 +524,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

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.14.4
+0.14.5

package/core/commands/define-product.md

@@ -403,6 +403,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 BR / AC / Business Logic / Scope)*
+# 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).
+
+
 ---
 
 ## Phase 0 — Knowledge Sync *(AI tự điền — bối cảnh hệ thống, KHÔNG phải yêu cầu nghiệp vụ; không cần input PO)*
@@ -457,8 +498,12 @@ Hỏi:
    ```
    | Bước | Hành động | Trạng thái/Kết quả nghiệp vụ | Ghi chú |
    ```
-3. **Exit Point**: Kết quả cuối khi flow hoàn thành là gì?
-4. **Edge Cases**: Các kịch bản thất bại nghiệp vụ ngoài happy path? (input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng → kết quả nghiệp vụ kỳ vọng)
+3. **Màn hình & thành phần chính** *(mức nghiệp vụ — KHÔNG pixel/layout/màu)*: Feature gồm những **màn hình / bước giao diện** chính nào? Mỗi màn có **thành phần & hành động chính** gì (vd: ô nhập, nút, danh sách → bấm ra kết quả gì)? Đây là nguồn cho Wireframe của PRD và độ phủ BDD — nếu PO không chắc, AI gợi ý rồi PO xác nhận.
+   ```
+   | Màn hình | Thành phần chính | Hành động → kết quả nghiệp vụ |
+   ```
+4. **Exit Point**: Kết quả cuối khi flow hoàn thành là gì?
+5. **Edge Cases**: Các kịch bản thất bại nghiệp vụ ngoài happy path? (input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng → kết quả nghiệp vụ kỳ vọng)
 
 Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
@@ -551,6 +596,10 @@ Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/prod
 > viết thường, chỉ a-z 0-9 và dấu `-`. Đây là định danh feature-package dùng xuyên suốt pipeline —
 > PRD, BDD, tech-docs, design-spec, trace của feature này đều kế thừa **nguyên văn** `slug` này
 > (`/generate-prd` đặt `prd-slug = slug`). Sinh một lần ở đây, các bước sau KHÔNG tái sinh.
+>
+> **Ranh giới tên file:** tên file = `{TICKET-ID}-{slug}.md`. TICKET-ID **được phép chứa `-`**
+> (vd Jira key `LOYAL-29` → `LOYAL-29-loyalty-points.md`). Khi tách lại slug, các bước sau strip
+> **đúng chuỗi TICKET-ID** ở đầu, KHÔNG tách theo dấu `-` đầu tiên.
 
 Điền tất cả section bằng dữ liệu thu thập qua các phase.
 

package/core/commands/generate-bdd.md

@@ -567,17 +567,21 @@ Từ vựng step của System BDD (luôn dùng — bất kể từ vựng FE/App
 
 *Bỏ qua section này nếu đang chạy spec repo mode.*
 
-Đọc bảng Metadata của PRD tìm row `| **Service** |` và `| **Module** |`.
+Routing service là **domain-keyed** và **context-loader (Bước 1.5) đã phân giải sẵn** từ `@trace.domain`/Domain của PRD — KHÔNG re-resolve ở đây, chỉ dùng lại các biến đã set:
+- `active_service` = `services.{domain}.path` (path submodule, vd `user-service/`) — hoặc `"unresolved"` nếu domain không khớp entry nào, hoặc bỏ trống ở single-service.
+- `active_module` = module của service (`services.{domain}.module`, đã override `tech_stack.module` ở Bước 1.5) — dùng cho từ vựng bên dưới.
 
-| Điều kiện | Hành động |
+Chỉ cần kiểm tra trạng thái đã phân giải:
+
+| Trạng thái (từ context-loader) | Hành động |
 |---|---|
-| PRD có row `Service` VÀ giá trị không phải "default" | Dùng làm `active_service` + `active_module`. Nạp catalog cho module đó. |
-| PRD không có row `Service` VÀ `services` được định nghĩa trong project-context.yaml | Hỏi: "BDD này dành cho service nào?" (liệt kê service, chờ chọn) |
-| Dự án single-service (không có mảng `services`) | `active_service = "default"`, `active_module = tech_stack.module` |
+| `active_service` đã phân giải thành path service | Tiếp tục với `active_module` đã set. |
+| `active_service = "unresolved"` (có section `services` nhưng domain PRD không khớp entry nào) | **DỪNG**, báo: "Domain `{domain}` của PRD không khớp service nào trong `services:` của project-context.yaml — bổ sung mapping rồi chạy lại." (Không đoán/hỏi tay — domain là khoá định danh, lệch là lỗi cấu hình cần sửa ở SoT.) |
+| Single-service (không có section `services`) | `active_module = tech_stack.module` (đã set ở Bước 6.5). Tiếp tục. |
+
+**Output path (umbrella mode):** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature`
 
-**Output path (umbrella mode):**
-- `active_service = "default"` → `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature`
-- `active_service ≠ "default"` → `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_service}/{TICKET-ID}-UC{N}-{slug}.feature`
+*(Không thêm subfolder theo service: feature-package đã domain-scoped sẵn ở `{domain}/`, mà service route 1-1 theo domain — nên thêm subfolder service sẽ chỉ lặp lại domain. `active_service` chỉ dùng cho `service_root`/từ vựng, KHÔNG vào path spec.)*
 
 **Từ vựng theo platform** — điều chỉnh cách viết step BDD theo `active_module`:
 
@@ -627,7 +631,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 
 1. Phân giải search path theo mode:
    - **Spec repo mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC*.feature`
-   - **Umbrella mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC*.feature` (hoặc với `{active_service}/` nếu multi-service)
+   - **Umbrella mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC*.feature`
 2. Đọc `| **Version** |` hiện tại của PRD từ metadata (vd: `1.2`).
 
 **Nếu không có file feature nào** → gen mới, tiếp tục bình thường. Dùng version PRD làm `@trace.prd_version`.
@@ -732,8 +736,7 @@ CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào kh
 
 **Output path theo mode:**
 - **Spec repo mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature`
-- **Umbrella mode (single-service)**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature`
-- **Umbrella mode (multi-service)**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_service}/{TICKET-ID}-UC{N}-{slug}.feature`
+- **Umbrella mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature` *(service route 1-1 theo domain → không thêm subfolder service)*
 
 Với mỗi UC, ghi vào path đã phân giải ở trên. Dùng từ vựng cho active platform (từ Platform Selection hoặc Service Detection).
 

package/core/commands/generate-prd.md

@@ -405,9 +405,17 @@ Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 *Context bổ sung cho lệnh này: Đọc toàn bộ file product-definition. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, **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.
 
-**Phân giải `slug`** (kế thừa, KHÔNG tái sinh): lấy `slug` từ tên file product-definition — đoạn sau `{TICKET-ID}-` (vd `LOYAL29-loyalty-points.md` → `slug = loyalty-points`). Đặt `prd-slug = slug` này cho feature-package PRD, để folder `{specs_dir}/{domain}/{prd-slug}/` khớp 1-1 với product-definition. KHÔNG tự bịa slug mới — nếu tên file không theo dạng `{TICKET-ID}-{slug}.md`, dừng và hỏi người dùng.
+**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.
@@ -419,7 +427,24 @@ Tiếp tục sang bước kế tiếp của lệnh đang gọi.
   ```
   PRD là artifact ký duyệt — không sinh từ nguồn discovery chưa chốt.
 
-CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domain: {domain}), PO: **{tên PO — hoặc hỏi nếu product-definition để trống}**. Nguồn: discovery hoàn tất (Phase 7/7). Tiếp tục? (Y/N)"
+**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)"
 
 ---
 
@@ -435,6 +460,45 @@ CHECKPOINT trước khi sinh: "Sinh PRD cho **{TICKET-ID} — {feature}** (domai
   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ụ
+# 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 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:
@@ -449,6 +513,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)
@@ -456,6 +526,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 |
@@ -529,7 +601,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 | **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)* |
 
 ---
@@ -559,13 +631,21 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 **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.
+
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
-**AC2:** {…}
+**AC2:** {…} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
 ---
 
@@ -583,6 +663,8 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 **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 |
@@ -693,10 +775,14 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 
 - [ ] 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