@educa-corp/sdd-framework 0.2.9 → 0.3.0

package/commands/generate-prd.md

@@ -553,6 +553,34 @@ 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).
 
+## Hình dạng bảng Business Rule *(3 cột mặc định — mở cột khi nội dung là bản ghi lặp)*
+
+Bảng 3 cột `ID | Business Rule | Business Logic` là **mặc định**, KHÔNG phải luật cứng. Nó hoạt động tốt khi Business Logic là **văn xuôi** (mô tả luật bằng câu). Nó **gãy** khi Business Logic là một **bản ghi có cấu trúc lặp** — lúc đó ép vào một ô buộc phải serialize bản ghi thành chuỗi, và bảng mất khả năng đọc lướt / đếm / diff.
+
+**Điều kiện kích hoạt mở cột** — cả hai phải đúng:
+1. **Mọi** BR trong một UC chia sẻ **cùng một bộ thuộc tính** lặp lại (vd `trigger` / `data` / `tần suất` / `nguồn`); VÀ
+2. Bộ thuộc tính đó là **cấu trúc đều**, không phải văn xuôi tự do.
+
+**Dấu hiệu tự phát hiện (dùng khi tự kiểm trước khi ghi):** đang phải dùng `<br/>` để nhồi **nhiều hơn một bản ghi cùng cấu trúc** vào một ô Business Logic. Một `<br/>` ngăn cách các ý của **cùng một** luật thì bình thường — nhiều `<br/>` ngăn cách các **bản ghi ngang hàng** là tín hiệu sai hình dạng.
+
+**Khi kích hoạt:** promote thuộc tính thành **cột**, một bản ghi = một **dòng**. Giữ nguyên hai cột `ID` + `Business Rule` (traceability phụ thuộc chúng); chỉ cột `Business Logic` được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên **§1d Quy ước**, đừng lặp trong từng ô.
+
+**Khi KHÔNG kích hoạt:** giữ nguyên 3 cột. Phần lớn PRD tính năng rơi vào đây — BR của chúng là văn xuôi ("coi Landing là không sẵn sàng khi dịch vụ gặp sự cố; quá 3 giây chưa trả nội dung; hoặc trả nội dung rỗng"), không có bộ thuộc tính nào lặp. **Luật này tự kích hoạt theo hình dạng nội dung — không phải một cờ người dùng phải nhớ bật.**
+
+> **⚠️ Guard — BR ID churn (BẮT BUỘC kiểm khi mở cột trên PRD ĐÃ TỒN TẠI):**
+> Mở cột đúng nghĩa = một bản ghi một dòng ⇒ **số BR tăng**. Vì BR ID tăng liên tục trên toàn PRD (xem "Quy ước đánh số"), chèn dòng ở giữa sẽ **đánh số lại mọi BR phía sau**. BDD mang tag `@trace.business_rules: {TICKET}-UC1-BR1, …` — nếu PRD đã có BDD, mọi tag sau điểm chèn sẽ trỏ **sai trong im lặng**.
+> Trước khi mở cột trên một PRD đã tồn tại → kiểm tra `{paths.specs_dir}/{domain}/{prd-slug}/bdd/`:
+> - **Chưa có BDD** → mở cột tự do, không cần hỏi.
+> - **Đã có BDD** → **DỪNG**, báo người dùng: *"Mở cột sẽ đánh số lại {N} BR; {M} file BDD đang ref BR ID cũ. Chọn: (1) mở cột + re-gen BDD, (2) giữ hình dạng cũ."* Chờ chọn.
+>
+> PRD sinh **mới** không bị ảnh hưởng — chưa có downstream nào ref BR ID.
+
+## Quy ước tài liệu (§1d) & Note block *(hai slot tuỳ chọn)*
+
+- **§1d Quy ước** — khi tài liệu có quy ước áp dụng **xuyên suốt mọi BR** (giá trị mặc định dùng chung, cách đọc cột, định nghĩa cục bộ), khai báo **một lần** ở đây. BR **không** lặp lại; AC **trỏ tới** thay vì chép lại. Không có quy ước xuyên suốt → **xoá hẳn section** (như `Existing API Contract` khi greenfield). Phân biệt: §1b Phạm vi = ranh giới; business-dictionary = thuật ngữ cấp domain; §1d = quy ước **cục bộ của tài liệu này**.
+- **Note block sau bảng BR** — cho phép `> **Note {BR ref}:** …` ngay sau bảng để giải thích **quyết định đã chốt** (vì sao luật như vậy, ràng buộc nào dẫn tới). Đặt cạnh nơi phát sinh, đừng dồn xuống cuối file.
+  **Ranh giới với "Giả định AI":** Note = quyết định **đã chốt**; Giả định AI = **độ vênh cần PO chốt**. Note KHÔNG được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI, vì đó là thứ PO phải đọc.
+
 ## 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.
@@ -600,8 +628,13 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
   AI Agent sẽ điền các section dựa trên input từ PO.
   Các placeholder {…} cần được thay thế bằng nội dung thực tế.
 
-  FORMAT CHUẨN: Business Rule = bảng 3 cột
-  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+  FORMAT BR: MẶC ĐỊNH bảng 3 cột — ID | Business Rule | Business Logic
+    (KHÔNG tách Business Logic ra khối riêng).
+    NGOẠI LỆ — MỞ CỘT: nếu MỌI BR trong một UC chia sẻ cùng một bộ thuộc tính lặp lại
+    (vd trigger / data / tần suất), promote các thuộc tính đó thành CỘT RIÊNG —
+    một bản ghi = một DÒNG. Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi
+    NHIỀU HƠN MỘT bản ghi cùng cấu trúc vào một ô. Chi tiết + cảnh báo BR ID churn:
+    xem §3 "Business Rule" của template và mục "Hình dạng bảng Business Rule" của lệnh.
 
   TERMINOLOGY:
   - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
