@educa-corp/fw 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 > `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.11.2 — 2026-10-02
+
+- **Bản sửa PRD phải tự soát đồng bộ** trước khi tăng version, cho cả `/prd change` lẫn bước áp bản sửa của refine. Với từng BR / AC vừa viết: AC có kiểm được không, Luồng chính và Kết quả sau đã khớp chưa, User flow đã khớp chưa, UC khác trỏ tới có cần sửa theo không. Lý do: cả 3 lỗi lọt qua refine của LMS đều sinh ra từ chính bản sửa, và đều thuộc kiểu "thêm một dòng mà quên những chỗ liên quan".
+- **`/bdd` đưa ra các vấn đề refine đã ghi "Có từ trước, để sau"** của UC đang viết, ngay ở lượt 1. Viết được theo BR đang có thì viết, kèm 🤖. Muốn viết đúng phải thêm nghĩa mới vào PRD thì dừng, và gom vào một lần `/prd change`.
+- Cảnh báo kích thước PRD ghi đúng hơn: người đọc cả PRD là các agent refine / review (`/bdd` chỉ đọc một UC).
+
+## 0.11.1 — 2026-10-02
+
+Sửa vòng lặp *review → change → refine → finding mới*. Lần chạy đầu trên LMS: review gợi ý đổi tên một trạng thái, dẫn tới `change` rồi refine ra 8 finding, tốn khoảng 4,4M token mà không có thay đổi nghiệp vụ nào.
+
+- **`/prd review` không đưa ý kiến về nội dung**: không đề xuất đổi tên một khái niệm đang được gọi nhất quán, không gợi ý `/prd change`. Thuật ngữ chỉ đề xuất sửa khi cùng một khái niệm mà gọi bằng hai tên.
+- **`--form` chặn một chỗ sửa thì AI hỏi bạn có đổi nghĩa không.** Không đổi nghĩa thì áp ngay, vẫn giữ version. Sửa chỗ trỏ "xem mục 5" → "mục 6" không còn bị chặn.
+- **Refine sau `/prd change` chỉ báo lỗi do chính thay đổi gây ra**, cộng với critical. Vấn đề đã có ở bản đã duyệt được gom vào *"Có từ trước, để sau"*, không phải quyết, không chặn duyệt.
+- **`spec_edit diff <prd>`**: in phần đã đổi so với bản `approved` gần nhất trong git, kèm số UC bị chạm. Refine và review sau change dùng lệnh này để lấy đúng phạm vi.
+
 ## 0.11.0 — 2026-10-02
 
 - **Chế độ mới `/prd <EPIC-ID> review`**: rà **hình thức** PRD (chính tả, câu chữ, thuật ngữ, đúng khuôn), chạy sau refine. **Bắt buộc**: PRD không duyệt được nếu chưa review đúng version (`reviewed` = `version`), và `/bdd` dừng nếu PRD chưa review. Review sửa **trong cùng version**, không tăng version, PRD đã `approved` vẫn giữ `approved`. Lỗi chính tả và định dạng thì AI sửa luôn. Câu chữ, thuật ngữ, dòng sai khuôn thì bạn quyết, được quyết theo nhóm. Chỗ muốn sửa mà làm đổi nghĩa thì AI chỉ ghi chú.

package/commands/bdd.md

@@ -18,7 +18,7 @@ Tham số: `$ARGUMENTS`
 
 1. Chạy **một** lệnh Bash: `cat .fw/core/ref/common.md .fw/config.yaml; python .fw/core/tools/spec_edit.py --check`. Làm đúng theo `common.md` (luật chung: xưng hô, Python, config, cách hỏi, cách sửa file bằng `SE`). Không có `common.md` thì báo *"Chưa cài framework vào dự án này. Chạy `npx @educa-corp/fw install` ở thư mục gốc dự án."*
 2. Tìm PRD: `SE where {specs} <UC-ID>`. Kết quả là `D`. File BDD: `F = {thư mục của D}/bdd/<UC-ID>.feature`.
-3. Đọc đầu vào **duy nhất** từ PRD: `SE context D <UC-ID>`. Lệnh này in Tổng quan, các hành trình có UC này, các dòng Màn hình, khối UC, và đúng các mục của UC khác mà UC này trỏ tới. **Không đọc cả PRD.** Cần thêm một UC khác thì chỉ đọc `SE uc D UC-xxx`.
+3. Đọc đầu vào **duy nhất** từ PRD: `SE context D <UC-ID>`. Lệnh này in Tổng quan, các hành trình có UC này, các dòng Màn hình, khối UC, đúng các mục của UC khác mà UC này trỏ tới, và các vấn đề refine đã ghi *"Có từ trước, để sau"* cho UC này. **Không đọc cả PRD.** Cần thêm một UC khác thì chỉ đọc `SE uc D UC-xxx`.
 4. Đọc `{specs}/product/glossary.md` nếu có. Viết đúng thuật ngữ.
 
 ## Bước 2 — Chọn chế độ

package/docs/guide/README.md

@@ -1,7 +1,7 @@
 # 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.11.0**. Chỉ mô tả những lệnh **đã có**. Lệnh mới có thì hướng dẫn mới được bổ sung.
+> Hướng dẫn này viết cho **bản 0.11.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"*.
 
 ---

package/docs/guide/lenh/bdd.md

@@ -29,6 +29,8 @@ AI chỉ đọc **đúng phần PRD cần cho UC này**: Tổng quan, các hành
 - **Bảng nhánh**: các BR có nhiều nhánh, mỗi nhánh ứng với kịch bản nào. Bạn soát xem có nhánh nào bị sót không.
 - **Điểm giao nhận** với UC khác, lấy từ User flow. Ví dụ *"→ UC-003: người dùng nhận email có link đặt mật khẩu"*. Lỗi ở chỗ nối giữa các UC hay bị phát hiện muộn nhất, nên phải viết rõ.
 
+- **Vấn đề PRD còn để sau**: những lỗi mà refine đã thấy trong UC này nhưng chưa sửa. Viết được theo BR đang có thì AI viết, kèm 🤖. Không viết được thì AI dừng UC đó và đề nghị gom vào một lần `/prd change`.
+
 Bạn đồng ý, hoặc sửa: *"tách SC02 làm hai"*, *"thiếu nhánh email trống"*.
 
 **Lượt 2: ghi và duyệt.**

package/docs/guide/lenh/prd-refine.md

@@ -71,7 +71,7 @@ Sau mỗi lượt có sửa, lệnh sẽ nhắc *"`/clear` rồi `/prd EP-01 ref
 
 ## Sau khi đổi PRD
 
