@educa-corp/fw 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 > `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.7.0 — 2026-10-01
+
+- Chế độ mới **`/prd <EPIC-ID> refine`**: rà nội dung PRD qua 4 lăng kính (QA · DEV · SA · Phạm vi). Mỗi lăng kính là một sub-agent **Opus**, sau đó một agent **kiểm chứng** loại bỏ finding không đứng vững. Bạn quyết từng finding: nhận, sửa, bác hoặc hoãn.
+- Chống vòng lặp rà không dứt: **tối đa 2 lượt** cho mỗi version. Lượt 2 chỉ soi phần vừa sửa, chỉ báo critical hoặc lỗi do bản sửa. File `review/prd-refine.md` là **sổ quyết định**, điểm đã quyết không bị nêu lại.
+- **Bắt buộc refine trước khi duyệt PRD**: `status=approved` bị chặn khi `refined` khác `version`, hoặc còn critical/major chưa quyết. Sau `/prd change` thì refine lại, và chỉ rà phần vừa đổi.
+- `spec_edit upgrade` bổ sung các trường frontmatter còn thiếu so với khuôn mới (ví dụ `refined`).
+- Lệnh rà hình thức (chính tả, trình bày) sẽ là `/review <file>`, bỏ tên `/review-context`.
+
 ## 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"*.

package/commands/prd.md

@@ -1,6 +1,6 @@
 ---
-description: Viết PRD chính thức từ epic đã làm rõ (EPIC-ID), hoặc đổi PRD đã có (EPIC-ID change)
-argument-hint: "<EPIC-ID> [change <mô tả thay đổi>] [--force]"
+description: Viết PRD từ epic đã làm rõ (EPIC-ID), rà nội dung PRD (EPIC-ID refine), hoặc đổi PRD (EPIC-ID change)
+argument-hint: "<EPIC-ID> [refine | change <mô tả thay đổi>] [--force]"
 ---
 
 # /prd
@@ -29,9 +29,10 @@ Nếu **trước lệnh này** phiên đã có hội thoại khác, dòng đầu
 |---|---|
 | Không có `change`, chưa có `D`, epic `ready` | Chế độ **tạo**: đọc `.fw/core/ref/prd/new.md` |
 | Không có `change`, chưa có `D`, epic **chưa** `ready` | Dừng: *"EP-xx chưa làm rõ xong. Chạy `/product EP-xx` trước."* Có `--force` thì làm tiếp, nhưng in cảnh báo, ghi vào mục 4 của PRD dòng *"Tạo khi epic chưa ready (--force)"*, và không cho `approved` khi epic còn câu hỏi mở |
-| Không có `change`, **đã có** `D` | Dừng: *"PRD đã có. Muốn đổi thì chạy `/prd EP-xx change <mô tả>`."* Không ghi đè |
+| Không có `change` / `refine`, **đã có** `D` | Dừng: *"PRD đã có. Rà nội dung: `/prd EP-xx refine` · Đổi: `/prd EP-xx change <mô tả>`."* Không ghi đè |
+| Có `refine`, đã có `D` | Chế độ **rà nội dung**: đọc `.fw/core/ref/prd/refine.md` |
 | Có `change`, đã có `D` | Chế độ **đổi**: đọc `.fw/core/ref/prd/change.md` |
-| Có `change`, chưa có `D` | Dừng: *"Chưa có PRD. Chạy `/prd EP-xx` trước."* |
+| Có `change` hoặc `refine`, chưa có `D` | Dừng: *"Chưa có PRD. Chạy `/prd EP-xx` trước."* |
 
 ## Bước 3 — Luật chung
 
@@ -46,7 +47,7 @@ Nếu **trước lệnh này** phiên đã có hội thoại khác, dòng đầu
    - `SE pending <file>` · `SE confirm <file> UC-003-BR02 UC-003-AC01` · `SE next-uc {specs}` · `SE coverage <epic> <prd>`
    - Đọc **một mục**: `SE section <file> <mã>`. Mã mục là `<!-- sec:… -->` ở tiêu đề (vd `constraints`, `usecases`, `open`). **Luôn tìm mục theo mã**, không theo số hay tên tiêu đề, không tự cắt file bằng `sed`/`grep`. 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.
-7. **Duyệt.** `status=approved` chỉ đặt được khi không còn `🤖`, `open_questions=0`, và có người duyệt. Hỏi PO *"Ai duyệt PRD này?"* (mặc định là PO của epic), rồi đặt trong **một** lệnh: `SE set D status=approved approved_by=<tên> approved_at=YYYY-MM-DD`. `SE` tự chặn nếu chưa đủ. Không tìm cách lách.
+7. **Duyệt.** `status=approved` chỉ đặt được khi không còn `🤖`, `open_questions=0`, **đã refine đúng version này** (`refined` = `version`, không còn critical/major chưa quyết), và có người duyệt. Chưa refine thì báo *"Chạy `/prd EP-xx refine` trước khi duyệt."* Hỏi PO *"Ai duyệt PRD này?"* (mặc định là PO của epic), rồi đặt trong **một** lệnh: `SE set D status=approved approved_by=<tên> approved_at=YYYY-MM-DD`. `SE` tự chặn nếu chưa đủ. Không tìm cách lách.
 
 ## Bước 4 — Kết thúc
 
@@ -58,5 +59,5 @@ Trạng thái : {✅ Đã duyệt v{version} | 🟡 Nháp v{version} — còn {n
 Đã ghi     : {D} {· epic → handed-off · product.md nếu có}
 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}
+Bước tiếp  : {`/clear` rồi `/prd {id} refine` | /bdd UC-xxx | trả lời / xác nhận các mục trên}
 ```

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.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.
+> Hướng dẫn này viết cho **bản 0.7.0**. 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"*.
 
 ---
