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

package/commands/generate-bdd.md

@@ -641,7 +641,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 - So với version PRD hiện tại.
 - Nếu **giống** → hỏi: "BDD đã sinh từ PRD v{version}. Gen lại? (Y/N)"
 - Nếu **khác** (PRD đã cập nhật):
-  1. Đọc `## Changelog` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
+  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
   2. Hiện CHECKPOINT:
      ```
      ⚠️  Phát hiện PRD version drift

package/commands/generate-bdd.tmpl

@@ -246,7 +246,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 - So với version PRD hiện tại.
 - Nếu **giống** → hỏi: "BDD đã sinh từ PRD v{version}. Gen lại? (Y/N)"
 - Nếu **khác** (PRD đã cập nhật):
-  1. Đọc `## Changelog` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
+  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
   2. Hiện CHECKPOINT:
      ```
      ⚠️  Phát hiện PRD version drift

package/commands/refine-prd.md

@@ -901,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} |
    ```

package/commands/refine-prd.tmpl

@@ -218,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} |
    ```

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
@@ -589,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
@@ -599,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.
 > ```
@@ -645,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:
@@ -669,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)
 
@@ -759,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"
@@ -945,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:**
 
@@ -1019,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 |

package/commands/review-context.tmpl

@@ -17,6 +17,11 @@ Nếu `$ARGUMENTS` chứa `--fix` → bỏ qua sang Fix Mode bên dưới (áp d
 
 ---
 
+## Ngôn ngữ nghiệp vụ *(áp khi viết — Fix Mode & Resume Mode)*
+{{include:steps/business-language.md}}
+
+---
+
 ## Phát hiện Review Mode
 
 Sau khi phân giải target file:
@@ -42,6 +47,19 @@ Suy ra tên file findings output:
 - **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
@@ -52,33 +70,35 @@ Suy ra tên file findings output:
 
 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.
 > ```
@@ -98,6 +118,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:
@@ -122,13 +145,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)
 
@@ -212,6 +242,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"
@@ -298,9 +329,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:**
 
@@ -372,11 +406,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 |

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.14.5
+0.14.6

package/core/commands/generate-bdd.md

@@ -641,7 +641,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 - So với version PRD hiện tại.
 - Nếu **giống** → hỏi: "BDD đã sinh từ PRD v{version}. Gen lại? (Y/N)"
 - Nếu **khác** (PRD đã cập nhật):
-  1. Đọc `## Changelog` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
+  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
   2. Hiện CHECKPOINT:
      ```
      ⚠️  Phát hiện PRD version drift

package/core/commands/refine-prd.md

@@ -901,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} |
    ```

package/core/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
@@ -589,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
@@ -599,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.
 > ```
@@ -645,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:
@@ -669,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)
 
@@ -759,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"
@@ -945,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:**
 
@@ -1019,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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edupia-tutor/spec-driven-docs",
-  "version": "0.14.5",
+  "version": "0.14.6",
   "description": "AI-First Spec-Driven Development workflow framework for Claude Code",
   "bin": {
     "spec-driven-docs": "./bin/index.js"