-`/prd EP-01 change …` tăng version, nên bạn phải refine lại trước khi duyệt. Lần đó **chỉ soi các mục vừa đổi** (theo dòng Lịch sử thay đổi), nhưng agent vẫn đọc cả PRD. Vì thế PRD càng lớn thì mỗi lần đổi càng đắt: với PRD 91 KB của LMS, thêm một dòng tốn khoảng 6M token trước bản 0.11.0, và ước tính khoảng 3M từ bản 0.11.0. Lượt nào không có finding nào thì không cần agent kiểm chứng. Cách giảm chi phí hiệu quả nhất vẫn là **tách epic** để PRD nhỏ lại.
+`/prd EP-01 change …` tăng version, nên bạn phải refine lại trước khi duyệt. Lần đó **chỉ soi đúng phần vừa đổi** so với bản đã duyệt gần nhất, và **chỉ báo lỗi do chính thay đổi gây ra** (cộng với critical). Lỗi đã có từ trước trong mục bị chạm chỉ được ghi vào *"Có từ trước, để sau"*, không cần bạn quyết. Agent vẫn đọc cả PRD để thấy ảnh hưởng lan sang chỗ khác. Vì thế PRD càng lớn thì mỗi lần đổi càng đắt: với PRD 91 KB của LMS, thêm một dòng tốn khoảng 6M token trước bản 0.11.0, và ước tính khoảng 3M từ bản 0.11.0. Lượt nào không có finding nào thì không cần agent kiểm chứng. Cách giảm chi phí hiệu quả nhất vẫn là **tách epic** để PRD nhỏ lại.
 
 ## Duyệt PRD
 

package/docs/guide/lenh/prd-review.md

@@ -22,7 +22,7 @@
 |---|---|---|
 | **A. Tự sửa** | Chính tả, dấu tiếng Việt, dấu câu, bảng vỡ cột, danh sách lệch | AI sửa luôn, báo lại cho bạn số chỗ đã sửa |
 | **B. Đề xuất** | Câu khó hiểu (quá dài, đại từ không rõ chỉ ai, phủ định kép) · một khái niệm gọi hai tên, hoặc sai glossary · dòng sai khuôn, ví dụ dòng Nền tảng ghi bằng lời | **Bạn quyết** |
-| **C. Ghi chú** | Muốn sửa thì phải **đổi nghĩa**: đổi số, điều kiện, phạm vi | Không sửa. Muốn đổi thì dùng `/prd EP-01 change` |
+| **C. Ghi chú** | Lỗi hình thức mà sửa thì chắc chắn đổi nghĩa | Không sửa, không chặn duyệt. Chỉ để bạn biết |
 
 Bạn quyết loại B theo mã, hoặc theo nhóm:
 
@@ -36,7 +36,9 @@ bác R05
 ## Review không bao giờ làm đổi nghĩa
 
 - **Không tăng version.** PRD đang `approved` thì vẫn giữ `approved`.
-- Công cụ **tự chặn** mọi chỗ sửa làm thay đổi **số, mã** (UC, BR, AC…), **dấu 🤖 / ✅, gạch ngang hoặc nguồn**. Ví dụ AI định sửa *"tối đa 1.000 dòng"* thành *"tối đa 2.000 dòng"* thì công cụ chặn. Chỗ đó được chuyển thành ghi chú C.
+- Công cụ **tự chặn** mọi chỗ sửa làm thay đổi **số, mã** (UC, BR, AC…), **dấu 🤖 / ✅, gạch ngang hoặc nguồn**. Ví dụ AI định sửa *"tối đa 1.000 dòng"* thành *"tối đa 2.000 dòng"* thì công cụ chặn.
+- Bị chặn mà thật ra không đổi nghĩa, ví dụ thêm mã `EP-03` vào tiêu đề cho khớp với bảng, thì **AI hỏi bạn**. Bạn trả lời *"không đổi nghĩa"* thì AI áp luôn, vẫn trong cùng version.
+- **Review không đề xuất đổi tên khái niệm** đang được gọi nhất quán, và không gợi ý `/prd change`. Đặt tên là việc của nghiệp vụ. Lần đầu chạy ở LMS, review gợi ý đổi tên một trạng thái; lần đổi đó kéo theo refine 8 finding, tốn khoảng 4M token, và tên mới bị refine chỉ ra là sai nghĩa.
 - Nhờ vậy, review không cần refine lại sau đó.
 
 ## Phạm vi