@@ -21,10 +21,10 @@
 ## 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)
+cài framework ──► /product ──► /product EP-xx ──► /prd EP-xx ──► /prd EP-xx refine ──► duyệt ┄┄► (/bdd — sắp có)
+                  tầng          làm rõ một         viết PRD       rà nội dung
+                  sản phẩm      tính năng              ▲                  │  (bắt buộc)
+                                                       └── /prd EP-xx change ◄──┘  đổi PRD thì refine lại
 ```
 
 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**:
@@ -48,6 +48,7 @@ Bước tiếp  : `/clear` rồi `/product EP-01`
 | `/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> refine` | PO / BA | **Rà nội dung** PRD qua 4 lăng kính. **Bắt buộc** trước khi duyệt | [/prd refine](lenh/prd-refine.md) |
 | `/prd <EPIC-ID> change <mô tả>` | PO / BA | Thêm, sửa hoặc bỏ nội dung PRD | [/prd](lenh/prd.md) |
 
 ---

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

@@ -0,0 +1,83 @@
+[← Hướng dẫn](../README.md) · [Bảng lệnh](../README.md#bảng-lệnh) · [/prd](prd.md)
+
+# `/prd EP-01 refine` — rà nội dung PRD
+
+> AI rà PRD qua **4 lăng kính** để tìm chỗ nghiệp vụ còn thiếu, mơ hồ hoặc mâu thuẫn, tức những chỗ sẽ làm dev hay QC làm sai hoặc phải đoán. **Bắt buộc**: chưa refine thì không duyệt được PRD.
+> Không rà chính tả hay cách trình bày. Việc đó là của `/review` *(sắp có)*.
+
+| | |
+|---|---|
+| **Gõ** | `/prd EP-01 refine` |
+| **Ai** | PO / BA |
+| **Cần có trước** | PRD đã có |
+| **Số lượt rà** | Tối đa **2** cho mỗi version PRD |
+| **Ghi ra** | `specs/{domain}/{slug}/review/prd-refine.md` · PRD nhận các bản sửa bạn đã chấp nhận |
+| **Bước tiếp** | Duyệt PRD |
+
+---
+
+## 4 lăng kính
+
+| Lăng kính | Soi | Ví dụ finding |
+|---|---|---|
+| **QA** | AC có kiểm được là đạt hay không? AC có lặp lại BR không? | *"UC-002-AC03 nói 'hiển thị thông báo phù hợp' — không kiểm được"* |
+| **DEV** | BR và Business Logic có đủ để làm mà không phải đoán? Nhánh thiếu, điều kiện biên, xử lý khi lỗi, BR mâu thuẫn | *"Gửi email đặt lại mật khẩu thất bại thì sao?"* |
+| **SA** | Các UC có thông suốt, nhất quán? Trạng thái, vòng đời của đối tượng; ai được làm gì | *"UC-002 cho Admin khoá tài khoản, nhưng UC-009 tự tạo tài khoản không nói trạng thái ban đầu"* |
+| **Phạm vi** | PRD có vượt ngoài phạm vi epic, đi ngược ràng buộc `CON-xx`, hay giẫm lên epic khác không? | *"UC-009 xử lý đơn hàng CRM — thuộc EP-03"* |
+
+*(Các ví dụ trên là ví dụ minh hoạ.)*
+
+Mỗi lăng kính là một agent riêng, chạy song song, **bắt buộc dùng model Opus**. Sau đó có thêm **một agent kiểm chứng**, nhiệm vụ duy nhất là **cố chứng minh từng finding là sai** bằng cách tra lại PRD. Finding nào không đứng vững thì bị bỏ. Đây là lớp chặn chính đối với các finding do AI ảo giác.
+
+## Mức độ
+
+| Mức | Nghĩa | Có chặn duyệt không |
+|---|---|---|
+| `critical` | Không sửa thì sẽ **làm sai** hoặc không làm được | Có, cho tới khi bạn quyết |
+| `major` | Không sửa thì người làm **phải đoán** | Có, cho tới khi bạn quyết |
+| `minor` | Làm rõ thêm cho dễ đọc, không đổi hành vi | Không |
+
+## Bạn quyết thế nào
+
+AI trình bảng tóm tắt. Chi tiết từng finding nằm trong `review/prd-refine.md`. Bạn trả lời bằng mã:
+
+```
+nhận F01, F03 · bác F02 vì đã có ở UC-002 · F04 sửa thành "khoá 30 phút" · hoãn F05
+```
+
+| Quyết định | Kết quả |
+|---|---|
+| `nhận` | AI sửa PRD theo đề xuất |
+| `sửa: …` | AI sửa PRD theo nội dung bạn đưa |
+| `bác: <lý do>` | Không sửa. Lần rà sau **không nêu lại** điểm này |
+| `hoãn` | Không sửa lúc này. Được ghi vào "Câu hỏi còn mở" của PRD để bước QC xử lý |
+
+Bác hay hoãn đều tính là **đã quyết**. Chỉ cần mọi critical và major đều đã có quyết định là đi tiếp được.
+
+## Vì sao chỉ có 2 lượt
+
+Kinh nghiệm cho thấy: rà → sửa → rà lại thì lần nào cũng ra vấn đề mới, nhiều cái là ảo giác, và vòng lặp không dứt. Vì vậy:
+
+| Lượt | Soi gì | Được báo gì |
+|---|---|---|
+| **1** | Toàn bộ PRD | Mọi mức độ |
+| **2** (chỉ khi lượt 1 có bản sửa) | **Chỉ phần vừa sửa**, và các mục tham chiếu tới nó | **Chỉ** critical, hoặc lỗi do chính bản sửa gây ra |
+| 3 | **Không có** | — |
+
+Thêm vào đó, file refine là **sổ quyết định**: lần rà sau đọc lại sổ và không nêu lại những điểm bạn đã quyết.
+
+Sau mỗi lượt có sửa, lệnh sẽ nhắc *"`/clear` rồi `/prd EP-01 refine`"* để chạy lượt 2.
+
+## 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ỉ rà các mục vừa đổi** (theo dòng Lịch sử thay đổi), nên nhanh và rẻ.
+
+## Duyệt PRD
+
+PRD chỉ được đặt `approved` khi đủ cả 4 điều kiện:
+1. Không còn 🤖.
+2. Không còn câu hỏi mở.
+3. **Đã refine đúng version này** (`refined` = `version`), và không còn critical/major chưa quyết.
+4. Đã ghi người duyệt.
+
+Công cụ tự chặn nếu thiếu điều kiện nào.

package/docs/guide/lenh/prd.md

@@ -11,7 +11,7 @@
 | **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 |
+| **Bước tiếp** | [`/prd EP-01 refine`](prd-refine.md) → duyệt PRD → `/bdd UC-xxx` *(sắp có)* | [`/prd EP-01 refine`](prd-refine.md) (chỉ rà phần vừa đổi) → duyệt lại |
 
 ---
 
@@ -34,7 +34,7 @@ Bạn đồng ý, gộp hoặc tách UC.
 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`.