@@ -679,6 +712,18 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 - {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
 
+## d. Quy ước *(TUỲ CHỌN — chỉ thêm khi tài liệu có quy ước áp dụng xuyên suốt; nếu không có → XOÁ HẲN section này)*
+
+> Khai báo **MỘT LẦN** các quy ước áp dụng cho **mọi BR** ở §3. BR **KHÔNG** lặp lại nội dung đã khai ở đây,
+> AC §2 **trỏ tới** quy ước thay vì chép lại. Đây là nơi chứa định nghĩa dùng chung, giá trị mặc định,
+> và cách đọc các cột của bảng BR — những thứ trước đây bị xé nhỏ và lặp trong từng dòng.
+>
+> Phân biệt với **§1b Phạm vi** (ranh giới làm/không làm) và **business-dictionary** (định nghĩa thuật ngữ
+> cấp domain, dùng chung nhiều PRD): §1d chỉ chứa quy ước **cục bộ của tài liệu này**.
+
+- **{Tên quy ước}**: {nội dung áp dụng cho mọi BR bên dưới}
+- **{Giá trị mặc định dùng chung}**: {…}
+
 ---
 
 # 2. Acceptance Criteria
@@ -713,11 +758,47 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 **Business Rule**
 
+> **Hình dạng bảng — mặc định 3 cột.** Dùng dạng này khi Business Logic là **văn xuôi** (mô tả luật bằng câu).
+
 | ID | Business Rule | Business Logic |
 |----|---------------|----------------|
 | {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
 | {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
 
+<!--
+  NGOẠI LỆ — MỞ CỘT (dùng THAY cho bảng 3 cột ở trên, KHÔNG dùng cả hai):
+
+  Điều kiện kích hoạt: MỌI BR trong UC này chia sẻ CÙNG một bộ thuộc tính lặp lại.
+  Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi NHIỀU HƠN MỘT bản ghi cùng
+  cấu trúc vào một ô Business Logic.
+
+  Khi kích hoạt: promote thuộc tính thành CỘT, một bản ghi = một DÒNG:
+
+    | ID  | Business Rule | {Thuộc tính 1} | {Thuộc tính 2} | {Thuộc tính 3} |
+    |-----|---------------|----------------|----------------|----------------|
+    | BR1 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+    | BR2 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+
+  Hai cột ID + Business Rule LUÔN giữ (traceability phụ thuộc chúng). Chỉ cột
+  Business Logic được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên
+  §1d Quy ước, ĐỪNG lặp trong từng ô.
+
+  ⚠️ CẢNH BÁO BR ID CHURN — đọc trước khi mở cột trên PRD ĐÃ TỒN TẠI:
+  Mở cột đúng nghĩa = một bản ghi một dòng ⇒ số BR TĂNG. Vì BR ID tăng liên tục
+  trên toàn PRD, chèn dòng ở giữa sẽ ĐÁNH SỐ LẠI mọi BR phía sau. Nếu PRD này đã có
+  BDD downstream, mọi tag `@trace.business_rules` trong .feature sẽ trỏ SAI trong im lặng.
+  → Trước khi mở cột trên PRD đã có: kiểm tra `{specs_dir}/{domain}/{prd-slug}/bdd/`.
+    - Chưa có BDD → mở cột tự do.
+    - ĐÃ có BDD → DỪNG, báo người dùng: cần re-gen BDD sau khi đổi, hoặc giữ nguyên hình dạng cũ.
+  PRD sinh MỚI không bị ảnh hưởng (chưa có downstream).
+-->
+
+> **Note {BR ref}:** *(TUỲ CHỌN)* {giải thích **quyết định đã chốt** — vì sao luật này như vậy, ràng buộc
+> nào dẫn tới nó, biên nào đã cân nhắc}. Đặt ngay sau bảng, cạnh nơi phát sinh.
+>
+> **Ranh giới với "Giả định AI" (Appendix):** Note = quyết định **đã chốt**, giải thích cho người đọc sau.
+> Giả định AI = **độ vênh CẦN PO chốt**. Note **KHÔNG** được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI.
+
 ---
 
 #### {TICKET}-{N}-UC2: {Tên use case}
@@ -738,6 +819,12 @@ flowchart TD
 
 ## b. Wireframe
 
+> **KHÔNG nhân bản §3.** Wireframe liệt kê **màn + thành phần + hành động** — nó là nguồn coverage màn hình
+> cho `/generate-bdd` (C.1), KHÔNG phải bản sao thứ hai của bảng Business Rule.
+> Nếu một dòng Wireframe không thêm thông tin nào ngoài BR đã có → **tham chiếu BR ID, đừng chép nội dung**.
+> Nếu cả §4b không thêm gì mới so với §3 → **xoá hẳn §4b** (hai nguồn sự thật cho cùng một dữ liệu sẽ lệch nhau
+> ngay lần sửa đầu tiên).
+
 ### Screen 1: {Tên màn}
 
 | Thành phần | Chi tiết |
@@ -828,7 +915,10 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 - [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
 - [ ] 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`
+- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung **một bảng** — KHÔNG tách Business Logic ra khối riêng
+- [ ] **Hình dạng bảng BR đúng với nội dung**: 3 cột khi Business Logic là văn xuôi; **mở cột** (1 bản ghi = 1 dòng) khi mọi BR trong UC chia sẻ cùng bộ thuộc tính lặp. Kiểm cụ thể: **0 ô Business Logic chứa nhiều hơn một bản ghi cùng cấu trúc** (dấu hiệu: `<br/>` ngăn cách các bản ghi ngang hàng thay vì các ý của cùng một luật) — xem "Hình dạng bảng Business Rule"
+- [ ] **Nếu mở cột trên PRD đã tồn tại**: đã kiểm `bdd/` và xử lý BR ID churn (chưa có BDD → tự do; đã có BDD → đã hỏi người dùng, không tự ý đổi)
+- [ ] **§1d Quy ước**: nếu có quy ước xuyên suốt → khai báo MỘT LẦN ở §1d, 0 lần lặp lại trong ô BR, AC trỏ tới thay vì chép; nếu không có → section đã xoá hẳn (không để rỗng)
 - [ ] 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)`
@@ -838,6 +928,7 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 - [ ] **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
+- [ ] **Wireframe không nhân bản §3**: 0 dòng §4b lặp lại nội dung đã có ở bảng Business Rule — không thêm thông tin thì ref BR ID; cả §4b không thêm gì mới thì xoá hẳn (tránh hai nguồn sự thật)
 - [ ] **Đị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
 
 ## Output

package/commands/generate-prd.tmpl

@@ -82,6 +82,34 @@ 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).
 
+## Hình dạng bảng Business Rule *(3 cột mặc định — mở cột khi nội dung là bản ghi lặp)*
+
+Bảng 3 cột `ID | Business Rule | Business Logic` là **mặc định**, KHÔNG phải luật cứng. Nó hoạt động tốt khi Business Logic là **văn xuôi** (mô tả luật bằng câu). Nó **gãy** khi Business Logic là một **bản ghi có cấu trúc lặp** — lúc đó ép vào một ô buộc phải serialize bản ghi thành chuỗi, và bảng mất khả năng đọc lướt / đếm / diff.
+
+**Điều kiện kích hoạt mở cột** — cả hai phải đúng:
+1. **Mọi** BR trong một UC chia sẻ **cùng một bộ thuộc tính** lặp lại (vd `trigger` / `data` / `tần suất` / `nguồn`); VÀ
+2. Bộ thuộc tính đó là **cấu trúc đều**, không phải văn xuôi tự do.
+
+**Dấu hiệu tự phát hiện (dùng khi tự kiểm trước khi ghi):** đang phải dùng `<br/>` để nhồi **nhiều hơn một bản ghi cùng cấu trúc** vào một ô Business Logic. Một `<br/>` ngăn cách các ý của **cùng một** luật thì bình thường — nhiều `<br/>` ngăn cách các **bản ghi ngang hàng** là tín hiệu sai hình dạng.
+
+**Khi kích hoạt:** promote thuộc tính thành **cột**, một bản ghi = một **dòng**. Giữ nguyên hai cột `ID` + `Business Rule` (traceability phụ thuộc chúng); chỉ cột `Business Logic` được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên **§1d Quy ước**, đừng lặp trong từng ô.
+
+**Khi KHÔNG kích hoạt:** giữ nguyên 3 cột. Phần lớn PRD tính năng rơi vào đây — BR của chúng là văn xuôi ("coi Landing là không sẵn sàng khi dịch vụ gặp sự cố; quá 3 giây chưa trả nội dung; hoặc trả nội dung rỗng"), không có bộ thuộc tính nào lặp. **Luật này tự kích hoạt theo hình dạng nội dung — không phải một cờ người dùng phải nhớ bật.**
+
+> **⚠️ Guard — BR ID churn (BẮT BUỘC kiểm khi mở cột trên PRD ĐÃ TỒN TẠI):**
+> Mở cột đúng nghĩa = một bản ghi một dòng ⇒ **số BR tăng**. Vì BR ID tăng liên tục trên toàn PRD (xem "Quy ước đánh số"), chèn dòng ở giữa sẽ **đánh số lại mọi BR phía sau**. BDD mang tag `@trace.business_rules: {TICKET}-UC1-BR1, …` — nếu PRD đã có BDD, mọi tag sau điểm chèn sẽ trỏ **sai trong im lặng**.
+> Trước khi mở cột trên một PRD đã tồn tại → kiểm tra `{paths.specs_dir}/{domain}/{prd-slug}/bdd/`:
+> - **Chưa có BDD** → mở cột tự do, không cần hỏi.
+> - **Đã có BDD** → **DỪNG**, báo người dùng: *"Mở cột sẽ đánh số lại {N} BR; {M} file BDD đang ref BR ID cũ. Chọn: (1) mở cột + re-gen BDD, (2) giữ hình dạng cũ."* Chờ chọn.
+>
+> PRD sinh **mới** không bị ảnh hưởng — chưa có downstream nào ref BR ID.
+
+## Quy ước tài liệu (§1d) & Note block *(hai slot tuỳ chọn)*
+
+- **§1d Quy ước** — khi tài liệu có quy ước áp dụng **xuyên suốt mọi BR** (giá trị mặc định dùng chung, cách đọc cột, định nghĩa cục bộ), khai báo **một lần** ở đây. BR **không** lặp lại; AC **trỏ tới** thay vì chép lại. Không có quy ước xuyên suốt → **xoá hẳn section** (như `Existing API Contract` khi greenfield). Phân biệt: §1b Phạm vi = ranh giới; business-dictionary = thuật ngữ cấp domain; §1d = quy ước **cục bộ của tài liệu này**.
+- **Note block sau bảng BR** — cho phép `> **Note {BR ref}:** …` ngay sau bảng để giải thích **quyết định đã chốt** (vì sao luật như vậy, ràng buộc nào dẫn tới). Đặt cạnh nơi phát sinh, đừng dồn xuống cuối file.
+  **Ranh giới với "Giả định AI":** Note = quyết định **đã chốt**; Giả định AI = **độ vênh cần PO chốt**. Note KHÔNG được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI, vì đó là thứ PO phải đọc.
+
 ## 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.
@@ -133,7 +161,10 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 - [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
 - [ ] 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`
+- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung **một bảng** — KHÔNG tách Business Logic ra khối riêng
+- [ ] **Hình dạng bảng BR đúng với nội dung**: 3 cột khi Business Logic là văn xuôi; **mở cột** (1 bản ghi = 1 dòng) khi mọi BR trong UC chia sẻ cùng bộ thuộc tính lặp. Kiểm cụ thể: **0 ô Business Logic chứa nhiều hơn một bản ghi cùng cấu trúc** (dấu hiệu: `<br/>` ngăn cách các bản ghi ngang hàng thay vì các ý của cùng một luật) — xem "Hình dạng bảng Business Rule"
+- [ ] **Nếu mở cột trên PRD đã tồn tại**: đã kiểm `bdd/` và xử lý BR ID churn (chưa có BDD → tự do; đã có BDD → đã hỏi người dùng, không tự ý đổi)
+- [ ] **§1d Quy ước**: nếu có quy ước xuyên suốt → khai báo MỘT LẦN ở §1d, 0 lần lặp lại trong ô BR, AC trỏ tới thay vì chép; nếu không có → section đã xoá hẳn (không để rỗng)
 - [ ] 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)`
@@ -143,6 +174,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 - [ ] **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
+- [ ] **Wireframe không nhân bản §3**: 0 dòng §4b lặp lại nội dung đã có ở bảng Business Rule — không thêm thông tin thì ref BR ID; cả §4b không thêm gì mới thì xoá hẳn (tránh hai nguồn sự thật)
 - [ ] **Đị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
 
 ## Output

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.2.9
+0.3.0

package/core/commands/generate-prd.md

@@ -553,6 +553,34 @@ 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).
 
+## Hình dạng bảng Business Rule *(3 cột mặc định — mở cột khi nội dung là bản ghi lặp)*
+
+Bảng 3 cột `ID | Business Rule | Business Logic` là **mặc định**, KHÔNG phải luật cứng. Nó hoạt động tốt khi Business Logic là **văn xuôi** (mô tả luật bằng câu). Nó **gãy** khi Business Logic là một **bản ghi có cấu trúc lặp** — lúc đó ép vào một ô buộc phải serialize bản ghi thành chuỗi, và bảng mất khả năng đọc lướt / đếm / diff.
+
+**Điều kiện kích hoạt mở cột** — cả hai phải đúng:
+1. **Mọi** BR trong một UC chia sẻ **cùng một bộ thuộc tính** lặp lại (vd `trigger` / `data` / `tần suất` / `nguồn`); VÀ
+2. Bộ thuộc tính đó là **cấu trúc đều**, không phải văn xuôi tự do.
+
+**Dấu hiệu tự phát hiện (dùng khi tự kiểm trước khi ghi):** đang phải dùng `<br/>` để nhồi **nhiều hơn một bản ghi cùng cấu trúc** vào một ô Business Logic. Một `<br/>` ngăn cách các ý của **cùng một** luật thì bình thường — nhiều `<br/>` ngăn cách các **bản ghi ngang hàng** là tín hiệu sai hình dạng.
+
+**Khi kích hoạt:** promote thuộc tính thành **cột**, một bản ghi = một **dòng**. Giữ nguyên hai cột `ID` + `Business Rule` (traceability phụ thuộc chúng); chỉ cột `Business Logic` được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên **§1d Quy ước**, đừng lặp trong từng ô.
+
+**Khi KHÔNG kích hoạt:** giữ nguyên 3 cột. Phần lớn PRD tính năng rơi vào đây — BR của chúng là văn xuôi ("coi Landing là không sẵn sàng khi dịch vụ gặp sự cố; quá 3 giây chưa trả nội dung; hoặc trả nội dung rỗng"), không có bộ thuộc tính nào lặp. **Luật này tự kích hoạt theo hình dạng nội dung — không phải một cờ người dùng phải nhớ bật.**
+
+> **⚠️ Guard — BR ID churn (BẮT BUỘC kiểm khi mở cột trên PRD ĐÃ TỒN TẠI):**
+> Mở cột đúng nghĩa = một bản ghi một dòng ⇒ **số BR tăng**. Vì BR ID tăng liên tục trên toàn PRD (xem "Quy ước đánh số"), chèn dòng ở giữa sẽ **đánh số lại mọi BR phía sau**. BDD mang tag `@trace.business_rules: {TICKET}-UC1-BR1, …` — nếu PRD đã có BDD, mọi tag sau điểm chèn sẽ trỏ **sai trong im lặng**.
+> Trước khi mở cột trên một PRD đã tồn tại → kiểm tra `{paths.specs_dir}/{domain}/{prd-slug}/bdd/`:
+> - **Chưa có BDD** → mở cột tự do, không cần hỏi.
+> - **Đã có BDD** → **DỪNG**, báo người dùng: *"Mở cột sẽ đánh số lại {N} BR; {M} file BDD đang ref BR ID cũ. Chọn: (1) mở cột + re-gen BDD, (2) giữ hình dạng cũ."* Chờ chọn.
+>
+> PRD sinh **mới** không bị ảnh hưởng — chưa có downstream nào ref BR ID.
+
+## Quy ước tài liệu (§1d) & Note block *(hai slot tuỳ chọn)*
+
+- **§1d Quy ước** — khi tài liệu có quy ước áp dụng **xuyên suốt mọi BR** (giá trị mặc định dùng chung, cách đọc cột, định nghĩa cục bộ), khai báo **một lần** ở đây. BR **không** lặp lại; AC **trỏ tới** thay vì chép lại. Không có quy ước xuyên suốt → **xoá hẳn section** (như `Existing API Contract` khi greenfield). Phân biệt: §1b Phạm vi = ranh giới; business-dictionary = thuật ngữ cấp domain; §1d = quy ước **cục bộ của tài liệu này**.
+- **Note block sau bảng BR** — cho phép `> **Note {BR ref}:** …` ngay sau bảng để giải thích **quyết định đã chốt** (vì sao luật như vậy, ràng buộc nào dẫn tới). Đặt cạnh nơi phát sinh, đừng dồn xuống cuối file.
+  **Ranh giới với "Giả định AI":** Note = quyết định **đã chốt**; Giả định AI = **độ vênh cần PO chốt**. Note KHÔNG được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI, vì đó là thứ PO phải đọc.
+
 ## 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.
@@ -600,8 +628,13 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
   AI Agent sẽ điền các section dựa trên input từ PO.
   Các placeholder {…} cần được thay thế bằng nội dung thực tế.
 
-  FORMAT CHUẨN: Business Rule = bảng 3 cột
-  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+  FORMAT BR: MẶC ĐỊNH bảng 3 cột — ID | Business Rule | Business Logic
+    (KHÔNG tách Business Logic ra khối riêng).
+    NGOẠI LỆ — MỞ CỘT: nếu MỌI BR trong một UC chia sẻ cùng một bộ thuộc tính lặp lại
+    (vd trigger / data / tần suất), promote các thuộc tính đó thành CỘT RIÊNG —
+    một bản ghi = một DÒNG. Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi
+    NHIỀU HƠN MỘT bản ghi cùng cấu trúc vào một ô. Chi tiết + cảnh báo BR ID churn:
+    xem §3 "Business Rule" của template và mục "Hình dạng bảng Business Rule" của lệnh.
 
   TERMINOLOGY:
   - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
@@ -679,6 +712,18 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 - {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
 
+## d. Quy ước *(TUỲ CHỌN — chỉ thêm khi tài liệu có quy ước áp dụng xuyên suốt; nếu không có → XOÁ HẲN section này)*
+
+> Khai báo **MỘT LẦN** các quy ước áp dụng cho **mọi BR** ở §3. BR **KHÔNG** lặp lại nội dung đã khai ở đây,
+> AC §2 **trỏ tới** quy ước thay vì chép lại. Đây là nơi chứa định nghĩa dùng chung, giá trị mặc định,
+> và cách đọc các cột của bảng BR — những thứ trước đây bị xé nhỏ và lặp trong từng dòng.
+>
+> Phân biệt với **§1b Phạm vi** (ranh giới làm/không làm) và **business-dictionary** (định nghĩa thuật ngữ
+> cấp domain, dùng chung nhiều PRD): §1d chỉ chứa quy ước **cục bộ của tài liệu này**.
+
+- **{Tên quy ước}**: {nội dung áp dụng cho mọi BR bên dưới}
+- **{Giá trị mặc định dùng chung}**: {…}
+
 ---
 
 # 2. Acceptance Criteria
@@ -713,11 +758,47 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 **Business Rule**
 
+> **Hình dạng bảng — mặc định 3 cột.** Dùng dạng này khi Business Logic là **văn xuôi** (mô tả luật bằng câu).
+
 | ID | Business Rule | Business Logic |
 |----|---------------|----------------|
 | {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
 | {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
 
+<!--
+  NGOẠI LỆ — MỞ CỘT (dùng THAY cho bảng 3 cột ở trên, KHÔNG dùng cả hai):
+
+  Điều kiện kích hoạt: MỌI BR trong UC này chia sẻ CÙNG một bộ thuộc tính lặp lại.
+  Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi NHIỀU HƠN MỘT bản ghi cùng
+  cấu trúc vào một ô Business Logic.
+
+  Khi kích hoạt: promote thuộc tính thành CỘT, một bản ghi = một DÒNG:
+
+    | ID  | Business Rule | {Thuộc tính 1} | {Thuộc tính 2} | {Thuộc tính 3} |
+    |-----|---------------|----------------|----------------|----------------|
+    | BR1 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+    | BR2 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+
+  Hai cột ID + Business Rule LUÔN giữ (traceability phụ thuộc chúng). Chỉ cột
+  Business Logic được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên
+  §1d Quy ước, ĐỪNG lặp trong từng ô.
+
+  ⚠️ CẢNH BÁO BR ID CHURN — đọc trước khi mở cột trên PRD ĐÃ TỒN TẠI:
+  Mở cột đúng nghĩa = một bản ghi một dòng ⇒ số BR TĂNG. Vì BR ID tăng liên tục
+  trên toàn PRD, chèn dòng ở giữa sẽ ĐÁNH SỐ LẠI mọi BR phía sau. Nếu PRD này đã có
+  BDD downstream, mọi tag `@trace.business_rules` trong .feature sẽ trỏ SAI trong im lặng.
+  → Trước khi mở cột trên PRD đã có: kiểm tra `{specs_dir}/{domain}/{prd-slug}/bdd/`.
+    - Chưa có BDD → mở cột tự do.
+    - ĐÃ có BDD → DỪNG, báo người dùng: cần re-gen BDD sau khi đổi, hoặc giữ nguyên hình dạng cũ.
+  PRD sinh MỚI không bị ảnh hưởng (chưa có downstream).
+-->
+
+> **Note {BR ref}:** *(TUỲ CHỌN)* {giải thích **quyết định đã chốt** — vì sao luật này như vậy, ràng buộc
+> nào dẫn tới nó, biên nào đã cân nhắc}. Đặt ngay sau bảng, cạnh nơi phát sinh.
+>
+> **Ranh giới với "Giả định AI" (Appendix):** Note = quyết định **đã chốt**, giải thích cho người đọc sau.
+> Giả định AI = **độ vênh CẦN PO chốt**. Note **KHÔNG** được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI.
+
 ---
 
 #### {TICKET}-{N}-UC2: {Tên use case}
@@ -738,6 +819,12 @@ flowchart TD
 
 ## b. Wireframe
 
+> **KHÔNG nhân bản §3.** Wireframe liệt kê **màn + thành phần + hành động** — nó là nguồn coverage màn hình
+> cho `/generate-bdd` (C.1), KHÔNG phải bản sao thứ hai của bảng Business Rule.
+> Nếu một dòng Wireframe không thêm thông tin nào ngoài BR đã có → **tham chiếu BR ID, đừng chép nội dung**.
+> Nếu cả §4b không thêm gì mới so với §3 → **xoá hẳn §4b** (hai nguồn sự thật cho cùng một dữ liệu sẽ lệch nhau
+> ngay lần sửa đầu tiên).
+
 ### Screen 1: {Tên màn}
 
 | Thành phần | Chi tiết |
@@ -828,7 +915,10 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 - [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
 - [ ] 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`
+- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung **một bảng** — KHÔNG tách Business Logic ra khối riêng
+- [ ] **Hình dạng bảng BR đúng với nội dung**: 3 cột khi Business Logic là văn xuôi; **mở cột** (1 bản ghi = 1 dòng) khi mọi BR trong UC chia sẻ cùng bộ thuộc tính lặp. Kiểm cụ thể: **0 ô Business Logic chứa nhiều hơn một bản ghi cùng cấu trúc** (dấu hiệu: `<br/>` ngăn cách các bản ghi ngang hàng thay vì các ý của cùng một luật) — xem "Hình dạng bảng Business Rule"
+- [ ] **Nếu mở cột trên PRD đã tồn tại**: đã kiểm `bdd/` và xử lý BR ID churn (chưa có BDD → tự do; đã có BDD → đã hỏi người dùng, không tự ý đổi)
+- [ ] **§1d Quy ước**: nếu có quy ước xuyên suốt → khai báo MỘT LẦN ở §1d, 0 lần lặp lại trong ô BR, AC trỏ tới thay vì chép; nếu không có → section đã xoá hẳn (không để rỗng)
 - [ ] 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)`
@@ -838,6 +928,7 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 - [ ] **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
+- [ ] **Wireframe không nhân bản §3**: 0 dòng §4b lặp lại nội dung đã có ở bảng Business Rule — không thêm thông tin thì ref BR ID; cả §4b không thêm gì mới thì xoá hẳn (tránh hai nguồn sự thật)
 - [ ] **Đị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
 
 ## Output

package/core/templates/prd.template.md

@@ -5,8 +5,13 @@
   AI Agent sẽ điền các section dựa trên input từ PO.
   Các placeholder {…} cần được thay thế bằng nội dung thực tế.
 
-  FORMAT CHUẨN: Business Rule = bảng 3 cột
-  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+  FORMAT BR: MẶC ĐỊNH bảng 3 cột — ID | Business Rule | Business Logic
+    (KHÔNG tách Business Logic ra khối riêng).
+    NGOẠI LỆ — MỞ CỘT: nếu MỌI BR trong một UC chia sẻ cùng một bộ thuộc tính lặp lại
+    (vd trigger / data / tần suất), promote các thuộc tính đó thành CỘT RIÊNG —
+    một bản ghi = một DÒNG. Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi
+    NHIỀU HƠN MỘT bản ghi cùng cấu trúc vào một ô. Chi tiết + cảnh báo BR ID churn:
+    xem §3 "Business Rule" của template và mục "Hình dạng bảng Business Rule" của lệnh.
 
   TERMINOLOGY:
   - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
@@ -84,6 +89,18 @@
 
 - {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
 
+## d. Quy ước *(TUỲ CHỌN — chỉ thêm khi tài liệu có quy ước áp dụng xuyên suốt; nếu không có → XOÁ HẲN section này)*
+
+> Khai báo **MỘT LẦN** các quy ước áp dụng cho **mọi BR** ở §3. BR **KHÔNG** lặp lại nội dung đã khai ở đây,
+> AC §2 **trỏ tới** quy ước thay vì chép lại. Đây là nơi chứa định nghĩa dùng chung, giá trị mặc định,
+> và cách đọc các cột của bảng BR — những thứ trước đây bị xé nhỏ và lặp trong từng dòng.
+>
+> Phân biệt với **§1b Phạm vi** (ranh giới làm/không làm) và **business-dictionary** (định nghĩa thuật ngữ
+> cấp domain, dùng chung nhiều PRD): §1d chỉ chứa quy ước **cục bộ của tài liệu này**.
+
+- **{Tên quy ước}**: {nội dung áp dụng cho mọi BR bên dưới}
+- **{Giá trị mặc định dùng chung}**: {…}
+
 ---
 
 # 2. Acceptance Criteria
@@ -118,11 +135,47 @@
 
 **Business Rule**
 
+> **Hình dạng bảng — mặc định 3 cột.** Dùng dạng này khi Business Logic là **văn xuôi** (mô tả luật bằng câu).
+
 | ID | Business Rule | Business Logic |
 |----|---------------|----------------|
 | {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
 | {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
 
+<!--
+  NGOẠI LỆ — MỞ CỘT (dùng THAY cho bảng 3 cột ở trên, KHÔNG dùng cả hai):
+
+  Điều kiện kích hoạt: MỌI BR trong UC này chia sẻ CÙNG một bộ thuộc tính lặp lại.
+  Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi NHIỀU HƠN MỘT bản ghi cùng
+  cấu trúc vào một ô Business Logic.
+
+  Khi kích hoạt: promote thuộc tính thành CỘT, một bản ghi = một DÒNG:
+
+    | ID  | Business Rule | {Thuộc tính 1} | {Thuộc tính 2} | {Thuộc tính 3} |
+    |-----|---------------|----------------|----------------|----------------|
+    | BR1 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+    | BR2 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+
+  Hai cột ID + Business Rule LUÔN giữ (traceability phụ thuộc chúng). Chỉ cột
+  Business Logic được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên
+  §1d Quy ước, ĐỪNG lặp trong từng ô.
+
+  ⚠️ CẢNH BÁO BR ID CHURN — đọc trước khi mở cột trên PRD ĐÃ TỒN TẠI:
+  Mở cột đúng nghĩa = một bản ghi một dòng ⇒ số BR TĂNG. Vì BR ID tăng liên tục
+  trên toàn PRD, chèn dòng ở giữa sẽ ĐÁNH SỐ LẠI mọi BR phía sau. Nếu PRD này đã có
+  BDD downstream, mọi tag `@trace.business_rules` trong .feature sẽ trỏ SAI trong im lặng.
+  → Trước khi mở cột trên PRD đã có: kiểm tra `{specs_dir}/{domain}/{prd-slug}/bdd/`.
+    - Chưa có BDD → mở cột tự do.
+    - ĐÃ có BDD → DỪNG, báo người dùng: cần re-gen BDD sau khi đổi, hoặc giữ nguyên hình dạng cũ.
+  PRD sinh MỚI không bị ảnh hưởng (chưa có downstream).
+-->
+
+> **Note {BR ref}:** *(TUỲ CHỌN)* {giải thích **quyết định đã chốt** — vì sao luật này như vậy, ràng buộc
+> nào dẫn tới nó, biên nào đã cân nhắc}. Đặt ngay sau bảng, cạnh nơi phát sinh.
+>
+> **Ranh giới với "Giả định AI" (Appendix):** Note = quyết định **đã chốt**, giải thích cho người đọc sau.
+> Giả định AI = **độ vênh CẦN PO chốt**. Note **KHÔNG** được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI.
+
 ---
 
 #### {TICKET}-{N}-UC2: {Tên use case}
@@ -143,6 +196,12 @@ flowchart TD
 
 ## b. Wireframe
 
+> **KHÔNG nhân bản §3.** Wireframe liệt kê **màn + thành phần + hành động** — nó là nguồn coverage màn hình
+> cho `/generate-bdd` (C.1), KHÔNG phải bản sao thứ hai của bảng Business Rule.
+> Nếu một dòng Wireframe không thêm thông tin nào ngoài BR đã có → **tham chiếu BR ID, đừng chép nội dung**.
+> Nếu cả §4b không thêm gì mới so với §3 → **xoá hẳn §4b** (hai nguồn sự thật cho cùng một dữ liệu sẽ lệch nhau
+> ngay lần sửa đầu tiên).
+
 ### Screen 1: {Tên màn}
 
 | Thành phần | Chi tiết |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"

package/templates/prd.template.md

@@ -5,8 +5,13 @@
   AI Agent sẽ điền các section dựa trên input từ PO.
   Các placeholder {…} cần được thay thế bằng nội dung thực tế.
 
-  FORMAT CHUẨN: Business Rule = bảng 3 cột
-  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+  FORMAT BR: MẶC ĐỊNH bảng 3 cột — ID | Business Rule | Business Logic
+    (KHÔNG tách Business Logic ra khối riêng).
+    NGOẠI LỆ — MỞ CỘT: nếu MỌI BR trong một UC chia sẻ cùng một bộ thuộc tính lặp lại
+    (vd trigger / data / tần suất), promote các thuộc tính đó thành CỘT RIÊNG —
+    một bản ghi = một DÒNG. Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi
+    NHIỀU HƠN MỘT bản ghi cùng cấu trúc vào một ô. Chi tiết + cảnh báo BR ID churn:
+    xem §3 "Business Rule" của template và mục "Hình dạng bảng Business Rule" của lệnh.
 
   TERMINOLOGY:
   - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
@@ -84,6 +89,18 @@
 
 - {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
 
+## d. Quy ước *(TUỲ CHỌN — chỉ thêm khi tài liệu có quy ước áp dụng xuyên suốt; nếu không có → XOÁ HẲN section này)*
+
+> Khai báo **MỘT LẦN** các quy ước áp dụng cho **mọi BR** ở §3. BR **KHÔNG** lặp lại nội dung đã khai ở đây,
+> AC §2 **trỏ tới** quy ước thay vì chép lại. Đây là nơi chứa định nghĩa dùng chung, giá trị mặc định,
+> và cách đọc các cột của bảng BR — những thứ trước đây bị xé nhỏ và lặp trong từng dòng.
+>
+> Phân biệt với **§1b Phạm vi** (ranh giới làm/không làm) và **business-dictionary** (định nghĩa thuật ngữ
+> cấp domain, dùng chung nhiều PRD): §1d chỉ chứa quy ước **cục bộ của tài liệu này**.
+
+- **{Tên quy ước}**: {nội dung áp dụng cho mọi BR bên dưới}
+- **{Giá trị mặc định dùng chung}**: {…}
+
 ---
 
 # 2. Acceptance Criteria
@@ -118,11 +135,47 @@
 
 **Business Rule**
 
+> **Hình dạng bảng — mặc định 3 cột.** Dùng dạng này khi Business Logic là **văn xuôi** (mô tả luật bằng câu).
+
 | ID | Business Rule | Business Logic |
 |----|---------------|----------------|
 | {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
 | {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
 
+<!--
+  NGOẠI LỆ — MỞ CỘT (dùng THAY cho bảng 3 cột ở trên, KHÔNG dùng cả hai):
+
+  Điều kiện kích hoạt: MỌI BR trong UC này chia sẻ CÙNG một bộ thuộc tính lặp lại.
+  Dấu hiệu tự phát hiện: đang phải dùng <br/> để nhồi NHIỀU HƠN MỘT bản ghi cùng
+  cấu trúc vào một ô Business Logic.
+
+  Khi kích hoạt: promote thuộc tính thành CỘT, một bản ghi = một DÒNG:
+
+    | ID  | Business Rule | {Thuộc tính 1} | {Thuộc tính 2} | {Thuộc tính 3} |
+    |-----|---------------|----------------|----------------|----------------|
+    | BR1 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+    | BR2 | {luật ngắn}   | {giá trị}      | {giá trị}      | {giá trị}      |
+
+  Hai cột ID + Business Rule LUÔN giữ (traceability phụ thuộc chúng). Chỉ cột
+  Business Logic được tách thành N cột. Giá trị dùng chung cho mọi dòng → đưa lên
+  §1d Quy ước, ĐỪNG lặp trong từng ô.
+
+  ⚠️ CẢNH BÁO BR ID CHURN — đọc trước khi mở cột trên PRD ĐÃ TỒN TẠI:
+  Mở cột đúng nghĩa = một bản ghi một dòng ⇒ số BR TĂNG. Vì BR ID tăng liên tục
+  trên toàn PRD, chèn dòng ở giữa sẽ ĐÁNH SỐ LẠI mọi BR phía sau. Nếu PRD này đã có
+  BDD downstream, mọi tag `@trace.business_rules` trong .feature sẽ trỏ SAI trong im lặng.
+  → Trước khi mở cột trên PRD đã có: kiểm tra `{specs_dir}/{domain}/{prd-slug}/bdd/`.
+    - Chưa có BDD → mở cột tự do.
+    - ĐÃ có BDD → DỪNG, báo người dùng: cần re-gen BDD sau khi đổi, hoặc giữ nguyên hình dạng cũ.
+  PRD sinh MỚI không bị ảnh hưởng (chưa có downstream).
+-->
+
+> **Note {BR ref}:** *(TUỲ CHỌN)* {giải thích **quyết định đã chốt** — vì sao luật này như vậy, ràng buộc
+> nào dẫn tới nó, biên nào đã cân nhắc}. Đặt ngay sau bảng, cạnh nơi phát sinh.
+>
+> **Ranh giới với "Giả định AI" (Appendix):** Note = quyết định **đã chốt**, giải thích cho người đọc sau.
+> Giả định AI = **độ vênh CẦN PO chốt**. Note **KHÔNG** được nuốt Giả định AI — nghi ngờ thì để ở Giả định AI.
+
 ---
 
 #### {TICKET}-{N}-UC2: {Tên use case}
@@ -143,6 +196,12 @@ flowchart TD
 
 ## b. Wireframe
 
+> **KHÔNG nhân bản §3.** Wireframe liệt kê **màn + thành phần + hành động** — nó là nguồn coverage màn hình
+> cho `/generate-bdd` (C.1), KHÔNG phải bản sao thứ hai của bảng Business Rule.
+> Nếu một dòng Wireframe không thêm thông tin nào ngoài BR đã có → **tham chiếu BR ID, đừng chép nội dung**.
+> Nếu cả §4b không thêm gì mới so với §3 → **xoá hẳn §4b** (hai nguồn sự thật cho cùng một dữ liệu sẽ lệch nhau
+> ngay lần sửa đầu tiên).
+
 ### Screen 1: {Tên màn}
 
 | Thành phần | Chi tiết |