@educa-corp/sdd-framework 0.9.1 → 0.9.3

package/core/steps/gap-verify.md

@@ -0,0 +1,231 @@
+# Gap Verify — cổng thẩm định độc lập, chống finding bịa
+
+**Vì sao có cái này:** `steps/review-fanout.md` chỉ có một chiều lực — vòng
+completeness-critic ở Phase 2 luôn hỏi *"còn thiếu gì nữa?"*, nên nó đẩy **recall** lên
+và **không có gì kéo precision lại**. Fan-out càng rộng, critic càng lặp, thì finding bịa
+càng nhiều: khẳng định hành vi spec không nêu, trích evidence sai, hoặc gắn nhãn "gap"
+cho thứ thực ra là chuyện làm-kỹ-test.
+
+Bước này là nửa còn thiếu đó. Nó **mở lại tài liệu nguồn** và bắt mỗi finding tự chứng minh
+trước khi được giữ.
+
+> **Nguyên tắc tối thượng:** một finding chỉ hợp lệ khi có **ĐỦ 2 vế** —
+> **(1)** spec nguồn nêu hoặc ngụ ý hành vi X, **VÀ** **(2)** không tài liệu nào trong nguồn
+> trả lời/phủ X. Thiếu một trong hai → **không phải finding**.
+
+> ⚠️ **Cấm dùng chính trường evidence/quote của finding làm bằng chứng.** Phải mở file nguồn
+> và đọc lại đoạn được trích — evidence có thể bị diễn giải sai hoặc bịa. Đây là toàn bộ lý do
+> bước này tồn tại; bỏ qua nó thì bước này chỉ là một vòng critic nữa.
+
+*Ported từ `ui-automation-testing` — `skills/qa-tc-analyst/gap-verifier.md`.*
+
+---
+
+## Tham số lệnh gọi truyền vào
+
+| Tham số | Bắt buộc | Nghĩa |
+|---|:---:|---|
+| `FINDINGS` | ✅ | Tập finding cần thẩm định. Chỉ xét cái đang ở trạng thái mở (`Open` / `pending`); bỏ qua cái đã đóng trừ khi được yêu cầu soát lại. |
+| `EVIDENCE_ROOT` | ✅ | Nơi chứa **sự thật gốc** — mặc định `{paths.specs_dir}` (spec submodule của PO). Verifier chỉ được lấy căn cứ từ đây. |
+| `VERDICT_FIELD` | ✅ | Ghi kết quả vào đâu. `/qc-analyze` → cột `Trạng thái` + `Câu trả lời` của bảng gap; `/refine-prd` · `/review-context` → `status` + `suggestion` của findings YAML. |
+| `RERATE` | | `on` (mặc định) chạy GIAI ĐOẠN 1B — hiệu chỉnh mức độ. `off` bỏ qua, chỉ giữ/bỏ. |
+
+> **Bỏ qua ở chế độ sub-agent:** nếu Gate Bước 0 đã set `_agent_mode: true`, orchestrator
+> chịu trách nhiệm gọi bước này một lần trên tập finding đã hợp nhất — sub-agent **không**
+> tự verify phần của mình (verify từng mảnh rời không thấy được T6 trùng lặp).
+
+---
+
+## RÀNG BUỘC NGUỒN
+
+- **Chỉ `EVIDENCE_ROOT`** làm căn cứ. **KHÔNG** dùng artifact nội bộ do chính pipeline sinh ra
+  (`{paths.qc_dir}/**`, `{paths.refinement_dir}/**`, test-case, report) — đó là vòng lặp:
+  lấy kết luận của mình làm bằng chứng cho mình.
+- **Bỏ qua** — không đọc, không trích làm căn cứ — các section **Change Log**, **Appendix**,
+  và **Giả định AI / AI Assumptions** trong mọi tài liệu. Căn cứ chỉ lấy từ **thân bài**
+  (AC · BR · UC · Wireframe · Screen Spec · Scenario).
+  *Change log là "delta narrative", phải re-ground về thân bài; Appendix và Giả định AI là
+  ghi chú nháp, không phải nguồn chân lý.*
+- Đọc **cả tài liệu gốc cấp trên** (`{paths.product_definitions_dir}/`) và **tài liệu liên quan**
+  (`{paths.business_dictionary}`, `{paths.core_entities}`) — một finding có thể đã được trả lời
+  ở tài liệu khác, không riêng spec đang xét.
+
+---
+
+## 5 anti-pattern — nhận diện trước khi kết luận
+
+| # | Anti-pattern | Dấu hiệu |
+|---|---|---|
+| **AP1** | Phạm vi tích hợp lẫn vào spec nghiệp vụ | Finding nói về API contract, queue, service-to-service, retry backend, webhook — thứ PRD đã khai "ngoài phạm vi" |
+| **AP2** | Rule cha bị tính là thiếu ở con | *"PRD con không mô tả X"* mà X đã có trong `{paths.product_definitions_dir}/` — PRD con **kế thừa** cha theo thiết kế |
+| **AP3** | Finding UI tạo ra mà chưa đọc design-spec | *"thiếu behavior/navigation/state X"* mà X được mô tả rõ trong design-spec §Actions / §Screen States |
+| **AP4** | Bias "nhiều finding = làm kỹ" | Cố sinh nhiều để thể hiện thoroughness. **5 finding thật tốt hơn 22 finding với 20 cái ảo.** Không cần điền đủ K nếu thực tế chỉ có M < K |
+| **AP5** | Trích từ nguồn cấm | Evidence tham chiếu §Giả định AI / AI Assumptions / Change Log |
+| **AP6** | Nâng note thứ cấp thành finding | Một ghi chú *"nghi X lệch"* trong BDD/design-spec là **claim cần verify, KHÔNG phải bằng chứng**. Chưa mở nguồn sơ cấp (PRD·BR·contract·Figma) thì chưa được raise. Không mở được asset → ghi *"chưa verify — cần Designer xác nhận"*, KHÔNG khẳng định *"asset đang sai"* |
+
+---
+
+## 3 câu hỏi lọc bắt buộc
+
+Mỗi finding phải vượt **cả ba**. Rớt bất kỳ câu nào → loại.
+
+| Câu | Giữ khi | Rớt thì |
+|---|---|---|
+| **Q1** — *"X đã được spec ở design-spec / product-definition / tech-docs chưa?"* | **Chưa** — tìm khắp `EVIDENCE_ROOT` không thấy | `❌ INVALID — spec đã trả lời` |
+| **Q2** — *"X có thuộc phạm vi spec này không?"* | **Có** — spec này đặc tả hành vi X | `❌ INVALID — ngoài phạm vi` |
+| **Q3** — *"Người thực thi tự quyết được không cần PO/BA confirm?"* | **Không** — bắt buộc cần PO/BA chốt | `⚠️ RECLASSIFY` (xem T5d/T5e) |
+
+> **Q3 là câu bảo vệ thời gian của PO.** Mọi thứ QC/dev tự quyết được mà vẫn đẩy lên PO
+> đều là chi phí thuần — và tệ hơn, nó làm loãng những câu thật.
+
+---
+
+## GIAI ĐOẠN 1 — T1…T6 cho từng finding
+
+Chạy tuần tự. Rớt bất kỳ test nào → không hợp lệ, ghi verdict tương ứng.
+
+### T1 — Evidence có thật & đúng nội dung *(chống bịa trích dẫn)*
+Mở đúng file/section mà finding trích. Tìm đoạn nguyên văn.
+- **FAIL nếu:** trích dẫn không tồn tại · bị diễn giải sai lệch nghĩa · hoặc đoạn trích
+  **không thực sự nói điều finding khẳng định**.
+- **FAIL nếu evidence trích từ Change Log / Appendix / Giả định AI** — nguồn cấm.
+  Phải re-ground về thân AC/BR/UC/Wireframe; thân bài không nói điều đó → finding sai.
+- → `❌ INVALID — evidence bịa/sai/nguồn-cấm`
+
+### T2 — Hành vi "thiếu" đúng là yêu cầu của spec *(chống bịa yêu cầu)*
+Với finding MISSING/AMBIGUOUS: spec nguồn **có thật sự nêu hoặc ngụ ý** hành vi X không?
+- **FAIL nếu:** X **không được tài liệu nào yêu cầu** — finding tự nghĩ ra một yêu cầu
+  rồi than spec không mô tả nó.
+- → `❌ INVALID — yêu cầu tự bịa`
+
+### T3 — Chưa được trả lời ở nơi khác *(chống finding đã cover)*
+Tìm khắp `EVIDENCE_ROOT` (gồm tài liệu gốc + liên quan) xem câu hỏi đã có lời đáp chưa —
+kể cả **trả lời ngầm định** bằng cách diễn đạt điều kiện.
+- → `❌ INVALID — spec đã trả lời` *(kèm trích nguồn trả lời)*
+
+### T3b — Mâu thuẫn thật hay chỉ khác UC/pha *(chỉ áp cho finding CONTRADICTORY)*
+Xác định **UC + pha** của TỪNG rule (chuẩn bị / thực hiện / nộp / công bố / quay lại).
+- **FAIL nếu:** hai rule thuộc **UC/pha khác nhau** → thường là ngữ cảnh **tuần tự** hoặc
+  **không giao nhau**, không phải mâu thuẫn tại cùng một thời điểm quyết định.
+- → `❌ INVALID — khác UC/pha, không mâu thuẫn`
+
+### T4 — Kế thừa tài liệu gốc *(chống "con không lặp lại cha")*
+Rule đã định nghĩa trong `{paths.product_definitions_dir}/` thì việc spec con không lặp lại
+**không phải finding**.
+- → `❌ INVALID — đã có ở tài liệu gốc`
+
+### T5 — Đúng loại *(chống phân loại nhầm)*
+
+> ⚠️ **BẮT BUỘC xác định HƯỚNG trước khi gán loại** (tài liệu dẫn xuất so với PRD):
+> - **THIẾU (dẫn xuất < PRD):** PRD yêu cầu màn/rule mà design/BDD KHÔNG có → `MISSING`.
+>   Xử lý = bổ sung vào tài liệu dẫn xuất.
+> - **THỪA (dẫn xuất > PRD):** design/BDD **tự thêm** hành vi PRD không sanction →
+>   `CONTRADICTORY`, **KHÔNG dùng `MISSING`**. Xử lý = PO chốt giữ (định nghĩa hệ quả vào PRD)
+>   hay gỡ.
+>
+> Sai hướng = framing sai — gọi *"design thiếu"* trong khi design **thừa**.
+
+| Nhóm | Nghĩa | Verdict |
+|---|---|---|
+| **(a)** Finding nghiệp vụ thật | spec nêu hành vi, không tài liệu nào phủ | `✅ VALID` — giữ mở |
+| **(b)** Lệch đồng bộ (SYNC) | PRD đã cập nhật nhưng design-spec / BDD chưa phản ánh nội dung mới | `✅ VALID — SYNC` — **giữ mở**, mức Low–Medium, giao đội spec. KHÔNG đóng: cần track để cập nhật |
+| **(c)** Metadata lệch | chênh version header, sai tên trace, format — **nội dung nghiệp vụ vẫn đúng** | `⚠️ RECLASSIFY — metadata` |
+| **(d)** Làm-kỹ-test | thêm giá trị biên, liệt kê đủ ô decision table, biến thể dữ liệu — mà **rule/behavior đã được phủ** | `⚠️ RECLASSIFY — làm-kỹ-test` |
+| **(e)** Tech/UX tự quyết | số lần retry, timeout/delay, loading spinner, animation, exact-copy nút/label, xử lý crash, cơ chế lưu session — thuộc Dev/Design, không phải PO/BA | `⚠️ RECLASSIFY — tech/UX tự quyết` |
+
+> **Ranh giới SYNC vs metadata:** SYNC = *nội dung* PRD mới chưa được phản ánh vào tài liệu
+> dẫn xuất (section còn thiếu). Metadata = chỉ số version lệch, nội dung đã đúng.
+>
+> **Ranh giới (c)(d) vs (a):** nếu **bản thân hành vi/rule đã có scenario hoặc mô tả phủ**,
+> mọi đề xuất *"thêm ca biên / thêm giá trị / đủ ô bảng"* đều là (d), KHÔNG phải finding.
+>
+> **Ngoại lệ GIỮ ở (e):** *ý chính / khung thông điệp* của popup do PO chốt intent;
+> và mọi ranh giới pháp lý / privacy.
+
+### T6 — Không trùng lặp *(chống double-count)*
+So với các finding còn lại: cùng root cause → merge, giữ một, ghi rõ *"merge từ …"*.
+- → `🔁 MERGE → {id}`
+
+**Qua sạch T1–T6 (+T3b nếu CONTRADICTORY) → `✅ VALID`.**
+
+---
+
+## GIAI ĐOẠN 1B — Hiệu chỉnh mức độ *(chạy khi `RERATE=on`)*
+
+T1–T6 quyết định finding **còn hay bỏ**; giai đoạn này quyết định cái còn lại **nặng hay nhẹ**.
+Nhiều finding hợp lệ về mặt tồn tại nhưng **bị gán mức quá cao** — và một danh sách toàn
+🔴 Critical thì không xếp được ưu tiên, tức mất luôn giá trị của cột mức độ.
+
+Với **mỗi** finding còn mở, hạ mức hoặc chuyển sang "ghi chú phạm vi" nếu rơi vào một trong
+năm nhóm sau — cả năm đều **không phải lỗ hổng của feature đang xét**:
+
+| # | Nhóm | Dấu hiệu | Xử lý |
+|---|---|---|---|
+| **R1** | Lệch pha với tài liệu gốc | Mâu thuẫn thật giữa PRD con (đã duyệt, version mới hơn) và product-definition / dictionary về cùng một quan sát | → **Low**, nhãn *"master-sync"*. Con chi phối ⇒ không ảnh hưởng test. Không chặn |
+| **R2** | Spec con tự rõ, chỉ nền domain lệch | PRD con phát biểu dứt khoát; chỉ dictionary/master mâu thuẫn | → **ghi chú phạm vi** (không phải finding của feature); đề nghị sync riêng nền domain |
+| **R3** | Nguồn tự đánh dấu "giả định" | Evidence là mục trong design-spec có cảnh báo ⚠️ *"là giả định, cần Designer bổ sung"* | → **ghi chú phạm vi**, không lập finding *(đồng nhất luật AP5)* |
+| **R4** | Nhánh phòng vệ bất-khả-đạt | Nhánh guard chỉ chạy trên dữ liệu **ngoài** enum hợp lệ; ca đạt tới được đã có phủ | → **Low**, nhãn *"test-design"* — vấn đề cách mô phỏng dữ liệu, không phải mơ hồ spec |
+| **R5** | Greenfield thiếu tech-doc | Thiếu openapi/tech-doc cho hành động lõi ở feature xây mới | → nhãn *"feasibility"* — chặn **tự-động-hoá**, KHÔNG phải khuyết tật nghiệp vụ ở tầng PRD |
+
+> **Mẹo chi phối:** một *pass-through rule* (hệ thống KHÔNG validate gì) làm tan phần lớn
+> "mơ hồ" vì không có bề mặt test → hạ mạnh. Ngược lại, drift mà **chính PRD tự flag**, hoặc
+> mơ hồ ở **luồng chính có giao diện**, là finding THẬT — giữ nguyên mức.
+
+**Cách ghi:** GIỮ mô tả gốc (audit trail), thêm mục *"Phản biện & Re-rating"* liệt kê lý do
+từng thay đổi mức, rồi cập nhật cột mức độ. Finding chuyển hẳn sang "ghi chú phạm vi" thì
+đánh dấu rõ — **KHÔNG xoá**.
+
+---
+
+## GIAI ĐOẠN 2 — Bảng thẩm định
+
+Xuất bảng verdict *(không chèn dòng trắng giữa các hàng — dòng trắng làm vỡ bảng Markdown)*:
+
+| ID | Verdict | Test rớt | Bằng chứng thẩm định (mở file nguồn) |
+|---|---|---|---|
+| … | `✅ VALID` / `❌ INVALID` / `⚠️ RECLASSIFY` / `🔁 MERGE` | T1..T6 / — | trích đúng dòng trong `EVIDENCE_ROOT` chứng minh verdict |
+
+**Số liệu tổng:** tổng verify = N · VALID = a · INVALID = b · RECLASSIFY = c · MERGE = d.
+
+---
+
+## GIAI ĐOẠN 3 — Áp verdict vào `VERDICT_FIELD`
+
+**KHÔNG XOÁ finding nào** — giữ audit trail. Đóng kèm lý do thì kiểm chứng được; xoá thì không.
+
+| Verdict | Áp thế nào |
+|---|---|
+| `✅ VALID` | giữ nguyên, trạng thái mở |
+| `✅ VALID — SYNC` | giữ mở, loại `SYNC`, mức Low–Medium, giao đội spec; phần trả lời để trống |
+| `❌ INVALID` | → **đóng**; ghi lý do ngắn + trích nguồn (vd *"Closed — spec đã trả lời tại §BR13: …"*) |
+| `⚠️ RECLASSIFY` | → **đóng**; ghi rõ *"Không phải finding nghiệp vụ — [metadata / làm-kỹ-test / tech-UX tự quyết]"* + đề xuất chuyển sang mục việc tương ứng |
+| `🔁 MERGE` | → **đóng**; ghi *"Trùng root cause với {id}"* |
+
+Sau khi áp:
+1. Cập nhật **tổng số** ở header + bảng **ưu tiên xử lý** — chỉ đếm cái còn mở.
+2. Kiểm format bảng Markdown: **không có dòng trắng giữa các hàng**.
+3. Nếu artifact có section liệt kê **tài liệu đã đọc**: verifier vừa mở trực tiếp nguồn nên
+   đối chiếu lại — file đã dùng làm evidence mà **thiếu** trong bảng, hoặc file liệt kê nhưng
+   không tồn tại → sửa cho khớp.
+
+---
+
+## Đầu ra + cam kết
+
+In tóm tắt:
+
+```
+[GAP VERIFY] {artifact} — verify {N} finding đang mở:
+  ✅ VALID: {a}  |  ❌ INVALID: {b}  |  ⚠️ RECLASSIFY: {c}  |  🔁 MERGE: {d}
+  INVALID chi tiết: {id} (evidence bịa), {id} (spec đã trả lời), …
+  Sau verify còn {a} finding nghiệp vụ đang mở.
+```
+
+**Cam kết cuối — bắt buộc in nguyên văn:**
+
+> *"Đã mở trực tiếp file nguồn trong `{EVIDENCE_ROOT}` để kiểm chứng từng finding — KHÔNG dựa
+> vào trường evidence của artifact. Mỗi finding còn mở đều có đủ 2 vế: spec nêu hành vi +
+> không tài liệu nào phủ. Không giữ lại finding bịa/sai sự thật."*
+
+Cam kết này **không phải nghi thức**: nó là chỗ duy nhất bước này tự khai đã làm đúng việc
+mà không ai kiểm được từ bên ngoài. Không in được cam kết ⇒ chưa chạy đúng bước.