+5. Tiếp theo **bắt buộc rà nội dung**: `/clear` rồi [`/prd EP-01 refine`](prd-refine.md). Rà xong, hết 🤖 và hết câu hỏi mở thì mới duyệt được. AI hỏi *"Ai duyệt PRD này?"* rồi đặt `status: approved`.
 
 ## PRD trông như thế nào
 
@@ -71,7 +71,7 @@ Dùng cho **mọi** thay đổi: thêm, sửa, bỏ.
 | 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ượ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à phải **refine lại** (chỉ rà phần vừa đổi) rồi **duyệt lại**.
 
 ## Lưu ý
 

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

@@ -7,17 +7,18 @@
 ## Đườ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
+/product ──► /product EP-xx ──► /prd EP-xx ──► /prd EP-xx refine ──► 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ả) |
+| 3 | `/prd EP-xx` | Duyệt cách chia UC, xác nhận các mục 🤖 | [/prd](../lenh/prd.md) |
+| 4 | `/prd EP-xx refine` | Quyết từng finding: nhận, sửa, bác hay hoãn. Tối đa 2 lượt. Xong thì duyệt PRD | [/prd refine](../lenh/prd-refine.md) |
+| 5 | `/prd EP-xx change …` | Khi yêu cầu đổi. Duyệt kế hoạch thay đổi, refine lại phần vừa đổi, rồi duyệt lại PRD | [/prd](../lenh/prd.md#đổi-prd-prd-ep-01-change-mô-tả) |
 
 ## Mẹo
 

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

@@ -20,11 +20,14 @@
 | 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?"* |
+| `… bản v1.2 chưa refine` | PRD chưa được rà nội dung ở version này | Chạy `/prd EP-xx refine` |
+| `… còn finding critical/major chưa có quyết định: F01, F04` | Bạn chưa quyết các finding đó | Trả lời: nhận, sửa, bác (kèm lý do) hay hoãn |
+| `Bản v1.1 đã refine xong` | Gọi refine lại khi PRD chưa đổi | Không cần làm gì. Thật sự muốn rà lại từ đầu thì thêm `--full` |
 | `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ả>` |
+| `PRD đã có …` | Gọi `/prd EP-xx` khi PRD đã tồn tại | Rà nội dung: `/prd EP-xx refine` · Đổi: `/prd EP-xx change <mô tả>` |
 
 ## Vẫn chưa được?
 

package/package.json

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

package/ref/prd/lenses.md

@@ -0,0 +1,78 @@
+# Lăng kính rà nội dung PRD — dành cho sub-agent
+
+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.
+
+## 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.
+2. **Có trích dẫn.** Mỗi finding trích **nguyên văn** đoạn PRD liên quan (≤ 120 ký tự) kèm mã mục (`UC-003-BR02`, `UC-003`, hoặc `Tổng quan`). Finding dạng *"PRD thiếu X"* thì nêu mục lẽ ra phải chứa X.
+3. **Không nêu lại** những gì đã có quyết định trong file refine (`R`), dù là `nhận`, `bác` hay `hoãn`.
+4. **Không hỏi những gì bước sau sẽ trả lời**: giao diện chi tiết (thuộc design-spec), kịch bản kiểm thử (thuộc BDD), cách làm kỹ thuật (thuộc TDD).
+5. **Mức độ:**
+
+| Mức | Khi nào | Ví dụ |
+|---|---|---|
+| `critical` | Không sửa thì dev hoặc QC **sẽ làm sai**, hoặc không làm được | Hai BR mâu thuẫn trực tiếp |
+| `major` | Không sửa thì người làm **phải đoán** | Không nói chuyện gì xảy ra khi import có dòng sai định dạng |
+| `minor` | Làm rõ thêm cho dễ đọc, không đổi hành vi | Tên trạng thái dùng hai cách gọi |
+
+## QA — hình thức của AC
+
+Cố ý hẹp. Chỉ hỏi:
+- AC có nêu **kết quả nhìn thấy được**, kiểm được là đạt / không đạt không?
+- AC có **lặp lại** nội dung BR không? Nếu lặp thì đề xuất làm mỏng AC và trỏ sang BR.
+
+**Không** hỏi "AC đủ chi tiết chưa". Chi tiết cơ chế (số lần, thời hạn, nhánh lỗi) thuộc về BR / Business Logic. Nếu thiếu cơ chế thì đề xuất **thêm vào BR**, không phình AC.
+
+## DEV — BR và Business Logic có đủ để làm không
+
+Đọc như một dev sắp làm: đã đủ để làm **mà không phải đoán** chưa? Soi:
+- nhánh nghiệp vụ còn thiếu;
+- điều kiện biên chưa nói (0, rỗng, tối đa, trùng, đồng thời);
+- xử lý khi có lỗi hay ngoại lệ bị bỏ ngỏ, ví dụ *"gửi email đặt lại mật khẩu thất bại thì sao?"*;
+- BR mơ hồ, hoặc mâu thuẫn với BR khác.
+
+## SA — thông suốt và nhất quán giữa các UC
+
+Đọc như một architect: toàn bộ luồng có **thông suốt và nhất quán** không? Soi:
+- tương tác giữa các UC đã được định nghĩa chưa (UC này tạo ra thứ mà UC kia cần);
+- **trạng thái và vòng đời** của đối tượng nghiệp vụ có nhất quán không, ví dụ tài khoản: mới → active → inactive;
+- **ai được làm gì, ai sở hữu gì**;
+- cùng một khái niệm có bị gọi hoặc hiểu khác nhau ở hai UC không.
+
+Không phán về kiến trúc hay mô hình dữ liệu kỹ thuật.
+
+## Phạm vi — PRD có đi đúng đường đã chốt không
+
+Đọc thêm file epic (mục checkpoint 1) và `product.md` (mục Ràng buộc, Danh sách epic). Soi:
+- PRD có **vượt ra ngoài** phạm vi epic, hoặc làm điều epic ghi là "ngoài phạm vi" không;
+- PRD có **đi ngược** một ràng buộc `CON-xx` không;
+- PRD có **giẫm lên** phạm vi của epic khác không.
+
+Không hỏi lại ưu tiên hay mục tiêu, vì đã chốt ở `/product`.
+
+## Định dạng trả về
+
+Trả về **chỉ** danh sách sau, không viết gì thêm:
+
+```
+- lens: DEV
+  severity: major
+  item: UC-003-BR02
+  quote: "…nguyên văn…"
+  finding: "…"
+  suggestion: "…"
+  if_accepted: "…"        # chỉ critical / major: chốt đề xuất này thì phát sinh trường hợp gì
+```
+
+Không tìm thấy gì thì trả về `[]`.
+
+## Kiểm chứng — dành cho agent kiểm chứng
+
+Bạn nhận danh sách finding của 4 lăng kính. Với **từng** finding, **cố chứng minh nó sai**:
+1. Tra PRD: đoạn `quote` có đúng là nguyên văn không? Điều finding nói "thiếu" có thật là thiếu không, hay đã nằm ở mục khác (BR khác, Business Logic, UC khác, Tổng quan)?
+2. Finding có hỏi điều thuộc bước sau (giao diện, kịch bản test, kỹ thuật) không?
+3. Finding có đề xuất giải pháp kỹ thuật không?
+4. Mức độ có đúng định nghĩa không?
+
+Trả về cho mỗi finding một trong ba kết luận: `ĐÚNG` · `SAI: <lý do, kèm trích dẫn chứng minh>` · `HẠ MỨC: <mức mới, lý do>`.

package/ref/prd/refine.md

@@ -0,0 +1,44 @@
+# /prd — chế độ rà nội dung (refine)
+
+Mục đích: tìm chỗ **nghiệp vụ còn thiếu, mơ hồ, mâu thuẫn** đến mức sẽ làm sai hoặc phải đoán ở các bước sau. **Không** rà chính tả hay trình bày, vì đó là việc của `/review`.
+
+File refine: `R = {specs}/{domain}/{slug}/review/prd-refine.md` (khuôn `.fw/core/templates/prd-refine.md`).
+
+## Bước A — Xác định lượt
+
+Chạy `SE upgrade D` trước. Lệnh này bổ sung trường `refined` cho PRD tạo bằng bản cũ, và đổi mã nguồn `R…` thành `BR…`.
+
+Đọc frontmatter của `D` (`version`, `refined`) và của `R` (nếu có: `prd_version`, `round`).
+
+| Tình huống | Lượt | Phạm vi |
+|---|---|---|
+| `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 dòng Lịch sử thay đổi từ sau `refined` tới nay |
+
+**Không có lượt 3.** Sau lượt 2 thì luôn đặt `refined` (Bước D).
+
+## Bước B — Rà (sub-agent, bắt buộc model Opus)
+
+1. Dùng công cụ **Agent**, `model: "opus"`, gọi **4 agent song song trong cùng một lượt**: QA · DEV · SA · Phạm vi. Mỗi agent nhận:
+   - đường dẫn `D`, `R` (nếu có), `.fw/core/ref/prd/lenses.md`, và tên lăng kính của nó;
+   - **phạm vi** của lượt (Bước A), và **ngưỡng báo**: lượt 1 báo mọi mức · lượt 2 chỉ báo critical hoặc lỗi do chính bản sửa gây ra;
+   - riêng lăng kính Phạm vi: thêm đường dẫn file epic và `{specs}/product/product.md`.
+2. Gom kết quả, rồi gọi **1 agent kiểm chứng** (`model: "opus"`) với danh sách finding, `D`, và phần "Kiểm chứng" trong `lenses.md`. Chỉ giữ finding nào được kết luận **ĐÚNG**.
+3. Gộp các finding 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à nêu rõ là cần PO chọn.
+
+## Bước C — Ghi và trình
+
+1. Chưa có `R`: `SE create R` theo khuôn. Đã có: `SE edit` thêm một mục `## Lượt {n} — v{version}` ở **cuối**. Không sửa các lượt cũ, vì chúng là sổ quyết định.
+2. Mã finding đánh **nối tiếp** qua mọi lượt (F01…), không đánh lại.
+3. `SE set R prd_version={version} round={n} status=pending`.
+4. Trình cho PO: **một bảng tóm tắt** (mã · mức · lăng kính · mục · một dòng vấn đề), sắp theo mức độ. Kèm số finding bị bỏ ở bước kiểm chứng, để PO thấy bước này có tác dụng. Nhắc PO: *"Chi tiết xem {R}. Quyết bằng mã: 'nhận F01, F03 · bác F02 vì … · F04 sửa thành … · hoãn F05'."*
+5. Không có finding nào: báo, rồi sang Bước D luôn.
+
+## Bước D — Áp quyết định
+
+1. Ghi quyết định của PO vào `R` (`- Quyết định: …`). **Mọi** finding critical / major đều phải có quyết định khác `chờ`. Còn thiếu thì hỏi lại, tối đa 4 mã mỗi lượt.
+2. Finding `nhận` hoặc `sửa`: áp vào `D` trong **một** lần `SE edit`, theo đúng luật của `.fw/core/ref/prd/change.md` (mã mới lấy số kế tiếp, mục bỏ thì gạch ngang, `(nguồn: PRD)`). Thêm một dòng Lịch sử thay đổi nêu mã finding, ví dụ *"v1.1 — refine lượt 1: F01, F03, F04"*.
+3. Có áp bản sửa: tăng version phụ (`SE set D version=… status=draft approved_by=— approved_at=—`), rồi `SE set R status=applied`. Nếu đây là **lượt 1**, báo *"`/clear` rồi `/prd {id} refine` để chạy lượt 2, chỉ soi phần vừa sửa."*
+4. 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)"*.

