@educa-corp/sdd-framework 0.8.1 → 0.9.1

package/core/commands/qc-analyze.md

@@ -9,9 +9,6 @@ ported_from: ai-automation-qc-base
 > Stage 1 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-analyst của team QC. Markdown-first: không có script ở đây.
 
 ## Gate
-
-*Checkpoint: **chặn thường** — lệnh ghi 2 file artifact. `--yes` bỏ qua được (gate Bước 3a).*
-
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
 Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
@@ -165,7 +162,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
 
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID hoặc file feature/PRD. Đọc spec chính thức của UC đó — file `.feature` (mang `@trace.id={UC-ID}` và mỗi scenario `@trace.scenario={UC-ID}-SC{N}`), PRD, và design-spec — từ feature package `{paths.specs_dir}/{domain}/{prd-slug}/` (file `.feature` dưới `bdd/`, file PRD `{TICKET-ID}-{prd-slug}.md` ở gốc folder, và design-spec dưới `design-spec/`). Spec của framework CHÍNH LÀ source of truth; đừng suy lại các requirement đã có ở đó. **Ngoài ra đọc tech-doc gộp** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` làm **nguồn thứ hai** — xem §Đối chiếu tài liệu kỹ thuật.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID hoặc file feature/PRD. Đọc spec chính thức của UC đó — file `.feature` (mang `@trace.id={UC-ID}` và mỗi scenario `@trace.scenario={UC-ID}-SC{N}`), PRD, và design-spec — từ feature package `{paths.specs_dir}/{domain}/{prd-slug}/` (file `.feature` dưới `bdd/`, file PRD `{TICKET-ID}-{prd-slug}.md` ở gốc folder, và design-spec dưới `design-spec/`). Spec của framework CHÍNH LÀ source of truth; đừng suy lại các requirement đã có ở đó.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -177,103 +174,30 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ---
 
-## Platform Resolution *(thiết lập cho cả QC pass — mọi stage sau kế thừa)*
-
-> **PHẢI chạy TRƯỚC Guard bên dưới.** `{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform), nên
-> một UC đa nền có **nhiều file `.feature`** — `bdd/web/`, `bdd/app/`, `bdd/system/` — và mỗi
-> file mang `@trace.status` **riêng**: bản web có thể `approved` trong khi bản app còn `draft`.
-> Guard đọc "file `.feature` của UC" khi chưa biết platform là đọc một file **bất kỳ trong ba**:
-> báo `approved` trong khi bản đang dùng còn nháp, hoặc chặn oan một bản đã duyệt.
-> Chốt platform trước thì Guard mới có đúng một file để đọc.
-
-`{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) — `web SC3` và `app SC3` là hai scenario khác nhau, và sổ trace tách theo `{UC-ID}-{platform}.tsv`. Nên **một QC pass khoá đúng MỘT platform**, và mọi artifact QC nằm dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`.
-
-Phân giải `active_platform` — theo thứ tự, dừng ở cái đầu tiên khớp:
-1. `$ARGUMENTS` nêu platform (`web`/`app`/`system`) → dùng.
-2. Target ở Bước 1 là một file `.feature` → đọc `# @trace.platform` của nó.
-3. Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/*/` — **đúng một** thư mục platform tồn tại → dùng nó.
-4. Nhiều platform mà không suy được → hỏi *"QC pass này cho platform nào? (web/app/system)"*.
-   **Có `--yes`:** không hỏi — dừng với lỗi rõ ràng, vì đoán bừa platform là ghi artifact vào sai
-   thư mục và ghi `qc_status` vào sai sổ trace:
-   ```
-   ❌ {UC-ID} có {n} platform ({list}) — không suy được platform nào cho QC pass này.
-      Chạy headless thì phải nêu tường minh: /qc-analyze {UC-ID} web --yes
-   ```
-
-Lưu `active_platform`. Đọc **đúng file `.feature` của platform đó** (`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{UC-ID}*.feature`) làm nguồn SC — không trộn SC chéo platform.
-
----
-
 ## Guard — BDD đã duyệt chưa
 
-*Chạy SAU Platform Resolution — xem lý do ở khối trên.*
-
-Đọc `# @trace.status:` từ header file `.feature` **của `{active_platform}` đã phân giải**:
+Đọc `# @trace.status:` từ header file `.feature` của UC target:
 - `approved` → tiếp tục bình thường.
 - `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
   ```
-  ⚠️  BDD của {UC-ID} ({active_platform}) đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
+  ⚠️  BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
      Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
      Vẫn chạy QC bây giờ? (Y/N)
   ```
-  Chỉ tiếp khi chọn Y — **trừ khi `$ARGUMENTS` có `--yes`**: coi như Y, **nhưng vẫn IN khối cảnh
-  báo** (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy QC đã chạy trên BDD nháp).
-
-> **Vì sao `--yes` phải phủ cả guard mềm này.** `steps/gate.md` mở đường chạy headless
-> (`claude -p "… --yes"`), nhưng `--yes` chỉ khai là bỏ qua CHECKPOINT của gate. Guard mềm ở đây
-> là một `(Y/N)` thứ hai — nên lệnh vẫn treo vô hạn ở chế độ không có người trả lời, và đường
-> headless mà gate hứa bị bít cho đúng lệnh này. Một cổng chỉ chặn được khi có người ngồi đó
-> thì ở chế độ headless nó không phải cổng, nó là treo.
+  Chỉ tiếp khi chọn Y.
 
 ---
 
-## Đối chiếu tài liệu kỹ thuật *(nguồn thứ hai — bắt lệch nghiệp vụ ↔ kỹ thuật)*
-
-Định vị tech-doc gộp cấp PRD: `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`.
-Nó phủ **nhiều UC** — lọc theo `@trace.ucs` ở header, chỉ đọc phần chạm `{UC-ID}` đang xét.
-
-**Không tìm thấy → cảnh báo mềm, KHÔNG chặn** (dự án có thể chưa dựng tech-doc):
-```
-⚠️  Không có tech-doc cho {TICKET-ID} — phân tích chỉ dựa trên PRD + BDD + design-spec.
-   Lệch giữa yêu cầu nghiệp vụ và hợp đồng kỹ thuật (enum, mã lỗi, ràng buộc field) sẽ KHÔNG được phát hiện ở trạm này.
-```
-
-**Có → đối chiếu các mục sau với PRD/BDD, mỗi chỗ vênh là một gap `CONTRADICTORY`:**
-
-| Mục tech-doc | Đối chiếu gì với PRD/BDD |
-|---|---|
-| §3 Mô hình dữ liệu | thực thể/field/quan hệ PRD nhắc tới có khớp không |
-| **§4 Hợp đồng API** | **enum & tập giá trị hợp lệ** · ràng buộc field (độ dài, định dạng, bắt buộc) · **mã lỗi** — PRD nêu bao nhiêu nhánh lỗi, contract định nghĩa bao nhiêu |
-| §4.5 Ánh xạ component UI | màn/component PRD·design-spec mô tả có mặt đủ không |
-| §5 Luồng chính | thứ tự bước, nhánh rẽ có khớp scenario `.feature` không |
-| §6 Điểm tích hợp | side-effect PRD nêu (gửi sự kiện, gọi dịch vụ khác) có được định nghĩa không |
-| §8 Xử lý lỗi & biên | trường hợp biên PRD nêu có đường xử lý không, và ngược lại |
-
-> **Vì sao mục này tồn tại.** Có một lớp gap **chỉ lộ ra khi so hai loại tài liệu với nhau** —
-> đọc riêng bên nào cũng thấy hợp lý. Ca điển hình: PRD viết *"chọn lớp 1–6"*, contract định
-> nghĩa enum `1..9`. Không ai đọc cả hai thì không ai thấy, và nó ra tận lúc chạy thật.
-> **Đây là lý do trạm này đọc tech-doc — không phải để hiểu kỹ thuật, mà để bắt chỗ hai bên nói khác nhau.**
-
-### §12 GAP Register — ĐỌC, KHÔNG GHI
-
-Tech-doc có sổ ẩn số thiết kế riêng (`§12`), với vòng đời và người chịu trách nhiệm riêng, và
-`/generate-code` đã canh nó. **Trạm này chỉ đọc, tuyệt đối không ghi vào.**
+## Platform Resolution *(thiết lập cho cả QC pass — mọi stage sau kế thừa)*
 
-Với mỗi mục `open` trong §12 chạm `{UC-ID}`:
-- **KHÔNG mở gap mới** trong `DOC_GAP.md` về cùng chuyện đó.
-- Ghi vào `REQUIREMENT_ANALYSIS.md` mục *"Đang chờ chốt (từ §12 tech-doc)"*: `{id}` · điều chưa biết · owner · severity.
-- Test case chạm nó về sau sẽ bị chặn — nhưng bị chặn bởi **một mục đã có người xử lý**, không phải bởi một câu hỏi mới gửi PO.
+`{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) — `web SC3` và `app SC3` là hai scenario khác nhau, và sổ trace tách theo `{UC-ID}-{platform}.tsv`. Nên **một QC pass khoá đúng MỘT platform**, và mọi artifact QC nằm dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`.
 
-> **Vì sao không ghi vào.** Một ẩn số đã nằm trong §12 nghĩa là **đã có người đang lo**: có
-> owner, có mức chặn, có cổng chặn sinh code. Mở lại nó thành gap QC là gửi PO một câu hỏi
-> về thứ không phải việc của PO, và tạo hai sổ cùng theo dõi một chuyện — rồi chúng lệch nhau.
-> Đây đúng là **câu hỏi lọc Q1** của `steps/gap-verify.md` (*"chỗ này đã được trả lời ở tài liệu
-> khác chưa?"*), chỉ mở rộng phạm vi "tài liệu khác" thêm một nguồn.
+Phân giải `active_platform`:
+- Target ở Bước 1 là một file `.feature` → đọc `# @trace.platform` của nó.
+- `$ARGUMENTS` nêu platform (`web`/`app`/`system`) → dùng.
+- Ngược lại → hỏi: *"QC pass này cho platform nào? (web/app/system)"* và chờ chọn.
 
-**Ngoại lệ — mục `spec-defect` là việc của PO.** §12 phân ba loại: `nội tại` (backend tự quyết) ·
-`cross-service` (đội khác) · `spec-defect` (PRD/BDD sai hoặc thiếu). Hai loại đầu → ghi "đang chờ".
-Loại thứ ba **đúng là gap tài liệu** → vẫn ghi vào `DOC_GAP.md`, trỏ ngược về `{id}` của §12 để
-không đếm hai lần.
+Lưu `active_platform`. Đọc **đúng file `.feature` của platform đó** (`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{UC-ID}*.feature`) làm nguồn SC — không trộn SC chéo platform.
 
 ---
 
@@ -304,204 +228,42 @@ File `.feature` chính thức đã định nghĩa scenario là `@trace.scenario=
 và ghi lại mapping — qc-design-test và qc-run-test cần nó để gắn tag
 `@trace.verifies` cho test và ghi `qc_status` theo từng scenario.
 
-## Quét gap — hai nguồn, gộp rồi mới thẩm định
-
-Gap đến từ **hai chỗ**, và chúng bổ sung nhau chứ không thay thế:
-
-| Nguồn | Trả lời câu | Gap là |
-|---|---|---|
-| **4 kỹ năng phân tích** ở trên | *"yêu cầu là gì?"* | sản phẩm phụ — đang bóc luật nghiệp vụ thì gặp chỗ mâu thuẫn |
-| **Quét theo lăng kính** *(dưới đây)* | *"còn thiếu gì?"* | mục tiêu chính |
-
-### Quét theo lăng kính
-
-Chạy `steps/review-fanout.md` với:
+## DOC_GAPS (bắt buộc)
 
-| Tham số | Giá trị |
-|---|---|
-| `DIMENSIONS` | **4 lăng kính** — `D2 Xử lý lỗi` · `D3 Giao diện` · `D4 Dữ liệu & cấu hình` · `D5 Đối chiếu chéo` **(thu hẹp — xem dưới)** *(định nghĩa ở `{paths.qc_skills_dir}/qa-analyst/exhaustive-gap-scanner.md`)* |
-| `FINDINGS SCHEMA` | như §Output dưới đây |
-| `GRANULARITY` | **`auto`** — chia theo ngưỡng kích thước, KHÔNG ép mịn theo từng UC |
-| `VERIFY` | **`off`** — thẩm định chạy MỘT lần ở bước sau, trên tập đã gộp |
-
-**`D5` chạy ở dạng THU HẸP — chỉ 2 trong 4 cặp tài liệu:**
-
-| Cặp | |
-|---|---|
-| `PRD ↔ design-spec/` | ✅ **SO** — không ai đối chiếu nội dung. `/generate-bdd` chỉ kiểm `Built from PRD` (số phiên bản); cùng phiên bản mà nội dung lệch thì lọt |
-| `bdd/{platform}/ ↔ design-spec/` | ✅ **SO** — không ai |
-| `PRD ↔ bdd/` | ❌ bỏ — `/review-context` **B1** đã làm |
-| `PRD·bdd/ ↔ tech-docs/` | ❌ bỏ — §Đối chiếu tài liệu kỹ thuật **ở trên** đã làm |
-
-> **Cả hai cặp SO đều dính `design-spec/`** — artifact duy nhất trong feature package mà **không
-> tài liệu nào đối chiếu nội dung với nó**. Đừng lẫn với `tech-docs/`: `design-spec/` là *giao diện
-> Designer vẽ*, `tech-docs/` là *hợp đồng hệ thống* — và `tech-docs/` đã được phủ ở §trên.
->
-> Trạm này **đã đọc `design-spec/`** từ trước (nó nằm trong danh sách nguồn ở Gate), nên `D5`
-> không nạp thêm file nào — chỉ bắt nó **so** thay vì chỉ **đọc**. Rẻ hơn một lăng kính thường.
-
-**`D1 Luật nghiệp vụ` là lăng kính duy nhất KHÔNG bật:** `qa-analyst/business-rules.md` đã hỏi
-4/5 câu của nó, và hỏi cụ thể hơn — *"min/max · ký tự cho phép · trim · định dạng"* thay vì
-*"ngưỡng đã chốt chưa"*.
-
-> **Ghi lại vì sao `D5` từng bị tắt:** lý do ban đầu là *"trùng nhiều"* — **đúng một nửa**. Nó phủ
-> **bốn** cặp, chỉ **hai** cặp đã có người làm. Sai vì suy từ ấn tượng thay vì đếm danh sách; bảng
-> kiểm chứng 31 câu hỏi (`docs/plans/qc-implementation-log.md`) là thứ đáng lẽ phải làm **trước**
-> khi quyết. Đừng tắt lại `D5` mà không đọc bảng đó.
-
-> **`GRANULARITY = auto`, không phải `per-uc`.** `/refine-prd` ép mịn theo từng UC vì ở tầng PRD
-> một gap bỏ sót **im lặng đi tiếp** tới tận lúc chạy thật. Ở đây khác: gap bỏ sót còn **bốn lớp
-> chặn phía sau** — trạm 3 bật ngược khi không viết nổi giá trị mong đợi, trạm 4 soát độ phủ,
-> trạm 5 phân loại lỗi thật vs script sai. Ép mịn ở đây tốn gấp ~3 lần cho tính năng nhỏ mà đổi
-> lấy một lưới an toàn đã có sẵn ba lớp khác.
-
-### Gộp trước, thẩm định sau
-
-Gộp gap từ **cả hai nguồn** vào một tập trước khi sang bước thẩm định.
-
-> **Không thẩm định từng nguồn riêng.** Phép kiểm `T6` của `gap-verify` là *"hai gap cùng gốc
-> thì gộp lại"* — nó chỉ chạy được khi **thấy toàn bộ** tập. Thẩm định hai lần trên hai tập rời
-> thì không bắt được trùng lặp chéo nguồn, và PO nhận hai câu hỏi giống nhau.
-
----
-
-## DOC_GAP (bắt buộc)
-
-Luôn tạo một file gaps theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`:
+Luôn tạo một file gaps theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`:
 - Mỗi gap `GAP-xx`, phân loại MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, với severity (🔴 Blocker → 🟢 Low) và function/BR/AC bị ảnh hưởng.
 - Không bao giờ bịa câu trả lời; đánh dấu giả định là `ASSUMPTION` để PO/dev confirm.
 - Bất kỳ `🔴 Blocker` nào còn `Open` ⇒ UC chưa sẵn sàng cho qc-design-test — bàn giao cho qc-plan.
 - **Đẩy các defect spec thực sự lên PO (không chỉ giữ local).** Một blocker là lỗi thật
   trong spec chính thức — `AMBIGUOUS` / `CONTRADICTORY` / `MISSING` trong PRD/BDD — phải tới
-  PO qua feedback flow, không chỉ nằm trong `DOC_GAP.md`: tạo `/report-bug {UC-ID} {desc}`
+  PO qua feedback flow, không chỉ nằm trong `DOC_GAPS.md`: tạo `/report-bug {UC-ID} {desc}`
   (BUG_FLOW của nó phân loại PRD vs BDD), hoặc `/propose-scenario {UC-ID}` nếu gap là thiếu test
   coverage. Gap `ASSUMPTION` / `OPEN QUESTION` được confirm qua questions-for-dev của qc-plan — không file thành bug.
 
-### Thẩm định trước khi bàn giao *(bắt buộc)*
-
-Sinh xong `DOC_GAP.md`, **đọc `.agent/steps/gap-verify.md` và chạy toàn bộ quy trình trong đó**
-với:
-- `FINDINGS` = mọi gap đang `Open` trong `DOC_GAP.md`
-- `EVIDENCE_ROOT` = `{paths.specs_dir}` — spec repo của PO, **không** phải `{paths.qc_dir}`
-- `VERDICT_FIELD` = cột `Trạng thái` + `Câu trả lời` của bảng gap
-- `RERATE` = `on`
-
-Gap rớt thẩm định được **đóng kèm lý do**, KHÔNG xoá — người đọc phải kiểm chứng được vì sao
-nó bị loại. Cập nhật `Tổng số gap` + bảng ưu tiên sau khi áp verdict, và in khối
-`[GAP VERIFY]` + cam kết cuối vào report.
-
-> **Vì sao bắt buộc, không phải tuỳ chọn.** Bước phân tích ở trên chỉ có lực **tìm thêm** —
-> bốn skill lần lượt quét spec và mỗi cái đều được khuyến khích ghi ra chỗ nghi ngờ. Không có
-> bước nào hỏi ngược *"cái vừa ghi có thật không?"*. Hệ quả đo được ở đội QC: phần lớn gap sinh
-> ra là gap ảo — spec đã trả lời ở tài liệu khác, hoặc trích dẫn sai, hoặc là chuyện QC tự quyết
-> được. Mà gap ảo không chỉ tốn thời gian PO: nó **làm PO mất tin vào cả danh sách**, và lúc đó
-> những gap thật cũng chết theo. `gap-verify` là bộ lọc duy nhất đứng giữa hai chuyện đó.
-
 ## Output
 
-Ghi **hai file** dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/` + **một** dưới `{paths.refinement_dir}/` — **đừng** tách phân tích
+Ghi **đúng HAI file** dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/` — **đừng** tách phân tích
 thành một-file-mỗi-bước (không có file spec-breakdown / business-rules / data-flow / AC riêng):
 
 1. **`{paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md`** — bản phân tích hợp nhất duy nhất.
    Section theo thứ tự: phân rã requirement → bảng business-rule (`BR-xx`) → data-flow →
    acceptance-criteria (`AC-xx`), mỗi `BR`/`AC` map tới `{UC-ID}-SC{N}` (của `.feature` platform này) sở hữu nó.
-   Cuối file thêm mục **"Đang chờ chốt (từ §12 tech-doc)"** — các ẩn số thiết kế `open` chạm UC này
-   (`{id}` · điều chưa biết · owner · severity). Rỗng thì ghi "Không có"; **đừng bỏ mục**.
-2. **`{paths.qc_dir}/{UC-ID}/{active_platform}/DOC_GAP.md`** — file gap, theo
-   `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md` + luật viết ở
-   `{paths.qc_skills_dir}/qa-analyst/spec-issue-reporter.md`. Bắt buộc:
-   - **Bảng 10 cột** đúng thứ tự, có cột **Giao cho đội** (Dev / PO / BA / Design / Kiến trúc / Dữ liệu).
-   - Ô câu hỏi đủ **bốn phần** tách bằng `<br/>`: **Bối cảnh → Vấn đề → Tại sao quan trọng → Gợi ý**.
-     *Ba phần đầu cho PO xếp ưu tiên; phần cuối cho PO trả lời nhanh mà không phải nghĩ lại từ đầu.*
-   - Section **"Tài liệu đầu vào đã đọc để phân tích"** đặt ngay sau metadata — liệt kê **đủ** mọi
-     file đã mở. Đây là căn cứ độ phủ: không có nó thì không ai phân biệt được *"đã đọc và không thấy"*
-     với *"chưa đọc"*.
-   - Mức nặng nhất dùng từ **`🔴 Blocker`** (không phải `Critical`) — `/qc-run-test` đọc đúng từ này
-     để đặt *"scenario đang chờ PO"* vào sổ trace.
-3. **`{paths.refinement_dir}/{UC-ID}-qa-findings.yaml`** — **cùng dữ liệu gap**, ở định dạng Review Board đọc được. Xem §Bản findings dưới đây.
+2. **`{paths.qc_dir}/{UC-ID}/{active_platform}/DOC_GAPS.md`** — file gaps (theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`).
 
 `{paths.qc_dir}` là folder top-level NHÌN THẤY trong QC repo (mặc định `docs/`, **không** phải
 `.agent/review/` ẩn) để team QC mở và xử lý output dễ dàng. Spec chính thức ở lại
 spec submodule của PO — đừng ghi phân tích vào đó.
 
-### Bản findings — một nguồn, hai mặt
-
-File `.yaml` và `DOC_GAP.md` là **cùng một tập gap**, không phải hai tập. Sinh `DOC_GAP.md`
-trước (nó là bản người đọc), rồi **render** sang `.yaml` — đừng phân tích lại lần hai.
-
-Dùng **đúng schema của `/refine-prd`** để Review Board đọc được cả hai loại file:
-
-```yaml
-prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
-uc_id: "{UC-ID}"
-platform: "{active_platform}"
-generated_at: "{ISO datetime}"
-generated_by: "qc-analyze"
-status: "pending_review"
-
-findings:
-  - id: "F001"
-    lens: "QA"                    # LUÔN là QA — file này chỉ có một lăng kính
-    severity: "critical"          # critical | major | minor  ← map từ 🔴/🟠/🟡⚪ của DOC_GAP
-    section: "{section PRD/BDD chứa vấn đề}"
-    uc_id: "{UC-ID}"
-    quote: "{trích nguyên văn ≤120 ký tự từ spec tại đúng chỗ}"
-    finding: "{gap là gì}"
-    suggestion: "{cần PO/BA làm rõ điều gì}"
-    resolution_edge_cases: []     # để [] — phân tích bậc-hai là việc của /refine-prd
-    auto_fixable: false           # LUÔN false — xem cảnh báo dưới
-    status: "pending"
-    applied_via: ""
-    gap_ref: "GAP-xx"             # trỏ ngược về hàng trong DOC_GAP.md
-
-summary:
-  total_findings: {N}
-  by_severity: { critical: {N}, major: {N}, minor: {N} }
-  by_lens: { QA: {N} }
-  recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
-```
-
-> **`auto_fixable` LUÔN `false`, và KHÔNG có `--resume` cho file này.**
->
-> Review Board có nút *"chấp nhận rồi tự sửa PRD"*. Với gap của `/refine-prd` thì đúng — nó chạy
-> ở **thời điểm PRD**, sửa PRD lúc đó là sửa đúng chỗ đúng lúc.
->
-> Gap của lệnh này phát hiện **sau khi code đã xong**. Tự sửa PRD ở thời điểm đó là **sửa sau lưng
-> cả dây chuyền**: BDD sinh từ PRD cũ, code sinh từ BDD đó, sổ kết quả kiểm thử neo vào scenario
-> của BDD đó. Đổi PRD mà không đi lại đường ấy thì mọi thứ phía sau nói dối.
->
-> Đường đúng vẫn là kênh đã có: `/report-bug` cho defect spec thật, `/propose-scenario` cho thiếu
-> độ phủ. File `.yaml` này để **PO đọc và quyết trong một chỗ quen**, không phải để máy tự áp.
-
-**File riêng, không ghi chung với `/refine-prd`.** Tên có `{UC-ID}` nên không đụng
-`{prd-slug}-findings.yaml`. Ghi chung sẽ phá trường `applied_to_version` mà `/refine-prd` dùng để
-phân biệt *"PRD đổi do chính tôi áp fix"* với *"có người lạ sửa"* — và nó sẽ mãi mãi tưởng có
-người sửa sau lưng, mỗi lần chạy đều quét lại toàn bộ kèm cảnh báo giả.
-
----
-
 ## Report
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
 Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
-/qc-analyze Hoàn tất — {UC-ID} ({active_platform})
-Files : {paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAP.md (10 cột)
-        {paths.refinement_dir}/{UC-ID}-qa-findings.yaml    ← mở bằng Review Board (chuột phải)
-Nguồn : PRD · BDD({active_platform}) · design-spec · tech-doc{nếu thiếu tech-doc: " (THIẾU — không đối chiếu được nghiệp vụ ↔ kỹ thuật)"}
-Quét  : 4 kỹ năng phân tích + 4 lăng kính (xử lý lỗi · giao diện · dữ liệu & cấu hình
-        · đối chiếu chéo: PRD↔design-spec, bdd↔design-spec)
-Verify: {raw} gap thô → {N} còn Open  (❌ {invalid} bịa/đã-trả-lời · ⚠️ {reclass} không phải gap nghiệp vụ · 🔁 {merge} trùng)
-Gaps  : {N} ({blockers} blocker)   ← blocker là spec-defect? → /report-bug {UC-ID}  | coverage gap → /propose-scenario {UC-ID}
-Chờ chốt: {G} ẩn số §12 tech-doc đang open chạm UC này (đã ghi vào REQUIREMENT_ANALYSIS, KHÔNG hỏi lại PO)
-SC map: {M} BR/AC map tới {K} scenario
-Next  : /qc-plan {UC-ID} {active_platform}   ← rủi ro / what-if / câu hỏi cho dev
-        (giải quyết các gap 🔴 Blocker với PO/Dev trước)
+/qc-analyze Hoàn tất — {UC-ID}
+Files: {paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAPS.md   (2 files)
+Gaps: {N} ({blockers} blocker)   ← blocker là spec-defect? → /report-bug {UC-ID}  | coverage gap → /propose-scenario {UC-ID}
+SC mapping: {M} BR/AC map tới {K} scenario
+Next: /qc-plan {UC-ID}   ← risk / what-if / questions-for-dev
+      (giải quyết các gap 🔴 Blocker với PO/Dev trước)
 ```
-
-> **Dòng `Next` là bắt buộc in, không phải trang trí.** Dây gốc của đội QC ra **cả** file gap
-> **và** kế hoạch test trong một lần chạy (13/14 lần đo được ở repo của họ). Ở framework đó là
-> **hai lệnh**. Người quen dây cũ sẽ dừng lại ở đây và tưởng đã xong — dòng này là chỗ duy nhất
-> nói cho họ biết còn một bước nữa.
-

package/core/commands/qc-design-test.md

@@ -162,7 +162,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
 
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. **Phân giải `active_platform`** (QC pass khoá 1 platform): nếu `$ARGUMENTS` nêu platform → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi. Đọc output của qc-analyze + qc-plan (`REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`) từ `{paths.qc_dir}/{UC-ID}/{active_platform}/` và file `.feature` của đúng platform đó (với `@trace.scenario` mỗi scenario). Với layer GUI, cũng đọc bảng **Test Selectors** §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này**) — các test-id ổn định mà QC sẽ định vị theo.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. **Phân giải `active_platform`** (QC pass khoá 1 platform): nếu `$ARGUMENTS` nêu platform → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi. Đọc output của qc-analyze + qc-plan (`REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md`, `TEST_PLAN.md`) từ `{paths.qc_dir}/{UC-ID}/{active_platform}/` và file `.feature` của đúng platform đó (với `@trace.scenario` mỗi scenario). Với layer GUI, cũng đọc bảng **Test Selectors** §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này**) — các test-id ổn định mà QC sẽ định vị theo.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,

package/core/commands/qc-plan.md

@@ -162,7 +162,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
 
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. **Phân giải `active_platform`** (QC pass khoá 1 platform — artifact dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`): nếu `$ARGUMENTS` nêu platform (web/app/system) → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi platform nào. Đọc output của qc-analyze (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) từ `{paths.qc_dir}/{UC-ID}/{active_platform}/` và file `.feature` của đúng platform đó.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. **Phân giải `active_platform`** (QC pass khoá 1 platform — artifact dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`): nếu `$ARGUMENTS` nêu platform (web/app/system) → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi platform nào. Đọc output của qc-analyze (`REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`) từ `{paths.qc_dir}/{UC-ID}/{active_platform}/` và file `.feature` của đúng platform đó.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -183,12 +183,9 @@ thiết kế test case cụ thể (đó là qc-design-test).
 
 ## Skills (`{paths.qc_skills_dir}/qa-planner/`)
 
-- `test-plan.md` — khung plan: scope theo từng test layer (functional / integration /
-  e2e / non-functional), what-if, entry/exit criteria, và danh sách questions-for-dev
-  suy ra từ `DOC_GAP.md`.
-- `risk-model.md` — **cách tính** mức rủi ro: 7 nguồn rủi ro · khả năng × thiệt hại → P0–P3 ·
-  và dùng mức đó chia **độ sâu** test. `test-plan.md` có khung bảng `§6`; file này là cách điền.
-  Nạp cùng lúc, không phải thay thế.
+- `test-plan.md` — tự đủ: risk matrix, what-if, scope theo từng test layer
+  (functional / integration / e2e / non-functional), entry/exit criteria, và
+  danh sách questions-for-dev suy ra từ `DOC_GAPS.md`.
 
 ## Output
 

package/core/commands/qc-run-test.md

@@ -225,7 +225,7 @@ Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_di
 | `qc_status` | Đọc cột `status` của row **TRƯỚC** — xem §Guard ngay dưới bảng. Row `OK`/`GAP`/`UNTRACKED`: `pass` nếu mọi QC test của SC này pass · `fail` nếu có cái fail · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó. Row **`DRIFT`/`ORPHANED`**: **không bao giờ ghi `pass`** — hạ về `not_run` |
 | `qc_run_at` | hôm nay `YYYY-MM-DD` |
 | `last_updated` | hôm nay `YYYY-MM-DD` |
-| `qc_owner` | **SC đang chờ ai** (view "pending" của PM/PO): `dev` nếu FAIL = product-gap (defect thật → dev fix) · `po` nếu `skip`/`not_run` vì một **`DOC_GAP` 🔴 Blocker đang open** chặn test (PO phải làm rõ PRD/BDD) · `—` nếu `pass`, hoặc FAIL = script-bug (QC tự fix — tạm thời) |
+| `qc_owner` | **SC đang chờ ai** (view "pending" của PM/PO): `dev` nếu FAIL = product-gap (defect thật → dev fix) · `po` nếu `skip`/`not_run` vì một **`DOC_GAPS` 🔴 Blocker đang open** chặn test (PO phải làm rõ PRD/BDD) · `—` nếu `pass`, hoặc FAIL = script-bug (QC tự fix — tạm thời) |
 | `qc_blocked_by` | artifact liên kết: `GAP-{id}` khi bị chặn bởi spec gap (set ở đây) · `BUG-{id}` khi `/report-bug` đã được file cho product-gap (backfill bởi `/report-bug`) · `—` ngược lại |
 
 Set `qc_owner`/`qc_blocked_by` cùng với `qc_status`. Khi `pass`, **clear** cả hai về `—` — nhưng **PHẢI chạy §Đóng bug đã verify bên dưới TRƯỚC**, vì `qc_blocked_by` chính là con trỏ tới bug và clear xong là mất đường về.

package/core/commands/refine-prd.md

@@ -1,4 +1,4 @@
-# /refine-prd — Phân tích PRD qua 4 lăng kính review
+# /refine-prd — Phân tích PRD qua 3 lăng kính review
 
 > **Ranh giới — lệnh này chỉ áp được fix cho vấn đề mà CHÍNH NÓ tìm ra.** Resume Mode Phase 2 tự
 > cấm đụng bất kỳ section nào không được một finding chấp nhận trỏ tới, và findings sinh từ việc soi
@@ -259,11 +259,10 @@ vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
 Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
-  (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check; `/qc-analyze` → 3 lăng kính quét gap).
+  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
 - **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
 - **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
-- **VERIFY** *(tuỳ chọn, mặc định `off`)* — `on` chèn **Phase 2.5** (`steps/gap-verify.md`) giữa critic và dedup: mỗi finding phải mở lại tài liệu nguồn tự chứng minh trước khi được giữ. Không truyền → hành vi không đổi.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -382,31 +381,6 @@ Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
 
 ---
 
-## Phase 2.5 — Thẩm định *(chỉ chạy khi `VERIFY = on`)*
-
-**Vì sao có bước này.** Phase 1 và Phase 2 chỉ có **một chiều lực**: fan-out mở rộng bề
-ngang, critic lặp cho tới khi không còn gì mới — cả hai đều hỏi *"còn thiếu gì nữa?"*.
-Không có gì hỏi ngược lại *"cái vừa tìm ra có thật không?"*. Nên quy trình này đẩy **recall**
-lên mà **không có gì kéo precision lại**, và càng lặp critic thì tỉ lệ finding bịa càng cao —
-đúng thứ nó tự sinh ra: khẳng định hành vi tài liệu không nêu, trích evidence sai, hoặc gắn
-nhãn vấn đề cho thứ thực ra là chuyện làm-kỹ-hơn.
-
-Chạy `steps/gap-verify.md` trên `ALL_FINDINGS` với:
-- `FINDINGS` = `ALL_FINDINGS` (sau Phase 2)
-- `EVIDENCE_ROOT` = `{paths.specs_dir}` — hoặc giá trị lệnh gọi chỉ định
-- `VERDICT_FIELD` = trường trạng thái của FINDINGS SCHEMA mà lệnh định nghĩa
-- `RERATE` = `on`
-
-Finding bị `❌ INVALID` / `⚠️ RECLASSIFY` / `🔁 MERGE` **không đi tiếp sang Phase 3** — nhưng
-**KHÔNG bị xoá**: chúng vào file findings với trạng thái đóng + lý do, để người đọc kiểm chứng
-được vì sao chúng bị loại. Ghi lại số liệu verdict cho report.
-
-> **Chạy TRƯỚC Phase 3, không phải sau.** Dedup và giải quyết xung đột là việc tốn suy luận;
-> làm nó trên một tập còn lẫn finding bịa là vừa phí, vừa nguy hiểm — một finding ảo có thể
-> "thắng" một finding thật ở bước giữ-cái-severity-cao-hơn.
-
----
-
 ## Phase 3 — Dedup, giải quyết xung đột, merge
 
 Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ
@@ -438,7 +412,7 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
 
 ---
 
-## Phân tích — 4 lăng kính (fan out cả bốn, rồi hội tụ)
+## Phân tích — 3 lăng kính (fan out cả ba, rồi hội tụ)
 
 Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
 
@@ -457,23 +431,22 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
        - **`applied_to_version` có mặt VÀ `==` version PRD hiện tại** → PRD đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
        - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → PRD đã bị sửa bởi **actor khác** (lệnh `/review-context`, sửa tay…) sau lần resume này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"PRD đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
 
-**DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
+**DIMENSIONS** = 3 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
 toàn bộ PRD qua đúng lăng kính của nó:
 
-- **Lăng kính QA (tầng nghiệm thu)** *(bật lại 2026-08-25 — xem `docs/plans/qc-implementation-log.md` B8)*: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
+<!-- ─────────────────────────────────────────────────────────────────────────────
+  LĂNG KÍNH BỊ TẮT (DISABLED — KHÔNG dùng, KHÔNG fan-out agent cho lăng kính này):
 
-> **Phạm vi lăng kính QA — hẹp có chủ ý, đừng nới.** Nó hỏi về **HÌNH THỨC** của AC (*"phát biểu này kiểm chứng được không?"* · *"có lặp tầng không?"*), **KHÔNG** về **NỘI DUNG** (*"còn thiếu gì?"*).
->
-> Lý do là thời điểm: ở đây **chỉ có PRD** — design-spec, BDD, tech-doc đều chưa tồn tại. Nên không thể phân biệt *"PRD thiếu X"* với *"PRD cố ý để X cho design-spec"*, và phép kiểm *"đã trả lời ở tài liệu khác chưa?"* **không có tài liệu khác để tra**.
->
-> Số liệu thật (14 lần chạy ở repo QC): review chỉ-đọc-PRD ra **14 gap** trung bình, review đủ 4 nguồn ra **9,4** — khoảng 5 gap chênh lệch là câu hỏi mà tài liệu sau **trả lời hộ**. Nới lăng kính này sang câu hỏi nội dung là cố tình sinh ra 5 gap đó rồi gửi PO.
->
-> Câu hỏi nội dung thuộc `/qc-analyze` (3 lăng kính: xử lý lỗi · giao diện · dữ liệu & cấu hình), nơi đã có đủ 4 nguồn để tra.
->
-> **CÁCH TẮT LẠI QA** *(nếu cần)*: gỡ bullet QA ở trên · đổi `4 lăng kính`/`cả bốn` → `3`/`cả ba` ở
-> dòng tiêu đề, heading `## Phân tích`, câu `DIMENSIONS = N lăng kính`, và `steps/review-fanout.md` ·
-> gỡ `QA` khỏi enum `lens:` + `by_lens` + ghi chú `phán đoán QA/DEV/SA/PO` · sửa
-> `docs/explain/03-refine-prd.md` cho khớp · rebuild `node bin/build.js`.
+  - **Lăng kính QA (tầng nghiệm thu)**: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
+
+  CÁCH THÊM LẠI QA (khi cần bật lại giai đoạn sau):
+    1. Chuyển bullet QA ở trên ra khỏi block comment này, đặt lên đầu danh sách DIMENSIONS.
+    2. Đổi "3 lăng kính"/"cả ba" → "4 lăng kính"/"cả bốn" ở: dòng tiêu đề (# /refine-prd),
+       heading "## Phân tích", câu "DIMENSIONS = N lăng kính", và steps/review-fanout.md.
+    3. Thêm "QA" lại vào enum của `lens:` trong FINDINGS SCHEMA + vào `by_lens`.
+    4. Thêm "QA" lại vào ghi chú "phán đoán DEV/SA/PO" ở LƯU Ý của schema.
+    5. Rebuild: node bin/build.js
+───────────────────────────────────────────────────────────────────────────── -->
 
 > **Nguyên tắc chung cho DEV & SA — đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ.**
 > Hai lăng kính này dùng con mắt kỹ thuật để **phát hiện chỗ nghiệp vụ mô tả thiếu/mơ hồ/mâu thuẫn đến mức sẽ chặn triển khai** — mục tiêu là **làm rõ vấn đề nghiệp vụ để sau này xử lý được về mặt kỹ thuật**. **KHÔNG** đưa góc nhìn kỹ thuật vào PRD, **KHÔNG** đề xuất giải pháp/cơ chế kỹ thuật. Mọi `finding` và `suggestion` phải **thuần nghiệp vụ** (tuân Business Language Guard): mô tả *cái nghiệp vụ còn thiếu/chưa rõ* và *hỏi cần làm rõ gì*, chứ không nói *làm thế nào về kỹ thuật*.
@@ -510,7 +483,7 @@ status: "pending_review"
 
 findings:
   - id: "F001"
-    lens: "DEV"          # QA | DEV | SA | PO
+    lens: "DEV"          # DEV | SA | PO
     severity: "major"    # critical | major | minor
     section: "§2. Acceptance Criteria"   # nhãn heading/section dạng người đọc
     uc_id: "{TICKET-ID}-UC{N}"           # UC mà finding thuộc về; "" nếu PRD-global (scope, metrics, problem statement)
@@ -526,8 +499,8 @@ findings:
     # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
     # false = cần human đọc kỹ và ghi quyết định trước khi accept
     # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
-    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 4 lăng kính
-    #   là phán đoán QA/DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
+    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 3 lăng kính
+    #   là phán đoán DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
     #   quick-accept cho Board, KHÔNG để máy tự áp.
     status: "pending"
     applied_via: ""
@@ -543,7 +516,7 @@ findings:
 summary:
   total_findings: {N}
   by_severity: { critical: {N}, major: {N}, minor: {N} }
-  by_lens: { QA: {N}, DEV: {N}, SA: {N}, PO: {N} }
+  by_lens: { DEV: {N}, SA: {N}, PO: {N} }
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
   # Rule: critical ≥ 1                       → BLOCKED
   #       critical = 0, major ≥ 1            → NEEDS_REVISION

package/core/commands/report-bug.md

@@ -1,7 +1,7 @@
 # /report-bug — File một Bug có trace-spec (cho Tester & QC)
 
 Dành cho **tester và QC** — gồm cả **product-gap** lòi ra từ pipeline `/qc-*`
-(`/qc-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAP` từ
+(`/qc-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAPS` từ
 `/qc-analyze`). Sinh một bug report có cấu trúc với đầy đủ spec context, phân loại layer
 khả nghi, và lưu lại để handoff cho team dev.
 

package/core/commands/review-context.md

@@ -267,11 +267,10 @@ vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
 Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
-  (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check; `/qc-analyze` → 3 lăng kính quét gap).
+  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
 - **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
 - **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
-- **VERIFY** *(tuỳ chọn, mặc định `off`)* — `on` chèn **Phase 2.5** (`steps/gap-verify.md`) giữa critic và dedup: mỗi finding phải mở lại tài liệu nguồn tự chứng minh trước khi được giữ. Không truyền → hành vi không đổi.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -390,31 +389,6 @@ Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
 
 ---
 
-## Phase 2.5 — Thẩm định *(chỉ chạy khi `VERIFY = on`)*
-
-**Vì sao có bước này.** Phase 1 và Phase 2 chỉ có **một chiều lực**: fan-out mở rộng bề
-ngang, critic lặp cho tới khi không còn gì mới — cả hai đều hỏi *"còn thiếu gì nữa?"*.
-Không có gì hỏi ngược lại *"cái vừa tìm ra có thật không?"*. Nên quy trình này đẩy **recall**
-lên mà **không có gì kéo precision lại**, và càng lặp critic thì tỉ lệ finding bịa càng cao —
-đúng thứ nó tự sinh ra: khẳng định hành vi tài liệu không nêu, trích evidence sai, hoặc gắn
-nhãn vấn đề cho thứ thực ra là chuyện làm-kỹ-hơn.
-
-Chạy `steps/gap-verify.md` trên `ALL_FINDINGS` với:
-- `FINDINGS` = `ALL_FINDINGS` (sau Phase 2)
-- `EVIDENCE_ROOT` = `{paths.specs_dir}` — hoặc giá trị lệnh gọi chỉ định
-- `VERDICT_FIELD` = trường trạng thái của FINDINGS SCHEMA mà lệnh định nghĩa
-- `RERATE` = `on`
-
-Finding bị `❌ INVALID` / `⚠️ RECLASSIFY` / `🔁 MERGE` **không đi tiếp sang Phase 3** — nhưng
-**KHÔNG bị xoá**: chúng vào file findings với trạng thái đóng + lý do, để người đọc kiểm chứng
-được vì sao chúng bị loại. Ghi lại số liệu verdict cho report.
-
-> **Chạy TRƯỚC Phase 3, không phải sau.** Dedup và giải quyết xung đột là việc tốn suy luận;
-> làm nó trên một tập còn lẫn finding bịa là vừa phí, vừa nguy hiểm — một finding ảo có thể
-> "thắng" một finding thật ở bước giữ-cái-severity-cao-hơn.
-
----
-
 ## Phase 3 — Dedup, giải quyết xung đột, merge
 
 Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