@educa-corp/fw 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 > `fw install` in các mục của những version mới hơn bản đang cài trong dự án.
 > Mỗi lần sửa lệnh, khuôn, bộ câu hỏi hay công cụ đều phải tăng version và thêm một mục ở đây. Test sẽ báo lỗi nếu version chưa có mục.
 
+## 0.6.1 — 2026-09-30
+
+- Thuật ngữ: **Acceptance Criteria (điều kiện nghiệm thu)**, viết tắt AC, thay cho "tiêu chí chấp nhận". **Business Rule (BR)** thay cho "rule". Cột "Logic" của bảng BR đổi thành **Business Logic**.
+- Epic đánh số Business Rule là `BR1.`, `BR2.`… (trước đây là `R1.`). `spec_edit upgrade` tự đổi mã trong epic cũ, và trong phần `(nguồn: …)` của PRD cũ. `coverage` coi `R3` và `BR3` là cùng một mã.
+- `(nguồn: …)` **chỉ được ghi mã**: `BR3` / `AC1` của epic, `CON-02`, hoặc `PRD` (mục thêm khi viết PRD, PO đã duyệt). `spec_edit` chặn khi tạo hoặc sửa PRD còn ghi nguồn bằng lời. `coverage` báo lỗi khi nguồn là mã không có trong epic.
+- PRD đã tạo bằng bản cũ: lần sửa đầu tiên sẽ yêu cầu đổi các chỗ ghi nguồn bằng lời thành mã (thường là `PRD`).
+
 ## 0.6.0 — 2026-09-30
 
 - Sẵn sàng publish lên npmjs với tên **`@educa-corp/fw`**. Cài lần đầu: `npx @educa-corp/fw install`.

package/commands/prd.md

@@ -5,7 +5,7 @@ argument-hint: "<EPIC-ID> [change <mô tả thay đổi>] [--force]"
 
 # /prd
 
-Mục đích: biến epic đã làm rõ (`/product`) thành **PRD chính thức**, gồm các use case, rule và tiêu chí chấp nhận có **mã ổn định**. Sau đó PRD là nguồn cho BDD, TDD và code.
+Mục đích: biến epic đã làm rõ (`/product`) thành **PRD chính thức**, gồm các use case, Business Rule (BR) và **Acceptance Criteria (điều kiện nghiệm thu)**, viết tắt **AC**, có **mã ổn định**. Sau đó PRD là nguồn cho BDD, TDD và code.
 
 - `/prd <EPIC-ID>`: tạo PRD từ epic `ready`.
 - `/prd <EPIC-ID> change <mô tả>`: thêm, sửa hoặc bỏ nội dung trong PRD đã có.
@@ -21,7 +21,7 @@ Nếu **trước lệnh này** phiên đã có hội thoại khác, dòng đầu
    - Không có `.fw/config.yaml`: dừng và báo *"Chưa cài framework. Chạy `npx @educa-corp/fw install` ở thư mục gốc dự án."*
 2. Tìm file epic: `{specs}/product/epics/{EPIC-ID}-*.md`. Đọc frontmatter để lấy `slug`, `domain`, `status`.
 3. File PRD: `D = {specs}/{domain}/{slug}/prd.md`.
-4. Đọc `{specs}/product/glossary.md` nếu có, và `SE section {specs}/product/product.md constraints`. Viết đúng thuật ngữ. PRD không được đi ngược ràng buộc nào. Rule bắt nguồn từ ràng buộc thì ghi `(nguồn: CON-01)`. `SE` báo không có mục đó (khuôn cũ): coi như chưa có ràng buộc, và nhắc một dòng *"Chạy `/product` để bổ sung Ràng buộc và Giai đoạn cho tầng sản phẩm."*
+4. Đọc `{specs}/product/glossary.md` nếu có, và `SE section {specs}/product/product.md constraints`. Viết đúng thuật ngữ. PRD không được đi ngược ràng buộc nào. BR bắt nguồn từ ràng buộc thì ghi `(nguồn: CON-01)`. `SE` báo không có mục đó (khuôn cũ): coi như chưa có ràng buộc, và nhắc một dòng *"Chạy `/product` để bổ sung Ràng buộc và Giai đoạn cho tầng sản phẩm."*
 
 ## Bước 2 — Chọn chế độ
 
