@educa-corp/fw 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 > `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.2 — 2026-09-30
+
+- **Hướng dẫn sử dụng** được cài vào dự án ở `.fw/guide/`, đúng với version đang dùng và đọc được khi không có mạng. Bắt đầu từ `.fw/guide/README.md`. Có thể hỏi Claude, ví dụ *"Đọc .fw/guide và cho biết cách đổi PRD"*.
+- `fw install` tự thêm `.fw/backup/` vào `.gitignore`, để các bản sao file đã sửa không bị commit nhầm.
+
+## 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/bin/fw.js

@@ -26,11 +26,13 @@ const SOURCES = [
   { from: 'templates', to: '.fw/core/templates' },
   { from: 'tools', to: '.fw/core/tools' },
   { from: 'bin/fw.js', to: '.fw/core/bin/fw.js' },
+  { from: 'docs/guide', to: '.fw/guide' },
 ];
 // Mọi file gói npm phải mang theo để fw.js chạy được — test đối chiếu với `files` của package.json.
 const RUNTIME_FILES = ['package.json', 'CHANGELOG.md', 'bin/config.template.yaml', ...SOURCES.map((s) => s.from)];
 const CONFIG = '.fw/config.yaml';
 const SETTINGS = '.claude/settings.json';
+const GITIGNORE_LINE = '.fw/backup/';
 
 // Lệnh AI dùng để sửa file spec (xem tools/spec_edit.py). Cho phép sẵn để PO không bị hỏi quyền mỗi lần.
 const SPEC_EDIT = '.fw/core/tools/spec_edit.py';
@@ -98,6 +100,18 @@ function allowSpecEdit(target) {
   return { added };
 }
 
+// .fw/backup/ chứa bản sao file người dùng đã sửa, giữ lại khi nâng cấp — không nên vào git.
+function ignoreBackup(target) {
+  const p = path.join(target, '.gitignore');
+  const text = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+  const lines = text.split(/\r?\n/).map((l) => l.trim());
+  if (lines.includes(GITIGNORE_LINE) || lines.includes('/' + GITIGNORE_LINE)) return false;
+  const sep = text && !text.endsWith('\n') ? '\n' : '';
+  const block = '\n# @educa-corp/fw — bản sao file đã sửa, tạo khi nâng cấp\n' + GITIGNORE_LINE + '\n';
+  fs.writeFileSync(p, text + sep + block);
+  return true;
+}
+
 function install(target) {
   const old = readManifest(target);
   const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
@@ -163,6 +177,7 @@ function install(target) {
     changes: changesSince(old.version),
     python: findPython(),
     permissions: allowSpecEdit(target),
+    gitignore: ignoreBackup(target),
   };
 }
 
@@ -193,6 +208,7 @@ function printReport(r) {
   }
   console.log(`  thêm ${r.added.length} · cập nhật ${r.updated.length} · gỡ ${r.removed.length}`);
   if (r.configCreated) console.log(`  tạo ${CONFIG} — hãy mở file này và khai specs, tracker, units`);
+  if (r.gitignore) console.log(`  thêm ${GITIGNORE_LINE} vào .gitignore`);
   if (r.permissions.error) console.log(`  ⚠ ${r.permissions.error}`);
   else if (r.permissions.added.length) console.log(`  thêm ${r.permissions.added.length} luật cho phép vào ${SETTINGS} (AI sửa spec không phải hỏi quyền)`);
   if (r.python) {

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/docs/guide/01-bat-dau.md

@@ -0,0 +1,99 @@
+[← Hướng dẫn](README.md)
+
+# Bắt đầu
+
+## 1. Máy cần có
+
+| Phần mềm | Bản | Kiểm tra | Cài |
+|---|---|---|---|
+| Node.js | 18 trở lên | `node --version` | https://nodejs.org |
+| Python | 3.8 trở lên | `python --version` | Windows: `winget install Python.Python.3.12` · macOS: `brew install python` |
+| Claude Code | — | `claude --version` | https://claude.com/claude-code |
+
+**Vì sao cần Python:** AI sửa tài liệu spec qua một công cụ viết bằng Python. Công cụ này chặn các lỗi như sửa không trúng chỗ, hỏng chữ có dấu. Thiếu Python thì mọi lệnh AI sẽ dừng ngay và báo cài.
+
+**Windows:** nên cài Python bằng `winget` như trên (bản python.org). Bản cài từ Microsoft Store thỉnh thoảng thoát lỗi mà không chạy. Lệnh AI tự chạy lại được, nhưng bản python.org ổn định hơn.
+
+## 2. Cài vào dự án
+
+Mở terminal **ở thư mục gốc của dự án**. Với dự án kiểu umbrella, đó là thư mục chứa các repo con.
+
+```bash
+npx @educa-corp/fw install
+```
+
+Kết quả mẫu:
+
+```
+fw 0.6.2 — đã cài
+  thêm 20 · cập nhật 0 · gỡ 0
+  tạo .fw/config.yaml — hãy mở file này và khai specs, tracker, units
+  thêm .fw/backup/ vào .gitignore
+  thêm 3 luật cho phép vào .claude/settings.json (AI sửa spec không phải hỏi quyền)
+  Python: python
+```
+
+Lệnh tạo ra:
+
+| Thư mục / file | Là gì | Commit vào git? |
+|---|---|---|
+| `.claude/commands/` | Các lệnh `/product`, `/prd`… | ✅ Có |
+| `.claude/settings.json` | Quyền cho AI sửa spec mà không hỏi mỗi lần | ✅ Có |
+| `.fw/core/` | Bộ câu hỏi, khuôn tài liệu, công cụ sửa spec, bản `fw` chạy offline | ✅ Có |
+| `.fw/config.yaml` | **Cấu hình của dự án. Bạn được sửa** | ✅ Có |
+| `.fw/guide/` | Bộ hướng dẫn này, đúng với version đang cài | ✅ Có |
+| `.fw/backup/` | Bản sao file bạn đã tự sửa, được giữ lại khi nâng cấp | ❌ Không. `fw install` đã tự thêm vào `.gitignore` |
+
+Commit xong, đồng đội clone về là **có ngay**, không cần tự cài.
+
+## 3. Khai cấu hình
+
+Mở `.fw/config.yaml`:
+
+```yaml
+workspace: LMS
+
+# Thư mục chứa mọi tài liệu (product, PRD, …). Umbrella: trỏ vào repo spec, ví dụ spec-repo/specs
+specs: specs
+
+# [jira] | [builtin] | [jira, builtin]
+tracker: [builtin]
+
+# Mỗi unit là một codebase build/deploy độc lập
+units: []
+#  - { name: web-phuhuynh, path: apps/parent-web, stack: react }
+```
+
+| Trường | Cần khai lúc nào |
+|---|---|
+| `specs` | **Ngay.** Mọi tài liệu sẽ được ghi vào thư mục này |
+| `tracker` | **Ngay.** `builtin` thì AI tự đánh mã epic `EP-01`, `EP-02`…. `jira` thì AI hỏi Jira key (ví dụ `EDU-100`) |
+| `units` | Chưa cần. Các lệnh hiện có chưa dùng tới trường này. Khai sẵn cũng được |
+
+## 4. Chạy lần đầu
+
+Mở Claude Code ở thư mục gốc dự án rồi gõ:
+
+```
+/product
+```
+
+AI sẽ hỏi về sản phẩm theo từng lượt, tối đa 4 câu mỗi lượt. Có sẵn tài liệu (BRD, đề án, slide) thì dán vào, AI sẽ trích trước để bạn chỉ cần xác nhận. Chi tiết xem [hướng dẫn /product](lenh/product.md).
+
+Một vòng làm việc đầy đủ:
+
+| # | Gõ | Kết quả |
+|---|---|---|
+| 1 | `/product` | `specs/product/product.md`: nhóm người dùng, danh sách epic |
+| 2 | `/clear` → `/product EP-01` | File làm rõ yêu cầu của EP-01 |
+| 3 | `/clear` → `/prd EP-01` | `specs/{domain}/{slug}/prd.md` |
+| 4 | Khi cần đổi: `/clear` → `/prd EP-01 change khoá tài khoản sau 3 lần sai` | PRD lên version mới |
+
+## 5. Nâng cấp
+
+```bash
+npx @educa-corp/fw upgrade          # lên bản mới nhất
+npx @educa-corp/fw upgrade 0.7.0    # lên đúng một version
+```
+
+Lệnh in ra version cũ → mới kèm danh sách thay đổi. File bạn đã tự sửa trong `.claude/commands/` hay `.fw/core/` sẽ được **sao lưu vào `.fw/backup/`** trước khi bị thay. `config.yaml` **không bao giờ** bị ghi đè. Chi tiết: [fw](lenh/fw.md).

package/docs/guide/02-khai-niem.md

@@ -0,0 +1,66 @@
+[← Hướng dẫn](README.md)
+
+# Khái niệm
+
+Chỉ những khái niệm bạn **gặp khi dùng** các lệnh hiện có.
+
+## Ba tầng tài liệu
+
+| Tầng | Trả lời câu hỏi | Lệnh | File |
+|---|---|---|---|
+| **Sản phẩm** | Sản phẩm cho ai, gồm những tính năng lớn nào? | `/product` | `specs/product/product.md` |
+| **Epic** (làm rõ yêu cầu) | Tính năng này thật ra cần gì? Còn chỗ nào chưa rõ? | `/product EP-01` | `specs/product/epics/EP-01-….md` |
+| **PRD** | Đặc tả chính thức để làm BDD, thiết kế và code | `/prd EP-01` | `specs/{domain}/{slug}/prd.md` |
+
+**Epic là nháp, PRD là bản chính thức.** Khi PRD được tạo, epic chuyển sang `handed-off` và chỉ còn là lịch sử quyết định. Muốn đổi yêu cầu thì sửa PRD, **không sửa epic**.
+
+## Thuật ngữ
+
+| Thuật ngữ | Nghĩa | Ví dụ |
+|---|---|---|
+| **Actor** (nhóm người dùng) | Nhóm người trực tiếp dùng hệ thống, mã `ACT-01`… | ACT-01 Admin |
+| **Epic** | Một nhóm tính năng lớn của sản phẩm | EP-01 Quản trị tài khoản và phân quyền |
+| **UC** (Use case) | Một mục tiêu của một actor, xong trong một lần tương tác | UC-005 Đổi mật khẩu và quên mật khẩu |
+| **BR** (Business Rule) | Luật nghiệp vụ hệ thống phải tuân theo, dạng *"Hệ thống PHẢI / KHÔNG ĐƯỢC …"* | UC-001-BR01: Email PHẢI bắt buộc và duy nhất |
+| **Business Logic** | Cách luật được thực hiện: rẽ nhánh, công thức, thông báo khi lỗi | Email trống hoặc đã có tài khoản → từ chối, báo lý do |
+| **AC** (Acceptance Criteria, điều kiện nghiệm thu) | Điều kiện kiểm được là đạt hay không đạt, dạng *"Khi … thì …"* | UC-002-AC01: Khi tài khoản mới quá 7 ngày chưa đăng nhập thì bị chuyển inactive, đăng nhập bị từ chối |
+| **Ràng buộc** | Điều kiện áp cho **mọi epic**, mã `CON-01`… | CON-01: Audit log không được xoá hay sửa |
+| **Checkpoint** | Một điểm dừng để bạn chốt. `/product` có 2 (sản phẩm) hoặc 3 (epic) checkpoint | — |
+
+## Mã ổn định
+
+| Đối tượng | Mã | Đánh số |
+|---|---|---|
+| UC | `UC-001` | Toàn sản phẩm, mọi epic dùng chung một dãy |
+| Business Rule trong PRD | `UC-003-BR02` | Trong từng UC |
+| AC trong PRD | `UC-003-AC04` | Trong từng UC |
+| Business Rule / AC trong epic | `BR1.`, `AC1.` | Trong epic. Chèn giữa thì dùng `BR8a.` |
+
+**Mã đã cấp không bao giờ đổi và không dùng lại.** Mục bỏ đi được giữ lại, gạch ngang và ghi *"Đã bỏ (v1.1)"*. Nhờ vậy BDD, code và test sau này luôn trỏ đúng mục.
+
+## Dấu 🤖 và ✅
+
+| Dấu | Nghĩa |
+|---|---|
+| 🤖 | AI trích hoặc tự thêm, **chờ bạn chốt** |
+| ✅ | Bạn đã xác nhận |
+
+Cách xác nhận: trả lời như bình thường (*"Đúng"*, *"OK"*), hoặc xác nhận theo mã (*"OK UC-003-BR04, UC-003-AC02"*).
+
+Tài liệu chỉ được đặt trạng thái "xong" (`ready` hoặc `approved`) khi **không còn 🤖**, **không còn câu hỏi mở**, và **đã ghi người duyệt**. Công cụ sẽ tự chặn nếu chưa đủ, AI không lách được.
+
+## Nguồn của từng mục trong PRD
+
+Mỗi Business Rule và AC trong PRD ghi rõ nó lấy từ đâu, và **chỉ ghi mã**:
+
+| Ghi | Nghĩa |
+|---|---|
+| `(nguồn: BR3, AC1)` | Lấy từ BR3 và AC1 của epic |
+| `(nguồn: CON-02)` | Lấy từ ràng buộc CON-02 của tầng sản phẩm |
+| `(nguồn: PRD)` | Thêm trong lúc viết PRD, bạn đã duyệt |
+
+Nhờ vậy công cụ kiểm được **mọi BR và AC của epic đều đã vào PRD**, không rơi mục nào.
+
+## Vì sao phải `/clear`
+
+Mỗi lượt hỏi-đáp, AI đọc lại **toàn bộ** hội thoại từ đầu phiên. Phiên càng dài thì mỗi lượt càng đắt. Đo thực tế: chạy tiếp trong phiên cũ đắt hơn khoảng **56%** mỗi lượt. Mọi thứ đã chốt đều nằm trong file, nên mở phiên mới **không mất gì**. Lệnh sẽ nhắc bạn đúng lúc nên `/clear`.

package/docs/guide/README.md

@@ -0,0 +1,59 @@
+# Hướng dẫn sử dụng `@educa-corp/fw`
+
+> Framework làm việc với Claude Code: đưa một tính năng đi từ **ý tưởng → làm rõ yêu cầu → PRD → …**, AI hỏi và viết, con người xác nhận ở mỗi bước.
+> Hướng dẫn này viết cho **bản 0.6.2**. Chỉ mô tả những lệnh **đã có**. Lệnh mới có thì hướng dẫn mới được bổ sung.
+> Trong dự án đã cài framework, bản hướng dẫn đúng với version đang dùng nằm ở **`.fw/guide/`**. Có thể hỏi Claude: *"Đọc .fw/guide và cho biết cách đổi PRD"*.
+
+---
+
+## Bạn muốn…
+
+| Bạn muốn | Đọc |
+|---|---|
+| Cài vào dự án và chạy lần đầu | [Bắt đầu](01-bat-dau.md) |
+| Hiểu vài khái niệm trước khi dùng (UC, BR, AC, 🤖/✅…) | [Khái niệm](02-khai-niem.md) |
+| Biết **vai trò của mình** dùng lệnh nào | [PO / BA](vai-tro/po-ba.md) · *Dev, QC: sắp có* |
+| Tra cứu một lệnh cụ thể | Bảng lệnh ngay bên dưới |
+| Gặp lỗi | [Xử lý sự cố](xu-ly-su-co.md) |
+
+---
+
+## Pipeline hiện có
+
+```
+cài framework ──► /product ──► /product EP-xx ──► /prd EP-xx ┄┄► (bước tiếp: /bdd — sắp có)
+                  tầng          làm rõ một         viết PRD
+                  sản phẩm      tính năng              ▲ │
+                                                       └─┘ /prd EP-xx change  (đổi PRD)
+```
+
+Mỗi lệnh kết thúc bằng một khối giống nhau. Bạn chỉ cần đọc dòng **Bước tiếp**:
+
+```
+---
+Trạng thái : 🟡 Đang làm rõ — checkpoint 1/3, còn 2 câu hỏi mở
+Đã ghi     : specs/product/epics/EP-01-quan-tri-tai-khoan-va-phan-quyen.md
+Luồng      : [Product ◀ bạn ở đây] → PRD → BDD → TDD · Design-spec → Code → Test → QC
+Bước tiếp  : `/clear` rồi `/product EP-01`
+```
+
+---
+
+## Bảng lệnh
+
+| Lệnh | Ai | Làm gì | Hướng dẫn |
+|---|---|---|---|
+| `npx @educa-corp/fw install` | Người cài dự án | Cài framework vào dự án (một lần) | [fw](lenh/fw.md) |
+| `npx @educa-corp/fw upgrade [version]` | Người phụ trách dự án | Nâng cấp framework | [fw](lenh/fw.md) |
+| `/product` | PO / BA | Làm rõ **tầng sản phẩm**: tầm nhìn, nhóm người dùng, danh sách epic, ràng buộc | [/product](lenh/product.md) |
+| `/product <EPIC-ID>` | PO / BA | **Làm rõ yêu cầu** một tính năng trước khi viết PRD | [/product](lenh/product.md) |
+| `/prd <EPIC-ID>` | PO / BA | Viết **PRD chính thức** từ epic đã làm rõ | [/prd](lenh/prd.md) |
+| `/prd <EPIC-ID> change <mô tả>` | PO / BA | Thêm, sửa hoặc bỏ nội dung PRD | [/prd](lenh/prd.md) |
+
+---
+
+## Ba điều nên nhớ
+
+1. **AI đề xuất, bạn xác nhận.** Mục AI tự trích hoặc tự thêm mang dấu 🤖. Chỉ khi bạn đồng ý thì nó mới thành ✅. Không có gì được coi là "đã chốt" nếu bạn chưa xác nhận.
+2. **Mọi thứ đã chốt đều nằm trong file.** Vì vậy bạn dừng lúc nào cũng được, và nên **`/clear` giữa các bước** để phiên mới rẻ hơn.
+3. **Mã không bao giờ đổi.** `UC-003-BR02` hôm nay và sau 10 lần sửa vẫn là cùng một Business Rule. Mục bỏ đi thì gạch ngang, không bị xoá.

package/docs/guide/lenh/fw.md

@@ -0,0 +1,51 @@
+[← Hướng dẫn](../README.md) · [Bảng lệnh](../README.md#bảng-lệnh)
+
+# `fw` — cài và nâng cấp framework
+
+> Lệnh chạy ở **terminal**, không chạy trong Claude Code, và không tốn token.
+
+| Lệnh | Làm gì |
+|---|---|
+| `npx @educa-corp/fw install` | Cài framework vào dự án. Chạy **một lần**, ở thư mục gốc dự án |
+| `npx @educa-corp/fw upgrade` | Nâng cấp lên bản mới nhất |
+| `npx @educa-corp/fw upgrade 0.7.0` | Nâng cấp (hoặc quay về) đúng một version |
+| `node .fw/core/bin/fw.js --version` | Xem dự án đang dùng bản nào |
+
+> ⚠️ Luôn gõ **tên đầy đủ** `@educa-corp/fw`. Trên npm có một gói khác tên `fw` của người khác, gõ `npx fw` sẽ tải nhầm gói đó.
+
+## `install` làm những gì
+
+1. Tải framework từ npm.
+2. Chép vào dự án: lệnh vào `.claude/commands/`; bộ câu hỏi, khuôn, công cụ sửa spec và **một bản `fw` chạy offline** vào `.fw/core/`; **hướng dẫn sử dụng** vào `.fw/guide/`.
+3. Tạo `.fw/config.yaml` nếu chưa có. File này **không bao giờ** bị ghi đè.
+4. Thêm quyền vào `.claude/settings.json` để AI sửa file spec mà không hỏi mỗi lần. Cấu hình khác trong file giữ nguyên.
+5. Thêm `.fw/backup/` vào `.gitignore` (nếu chưa có).
+6. Kiểm Python. Thiếu thì báo ❌ kèm lệnh cài.
+
+Bản `fw` chạy offline trong `.fw/core/bin/` có hai tác dụng: các việc tự động sau này (hook khi commit, CI) chạy **không cần mạng**, và luôn **đúng version** đã commit trong repo.
+
+## `upgrade` làm những gì
+
+```
+fw 0.6.0 → 0.6.1 — đã nâng cấp
+  Có gì mới:
+    - Thuật ngữ: Acceptance Criteria (điều kiện nghiệm thu) …
+  thêm 0 · cập nhật 9 · gỡ 0
+```
+
+| Tình huống | Kết quả |
+|---|---|
+| File framework bạn **chưa** sửa | Thay bằng bản mới |
+| File framework bạn **đã tự sửa** | Sao lưu vào `.fw/backup/<ngày giờ>/` rồi mới thay, và báo tên file |
+| File bản mới **bỏ đi** | Gỡ, nếu bạn chưa sửa. Đã sửa thì giữ lại và báo |
+| Lệnh có sẵn trong dự án **trùng tên** lệnh framework | Sao lưu trước khi thay |
+| `.fw/config.yaml` | Không đụng tới |
+
+Nâng cấp xong, commit các thay đổi để cả team cùng dùng bản mới.
+
+## Muốn giữ thay đổi riêng của dự án
+
+Đừng sửa file trong `.claude/commands/` hay `.fw/core/`, vì lần nâng cấp sau sẽ thay chúng (dù có sao lưu). Chỗ đúng để đặt thay đổi riêng:
+- `.fw/config.yaml`: cấu hình dự án.
+- `specs/product/glossary.md`: thuật ngữ của dự án.
+- Góp ý để sửa trong chính framework, rồi nâng cấp.

package/docs/guide/lenh/prd.md

@@ -0,0 +1,80 @@
+[← Hướng dẫn](../README.md) · [Bảng lệnh](../README.md#bảng-lệnh)
+
+# `/prd` — viết PRD chính thức
+
+> Biến epic đã làm rõ thành **PRD**: chia thành các use case, mỗi UC có Business Rule và AC riêng với **mã ổn định**. PRD là nguồn cho BDD, thiết kế và code ở các bước sau.
+
+| | Tạo PRD | Đổi PRD |
+|---|---|---|
+| **Gõ** | `/prd EP-01` | `/prd EP-01 change <mô tả thay đổi>` |
+| **Ai** | PO / BA | PO / BA |
+| **Cần có trước** | Epic `ready` (xem [/product](product.md)) | PRD đã có |
+| **Số lượt** | 2 | 2 |
+| **Ghi ra** | `specs/{domain}/{slug}/prd.md` · epic chuyển `handed-off` | `prd.md`, version tăng (1.0 → 1.1) |
+| **Bước tiếp** | Duyệt PRD → `/bdd UC-xxx` *(sắp có)* | Duyệt lại bản mới |
+
+---
+
+## Tạo PRD: `/prd EP-01`
+
+**Lượt 1: chia use case.** AI đề xuất danh sách UC, mỗi UC lấy những BR và AC nào của epic. Ví dụ thật với EP-01 của LMS (21 BR, 21 AC, chia thành 10 UC):
+
+| UC | Tên | Lấy từ epic |
+|---|---|---|
+| UC-001 | Tạo tài khoản nhân sự | BR1, BR2, BR3, BR4, BR8a, BR8b, BR19, AC1, AC21 |
+| UC-005 | Đổi mật khẩu và quên mật khẩu | BR4, BR6, BR12, AC15 |
+| … | … *(10 UC)* | … |
+
+Một BR có thể thuộc nhiều UC, ví dụ BR4 (mật khẩu mặc định) nằm ở cả UC-001 và UC-005.
+
+Bạn đồng ý, gộp hoặc tách UC.
+
+**Lượt 2: viết và duyệt.**
+1. AI ghi toàn bộ PRD trong một lần.
+2. Công cụ **kiểm độ phủ**: mọi BR và AC của epic đều phải có trong PRD. Thiếu thì AI bổ sung cho tới khi đủ. AI không được tự bỏ mục nào; muốn bỏ thì phải hỏi bạn.
+3. AI **chỉ in các mục 🤖**, tức những chỗ AI tự thêm, tách hoặc suy ra khi viết PRD. Không in lại cả PRD.
+4. Bạn mở file để đọc toàn bộ, rồi trả lời hoặc xác nhận theo mã: *"OK UC-003-BR04, UC-003-AC02"*.
+5. Hết 🤖 và hết câu hỏi mở thì AI hỏi *"Ai duyệt PRD này?"*, sau đó đặt `status: approved`.
+
+## PRD trông như thế nào
+
+```
+## 2. Use case
+### UC-001 — Tạo tài khoản nhân sự
+- Actor · Điều kiện trước · Kết quả sau · Luồng chính
+
+Business Rule (BR)
+| Mã          | Business Rule                                  | Business Logic                                   | Nguồn        |
+| UC-001-BR01 | Email PHẢI bắt buộc và duy nhất trên toàn hệ … | Email trống hoặc đã có tài khoản → từ chối, báo lý do | (nguồn: BR1) |
+
+Acceptance Criteria (điều kiện nghiệm thu)
+- UC-001-AC01. Khi Admin import file 10 dòng, trong đó 2 dòng trùng email thì 8 tài khoản được tạo, 2 dòng được báo lỗi kèm lý do. (nguồn: AC1)
+```
+
+Gồm 5 mục: **Tổng quan** (mục tiêu, actor, phạm vi, ràng buộc áp dụng) · **Use case** · **Màn hình** · **Câu hỏi còn mở** · **Lịch sử thay đổi**. Cột `Nguồn` chỉ ghi mã (xem [Khái niệm](../02-khai-niem.md#nguồn-của-từng-mục-trong-prd)).
+
+---
+
+## Đổi PRD: `/prd EP-01 change <mô tả>`
+
+Dùng cho **mọi** thay đổi: thêm, sửa, bỏ.
+
+```
+/prd EP-01 change khoá tài khoản sau 3 lần đăng nhập sai
+```
+
+**Lượt 1: kế hoạch.** AI tìm mọi mục bị ảnh hưởng, kể cả những mục kéo theo, rồi trình bảng *(ví dụ minh hoạ)*:
+
+| Mã | Loại | Hiện tại | Sẽ thành |
+|---|---|---|---|
+| UC-001-BR05 | sửa | Khoá sau 5 lần sai | Khoá sau 3 lần sai |
+| UC-001-AC07 | thêm | — | Khi sai 3 lần thì … |
+| UC-001-BR06 | bỏ | … | ~~…~~ Đã bỏ (v1.1) |
+
+**Lượt 2: áp dụng.** AI sửa đúng các mục đó, thêm dòng vào Lịch sử thay đổi, tăng version. PRD đang `approved` thì quay về `draft` và **cần duyệt lại**.
+
+## Lưu ý
+
+- **Bạn được tự sửa tay PRD.** Nhưng giữ nguyên mã, dấu ✅ / 🤖 và đoạn `<!-- sec:… -->`. Sửa nhiều thì nên dùng `change`, để AI tìm giúp các mục bị kéo theo.
+- **Không sửa epic sau khi đã có PRD.** Epic lúc này chỉ còn là lịch sử.
+- PRD tạo bằng bản framework cũ (trước 0.6.1) có thể còn ghi nguồn bằng lời, ví dụ *"(nguồn: PO chốt khi viết PRD)"*. Lần sửa đầu tiên AI sẽ được yêu cầu đổi các chỗ đó thành mã, thường là `PRD`.

package/docs/guide/lenh/product.md

@@ -0,0 +1,66 @@
+[← Hướng dẫn](../README.md) · [Bảng lệnh](../README.md#bảng-lệnh)
+
+# `/product` — làm rõ yêu cầu
+
+> AI **hỏi ngược lại** để bạn nói ra những điều đã biết nhưng chưa viết: phạm vi, trường hợp đặc biệt, luật nghiệp vụ. Làm việc này **trước** khi viết PRD, để AI không phải đoán.
+
+| | Tầng sản phẩm | Một epic |
+|---|---|---|
+| **Gõ** | `/product` | `/product EP-01` (hoặc tên tính năng) |
+| **Ai** | PO / BA | PO / BA |
+| **Cần có trước** | Đã cài framework | Nên có tầng sản phẩm `ready` |
+| **Số checkpoint** | 2 | 3 |
+| **Ghi ra** | `specs/product/product.md`, `glossary.md` | `specs/product/epics/EP-01-….md` |
+| **Bước tiếp** | `/product <epic ưu tiên cao nhất>` | `/prd EP-01` |
+
+---
+
+## Tầng sản phẩm: `/product`
+
+| Checkpoint | AI hỏi | Bạn chốt |
+|---|---|---|
+| 1. Tầm nhìn và người dùng | Sản phẩm giải quyết gì, cho ai · khác cách làm hiện tại ở đâu · có những nhóm người dùng nào · đo thành công bằng gì · những gì **không** làm | Tầm nhìn, nhóm người dùng `ACT-xx`, mục tiêu, ngoài phạm vi |
+| 2. Epic và ràng buộc | Các nhóm tính năng lớn · ưu tiên · chia **giai đoạn** (MVP, Phase 2…) · **ràng buộc** áp cho mọi epic (pháp lý, bảo mật, vận hành, dữ liệu) | Bảng epic, ràng buộc `CON-xx` |
+
+Cuối cùng AI hỏi **ai duyệt** tầng sản phẩm, mặc định là bạn.
+
+**Có sẵn tài liệu (BRD, đề án…)?** Dán vào ngay lượt đầu. AI trích trước và gắn 🤖, bạn chỉ cần xác nhận hoặc sửa. Các mục **Stakeholders, Giả định, Rủi ro** chỉ được điền khi tài liệu có, AI không hỏi riêng.
+
+## Một epic: `/product EP-01`
+
+| Checkpoint | AI hỏi | Ví dụ thật (dự án LMS, EP-01) |
+|---|---|---|
+| 1. Hiểu đúng vấn đề | Bối cảnh · vấn đề · mục tiêu · actor · trong và ngoài phạm vi · phụ thuộc | "Học sinh, phụ huynh có đăng nhập không?" → chỉ có tài khoản ở hệ thống đăng nhập tập trung, chưa dùng LMS |
+| 2. Luồng và chỗ hở | Điểm vào, luồng chính, màn hình · **soi chỗ hở**: lỗi, ranh giới phạm vi, phụ thuộc ngầm, mâu thuẫn, trường hợp nhiều | "Một phụ huynh có 2 con thì sao?" → mỗi con một email riêng |
+| 3. Chốt để sang PRD | AI **đề xuất** Business Rule (`BR1.`…) và AC (`AC1.`…), tự kiểm độ phủ trước khi trình | 21 Business Rule, 21 AC |
+
+Bước soi chỗ hở **luôn chạy ít nhất một vòng**, kể cả khi tài liệu bạn đưa rất dày. Tài liệu càng dày thì càng dễ tạo cảm giác "đã đủ".
+
+**Khi bạn đổi ý giữa chừng:** nếu điều mới trái với tầng sản phẩm (ví dụ `product.md` ghi "học sinh không đăng nhập"), AI sẽ báo, mở lại các mục liên quan (về 🤖), hạ checkpoint, và đưa phương án để bạn chọn.
+
+---
+
+## Trong một lượt hỏi-đáp
+
+- **Tối đa 4 câu hỏi**, tính cả câu phụ. Câu chưa trả lời được lưu vào mục "Câu hỏi còn mở" và được hỏi lại ở lượt sau.
+- File được **ghi ngay sau mỗi lượt**, nên bạn dừng lúc nào cũng được.
+- Thuật ngữ mới lặp từ 2 lần trở lên: AI hỏi nghĩa, và hỏi có thêm vào `glossary.md` không.
+
+## Dừng và chạy tiếp
+
+- Muốn dừng: nói *"dừng"*. AI lưu lại và báo cách chạy tiếp.
+- Chạy tiếp: `/clear` rồi gõ lại **đúng lệnh cũ**. AI đọc file và tiếp tục từ checkpoint đang dở, hỏi các câu còn mở trước.
+- Sau mỗi checkpoint, lệnh sẽ gợi ý `/clear`. Nên làm theo, vì phiên mới rẻ hơn và không mất gì.
+
+## Trạng thái của file
+
+| `status` | Nghĩa | Chạy lại lệnh thì |
+|---|---|---|
+| `in-progress` | Đang làm rõ | Tiếp từ checkpoint đang dở |
+| `ready` | Đã chốt hết, không còn 🤖, không còn câu hỏi mở, đã có người duyệt | Chỉ sửa khi bạn nói rõ mục cần sửa |
+| `handed-off` | *(chỉ epic)* Đã có PRD | **Dừng.** Muốn đổi yêu cầu thì dùng `/prd EP-01 change …` |
+
+## Lưu ý
+
+- **Đừng xoá dấu ✅ / 🤖 hay đoạn `<!-- sec:… -->`** khi tự sửa file. Đoạn `<!-- sec:… -->` là mã của từng mục, lệnh dùng nó để tìm mục (khi xem trên GitLab hay VS Code thì không thấy).
+- File tạo từ bản framework cũ hơn sẽ được **tự bổ sung** các mục và cột còn thiếu khi chạy lại lệnh. Nội dung đã chốt giữ nguyên.

package/docs/guide/vai-tro/po-ba.md

@@ -0,0 +1,27 @@
+[← Hướng dẫn](../README.md)
+
+# PO / BA
+
+> Bạn quyết định **làm cái gì**. Mọi bước sau (BDD, thiết kế, code, test) đều dựa trên những gì bạn chốt ở đây.
+
+## Đường đi của bạn
+
+```
+/product ──► /product EP-xx ──► /prd EP-xx ──► duyệt PRD ──► (giao cho BDD — sắp có)
+                                    ▲ │
+                                    └─┘ /prd EP-xx change   khi yêu cầu thay đổi
+```
+
+| Bước | Lệnh | Bạn làm gì | Hướng dẫn |
+|---|---|---|---|
+| 1 | `/product` | Trả lời về sản phẩm, nhóm người dùng, epic, ràng buộc. Chốt từng mục | [/product](../lenh/product.md) |
+| 2 | `/product EP-xx` | Trả lời AI hỏi về tính năng. Đây là chỗ **quan trọng nhất**: câu trả lời càng rõ thì PRD càng ít phải sửa | [/product](../lenh/product.md#một-epic-product-ep-01) |
+| 3 | `/prd EP-xx` | Duyệt cách chia UC, xác nhận các mục 🤖, ghi người duyệt | [/prd](../lenh/prd.md) |
+| 4 | `/prd EP-xx change …` | Khi yêu cầu đổi. Duyệt kế hoạch thay đổi, rồi duyệt lại PRD | [/prd](../lenh/prd.md#đổi-prd-prd-ep-01-change-mô-tả) |
+
+## Mẹo
+
+- **Có tài liệu thì dán vào ngay lượt đầu.** AI trích trước, bạn chỉ xác nhận. Nhưng AI vẫn sẽ hỏi những gì tài liệu **chưa nói**.
+- **Chưa biết câu trả lời thì nói "chưa biết".** Câu đó được lưu vào "Câu hỏi còn mở" và hỏi lại lần sau. Không nên trả lời đại cho xong.
+- **`/clear` sau mỗi checkpoint.** Rẻ hơn, và không mất gì.
+- Một epic thường cần **2–3 buổi**. Bạn dừng lúc nào cũng được.

package/docs/guide/xu-ly-su-co.md

@@ -0,0 +1,31 @@
+[← Hướng dẫn](README.md)
+
+# Xử lý sự cố
+
+## Khi cài và nâng cấp
+
+| Bạn thấy | Nguyên nhân | Làm gì |
+|---|---|---|
+| `npm error 404 … @educa-corp/fw` ngay sau khi có bản mới | Registry npm cần vài phút mới đọc được bản vừa phát hành | Đợi 3–5 phút. Vẫn lỗi thì chạy `npm cache clean --force` rồi thử lại |
+| `❌ KHÔNG TÌM THẤY PYTHON 3.8+` | Máy chưa có Python, hoặc có nhưng chưa nằm trong PATH | Cài Python (xem [Bắt đầu](01-bat-dau.md#1-máy-cần-có)), **mở terminal mới**, chạy lại lệnh |
+| `⚠ Python này cài từ Microsoft Store` | Bản Store thỉnh thoảng thoát lỗi mà không chạy | Vẫn dùng được. Nên cài bản python.org: `winget install Python.Python.3.12` |
+| `⚠ … file bạn đã sửa bị ghi đè, bản cũ ở .fw/backup/…` | Bạn từng sửa file của framework | Mở bản sao để lấy lại phần đã sửa nếu cần. Xem [fw](lenh/fw.md#muốn-giữ-thay-đổi-riêng-của-dự-án) |
+| `Đây là bản fw đã cài trong dự án …` | Bạn chạy `install` từ `.fw/core/bin/fw.js` | Dùng `npx @educa-corp/fw upgrade` |
+
+## Khi chạy lệnh trong Claude Code
+
+| Bạn thấy | Nghĩa là | Làm gì |
+|---|---|---|
+| Dòng bắt đầu bằng `spec_edit: …` | Công cụ sửa spec vừa **chặn** một chỗ sửa sai (không tìm thấy đoạn cần sửa, giá trị không hợp lệ…). **Không có gì bị ghi** | Không cần làm gì. AI đọc lại file rồi sửa đúng |
+| AI chạy lại cùng một lệnh `spec_edit` | Lần trước Python thoát mà không chạy (thường gặp với bản Store) | Bình thường, AI được dặn chạy lại một lần |
+| `không đặt được status=approved: còn 3 dòng 🤖` | Còn mục chưa được bạn xác nhận | Xác nhận các mục AI liệt kê |
+| `… chưa có approved_by` | Chưa ghi người duyệt | Trả lời câu *"Ai duyệt?"* |
+| `chưa được PRD dùng tới: BR7, AC12` | Có BR hoặc AC của epic chưa được đưa vào PRD | AI sẽ bổ sung. Nếu bạn muốn bỏ thì nói rõ |
+| `(nguồn: …) chỉ được ghi mã …` | PRD đang ghi nguồn bằng lời (thường là PRD tạo bằng bản trước 0.6.1) | AI sẽ đổi thành mã, thường là `PRD` |
+| `💡 Phiên này đã dài. Nên /clear …` | Phiên đang mang theo hội thoại cũ | Gõ `/clear` rồi gọi lại lệnh |
+| `EP-xx chưa làm rõ xong. Chạy /product EP-xx trước` | Epic chưa `ready` | Chạy tiếp `/product EP-xx`. Thật sự cần PRD sớm thì thêm `--force`, PRD sẽ được ghi chú là tạo khi epic chưa xong |
+| `PRD đã có …` | Gọi `/prd EP-xx` khi PRD đã tồn tại | Dùng `/prd EP-xx change <mô tả>` |
+
+## Vẫn chưa được?
+
+Ghi lại **lệnh đã gõ** và **dòng lỗi**, rồi gửi cho người phụ trách framework.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/fw",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Framework làm việc với Claude Code cho phòng PTPM",
   "bin": {
     "fw": "bin/fw.js"
@@ -18,6 +18,7 @@
     "ref/",
     "templates/",
     "tools/",
+    "docs/guide/",
     "CHANGELOG.md"
   ],
   "engines": {

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 = {}