@@ -44,7 +46,7 @@ bác R05
 | Khi nào | Rà gì |
 |---|---|
 | PRD chưa từng review | Toàn bộ PRD |
-| Sau `/prd EP-01 change` → refine | Chỉ các mục vừa đổi, theo Lịch sử thay đổi |
+| Sau `/prd EP-01 change` → refine | Chỉ phần vừa đổi so với bản đã duyệt gần nhất |
 
 Thứ tự sau mỗi lần đổi PRD: `change` → `refine` → `review` → duyệt.
 

package/package.json

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

package/ref/bdd/new.md

@@ -24,6 +24,10 @@ Chỉ **2 lượt** hỏi-đáp. PRD đã được duyệt và refine, nên khô
 
    **c. Điểm giao nhận** với UC khác, lấy từ User flow. Mỗi điểm một dòng, ví dụ *"→ UC-003: người dùng nhận email có link đặt mật khẩu (Then của SC06)"*.
 
+   **d. Vấn đề PRD còn để sau.** `SE context` có mục *"Vấn đề PRD còn để sau"* thì đây là lỗi refine đã thấy nhưng chưa sửa. Viết kịch bản là lúc chúng lộ ra, ví dụ AC không kiểm được hoặc một nhánh bị bỏ qua. Với mỗi vấn đề, chọn một trong hai:
+   - Viết được kịch bản **chỉ theo các BR đang có**, không phải thêm nghĩa mới: viết theo BR, rồi gắn `🤖` kèm câu *"theo BR…, chờ sửa PRD"*.
+   - Muốn viết đúng thì phải thêm nghĩa mới vào PRD: **dừng** UC này, và báo *"Cần `/prd EP-xx change …` trước, cho các vấn đề: …"*. Gom mọi vấn đề như vậy của cả epic vào **một** lần change.
+
    Kèm tối đa 4 câu hỏi, chỉ khi cần. Ví dụ: BR không tìm được kịch bản nào, điều phải giả định vì PRD chưa ghi, chỗ PRD mơ hồ. Không có gì cần hỏi thì chỉ hỏi *"Dàn ý này được chưa?"*.
 
 ## Lượt 2 — Ghi file

package/ref/prd/change.md

@@ -30,5 +30,12 @@ Khi PO đồng ý kế hoạch:
    - Thay đổi làm đổi luồng (thêm UC, đổi thứ tự, thêm nhánh lỗi) thì sửa luôn mục **User flow**. Yêu cầu là *"thêm User flow"* (PRD tạo bằng bản cũ) thì vẽ mục này từ checkpoint 2 của epic, theo luật trong `new.md`.
    - Thêm dòng vào mục **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ỏ)"*.
    - Dòng **Nền tảng** (ở Tổng quan, hoặc trong UC chạy khác mặc định) chỉ ghi mã: `web`, `app` (nơi người dùng dùng tính năng), `system` (luồng tự động, không có màn hình). Giải thích để sau dấu ` — `. Ví dụ: `- ✅ **Nền tảng:** system — luồng tự động nhận đơn từ EP-03`.
-2. Chạy `SE flowcheck D`. Còn UC chưa có trong hành trình nào thì sửa cho đủ. Sau đó 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=—`.
-3. Báo lại cho PO. Không in lại cả PRD, chỉ tóm tắt những gì đã đổi. Còn `🤖` thì xác nhận trước. Bản mới chưa duyệt được ngay, vì phải refine rồi review lại phần vừa đổi. Báo: *"Bước tiếp: `/clear` rồi `/prd {id} refine`, sau đó `/prd {id} review`, rồi duyệt."* Bản mới cần người duyệt mới, nên khi duyệt phải đặt lại `approved_by` và `approved_at`.
+2. **Soát đồng bộ trước khi tăng version.** Lỗi hay gặp nhất của bản sửa là thêm hoặc sửa một dòng mà quên những chỗ liên quan. Lần đo trên LMS: khoảng 20–25% bản sửa sinh ra lỗi mới, và cả 3 lỗi lọt qua refine đều thuộc kiểu này. Với **từng** dòng BR / AC vừa thêm hoặc sửa, đọc lại bằng `SE uc D <UC>` rồi trả lời:
+   - **AC kiểm được không?** Kết quả có nhìn thấy được, đánh đạt hay không đạt được không? Có khớp với các BR khác đang áp lên cùng tình huống không? Ví dụ một AC ghi *"vẫn đăng nhập được"* trong khi một BR khác bắt người đó đặt mật khẩu mới trước, thì AC đó không kiểm được.
+   - **Phần còn lại của UC đã khớp chưa?** Luồng chính, Điều kiện trước và Kết quả sau. Ví dụ thêm một nhánh BR mới thì Kết quả sau phải nói tới kết quả của nhánh đó.
+   - **User flow đã khớp chưa?** Hành trình đi qua UC này có nhánh nào bỏ qua luật mới không?
+   - **UC khác có trỏ tới mục này không?** Có thì xem các mục đó có cần sửa theo không.
+
+   Thiếu chỗ nào thì sửa luôn trong lần này, rồi ghi chỗ đã sửa thêm vào dòng Lịch sử thay đổi.
+3. Chạy `SE flowcheck D`. Còn UC chưa có trong hành trình nào thì sửa cho đủ. Sau đó 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=—`.
+4. Báo lại cho PO. Không in lại cả PRD, chỉ tóm tắt những gì đã đổi. Còn `🤖` thì xác nhận trước. Bản mới chưa duyệt được ngay, vì phải refine rồi review lại phần vừa đổi. Báo: *"Bước tiếp: `/clear` rồi `/prd {id} refine`, sau đó `/prd {id} review`, rồi duyệt."* Bản mới cần người duyệt mới, nên khi duyệt phải đặt lại `approved_by` và `approved_at`.

