@educa-corp/sdd-framework 0.9.0 → 0.9.2

package/core/skills/qc/qa-planner/test-plan.md

@@ -1,7 +1,9 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/test-plan.md
+upstream_sha: f259b4d123c565a42ba6c6ec96980a8e4c66284f
 ---
 
 # Lập Test Plan
@@ -10,15 +12,15 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
 
 **Đầu vào (bắt buộc, chỉ 2 nguồn — đúng 2 file qa-analyst trả ra):**
 1. `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md` — chức năng, BR-xx, AC-xx, data flow (qa-analyst).
-2. `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md` — bảng gap GAP-xx, mức độ, gap Blocker (qa-analyst).
+2. `{paths.qc_dir}/{UC-ID}/DOC_GAP.md` — bảng gap GAP-xx, mức độ, gap Blocker (qa-analyst).
 
 ## Khi nào trigger
 - "lập test plan cho [Feature]" / "viết test plan"
-- Sau khi qa-analyst xong (đã có REQUIREMENT_ANALYSIS + DOC_GAPS)
+- Sau khi qa-analyst xong (đã có REQUIREMENT_ANALYSIS + DOC_GAP)
 - Trước khi qa-designer thiết kế chi tiết TC — test plan là khung định hướng
 
 ## Khi KHÔNG trigger
-- Chưa có REQUIREMENT_ANALYSIS / DOC_GAPS → chạy qa-analyst trước
+- Chưa có REQUIREMENT_ANALYSIS / DOC_GAP → chạy qa-analyst trước
 - Thiết kế test case chi tiết (.Test.md) → dùng qa-designer
 - Bóc tách yêu cầu/spec, lập danh sách gap → dùng qa-analyst
 
@@ -28,7 +30,7 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
 
 1. Đọc `REQUIREMENT_ANALYSIS.md`: nắm chức năng, các BR-xx và AC-xx, data flow,
    integration/failure point.
-2. Đọc `DOC_GAPS.md`: lấy danh sách gap, đặc biệt **gap Blocker còn Open** → đây là
+2. Đọc `DOC_GAP.md`: lấy danh sách gap, đặc biệt **gap Blocker còn Open** → đây là
    nguồn cho cột "Phụ thuộc" và cho Entry criteria.
 3. Map mỗi nhóm BR sang **layer test** của qa-designer: functional/gui-screen,
    gui-feature, api, integration, e2e/journey, non-functional.
@@ -47,7 +49,8 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
   criteria yêu cầu đóng các gap đó trước khi thiết kế TC.
 - Liệt kê **E2E journey** đầy đủ (mỗi journey: tiền điều kiện, kết quả/định tuyến kỳ
   vọng, BR, phụ thuộc, priority) + bộ **verify point chung** sau submit.
-- Mục Rủi ro: rút trực tiếp từ gap Blocker + các BR logic phức tạp.
+- Mục Rủi ro: **nạp `risk-model.md`** — quét đủ 7 nguồn, chấm khả năng × thiệt hại → P0–P3,
+  rồi dùng mức đó chia độ sâu test. Đừng chấm thẳng ra P0/P1 theo cảm tính.
 
 ---
 
@@ -63,7 +66,7 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
 | Feature / Project / Module | … |
 | Người lập | qa-planner |
 | Ngày / Phiên bản | … |
-| Nguồn | REQUIREMENT_ANALYSIS · DOC_GAPS |
+| Nguồn | REQUIREMENT_ANALYSIS · DOC_GAP |
 
 ## 1. Mục tiêu
 Mục tiêu test của feature (1–3 câu).
@@ -95,12 +98,12 @@ Kỹ thuật áp dụng: EP+BVA, Decision Table (cho logic điều kiện), stat
 integration, negative/exploratory; tự động hoá theo `CLAUDE.md` (Playwright + pytest-playwright + Trace + pytest-html).
 
 ## 5. Tiêu chí Vào / Ra
-- **Entry:** gap Blocker (trong DOC_GAPS) đã Answered; doc phụ thuộc sẵn sàng; môi trường + tài khoản role.
+- **Entry:** gap Blocker (trong DOC_GAP) đã Answered; doc phụ thuộc sẵn sàng; môi trường + tài khoản role.
 - **Exit:** pass P0=100%, P1≥95%; không còn defect Blocker/Critical; mọi BR/AC được trace; báo cáo pytest-html + Playwright Trace.
 
 ## 6. Rủi ro (risk-based)
-| Rủi ro | Ảnh hưởng | Mức | Giảm thiểu |
-(rút từ gap Blocker + BR logic phức tạp)
+| Rủi ro | Nguồn | Khả năng | Thiệt hại | Mức | Giảm thiểu |
+(cách chấm mức + 7 nguồn rủi ro + cách dùng mức để chia độ sâu test: xem `risk-model.md`)
 
 ## 7. Dữ liệu & Môi trường
 Tài khoản các role, dữ liệu mẫu (biên/edge), môi trường staging.

package/core/skills/qc/qa-reviewer/script/e2e.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Script — E2E Journey

package/core/skills/qc/qa-reviewer/script/exploratory.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Session Note — Exploratory

package/core/skills/qc/qa-reviewer/script/functional.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Script — Functional

package/core/skills/qc/qa-reviewer/script/integration.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Script — Integration

package/core/skills/qc/qa-reviewer/script/non-functional.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Script — Non-Functional

package/core/skills/qc/qa-reviewer/test-case/e2e.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Case — E2E Journey

package/core/skills/qc/qa-reviewer/test-case/exploratory.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Charter — Exploratory