package/core/steps/qc-scope.md

@@ -0,0 +1,119 @@
+# QC Scope — phân giải phạm vi cho mọi lệnh `qc-*`
+
+**Chạy TRƯỚC phần logic riêng của lệnh, và SAU `steps/gate.md`.** Bước này chốt bốn thứ mà
+cả 6 trạm QC đều cần, để chúng không tự suy mỗi trạm một kiểu:
+
+| Biến | Là gì |
+|---|---|
+| `TICKET-ID` | mã PRD — **thư mục artifact QC mang tên này** |
+| `active_platform` | `web` \| `app` \| `system` \| … — một QC pass khoá đúng MỘT nền |
+| `qc_artifact_dir` | `{paths.qc_dir}/{TICKET-ID}/{active_platform}/` |
+| `uc_list` | các UC của (PRD × nền) này, kèm trạng thái BDD từng UC |
+
+> **Vì sao gom về một chỗ.** Luật phân giải nền từng được copy-paste ở 5 lệnh và câu chữ đã
+> lệch nhau. Năm bản của một luật là nơi drift sống: sửa bốn, quên một, và trạm bị quên ghi
+> artifact vào sai thư mục **trong im lặng**.
+
+---
+
+## 1 — `TICKET-ID`
+
+Artifact QC gom theo **PRD**, không theo UC. Nên mọi trạm phải quy được về `TICKET-ID`:
+
+| `$ARGUMENTS` là | Cách lấy |
+|---|---|
+| **UC-ID** (`{TICKET-ID}-UC{N}`) | phần **trước** `-UC` — đúng luật `steps/gate.md` Bước 1 dùng để tìm tech-doc gộp |
+| **TICKET-ID** | dùng trực tiếp |
+| một **path file** (`.feature` / PRD / design-spec) | phân giải `{domain}` + `{prd-slug}` theo luật `context-loader` Bước 1, rồi lấy `TICKET-ID` từ tên file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder |
+
+Đối chiếu: `TICKET-ID` suy ra phải khớp tên file PRD thật. Lệch → **DỪNG**, in cả hai giá
+trị. (Suy sai `TICKET-ID` là ghi cả một PRD vào sai thư mục — không có bước nào phía sau bắt được.)
+
+---
+
+## 2 — `active_platform`
+
+> **PHẢI phân giải TRƯỚC mọi phép đọc `.feature`.** `{UC-ID}-SC{N}` chỉ độc nhất trong
+> (UC × nền), 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`. Đọc "file `.feature` của UC" khi chưa biết nền 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.
+
+Theo thứ tự, dừng ở cái đầu tiên khớp:
+
+1. `$ARGUMENTS` nêu nền (`web`/`app`/`system`/…) → dùng.
+2. Target 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 nền → dùng nó.
+4. Glob `{paths.qc_dir}/{TICKET-ID}/*/` — **đúng một** thư mục nền đã có artifact → dùng nó.
+   *(chỉ dùng cho trạm 2–6; trạm `/qc-analyze` là trạm tạo ra thư mục đó nên không có gì để soi.)*
+5. Nhiều nền mà không suy được → hỏi *"QC pass này cho nền 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 nền là ghi artifact vào sai
+   thư mục và ghi `qc_status` vào sai sổ trace:
+   ```
+   ❌ {TICKET-ID} có {n} nền ({list}) — không suy được nền nào cho QC pass này.
+      Chạy headless thì phải nêu tường minh: /{lệnh} {TICKET-ID} web --yes
+   ```
+
+Lưu `active_platform`. Từ đây, **mọi** phép đọc `.feature` chỉ đọc thư mục
+`bdd/{active_platform}/` — không trộn SC chéo nền.
+
+---
+
+## 3 — `qc_artifact_dir`
+
+```
+qc_artifact_dir = {paths.qc_dir}/{TICKET-ID}/{active_platform}/
+```
+
+Chứa: `REQUIREMENT_ANALYSIS.md` · `DOC_GAP.md` · `TEST_PLAN.md` · `test-cases/*.Test.md`
+— **mỗi loại đúng MỘT file cho cả PRD**, các UC là mục/hàng bên trong.
+
+`{paths.qc_dir}` là folder top-level **nhìn thấy** trong repo QC (mặc định `docs/`, **không**
+phải `.agent/` ẩn) để đội QC mở và xử lý output dễ dàng. Spec chính thức ở lại spec submodule
+của PO — đừng ghi artifact QC vào đó.
+
+> **Sổ trace KHÔNG theo layout này.** Nó vẫn là `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv`
+> — một sổ cho mỗi (UC × nền), vì mỗi hàng là một scenario. Liên kết giữa hai bên đi qua
+> **cột `UC`** của bảng gap, không qua đường dẫn file.
+
+---
+
+## 4 — `uc_list`
+
+Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/*.feature`. Mỗi file → một
+UC: đọc `# @trace.id` (mã UC) và `# @trace.status` từ header.
+
+Chia hai nhóm:
+
+| Nhóm | Điều kiện | Xử lý |
+|---|---|---|
+| **Trong phạm vi** | `@trace.status: approved` | phân tích / thiết kế / chạy bình thường |
+| **Chưa xét** | khác `approved` | **KHÔNG** phân tích; vẫn ghi một hàng vào bảng phạm vi kèm trạng thái thật |
+
+In bảng phạm vi ra trước khi làm gì:
+```
+Phạm vi QC — {TICKET-ID} / {active_platform}
+  ✅ {UC-ID}  {tên UC}                     approved
+  ⏸  {UC-ID}  {tên UC}                     draft   → chưa xét
+  → {n} UC trong phạm vi · {m} chưa xét
+```
+
+**Cờ `--include-draft`:** phân tích cả UC chưa duyệt, nhưng **vẫn in bảng trên** và đánh dấu
+trong artifact là dựa trên BDD nháp.
+
+**Không UC nào `approved` và không có `--include-draft` → DỪNG:**
+```
+❌ {TICKET-ID} ({active_platform}): 0/{n} UC có BDD approved — không có gì để chạy.
+   Cách đúng: người duyệt đặt `# @trace.status: approved` rồi chạy lại.
+   Muốn chạy sớm trên BDD nháp (prototype): thêm --include-draft
+```
+
+> **Vì sao có `--include-draft` chứ không chặn cứng.** QC sớm trên BDD nháp là một cách dùng
+> **cố ý được cho phép** từ trước (guard cũ là cảnh báo mềm, không phải chặn). Bỏ hẳn nó là
+> lấy đi một năng lực đang có mà không ai khai. Còn để mặc định `approved`-only thì cái
+> thường gặp là cái an toàn, và cái sớm phải nói ra.
+
+> **Vì sao `--yes` không thay được `--include-draft`.** `--yes` nghĩa *"tôi không ngồi đây để
+> trả lời"*; `--include-draft` nghĩa *"tôi biết BDD còn nháp và vẫn muốn chạy"*. Gộp hai cái
+> là để một lần chạy headless âm thầm phân tích spec chưa chốt rồi bàn giao như thể đã chốt.

package/core/steps/review-fanout.md

@@ -8,10 +8,11 @@ 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` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
+  (`/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).
 - **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
@@ -130,6 +131,31 @@ 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ờ

package/core/templates/project-context.yaml

@@ -63,14 +63,16 @@ paths:
   refinement_dir: ".agent/review"
 
   # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
-  # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md).
-  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # REQUIREMENT_ANALYSIS.md, DOC_GAP.md, TEST_PLAN.md, test-cases/*.Test.md).
+  # Grouped by PRD: {qc_dir}/{TICKET-ID}/{platform}/ — ONE DOC_GAP.md / TEST_PLAN.md /
+  # REQUIREMENT_ANALYSIS.md per (PRD x platform), with the UCs as rows/sections inside
+  # (see steps/qc-scope.md). Default "docs" (the QC team's own
   # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
   # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
   qc_dir: "docs"
 
   # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner
-  # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled
+  # / qa-reviewer / qa-runner + DOC_GAP.template.md). Default = the framework-bundled
   # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their
   # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g.
   # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten

package/docs/02-concepts/pipeline-steps/08-qc-automation.md

@@ -38,7 +38,7 @@
 
 | Artifact | Nội dung |
 |----------|----------|
-| `docs/{UC-ID}/…` | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md`, `TEST_PLAN.md`, `test-cases/*.Test.md` |
+| `docs/{TICKET-ID}/{platform}/…` | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`, `test-cases/*.Test.md` — **mỗi loại đúng một file cho cả (PRD × nền)**, các UC là hàng/mục bên trong (cột `UC`) |
 | Script Python pytest-playwright | Sinh từ `.Test.md` đã review |
 | Cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` | Trạng thái QC **chính thức** |
 | Evidence + report | `/qc-report` — kèm product-gap đẩy về PO/Dev |
@@ -70,7 +70,7 @@ Dây chuyền **6 trạm**, output trạm trước là input trạm sau:
 
 | # | Trạm | Việc |
 |---|------|------|
-| 1 | `/qc-analyze` | Phân rã yêu cầu + phát hiện **gap tài liệu** (`DOC_GAPS.md`) |
+| 1 | `/qc-analyze` | Phân rã yêu cầu + phát hiện **gap tài liệu** (`DOC_GAP.md`) |
 | 2 | `/qc-plan` | Đánh giá **rủi ro** + câu hỏi cho dev (`TEST_PLAN.md`) |
 | 3 | `/qc-design-test` | Thiết kế **test case** dạng Markdown (`*.Test.md`) |
 | 4 | `/qc-review` | 🛑 **Cổng review** hai chiều: test case & script trước khi chạy |

package/docs/04-reference/commands.md

@@ -89,7 +89,7 @@ Mọi lệnh chạy chung một **Gate** (model check → target → context-loa
 
 | Lệnh | Input | Output | Owner |
 |------|-------|--------|-------|
-| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
+| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md` | QA |
 | `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
 | `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
 | `/qc-review` | Test case/script | 🛑 Cổng review | QA |