package/templates/prd-refine.md

@@ -0,0 +1,29 @@
+---
+type: prd-refine
+prd: {đường dẫn prd.md}
+prd_version: {version PRD lúc rà}
+round: 1                 # 1 | 2
+status: pending          # pending | applied | done
+updated: {YYYY-MM-DD}
+---
+
+# Refine PRD — {EPIC-ID}
+
+> Rà **nội dung** PRD qua 4 lăng kính: QA · DEV · SA · Phạm vi. Finding nào cũng đã qua bước **kiểm chứng**.
+> File này cũng là **sổ quyết định**: lần rà sau đọc lại để không nêu lại những điểm đã quyết. **Không xoá finding cũ.**
+> Quyết định: `chờ` · `nhận` · `sửa: <nội dung PO muốn>` · `bác: <lý do>` · `hoãn` (để bước QC).
+
+## Tóm tắt <!-- sec:summary -->
+
+| Lượt | Version | Tìm thấy | Bỏ sau kiểm chứng | critical | major | minor | Kết luận |
+|---|---|---|---|---|---|---|---|
+| 1 | {v} | {n} | {n} | {n} | {n} | {n} | {BLOCKED · NEEDS_REVISION · APPROVED_WITH_MINOR_CHANGES} |
+
+## Lượt 1 — v{version} <!-- sec:round-1 -->
+
+### F01 · {QA · DEV · SA · Phạm vi} · {critical · major · minor} · {mã mục}
+- Trích: "{nguyên văn trong PRD}"
+- Vấn đề: {…}
+- Đề xuất: {…}
+- Nếu chốt đề xuất này: {… — chỉ critical / major}
+- Quyết định: chờ