@@ -36,7 +36,7 @@ Nếu **trước lệnh này** phiên đã có hội thoại khác, dòng đầu
 ## Bước 3 — Luật chung
 
 1. **Mã ổn định.** `UC-NNN` đánh số trên toàn sản phẩm. `UC-NNN-BRnn`, `UC-NNN-ACnn` đánh số trong từng UC. Mã đã cấp thì **không bao giờ đổi, không dùng lại**. Thêm mới thì lấy số kế tiếp trong UC đó. Mục bỏ đi thì giữ dòng, gạch ngang nội dung, và ghi *"Đã bỏ (v…)"*.
-2. **Nguồn.** Mọi rule và tiêu chí lấy từ epic phải ghi `(nguồn: R3, AC1)`, đúng mã của epic.
+2. **Nguồn.** Mọi BR và AC phải ghi `(nguồn: …)`, và **chỉ ghi mã**: mã epic (`BR3`, `AC1`), ràng buộc (`CON-02`), hoặc `PRD` (thêm khi viết PRD, PO đã duyệt). Không ghi lời giải thích. `SE` chặn nếu sai.
 3. **Dấu.** Nội dung chuyển nguyên ý từ mục `✅` của epic thì giữ `✅`. Chỗ nào AI **tự thêm, tách hoặc suy ra** thì gắn `🤖`. Chỉ PO mới đổi được `🤖` thành `✅`.
 4. **Ngôn ngữ nghiệp vụ.** Không nói API, bảng dữ liệu hay framework.
 5. **Tối đa 4 câu hỏi mỗi lượt, tính cả câu phụ.**
@@ -56,7 +56,7 @@ In ra đúng khối sau:
 ---
 Trạng thái : {✅ Đã duyệt v{version} | 🟡 Nháp v{version} — còn {n} mục 🤖, {k} câu hỏi mở}
 Đã ghi     : {D} {· epic → handed-off · product.md nếu có}