package/ref/prd/lenses.md

@@ -2,6 +2,8 @@
 
 Bạn là **một** lăng kính. Chỉ soi đúng phần của lăng kính mình, trong đúng **phạm vi** và **ngưỡng báo** được giao. Tìm ít nhưng đúng còn hơn tìm nhiều mà sai.
 
+**Lượt sau `/prd change`** (phạm vi là kết quả `SE diff`): **chỉ báo lỗi do chính thay đổi gây ra**. Ví dụ: mâu thuẫn mới giữa phần vừa đổi và phần khác, chỗ phải đổi theo mà chưa đổi, nghĩa mới làm hỏng một BR hay AC khác. Ngoài ra chỉ báo thêm critical. **Không báo** vấn đề đã có y nguyên ở bản đã duyệt, kể cả khi nó nằm trong mục vừa bị chạm, vì bản đó đã qua refine. Vẫn đọc toàn bộ PRD để thấy ảnh hưởng lan sang chỗ khác.
+
 ## Luật chung
 
 1. **Viết bằng ngôn ngữ nghiệp vụ.** Mắt nhìn có thể là kỹ thuật, nhưng finding và đề xuất phải nói *nghiệp vụ còn thiếu hay chưa rõ điều gì*. Không đề xuất API, bảng dữ liệu, retry, timeout hay thư viện.
@@ -78,12 +80,14 @@ Bạn nhận: PRD `D`, file refine `R` (có thể chưa có), thư mục `W` ch
 - Finding có nêu lại một điểm **đã có quyết định** trong `R` không?
 - Mức độ có đúng định nghĩa không?
 
-Kết luận cho mỗi finding: `ĐÚNG` · `SAI` (bỏ) · `HẠ MỨC` (giữ, đổi mức).
+- **Lượt sau `/prd change`:** vấn đề này **đã có ở bản đã duyệt** chưa? Xem phần `-` trong `SE diff D`, và phần PRD không nằm trong diff. Đã có từ trước thì đây **không phải** lỗi do thay đổi.
+
+Kết luận cho mỗi finding: `ĐÚNG` · `SAI` (bỏ) · `HẠ MỨC` (giữ, đổi mức) · `CÓ TỪ TRƯỚC` (không thành finding; ghi một dòng vào mục *Có từ trước, để sau* ở cuối lượt, không cần PO quyết, không chặn duyệt).
 
 **2. Gộp** các finding ĐÚNG trùng nhau (cùng mục, cùng vấn đề), giữ bản rõ nhất. Hai đề xuất trái ngược nhau thì giữ cả hai trong **một** finding, và ghi rõ là cần PO chọn.
 
 **3. Sắp xếp** theo mức độ (critical → major → minor), sau đó theo lăng kính (QA → DEV → SA → Phạm vi). **Đánh mã F theo đúng thứ tự đó**, bắt đầu từ mã F kế tiếp.
 
-**4. Ghi vào `R`.** Chưa có `R` thì `SE create R` theo khuôn `.fw/core/templates/prd-refine.md`. Đã có thì `SE edit` thêm mục `## Lượt {n} — v{version} <!-- sec:round-{n} -->` ở **cuối**. **Không sửa các lượt cũ.** Thêm một dòng vào bảng Tóm tắt, rồi `SE set R prd_version={version} round={n} status=pending`. Mỗi finding theo đúng mẫu trong khuôn, `Quyết định: chờ`.
+**4. Ghi vào `R`.** Chưa có `R` thì `SE create R` theo khuôn `.fw/core/templates/prd-refine.md`. Đã có thì `SE edit` thêm mục `## Lượt {n} — v{version} <!-- sec:round-{n} -->` ở **cuối**. **Không sửa các lượt cũ.** Thêm một dòng vào bảng Tóm tắt, rồi `SE set R prd_version={version} round={n} status=pending`. Mỗi finding theo đúng mẫu trong khuôn, `Quyết định: chờ`. Có finding `CÓ TỪ TRƯỚC` thì thêm `### Có từ trước, để sau` ở cuối lượt, mỗi vấn đề một dòng: *"- {mã mục}: {vấn đề}"*.
 
-**5. Trả về một dòng:** *"thô {a} · bỏ {b} · hạ mức {c} · còn {d} (critical {x} · major {y} · minor {z}) → {R}"*.
+**5. Trả về một dòng:** *"thô {a} · bỏ {b} · hạ mức {c} · có từ trước {e} · còn {d} (critical {x} · major {y} · minor {z}) → {R}"*.

package/ref/prd/refine.md