package/templates/prd.md

@@ -6,6 +6,7 @@ status: draft            # draft | approved
 open_questions: 0
 approved_by: —           # người duyệt PRD; bắt buộc có khi status: approved
 approved_at: —           # YYYY-MM-DD
+refined: —              # version đã refine xong (/prd <EPIC-ID> refine); bắt buộc = version khi duyệt
 updated: {YYYY-MM-DD}
 ---
 

package/tools/spec_edit.py

@@ -35,9 +35,10 @@ FRONTMATTER = {
     "product": {"status": ["in-progress", "ready"], "checkpoint": (0, 2)},
     "epic": {"status": ["in-progress", "ready", "handed-off"], "checkpoint": (0, 3)},
     "prd": {"status": ["draft", "approved"]},
+    "prd-refine": {"status": ["pending", "applied", "done"], "round": (1, 2)},
 }
 # Trạng thái "đã xong": chỉ đặt được khi không còn 🤖 và không còn câu hỏi mở.
-DONE_STATUS = {"product": "ready", "epic": "ready", "prd": "approved"}
+DONE_STATUS = {"product": "ready", "epic": "ready", "prd": "approved", "prd-refine": "done"}
 COMMON_INT = {"open_questions": (0, 999)}
 DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 VERSION = re.compile(r"^\d+\.\d+$")