package/core/skills/qc/qa-reviewer/test-case/functional.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Case — Functional

package/core/skills/qc/qa-reviewer/test-case/integration.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Case — Integration
@@ -21,7 +21,7 @@ Review bộ TC tích hợp (GUI↔Backend, API, DB) và đánh giá chất lư
 ## Phase 1 — Clarify
 
 1. Đọc tất cả TC integration trong folder chỉ định; xác định loại: GUI↔Backend / API / DB
-2. Đọc REQUIREMENT_ANALYSIS + DOC_GAPS nếu có
+2. Đọc REQUIREMENT_ANALYSIS + DOC_GAP nếu có
 3. Xác định chuỗi tích hợp (caller → component → downstream)
 
 ---

package/core/skills/qc/qa-reviewer/test-case/non-functional.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Review Test Case — Non-Functional

package/core/skills/qc/qa-runner/e2e.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Gen Script — E2E Journey

package/core/skills/qc/qa-runner/exploratory/session.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Session Template & Convert Findings — Exploratory

package/core/skills/qc/qa-runner/functional/api.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Gen Script — Functional API

package/core/skills/qc/qa-runner/functional/gui-feature.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Gen Script — Functional GUI Feature (đa màn hình)

package/core/skills/qc/qa-runner/functional/gui-screen.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Gen Script — Functional GUI Screen (1 màn hình)

package/core/skills/qc/qa-runner/integration.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Gen Script — Integration

package/core/skills/qc/qa-runner/non-functional.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Gen Script — Non-Functional

package/core/skills/qc/qa-runner/report/report.md

@@ -1,7 +1,7 @@
 ---
 version: 1.1
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Report — Playwright Trace + pytest-html (stack chuẩn)

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/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,14 @@ 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).
+  # REQUIREMENT_ANALYSIS.md, DOC_GAP.md, TEST_PLAN.md, test-cases/*.Test.md).
   # One subfolder per UC: {qc_dir}/{UC-ID}/. 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/{UC-ID}/…` | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`, `test-cases/*.Test.md` |
 | 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 |

package/docs/explain/03-refine-prd.md

@@ -1,8 +1,8 @@
 [← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /review-context →](04-review-context.md)
 
-# 03 · `/refine-prd` — Tinh chỉnh PRD qua 3 lăng kính
+# 03 · `/refine-prd` — Tinh chỉnh PRD qua 4 lăng kính
 
-> **Một câu.** Fan-out review PRD qua **3 lăng kính DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
+> **Một câu.** Fan-out review PRD qua **4 lăng kính QA / DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
 
 ---
 
@@ -33,9 +33,10 @@ Một lượt review đơn không bao giờ liệt kê hết vấn đề — mod
 Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
 
 ### Phase 1 — Fan-out song song theo dimension
-- **DIMENSIONS = 3 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
+- **DIMENSIONS = 4 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
   | Lăng kính | Soi gì |
   |-----------|--------|
+  | **QA** (tầng nghiệm thu) *(bật 2026-08-25)* | AC có nêu **outcome quan sát/kiểm được** chưa? AC có lặp nội dung BR (trùng tầng) không? — hỏi về **HÌNH THỨC**, KHÔNG về nội dung thiếu |
   | **DEV** (cơ chế nghiệp vụ) | BR + Business Logic đã đủ & không mơ hồ để build không phải đoán chưa? Nhánh nghiệp vụ thiếu, điều kiện biên, đường lỗi bỏ ngỏ |
   | **SA** (thông suốt & nhất quán) | Luồng nghiệp vụ thông suốt trên cả feature/domain? Tương tác UC, quan hệ entity, vòng đời trạng thái, ai-làm-gì |
   | **PO** | Scope khoanh vùng? Priority? Success metric? Rủi ro scope creep? |
@@ -66,7 +67,8 @@ Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
 
 ## Cơ chế đặc biệt
 
-- **Không có `--fix` mode** (khác `/review-context`) — finding 3 lăng kính là phán đoán DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
+- **Lăng kính QA hẹp có chủ ý** — nó hỏi *"phát biểu này kiểm chứng được không?"*, KHÔNG hỏi *"còn thiếu gì?"*. Ở thời điểm PRD chỉ có PRD (design-spec/BDD/tech-doc chưa tồn tại), nên không phân biệt được *"PRD thiếu X"* với *"PRD để X cho design-spec"*. Câu hỏi nội dung thuộc `/qc-analyze`. Số liệu: review chỉ-PRD ra ~14 gap, review đủ 4 nguồn ra ~9,4 — chênh lệch là câu tài liệu sau trả lời hộ.
+- **Không có `--fix` mode** (khác `/review-context`) — finding 4 lăng kính là phán đoán QA/DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
 - **`resolution_edge_cases`** — phân tích bậc-hai (chỉ critical/major): "nếu chốt phương án này thì đẻ ra edge case gì?" → PO thấy trước khi accept (advisory, không chặn).
 - **QA lens đang DISABLED** (comment trong file) — có hướng dẫn bật lại nếu cần.
 
@@ -74,10 +76,10 @@ Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
 
 ## 👓 Góc nhìn tối ưu
 
-- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 3 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
+- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 4 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
 - **Completeness-critic tới 3 vòng** — điểm đáng đo: thực tế hội tụ ở vòng mấy? Nếu thường 1–2 vòng thì cap 3 hợp lý.
 - **Full/delta logic phức tạp** (`applied_to_version` tracking) — mạnh nhưng nhiều nhánh; dễ rơi về FULL khi có actor khác sửa PRD (vd `/review-context` xen giữa).
-- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (3 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
+- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (4 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
 
 ---