@@ -19,7 +19,7 @@ Xét **từ trên xuống**, gặp dòng nào khớp trước thì theo dòng đ
 | `refined` = `version` | **Dừng.** Báo *"Bản v{version} đã refine xong."* Có `--full` thì chạy lượt 1 trên toàn PRD | — |
 | Chưa có `R`, hoặc chưa từng refine | **1** | Toàn bộ PRD |
 | `R` có `round: 1` **đã áp** bản sửa, `prd_version` < `version` | **2** | Chỉ các mục mà lượt 1 đã sửa hoặc thêm (đọc từ quyết định `nhận` / `sửa` trong `R`), cộng các mục tham chiếu tới chúng |
-| `refined` có giá trị nhưng < `version` (PRD đã qua `/prd change`) | **1** | Chỉ các mục trong các dòng Lịch sử thay đổi (`SE section D history`) có version lớn hơn `refined` |
+| `refined` có giá trị nhưng < `version` (PRD đã qua `/prd change`) | **1** | **Đúng phần đã đổi**: `SE diff D` (so với bản `approved` gần nhất trong git, có sẵn số UC bị chạm). Không có bản đã duyệt trong git thì dùng các dòng Lịch sử thay đổi có version lớn hơn `refined`. Ngưỡng: **chỉ lỗi do chính thay đổi gây ra, hoặc critical** (xem đầu `lenses.md`) |
 
 **Không có lượt 3.** Sau lượt 2 thì luôn đặt `refined` (Bước D).
 
@@ -27,7 +27,7 @@ Xét **từ trên xuống**, gặp dòng nào khớp trước thì theo dòng đ
 
 Phiên chính **không đọc** kết quả chi tiết của các agent. Agent ghi ra file, phiên chính chỉ đọc bảng tóm tắt cuối cùng.
 
-1. **Chọn số agent rà** theo lượt và phạm vi ở Bước A. Đếm UC bằng các mã `UC-…` nêu trong phạm vi. Thay đổi chỉ ở Tổng quan, User flow hoặc Màn hình tính là 0 UC.
+1. **Chọn số agent rà** theo lượt và phạm vi ở Bước A. Số UC bị chạm lấy ở dòng đầu của `SE diff D`. Thay đổi chỉ ở Tổng quan, User flow hoặc Màn hình tính là 0 UC.
 
 | Lượt và phạm vi | Agent rà |
 |---|---|
@@ -49,7 +49,7 @@ Phiên chính **không đọc** kết quả chi tiết của các agent. Agent g
 ## Bước C — Trình
 
 1. Đọc `SE section R summary` và danh sách tiêu đề finding của lượt này. Danh sách đã được agent kiểm chứng **sắp xếp sẵn** theo mức độ, rồi theo lăng kính (QA → DEV → SA → Phạm vi).
-2. Trình **một bảng tóm tắt** gồm mã · mức · lăng kính · mục · một dòng vấn đề, đúng theo thứ tự đó. Kèm số finding thô, số bị bỏ ở bước kiểm chứng, và số bị hạ mức.
+2. Trình **một bảng tóm tắt** gồm mã · mức · lăng kính · mục · một dòng vấn đề, đúng theo thứ tự đó. Kèm số finding thô, số bị bỏ ở bước kiểm chứng, số bị hạ mức, và số vấn đề *có từ trước* (chỉ báo số, không cần PO quyết).
 3. Nhắc PO cách quyết:
    - *"Chi tiết xem {R}. Quyết theo mã: 'nhận F01, F03 · bác F02 vì … · F04 sửa thành … · hoãn F05'."*
    - *"Quyết theo nhóm được, áp cho major và minor: 'nhận tất cả minor' · 'nhận hết UC-003 trừ F12' · 'bác F20–F24 vì …'. Critical phải quyết từng mã."*
@@ -68,7 +68,8 @@ Phiên chính **không đọc** kết quả chi tiết của các agent. Agent g
    - đọc từng finding bằng `SE finding`, đọc UC liên quan bằng `SE uc`;
    - sửa hoặc thêm BR / AC **theo mã** bằng `SE item` (chỉ viết dòng mới); phần không phải dòng BR / AC (luồng, User flow, Tổng quan) thì dùng `SE edit`;
    - thêm dòng Lịch sử thay đổi nêu mã finding, ví dụ *"v1.3 — refine lượt 1: F01, F03, F04"*;
+   - **soát đồng bộ** từng dòng vừa viết theo bước 2 của `change.md` (AC kiểm được không · Luồng và Kết quả sau · User flow · UC khác trỏ tới). Thiếu thì sửa luôn;
    - chạy `SE flowcheck D`, rồi `SE set D version=… status=draft approved_by=— approved_at=—` và `SE set R status=applied`;
-   - **chỉ trả về một dòng**: *"áp {k} finding → v{version}; {số BR/AC sửa · thêm · bỏ}"*.
+   - **chỉ trả về một dòng**: *"áp {k} finding → v{version}; {số BR/AC sửa · thêm · bỏ}; đồng bộ thêm {m} chỗ"*.
 7. Lượt 1 có áp bản sửa: báo *"`/clear` rồi `/prd {id} refine` để chạy lượt 2, chỉ soi phần vừa sửa."*
 8. Không áp gì (mọi finding đều bác / hoãn), **hoặc** vừa xong **lượt 2**: `SE set D refined={version hiện tại}` và `SE set R status=done`. Finding `hoãn` thì ghi thêm vào mục **Câu hỏi còn mở** của `D`, kèm chú thích *"(để bước QC)"*. Rồi báo: *"Refine xong v{version}. Bước tiếp: `/clear` rồi `/prd {id} review` để rà hình thức, bắt buộc trước khi duyệt."*

package/ref/prd/review.md

@@ -18,7 +18,7 @@ Xét **từ trên xuống**, gặp dòng nào khớp trước thì theo dòng đ
 | `reviewed` = `version`, không có `--full` | **Dừng.** Báo *"Bản v{version} đã rà hình thức xong."* |
 | Đã có `W/review-{version}.md` (rà xong, đang chờ PO quyết) | **Không rà lại.** Sang thẳng Bước C |
 | `reviewed` là `—` (chưa từng review), hoặc có `--full` | Phạm vi: **toàn bộ PRD** |
-| `reviewed` < `version` | Phạm vi: chỉ các mục nêu trong các dòng Lịch sử thay đổi (`SE section D history`) có version **lớn hơn** `reviewed` |
+| `reviewed` < `version` | Phạm vi: **đúng phần đã đổi**, lấy bằng `SE diff D` (so với bản `approved` gần nhất trong git). Không có bản đã duyệt trong git thì dùng các dòng Lịch sử thay đổi có version lớn hơn `reviewed` |
 
 ## Bước B — Rà (1 sub-agent)
 
@@ -30,12 +30,15 @@ Dùng công cụ **Agent**, `model: "sonnet"`, gọi **1** agent. Giao cho agent
 2. Trình theo thứ tự:
    - **Đã tự sửa (A):** chỉ báo số chỗ, kèm 2–3 ví dụ. Danh sách đầy đủ nằm trong file.
    - **Bảng đề xuất (B):** mã · loại · mục · *trước → sau*, rút gọn mỗi bên khoảng 60 ký tự.
-   - **Ghi chú (C):** những chỗ muốn sửa thì phải đổi nghĩa. Mỗi chỗ một dòng, kèm gợi ý `/prd {id} change …`.
+   - **Ghi chú (C):** mỗi chỗ một dòng, để PO biết. **Không gợi ý `/prd … change`**, và nói rõ ghi chú không chặn duyệt. Đổi PRD là quyết định nghiệp vụ của PO, review không tự đề xuất.
 3. Nhắc PO cách quyết: *"Quyết theo mã: 'nhận hết' · 'nhận hết trừ R03' · 'R04 sửa thành …' · 'bác R05'."* Không có đề xuất nào thì sang thẳng Bước D.
 
 ## Bước D — Áp
 
-1. Áp các đề xuất được nhận bằng **một** lần `SE edit --form D`, với `old` là "Trước" và `new` là "Sau" (hoặc bản PO sửa). `SE` chặn chỗ nào thì chỗ đó làm đổi nghĩa: bỏ chỗ đó ra khỏi lần sửa, báo PO, và chuyển nó thành ghi chú C.
+1. Áp các đề xuất được nhận bằng **một** lần `SE edit --form D`, với `old` là "Trước" và `new` là "Sau" (hoặc bản PO sửa).
+   - `SE` chặn chỗ nào (vì chỗ đó đổi số, mã, dấu hoặc nguồn) thì **hỏi PO ngay**, kèm đúng thứ bị đổi. Ví dụ: *"R07 thêm mã EP-03 vào tiêu đề J7, cho khớp với tên trong bảng. Chỗ này có đổi nghĩa không?"*
+   - PO nói **không đổi nghĩa**: áp chỗ đó bằng `SE edit D` (không `--form`), vẫn trong cùng version.
+   - PO nói **có**: không sửa, chuyển thành ghi chú C.
 2. Có chỗ nào được sửa (A hoặc B) thì thêm **một** dòng vào cuối bảng Lịch sử thay đổi bằng `SE edit D`, **giữ nguyên version**: `| {version} | {ngày} | Rà hình thức: sửa {k} chỗ (chính tả, câu chữ, thuật ngữ, khuôn). Không đổi nội dung |`.
 3. `SE set D reviewed={version} updated={ngày}`.
    - PRD đang `approved` thì `SE` kiểm lại mọi điều kiện duyệt. Báo lỗi thì sửa theo lỗi, thường là một dòng sai khuôn còn sót, rồi chạy lại.
@@ -53,10 +56,15 @@ Bạn rà **hình thức** của PRD trong đúng phạm vi được giao. Phạ
 | Loại | Gồm | Làm gì |
 |---|---|---|
 | **A. Tự sửa** | Chính tả, dấu tiếng Việt, dấu câu, khoảng trắng thừa, bảng vỡ cột, danh sách lệch | Sửa luôn bằng **một** lần `SE edit --form D`. `SE` chặn chỗ nào thì chuyển chỗ đó sang B hoặc C |