@@ -128,7 +129,7 @@ def validate(ftype, key, value):
         fail("type `%s` chưa được khai trong spec_edit.py" % ftype)
     if key == "status" and value not in rules["status"]:
         fail("status=%s không hợp lệ với type %s. Chỉ nhận: %s" % (value, ftype, ", ".join(rules["status"])))
-    rng = rules.get(key) if key == "checkpoint" else COMMON_INT.get(key)
+    rng = rules.get(key) if isinstance(rules.get(key), tuple) else COMMON_INT.get(key)
     if rng:
         if not value.isdigit() or not rng[0] <= int(value) <= rng[1]:
             fail("%s=%s không hợp lệ. Phải là số nguyên từ %d đến %d" % (key, value, rng[0], rng[1]))
@@ -136,11 +137,50 @@ def validate(ftype, key, value):
         fail("updated=%s không hợp lệ. Định dạng YYYY-MM-DD" % value)
     if key == "approved_at" and value != "—" and not DATE.match(value):
         fail("approved_at=%s không hợp lệ. Định dạng YYYY-MM-DD, hoặc — nếu chưa duyệt" % value)
-    if key == "version" and not VERSION.match(value):
-        fail("version=%s không hợp lệ. Định dạng số.số, ví dụ 1.0, 1.1" % value)
+    if key in ("version", "prd_version") and not VERSION.match(value):
+        fail("%s=%s không hợp lệ. Định dạng số.số, ví dụ 1.0, 1.1" % (key, value))
+    if key == "refined" and value != "—" and not VERSION.match(value):
+        fail("refined=%s không hợp lệ. Là version PRD đã refine xong (vd 1.1), hoặc —" % value)
 
 
-def guard_done(ftype, block, body):
+# ── Refine: finding critical / major chưa có quyết định thì chưa được đi tiếp ──────────────
+FINDING = re.compile(r"^### (F\d+) · [^·\n]+ · (critical|major|minor) ·", re.M)
+DECISION = re.compile(r"^- Quyết định:\s*(.*)$", re.M)
+
+
+def undecided_findings(text):
+    """Mã các finding critical / major còn `chờ` (hoặc chưa ghi quyết định)."""
+    out = []
+    heads = list(FINDING.finditer(text))
+    for n, h in enumerate(heads):
+        end = heads[n + 1].start() if n + 1 < len(heads) else len(text)
+        block = text[h.end():end]
+        block = re.split(r"^##\s", block, maxsplit=1, flags=re.M)[0]
+        d = DECISION.search(block)
+        if h.group(2) in ("critical", "major") and (not d or d.group(1).strip().startswith("chờ")):
+            out.append(h.group(1))
+    return out
+
+
+def refine_path(prd_path):
+    return os.path.join(os.path.dirname(os.path.abspath(prd_path)), "review", "prd-refine.md")
+
+
+def guard_refined(path, block):
+    """PRD chỉ được duyệt khi đã refine đúng version đang có và không còn critical/major chưa quyết."""
+    ver = re.search(r"^version:\s*(\S+)", block, re.M)
+    ref = re.search(r"^refined:\s*(\S+)", block, re.M)
+    if not ref or not ver or ref.group(1) != ver.group(1):
+        fail("không đặt được status=approved: bản v%s chưa refine (refined=%s). Chạy `/prd <EPIC-ID> refine` trước."
+             % (ver.group(1) if ver else "?", ref.group(1) if ref else "chưa có"))
+    rp = refine_path(path)
+    pending = undecided_findings(read(rp)) if os.path.isfile(rp) else []
+    if pending:
+        fail("không đặt được status=approved: còn finding critical/major chưa có quyết định: %s (xem %s)"
+             % (", ".join(pending), rp))
+
+
+def guard_done(ftype, block, body, path):
     """Chặn đặt trạng thái 'đã xong' khi còn mục chờ PO — AI không được tự khẳng định."""
     done = DONE_STATUS.get(ftype)
     sm = re.search(r"^status:\s*(\S+)", block, re.M)