-Kiểm       : coverage {đủ | thiếu …} · {số UC} UC · {số BR} rule · {số AC} tiêu chí
+Kiểm       : coverage {đủ | thiếu …} · {số UC} UC · {số BR} BR · {số AC} AC
 Luồng      : Product → [PRD ◀ bạn ở đây] → BDD → TDD · Design-spec → Code → Test → QC
 Bước tiếp  : {/bdd UC-xxx | trả lời / xác nhận các mục trên | `/clear` rồi `/prd {id}` để tiếp}
 ```

package/commands/product.md

@@ -63,7 +63,7 @@ Trước checkpoint 1 của epic, AI tự điền mục **Bối cảnh hệ th
 - Tạo file mới: `SE create <file> <<'EOF'` … nội dung … `EOF`
 - Sửa nội dung: `SE edit <file> <<'EOF'` `[{"old": "…", "new": "…"}]` `EOF`. Gom mọi chỗ sửa của một lượt vào **một** lần gọi. Đoạn lặp giống nhau thì thêm `"all": true`.
 - Frontmatter: `SE set <file> checkpoint=1 open_questions=3 updated=YYYY-MM-DD`
-- Xem các mục còn chờ PO: `SE pending <file>`. PO xác nhận các mục có mã: `SE confirm <file> AC2 AC3 R8b`
+- Xem các mục còn chờ PO: `SE pending <file>`. PO xác nhận các mục có mã: `SE confirm <file> AC2 AC3 BR8b`
 - Đọc một mục: `SE section <file> <mã>` (mã là `<!-- sec:… -->` ở tiêu đề). **Luôn tìm mục theo mã**, không theo số hay tên. Khi sửa, giữ nguyên `<!-- sec:… -->`.
 - `SE` báo lỗi thì **không có gì được ghi**. Đọc lại file, sửa lệnh rồi chạy lại. Không bỏ qua lỗi. Lỗi mà **không in dòng nào** là Python chưa kịp chạy: chạy lại đúng lệnh đó một lần.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/fw",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Framework làm việc với Claude Code cho phòng PTPM",
   "bin": {
     "fw": "bin/fw.js"

package/ref/prd/change.md

@@ -5,9 +5,9 @@ Dùng cho **mọi** thay đổi: thêm, sửa, bỏ. Mã không bao giờ đánh
 ## Lượt 1 — Kế hoạch thay đổi
 
 1. Đọc `D`. Lấy mô tả thay đổi từ `$ARGUMENTS`. Không có mô tả thì hỏi PO *"Bạn muốn đổi gì?"* rồi dừng.
-2. Xác định các mục bị ảnh hưởng. Mô tả thay đổi có thể kéo theo mục khác (một rule đổi thì tiêu chí liên quan cũng phải đổi), nên phải tìm cả những mục đó.
+2. Xác định các mục bị ảnh hưởng. Mô tả thay đổi có thể kéo theo mục khác (một Business Rule (BR) đổi thì AC liên quan cũng phải đổi), nên phải tìm cả những mục đó.
 3. Cấp mã cho mục mới:
-   - Rule hoặc tiêu chí mới trong UC có sẵn: số lớn nhất **đang có trong UC đó**, kể cả dòng đã bỏ, cộng một.
+   - BR hoặc AC mới trong UC có sẵn: số lớn nhất **đang có trong UC đó**, kể cả dòng đã bỏ, cộng một.
    - UC mới: `SE next-uc {specs}`.
 4. Trình kế hoạch:
 
@@ -25,7 +25,7 @@ Dùng cho **mọi** thay đổi: thêm, sửa, bỏ. Mã không bao giờ đánh
 Khi PO đồng ý kế hoạch:
 
 1. **Một** lần `SE edit D` cho mọi chỗ sửa:
-   - Mục sửa và mục thêm mang `✅`, vì PO vừa duyệt kế hoạch.
+   - Mục sửa và mục thêm mang `✅`, vì PO vừa duyệt kế hoạch. Mục thêm ghi `(nguồn: PRD)`, trừ khi lấy từ một mã epic hay ràng buộc cụ thể.
    - Mục bỏ: giữ dòng, gạch ngang nội dung, ghi *"Đã bỏ (v{mới})"*.
    - Thêm dòng vào **5. Lịch sử thay đổi**, dạng *"v1.1 — UC-003: khoá sau 3 lần sai (BR02 sửa, AC05 thêm, BR04 bỏ)"*.
 2. Tăng version phụ (1.0 → 1.1): `SE set D version=1.1 updated=…`. PRD đang `approved` thì đặt luôn `status=draft approved_by=— approved_at=—`.

package/ref/prd/new.md

@@ -8,15 +8,15 @@ Chỉ **2 lượt** hỏi-đáp, vì epic đã được làm rõ kỹ. Không h
 2. Chạy `SE next-uc {specs}` để lấy mã UC đầu tiên. Các UC tiếp theo tăng dần từ mã đó.
 3. Đề xuất cách chia UC.
    - **Một UC = một mục tiêu của một actor**, xong trong một lần tương tác. Ví dụ "Đổi và quên mật khẩu", không phải "Quản lý bảo mật".
-   - Mỗi UC nên có khoảng 2–8 rule. Nhiều hơn thì cân nhắc tách, ít hơn một thì cân nhắc gộp.
-   - **Mọi `R…` và `AC…` của epic phải thuộc ít nhất một UC.** Một rule áp cho nhiều UC thì ghi ở tất cả các UC đó.
+   - Mỗi UC nên có khoảng 2–8 Business Rule (BR). Nhiều hơn thì cân nhắc tách, ít hơn một thì cân nhắc gộp.
+   - **Mọi `BR…` và `AC…` của epic phải thuộc ít nhất một UC.** Một BR áp cho nhiều UC thì ghi ở tất cả các UC đó.
 4. Trình cho PO dạng bảng:
 
 | UC | Tên | Actor | Lấy từ epic |
 |---|---|---|---|
-| UC-001 | … | ACT-01 | R8, R9, R10, AC4, AC5 |
+| UC-001 | … | ACT-01 | BR8, BR9, BR10, AC4, AC5 |
 
-   Kèm tối đa 3 câu hỏi khác, chỉ khi cần. Ví dụ: một rule nên đặt vào UC nào, hoặc hai UC có nên gộp không. Không có gì cần hỏi thì chỉ hỏi *"Cách chia này được chưa?"*.
+   Kèm tối đa 3 câu hỏi khác, chỉ khi cần. Ví dụ: một BR nên đặt vào UC nào, hoặc hai UC có nên gộp không. Không có gì cần hỏi thì chỉ hỏi *"Cách chia này được chưa?"*.
 
 ## Lượt 2 — Viết PRD
 
@@ -24,10 +24,10 @@ Khi PO đồng ý cách chia UC:
 
 1. Tạo `D` bằng **một** lần `SE create`, theo khuôn `.fw/core/templates/prd.md`:
    - **1. Tổng quan:** chuyển từ checkpoint 1 của epic. Ghi các ràng buộc `CON-xx` áp cho epic này.
-   - **2. Use case:** mỗi UC gồm điều kiện trước, kết quả sau, luồng chính (lấy các bước liên quan ở checkpoint 2 của epic), bảng rule, tiêu chí.
-     - **Cột Rule:** một rule mỗi dòng, dạng *"Hệ thống PHẢI / KHÔNG ĐƯỢC …"*.
-     - **Cột Logic:** rẽ nhánh, công thức, thông báo khi lỗi. Lấy từ edge case và nhật ký làm rõ của epic.
-     - **Tiêu chí:** dạng *"Khi … thì …"*, mô tả **kết quả nhìn thấy được**, không mô tả cơ chế.
+   - **2. Use case:** mỗi UC gồm điều kiện trước, kết quả sau, luồng chính (lấy các bước liên quan ở checkpoint 2 của epic), bảng BR, Acceptance Criteria (điều kiện nghiệm thu).
+     - **Cột Business Rule:** một BR mỗi dòng, dạng *"Hệ thống PHẢI / KHÔNG ĐƯỢC …"*.
+     - **Cột Business Logic:** rẽ nhánh, công thức, thông báo khi lỗi. Lấy từ edge case và nhật ký làm rõ của epic.
+     - **AC:** dạng *"Khi … thì …"*, mô tả **kết quả nhìn thấy được**, không mô tả cơ chế.
    - **3. Màn hình:** chuyển từ "Màn hình chính" của epic, kèm cột UC.
    - **4. Câu hỏi còn mở:** chỉ những gì phát sinh khi viết PRD.
    - **5. Lịch sử thay đổi:** dòng `1.0`.

package/ref/product/epic.md

@@ -39,12 +39,12 @@ Mỗi câu hỏi và câu trả lời được ghi vào **Nhật ký làm rõ**.
 
 ## Checkpoint 3 — Chốt để sang PRD
 
-1. Từ checkpoint 1–2 và nhật ký, AI **đề xuất** danh sách rule nghiệp vụ, dạng *"Hệ thống PHẢI / KHÔNG ĐƯỢC …"*. Đánh số `R1.`, `R2.`… ở đầu dòng. Chèn giữa thì dùng `R8a.`, **không đánh số lại**, vì `/prd` dùng các mã này để kiểm không rơi rule nào.
-2. AI **đề xuất** tiêu chí chấp nhận, dạng *"Khi … thì …"*, đánh số `AC1.`, `AC2.`…. Mỗi tiêu chí phải kiểm được là đạt hay không đạt.
+1. Từ checkpoint 1–2 và nhật ký, AI **đề xuất** danh sách Business Rule (BR), dạng *"Hệ thống PHẢI / KHÔNG ĐƯỢC …"*. Đánh số `BR1.`, `BR2.`… ở đầu dòng. Chèn giữa thì dùng `BR8a.`, **không đánh số lại**, vì `/prd` dùng các mã này để kiểm không rơi BR nào.
+2. AI **đề xuất** Acceptance Criteria (điều kiện nghiệm thu), dạng *"Khi … thì …"*, đánh số `AC1.`, `AC2.`…. Mỗi AC phải kiểm được là đạt hay không đạt.
 3. **Tự kiểm độ phủ** trước khi trình cho PO:
-   - Mỗi bước trong luồng chính có ít nhất một rule hoặc tiêu chí.
+   - Mỗi bước trong luồng chính có ít nhất một BR hoặc AC.
    - Mỗi edge case có kết quả mong muốn.
-   - Không có hai rule mâu thuẫn nhau.
+   - Không có hai BR mâu thuẫn nhau.
 4. Trình cho PO. PO chốt từng mục. Mục nào PO chưa chốt thì giữ dấu `🤖`.
 
 Chỉ đặt `status: ready` khi đủ cả hai điều kiện: **mọi mục đều mang dấu `✅`** và **mục `sec:open` = "Không còn"**. Còn câu hỏi mở thì vẫn ghi file, `status` giữ `in-progress`.

package/templates/prd.md

@@ -14,7 +14,7 @@ updated: {YYYY-MM-DD}
 > PRD chính thức. Nguồn làm rõ yêu cầu: `{đường dẫn file epic}` (chỉ còn là lịch sử, không sửa tiếp ở đó).
 > Dấu: `✅` = PO đã xác nhận · `🤖` = AI thêm khi viết PRD, chờ PO chốt.
 > Mã (`UC-…`, `…-BR…`, `…-AC…`) **không bao giờ đổi, không dùng lại**. Mục bỏ đi thì gạch ngang và ghi "Đã bỏ (v…)".
-> `(nguồn: R3, AC1)` = mục lấy từ rule / tiêu chí nào của epic.
+> `(nguồn: …)` chỉ ghi mã: `BR3` / `AC1` của epic · `CON-02` (ràng buộc) · `PRD` (thêm khi viết PRD, PO đã duyệt).
 
 ## 1. Tổng quan <!-- sec:overview -->
 
@@ -42,13 +42,13 @@ updated: {YYYY-MM-DD}
 |---|---|---|
 | 1 | {…} | {…} |
 
-**Rule**
+**Business Rule (BR)**
 
-| Mã | Rule | Logic | Nguồn |
+| Mã | Business Rule | Business Logic | Nguồn |
 |---|---|---|---|
-| ✅ UC-{NNN}-BR01 | {Hệ thống PHẢI / KHÔNG ĐƯỢC …} | {rẽ nhánh, công thức, điều kiện; thông báo khi lỗi} | (nguồn: R1) |
+| ✅ UC-{NNN}-BR01 | {Hệ thống PHẢI / KHÔNG ĐƯỢC …} | {rẽ nhánh, công thức, điều kiện; thông báo khi lỗi} | (nguồn: BR1) |
 
-**Tiêu chí chấp nhận**
+**Acceptance Criteria (điều kiện nghiệm thu)**
 
 - ✅ UC-{NNN}-AC01. Khi {…} thì {…}. (nguồn: AC1)
 

package/templates/product-epic.md

@@ -49,17 +49,17 @@ updated: {YYYY-MM-DD}
 
 ## Checkpoint 3 — Chốt để sang PRD <!-- sec:cp3 -->
 
-**Rule nghiệp vụ** (bản nháp, PRD sẽ viết chính thức). Đánh số `R1.`, `R2.`…; chèn thêm giữa thì dùng `R8a.`, không đánh số lại:
-- 🤖 R1. {Hệ thống PHẢI / KHÔNG ĐƯỢC …}
+**Business Rule (BR)** (bản nháp, PRD sẽ viết chính thức). Đánh số `BR1.`, `BR2.`…; chèn thêm giữa thì dùng `BR8a.`, không đánh số lại. Sang PRD sẽ thành `UC-xxx-BRnn`:
+- 🤖 BR1. {Hệ thống PHẢI / KHÔNG ĐƯỢC …}
 
-**Tiêu chí chấp nhận** (bản nháp). Đánh số `AC1.`, `AC2.`…:
+**Acceptance Criteria (điều kiện nghiệm thu)** (bản nháp). Đánh số `AC1.`, `AC2.`…:
 - 🤖 AC1. {Khi … thì …}
 
 ## Nhật ký làm rõ <!-- sec:log -->
 
 | Vòng | # | Nhóm | Câu hỏi | PO trả lời |
 |---|---|---|---|---|
-| 1 | 1 | {Phạm vi / Luồng / Rule / Phụ thuộc / Thuật ngữ} | {…} | {…} |
+| 1 | 1 | {Phạm vi / Luồng / Business Rule / Phụ thuộc / Thuật ngữ} | {…} | {…} |
 
 ## Câu hỏi còn mở <!-- sec:open -->
 

package/templates/product.md

@@ -46,7 +46,7 @@ updated: {YYYY-MM-DD}
 
 ## 6. Ràng buộc <!-- sec:constraints -->
 
-> Ràng buộc áp cho **mọi epic**. PRD có rule bắt nguồn từ ràng buộc nào thì ghi `(nguồn: CON-01)`.
+> Ràng buộc áp cho **mọi epic**. PRD có Business Rule (BR) bắt nguồn từ ràng buộc nào thì ghi `(nguồn: CON-01)`.
 
 | Mã | Loại | Ràng buộc |
 |---|---|---|

package/tools/spec_edit.py

@@ -13,11 +13,11 @@ Cách dùng (nội dung truyền qua stdin):
   spec_edit.py edit   <file>              stdin = JSON [{"old": "...", "new": "...", "all": false}]
   spec_edit.py set    <file> key=value…   sửa frontmatter
   spec_edit.py pending <file>             liệt kê các dòng còn dấu 🤖 (kèm số dòng)
-  spec_edit.py confirm <file> <mã>…       đổi 🤖 → ✅ trên dòng chứa mã (vd AC2 R8b ACT-03)
+  spec_edit.py confirm <file> <mã>…       đổi 🤖 → ✅ trên dòng chứa mã (vd AC2 BR8b ACT-03)
   spec_edit.py section <file> <mã>        in đúng một mục theo mã `<!-- sec:… -->` (vd constraints)
   spec_edit.py upgrade <file>             gắn mã mục cho file theo khuôn cũ (chạy một lần)
   spec_edit.py next-uc <thư mục specs>    in mã UC kế tiếp (quét mọi prd.md)
-  spec_edit.py coverage <epic> <prd>      liệt kê rule / tiêu chí của epic chưa được PRD dùng tới
+  spec_edit.py coverage <epic> <prd>      liệt kê BR / AC của epic chưa được PRD dùng tới
 
 Mã thoát: 0 = thành công · 1 = lỗi dữ liệu (không ghi gì) · 2 = sai cách dùng.
 """
@@ -42,7 +42,13 @@ COMMON_INT = {"open_questions": (0, 999)}
 DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 VERSION = re.compile(r"^\d+\.\d+$")
 UC_HEADING = re.compile(r"^###\s+UC-(\d{3})\b", re.M)
-EPIC_ITEM = re.compile("^\\s*- [\U0001F916\u2705] ((?:R|AC)\\d+[a-z]?)\\.", re.M)
+EPIC_ITEM = re.compile("^\\s*- [\U0001F916\u2705] ((?:BR|R|AC)\\d+[a-z]?)\\.", re.M)
+# Epic theo khu\u00f4n tr\u01b0\u1edbc 0.6.1 \u0111\u00e1nh s\u1ed1 Business Rule l\u00e0 R1\u2026; t\u1eeb 0.6.1 l\u00e0 BR1\u2026. Coi hai ki\u1ec3u l\u00e0 m\u1ed9t m\u00e3.
+OLD_BR = re.compile(r"(?<![\w-])R(\d+[a-z]?)(?![\w])")
+
+
+def br_code(code):
+    return OLD_BR.sub(r"BR\1", code.strip())
 SOURCE_REF = re.compile(r"\(nguồn:\s*([^)]*)\)")
 
 
@@ -74,6 +80,7 @@ def cmd_create(path):
         fail(path + " đã tồn tại — không ghi đè. Dùng `edit` hoặc `set`.")
     text = stdin_text()
     check_keys(file_type(text), [], sec_keys(text), creating=True)
+    check_sources(file_type(text), text)
     write(path, text)
     print("đã tạo " + path)
 
@@ -103,6 +110,7 @@ def cmd_edit(path):
     for e in edits:
         text = text.replace(e["old"], e["new"]) if e.get("all") else text.replace(e["old"], e["new"], 1)
     check_keys(file_type(text), before, sec_keys(text), creating=False)
+    check_sources(file_type(text), text)
     write(path, text)
     print("đã sửa %d chỗ trong %s" % (len(edits), path))
 
@@ -223,6 +231,34 @@ def template_sections(ftype):
     return [(k, normalize_title(t), SEC_KEY.sub("", t).strip()) for _, _, t, k in headings(lines) if k]
 
 
+# (nguồn: …) chỉ nhận mã, để script truy được BR/AC của PRD về đúng chỗ sinh ra nó:
+#   BR3 / AC1 (epic; R3 là kiểu cũ) · CON-02 (ràng buộc tầng sản phẩm) · PRD (thêm khi viết PRD, PO đã duyệt)
+SOURCE_TOKEN = re.compile(r"^(?:BR\d+[a-z]?|R\d+[a-z]?|AC\d+[a-z]?|CON-\d+|PRD)$")
+
+
+def bad_sources(text):
+    out = []
+    # Dòng trích dẫn (>) là chú thích của khuôn (vd "(nguồn: …) chỉ ghi mã"), không phải nguồn thật.
+    body = "\n".join(l for l in text.split("\n") if not l.lstrip().startswith(">"))
+    for refs in SOURCE_REF.findall(body):
+        for r in (x.strip() for x in refs.split(",")):
+            if r and not SOURCE_TOKEN.match(r) and r not in out:
+                out.append(r)
+    return out
+
+
+def source_rule_msg(bad):
+    return ("(nguồn: …) chỉ được ghi mã — BR3 / AC1 của epic, CON-02, hoặc PRD (mục thêm khi viết PRD, "
+            "PO đã duyệt). Đang ghi: " + " · ".join('"%s"' % b for b in bad))
+
+
+def check_sources(ftype, text):
+    if ftype == "prd":
+        bad = bad_sources(text)
+        if bad:
+            fail(source_rule_msg(bad))
+
+
 def check_keys(ftype, before, after, creating):
     dup = sorted({k for k in after if after.count(k) > 1})
     if dup:
@@ -271,10 +307,23 @@ def cmd_upgrade(path):
             added.append(k)
         else:
             unknown.append(title)
-    if added:
-        write(path, "\n".join(lines))
+    new_text = "\n".join(lines)
+    # Mã Business Rule: R3 → BR3 (khuôn từ 0.6.1). Epic: đổi mọi chỗ. PRD: chỉ trong (nguồn: …).
+    renamed = [0]
+    if ftype == "epic":
+        new_text, renamed[0] = OLD_BR.subn(r"BR\1", new_text)
+    elif ftype == "prd":
+        def fix(m):
+            out = OLD_BR.sub(r"BR\1", m.group(0))
+            renamed[0] += out != m.group(0)
+            return out
+        new_text = SOURCE_REF.sub(fix, new_text)
+    if new_text != text:
+        write(path, new_text)
     missing = [(k, orig) for k, _, orig in tpl if k not in used]
     print("đã gắn mã: %s" % (", ".join(added) or "không có gì mới"))
+    if renamed[0]:
+        print("đã đổi mã Business Rule R… → BR…: %d chỗ" % renamed[0])
     if unknown:
         print("⚠ tiêu đề không khớp khuôn (giữ nguyên): " + " · ".join(unknown))
     if missing:
@@ -293,21 +342,28 @@ def cmd_next_uc(specs_dir):
 def cmd_coverage(epic_path, prd_path):
     wanted = []
     for code in EPIC_ITEM.findall(read(epic_path)):
-        if code not in wanted:
-            wanted.append(code)
+        if br_code(code) not in wanted:
+            wanted.append(br_code(code))
     used = set()
     for refs in SOURCE_REF.findall(read(prd_path)):
-        used.update(r.strip() for r in refs.split(","))
+        used.update(br_code(r) for r in refs.split(","))
     missing = [c for c in wanted if c not in used]
-    # CON-xx là ràng buộc của tầng sản phẩm, không thuộc epic — hợp lệ.
-    unknown = sorted(r for r in used - set(wanted) - {""} if not re.match(r"^CON-\d+$", r))
-    print("epic có %d rule/tiêu chí · PRD dùng %d" % (len(wanted), len(wanted) - len(missing)), flush=True)
+    bad = bad_sources(read(prd_path))
+    # CON-xx (ràng buộc tầng sản phẩm) và PRD (thêm khi viết PRD) hợp lệ dù không có trong epic.
+    unknown = sorted(r for r in used - set(wanted) - {""}
+                     if SOURCE_TOKEN.match(r) and not re.match(r"^(CON-\d+|PRD)$", r))
+    print("epic có %d BR/AC · PRD dùng %d" % (len(wanted), len(wanted) - len(missing)), flush=True)
+    problems = []
+    if bad:
+        problems.append(source_rule_msg(bad))
     if unknown:
-        print("⚠ PRD ghi nguồn không có trong epic: " + ", ".join(unknown), flush=True)
+        problems.append("PRD ghi nguồn không có trong epic: %s (gõ nhầm mã?)" % ", ".join(unknown))
     if missing:
-        fail("chưa được PRD dùng tới: " + ", ".join(missing)
-             + ". Đưa vào một UC với (nguồn: …), hoặc hỏi PO có bỏ không.")
-    print("đủ — mọi rule/tiêu chí của epic đều có trong PRD")
+        problems.append("chưa được PRD dùng tới: %s. Đưa vào một UC với (nguồn: …), hoặc hỏi PO có bỏ không."
+                        % ", ".join(missing))
+    if problems:
+        fail("\n  - ".join([""] + problems))
+    print("đủ — mọi BR/AC của epic đều có trong PRD")
 
 
 PENDING, CONFIRMED = "\U0001F916", "✅"
@@ -327,7 +383,7 @@ def cmd_pending(path):
 
 def cmd_confirm(path, codes):
     if not codes:
-        fail("cần ít nhất một mã, ví dụ: confirm <file> AC2 AC3 R8b", 2)
+        fail("cần ít nhất một mã, ví dụ: confirm <file> AC2 AC3 BR8b", 2)
     lines = read(path).split("\n")
     # Mã khớp nguyên từ: AC2 không được khớp nhầm AC20.
     targets = {}