-| **B. Đề xuất** | Câu khó hiểu (quá dài, nhiều mệnh đề lồng nhau, đại từ không rõ chỉ ai, phủ định kép) · một khái niệm gọi hai tên, hoặc sai so với glossary và phần Khái niệm · dòng sai khuôn, ví dụ dòng Nền tảng ghi bằng lời thay vì mã `web` · `app` · `system` | **Không sửa.** Ghi vào file để PO quyết |
-| **C. Ghi chú** | Chỗ chỉ sửa được nếu đổi nghĩa: số, điều kiện, phạm vi, thêm hoặc bớt ý | **Không sửa.** Ghi một dòng |
+| **B. Đề xuất** | Câu khó hiểu (quá dài, nhiều mệnh đề lồng nhau, đại từ không rõ chỉ ai, phủ định kép) · **cùng một khái niệm mà gọi bằng hai tên** ở hai chỗ, hoặc sai so với glossary và phần Khái niệm (đề xuất dùng tên **đang dùng nhiều hơn**) · tham chiếu trỏ sai ("xem mục 5" trong khi đúng là mục 6) · dòng sai khuôn, ví dụ dòng Nền tảng ghi bằng lời thay vì mã `web` · `app` · `system`. A bị `SE` chặn thì cũng đưa vào đây | **Không sửa.** Ghi vào file để PO quyết |
+| **C. Ghi chú** | Lỗi hình thức mà sửa thì chắc chắn đổi nghĩa: số, điều kiện, phạm vi | **Không sửa.** Ghi một dòng |
 
-**Không làm:** rà nội dung nghiệp vụ (đó là việc của refine), đổi mã, đổi số, đổi dấu `🤖`/`✅`, đổi `(nguồn: …)`, sửa phần ngoài phạm vi. Viết lại câu thì giữ đúng mọi ý và mọi giá trị của câu cũ.
+**Không làm:**
+- Rà nội dung nghiệp vụ (việc của refine). Đổi mã, đổi số, đổi dấu `🤖`/`✅`, đổi `(nguồn: …)`. Sửa phần ngoài phạm vi.
+- **Đề xuất đổi tên một khái niệm đang được gọi nhất quán**, dù bạn thấy tên chưa hay hoặc đã cũ. Ví dụ: "đang dùng mật khẩu mặc định" được gọi đúng một tên ở mọi chỗ thì để nguyên, không đề xuất. Đặt tên khái niệm là quyết định nội dung. Lần đổi tên như vậy ở LMS v1.8 đã tốn khoảng 3M token refine, và tên mới bị refine chỉ ra là sai nghĩa.
+- Ghi ý kiến về nghiệp vụ vào C, hoặc gợi ý `/prd … change`.
+
+Viết lại câu thì giữ đúng mọi ý và mọi giá trị của câu cũ.
 
 **Ghi file** `W/review-{version}.md` bằng `SE create --replace`, đúng khuôn sau:
 
@@ -71,7 +79,7 @@ Bạn rà **hình thức** của PRD trong đúng phạm vi được giao. Phạ
 - Lý do: {…}
 
 ## Ghi chú (C)
-- {mã mục}: {vấn đề} → cần `/prd … change`
+- {mã mục}: {lỗi hình thức không sửa được mà không đổi nghĩa}
 ```
 
 Mục nào không có gì thì ghi `Không có`. Sau đó **chỉ trả về một dòng**: *"sửa {a} · đề xuất {b} · ghi chú {c} → {file}"*.

package/tools/spec_edit.py

@@ -31,6 +31,7 @@ Cách dùng (nội dung truyền qua stdin):
   spec_edit.py scenario <feature> <SC…>…  in đúng các kịch bản đó
   spec_edit.py sc <feature>               stdin = JSON [{"id": mã, "new": khối} | {"after": mã | "end", "new": khối} | {"remove": mã, "version": "1.1"}]
   spec_edit.py bddcheck <feature> [prd]   kiểm khuôn, tag, độ phủ AC / BR của file BDD
+  spec_edit.py diff <prd>                 phần đã đổi so với bản `approved` gần nhất trong git, kèm UC bị chạm
 
 Mã thoát: 0 = thành công · 1 = lỗi dữ liệu (không ghi gì) · 2 = sai cách dùng.
 """
@@ -118,7 +119,9 @@ FORM_KEEP = re.compile("UC-\\d{3}(?:-(?:BR|AC|SC)\\d+)?|(?:CON|ACT)-\\d+|\\b(?:B
 
 def form_changes(old, new):
     """Những thứ mang nghĩa bị thêm / mất khi đổi old → new. Rỗng = chỉ đổi hình thức."""
-    a, b = sorted(FORM_KEEP.findall(old)), sorted(FORM_KEEP.findall(new))
+    # "xem mục 5" → "mục 6" là sửa chỗ trỏ tới tiêu đề, không phải đổi số nghiệp vụ.
+    ref = lambda s: re.sub(r"\b([Mm]ục)\s+\d+", r"\1 #", s)
+    a, b = sorted(FORM_KEEP.findall(ref(old))), sorted(FORM_KEEP.findall(ref(new)))
     lost = [x for x in a if a.count(x) > b.count(x)]
     added = [x for x in b if b.count(x) > a.count(x)]
     return sorted(set(lost)), sorted(set(added))
@@ -618,13 +621,69 @@ def cmd_decide(path):
     print("đã ghi %d quyết định vào %s" % (len(ops), path))
 
 
+def git_show(rev_path):
+    import subprocess
+    r = subprocess.run(["git", "show", rev_path], capture_output=True)
+    return r.stdout.decode("utf-8", "replace") if r.returncode == 0 else None
+
+
+def last_approved(path):
+    """(commit, nội dung) của bản gần nhất trong git mà file đang `status: approved`. None nếu không có."""
+    import subprocess
+    r = subprocess.run(["git", "log", "--format=%H", "--", path], capture_output=True)
+    if r.returncode != 0:
+        return None
+    rel = "./" + os.path.relpath(path).replace("\\", "/")
+    for h in r.stdout.decode().split():
+        text = git_show("%s:%s" % (h, rel))
+        if text and re.search(r"^status:\s*approved", text, re.M):
+            return h, text
+    return None
+
+
+def cmd_diff(path):
+    """Phần PRD đã đổi so với bản đã duyệt gần nhất trong git — phạm vi chính xác cho refine / review sau change."""
+    import difflib
+    base = last_approved(path)
+    if not base:
+        fail("không tìm thấy bản `approved` nào của %s trong git (chưa commit bản đã duyệt?). "
+             "Dùng các dòng Lịch sử thay đổi làm phạm vi." % path)
+    h, old = base
+    new = read(path)
+    old_l, new_l = old.split("\n"), new.split("\n")
+    # Mỗi UC chỉ gồm khối của nó: từ tiêu đề ### UC-… tới tiêu đề ## / ### kế tiếp.
+    spans = []
+    for i, l in enumerate(new_l):
+        m = re.match(r"^###\s+(?:~~)?(UC-\d{3})", l)
+        if m:
+            end = next((j for j in range(i + 1, len(new_l)) if re.match(r"^#{2,3}\s", new_l[j])), len(new_l))
+            spans.append((i, end, m.group(1)))
+
+    def uc_at(i):
+        return next((u for s, e, u in spans if s <= i < e), None)
+    touched, body = [], []
+    sm = difflib.SequenceMatcher(None, old_l, new_l, autojunk=False)
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag == "equal":
+            continue
+        for j in range(j1, max(j2, j1 + 1)):
+            u = uc_at(min(j, len(new_l) - 1))
+            if u and u not in touched:
+                touched.append(u)
+        body += ["@@ dòng %d" % (j1 + 1)] + ["- " + l for l in old_l[i1:i2]] + ["+ " + l for l in new_l[j1:j2]]
+    print("# So với bản đã duyệt v%s (commit %s) · UC bị chạm: %s (%d UC)"
+          % (prd_version(old), h[:7], ", ".join(touched) or "không có (chỉ Tổng quan / User flow / Màn hình / Lịch sử)", len(touched)))
+    print("\n".join(body) if body else "(không có gì đổi)")
+
+
 PRD_SIZE_WARN = 60 * 1024
 
 
 def size_warning(path):
     size = os.path.getsize(path)
     if size > PRD_SIZE_WARN:
-        print("⚠ PRD %d KB (ngưỡng %d KB): mọi bước sau đều nạp toàn bộ PRD. Cân nhắc tách epic thành nhiều PRD nhỏ hơn."
+        print("⚠ PRD %d KB (ngưỡng %d KB): mỗi agent refine / review đều đọc toàn bộ PRD, nên mỗi lần đổi PRD đều đắt. "
+              "Cân nhắc tách epic thành nhiều PRD nhỏ hơn."
               % (size // 1024, PRD_SIZE_WARN // 1024))
 
 
@@ -1013,9 +1072,26 @@ def cmd_context(path, ucs):
         for c in foreign:
             hits = find_item(lines, c)
             out.append(lines[hits[0]] if hits else "(không tìm thấy %s trong PRD)" % c)
+    later = deferred_items(refine_path(path), re.compile(r"%s(?!\d)" % re.escape(uc)))
+    if later:
+        out += ["", "## Vấn đề PRD còn để sau (refine ghi \"Có từ trước, để sau\") — xem ref/bdd/new.md mục d"] + later
     print("\n".join(out).rstrip())
 
 
+def deferred_items(rpath, mention):
+    """Các dòng dưới `### Có từ trước, để sau` của file refine có nhắc tới UC (mention là regex mã UC)."""
+    if not os.path.isfile(rpath):
+        return []
+    out, inside = [], False
+    for l in read(rpath).split("\n"):
+        if re.match(r"^#{2,4}\s", l):
+            inside = l.lstrip("#").strip().startswith("Có từ trước")
+            continue
+        if inside and l.startswith("- ") and mention.search(l):
+            out.append(l)
+    return out
+
+
 def used_sc(text, uc):
     return sorted({int(m.group(3)) for m in SC_ANY.finditer(text) if m.group(2) == uc[3:]})
 
@@ -1181,7 +1257,7 @@ def main(argv):
         print("ok — Python %s" % sys.version.split()[0])
         return
     if len(argv) < 2 or argv[0] not in ("create", "edit", "set", "pending", "confirm", "next-uc", "coverage", "section", "upgrade", "flowcheck", "item", "uc", "finding", "decide",
-                                            "where", "context", "next-sc", "scenario", "sc", "bddcheck"):
+                                            "where", "context", "next-sc", "scenario", "sc", "bddcheck", "diff"):
         fail(__doc__.split("Cách dùng")[1], 2)
     cmd, path, rest = argv[0], argv[1], argv[2:]
     if cmd == "create":
@@ -1222,6 +1298,8 @@ def main(argv):
         cmd_next_uc(path)
     elif cmd == "where":
         cmd_where(path, rest)
+    elif cmd == "diff":
+        cmd_diff(path)
     elif cmd == "context":
         cmd_context(path, rest)
     elif cmd == "next-sc":