@@ -159,6 +199,11 @@ def guard_done(ftype, block, body):
         if fm and fm.group(1) == "—":
             fail("không đặt được status=%s: chưa có %s. Đặt cùng lệnh, ví dụ: "
                  "set <file> status=%s approved_by=<tên> approved_at=YYYY-MM-DD" % (done, field, done))
+    if ftype == "prd":
+        guard_refined(path, block)
+    if ftype == "prd-refine" and undecided_findings(body):
+        fail("không đặt được status=done: còn finding critical/major chưa có quyết định: %s"
+             % ", ".join(undecided_findings(body)))
 
 
 def cmd_set(path, pairs):
@@ -182,7 +227,7 @@ def cmd_set(path, pairs):
         # Giữ nguyên comment đi kèm ở cuối dòng, chỉ đổi giá trị.
         block = line.sub(lambda mm: mm.group(1) + value + (mm.group(3) or ""), block, count=1)
 
-    guard_done(ftype, block, text[m.end():])
+    guard_done(ftype, block, text[m.end():], path)
     write(path, text[: m.start(1)] + block + text[m.end(1):])
     print("đã đặt %s trong %s" % (", ".join(pairs), path))
 
@@ -191,7 +236,8 @@ def cmd_set(path, pairs):
 # Số và tên tiêu đề là cho người đọc, được đổi tự do. Script và AI tìm mục theo mã `sec:`.
 SEC_KEY = re.compile(r"<!--\s*sec:([a-z0-9-]+)\s*-->")
 HEADING = re.compile(r"^(#{2,6})\s+(.*)$")
-TEMPLATE_OF = {"product": "product.md", "epic": "product-epic.md", "prd": "prd.md"}
+TEMPLATE_OF = {"product": "product.md", "epic": "product-epic.md", "prd": "prd.md",
+               "prd-refine": "prd-refine.md"}
 TEMPLATES_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "templates")
 
 
@@ -286,6 +332,26 @@ def cmd_section(path, key):
         "" if have else ". File theo khuôn cũ: chạy `upgrade <file>` trước."))
 
 
+def missing_frontmatter(ftype, text):
+    """Các dòng frontmatter có trong khuôn mà file chưa có. Giá trị mẫu dạng {…} đổi thành —."""
+    name = TEMPLATE_OF.get(ftype)
+    tpath = os.path.join(TEMPLATES_DIR, name) if name else None
+    if not tpath or not os.path.isfile(tpath):
+        return []
+    tm = re.match(r"^---\r?\n(.*?)\r?\n---", read(tpath), re.S)
+    fm = re.match(r"^---\r?\n(.*?)\r?\n---", text, re.S)
+    if not tm or not fm:
+        return []
+    have = set(re.findall(r"^([a-z_]+):", fm.group(1), re.M))
+    out = []
+    for line in tm.group(1).split("\n"):
+        k = re.match(r"^([a-z_]+):\s*(\S*)(.*)$", line)
+        if k and k.group(1) not in have:
+            value = "—" if k.group(2).startswith("{") else k.group(2)
+            out.append("%s: %s%s" % (k.group(1), value, k.group(3)))
+    return out
+
+
 def cmd_upgrade(path):
     """Gắn mã sec: cho file theo khuôn cũ, bằng cách khớp tiêu đề với khuôn. Chỉ cần chạy một lần."""
     text = read(path)
@@ -308,6 +374,11 @@ def cmd_upgrade(path):
         else:
             unknown.append(title)
     new_text = "\n".join(lines)
+    # Trường frontmatter khuôn mới có mà file cũ chưa có (vd refined, approved_by) → thêm với giá trị —.
+    add_fm = missing_frontmatter(ftype, new_text)
+    if add_fm:
+        fm = re.match(r"^---\r?\n(.*?)(\r?\n)---", new_text, re.S)
+        new_text = new_text[:fm.end(1)] + "".join(fm.group(2) + l for l in add_fm) + new_text[fm.end(1):]
     # 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":
@@ -322,6 +393,8 @@ def cmd_upgrade(path):
         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 add_fm:
+        print("đã thêm trường frontmatter: " + ", ".join(l.split(":")[0] for l in add_fm))
     if renamed[0]:
         print("đã đổi mã Business Rule R… → BR…: %d chỗ" % renamed[0])
     if unknown: