@educa-corp/sdd-framework 0.9.3 → 0.9.4

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

@@ -123,4 +123,12 @@ def test_compatibility(browser_name, playwright):
 
 Mỗi issue: `file:line` | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (assertion không có ngưỡng, gọi production endpoint, hardcode credential) · 🟠 quan trọng (ngưỡng không khớp TC, thiếu parametrize, không teardown data) · 🟡 nhỏ (style, marker thiếu sub-domain, docstring thiếu ngưỡng).
-Score: A/B/C/D · Top 5 issue cần fix trước merge.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.

package/core/skills/qc/qa-reviewer/shared/read-doc-gap-inputs.md

@@ -0,0 +1,26 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/shared/read-doc-gap-inputs.md
+upstream_sha: 3caa1562399ef1167ac2dc620add2c6c729e55df
+---
+
+# Thủ tục: Nạp TOÀN BỘ tài liệu input từ DOC_GAP (BẮT BUỘC trước khi review TC)
+
+> Mục tiêu: reviewer phải đọc **đúng bộ tài liệu nguồn mà `/qc-analyze` đã dùng** để dựng TEST_PLAN + DOC_GAP — không chỉ file domain. Chỉ khi nắm đủ ngữ cảnh nguồn mới bắt được TC hiểu sai nghiệp vụ, thiếu case, hoặc trace sai spec.
+
+## Các bước
+
+1. **Tìm file DOC_GAP** tại `{qc_artifact_dir}DOC_GAP.md` — **một file cho cả PRD**, các UC là các hàng phân biệt bằng cột `UC`. Không có → chạy `/qc-analyze {TICKET-ID} {platform}` trước; **đừng soát TC trên ngữ cảnh thiếu** (soát mù thì kết luận "0 lỗi" là vô nghĩa).
+2. **`Read` toàn bộ DOC_GAP.** Định vị mục **`## Tài liệu đầu vào đã đọc để phân tích`** — bảng liệt kê **đầy đủ** file nguồn (cột "Đường dẫn", tính từ `{paths.specs_dir}/`), kèm vai trò & phiên bản.
+3. **`Read` TỪNG file trong bảng đó** — ghép prefix `{paths.specs_dir}/` vào đường dẫn ở cột. Đọc HẾT, không bỏ sót dòng nào (spec chính + ref bắt buộc + transitive 1-hop). Nếu bảng liệt kê phiên bản, kiểm tra file hiện tại khớp; lệch phiên bản → ghi chú vào REVIEW.
+4. **Đối chiếu chéo:** file nào có mặt ở header DOC_GAP ("Tài liệu nguồn (spec chính)"/"Coverage Attestation") mà thiếu trong bảng → vẫn đọc.
+5. Chỉ sau khi đã nạp xong toàn bộ input + file domain (`business-dictionary.md`, `product-definition/`) mới bắt đầu review — dùng chúng làm chuẩn đối chiếu để phán quyết `APPROVED` / `NEEDS_FIX`.
+
+## Nguyên tắc
+
+- **Chuẩn đối chiếu = tài liệu nguồn**, không phải suy đoán riêng của reviewer. Mọi nhận xét "TC hiểu sai/thiếu case" phải chỉ được về đoạn spec cụ thể trong các file đã đọc.
+- **Không đọc thiếu:** nếu DOC_GAP nói "Tổng: N tài liệu" thì phải mở đủ N.
+- Gap còn `Open` trong DOC_GAP: TC chạm vùng đó phải phản ánh đúng (đánh dấu blocked/assumption), không được coi như spec đã rõ.
+- Lane API: nếu DOC_GAP ghi SKIP → không đòi hỏi TC endpoint không tồn tại.

package/core/skills/qc/qa-reviewer/shared/review-check-groups.md

@@ -0,0 +1,207 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/ui-test-reviewer.md
+upstream_sha: 54f81eb6a132d3fb331f18ce0f1a7eb3a9cf19df
+---
+
+> **Bộ xương 7 nhóm kiểm tra + registry nhãn lỗi dùng chung** *(B13 phần 2)*.
+>
+> Cả 5 tầng của upstream dùng **đúng 7 tên nhóm giống nhau**, và **32/46 nhãn lỗi** có ở cả 5 —
+> nên bộ xương và registry về đây. Phần **thân** của mỗi nhóm khác nhau theo tầng (chỉ trùng
+> ~10/33 dòng giữa UI và API) nên **ở lại từng file tầng**.
+>
+> **Một chỗ CỐ Ý sửa lệch của upstream, không port nguyên:** Nhóm 1 của bản gốc đòi
+> *"**bảng** Tổng hợp TC"* và *"**bảng** Mục lục"* — nhưng luật trạm 3 của **chính họ**
+> (`qa-tc-designer/shared/tc-metadata-format.md`) ghi *"TOÀN BỘ file TC viết dạng LIST — KHÔNG
+> dùng bảng Markdown, áp dụng cho **Tổng hợp TC**, Trace Matrix, TC bị Block"*. Hai file của
+> upstream nói ngược nhau; luật trạm 3 mới hơn và có ngày tháng nên **luật trạm 3 thắng**.
+> Port nguyên Nhóm 1 là nhập khẩu đúng cái lỗi "cổng canh sai luật" mà B13 đang chữa.
+
+# 7 nhóm kiểm tra (dùng chung mọi tầng)
+
+**Chạy tuần tự.** Mỗi lỗi ghi đủ bốn phần:
+
+```
+TC ID  ·  loại lỗi (nhãn)  ·  mô tả  ·  gợi ý sửa
+```
+
+Thiếu *gợi ý sửa* thì finding không dùng được — trạm 3 nhận về một lời phàn nàn, không phải một
+việc. Và mỗi lỗi phải quy được về `FAIL` hoặc `WARN` để chấm điểm *(xem
+`review-file-template.md` §Thang điểm)*.
+
+| Nhóm | Kiểm gì | Thân nhóm ở đâu |
+|---|---|---|
+| **1 — Cấu trúc & Header** | Bố cục file · các mục bắt buộc · phân cấp heading · định dạng ngày | dùng chung, dưới đây |
+| **2 — Mã TC & Đặt tên** | Prefix theo nền/feature · số 3 chữ số · không trùng · tên ≤ 60 ký tự | dùng chung, dưới đây |
+| **3 — Phân nhóm & Type** | TC nằm đúng nhóm · `Type` khớp nội dung | riêng theo tầng |
+| **4 — Tags & Mức độ** | `smoke` vs `regression` · mức độ khớp `Type` | dùng chung, dưới đây |
+| **5 — Nội dung TC** | Preconditions · Test Data · Steps · **Expected Result** | **→ `review-file-template.md`** §Kiểm tra cấu trúc TC |
+| **6 — Coverage** | Đủ nhóm test · không trùng · tỷ lệ · **7 mẫu hay thiếu** | dùng chung + riêng theo tầng |
+| **7 — Traceability** | TC ↔ hàm test ↔ Page Object ↔ marker | dùng chung, dưới đây |
+
+---
+
+## Nhóm 1 — Cấu trúc & Header
+
+Bố cục đúng: `#` header → mục **Tổng hợp TC** → mục **Mục lục** → `## Nhóm <N>` → `### TC` →
+`####` section.
+
+- Có mục **Tổng hợp TC** đặt **trước** Mục lục → thiếu → `[MISSING_SUMMARY_TABLE]`.
+  Số TC trong đó khớp số TC thực tế → sai → `[SUMMARY_COUNT_MISMATCH]`.
+- **Cả hai mục phải là DANH SÁCH, không phải bảng** — có ký tự `|` → `[SHOULD_BE_LIST]`.
+  *(Tên nhãn `[MISSING_SUMMARY_TABLE]` giữ theo từ vựng đội QC dù nội dung giờ là danh sách —
+  đổi tên nhãn là bắt họ đổi thói quen mà không được gì.)*
+- **KHÔNG** có mục "Danh sách TC" tách rời khỏi Mục lục → có → `[HAS_TC_LIST]`.
+- **KHÔNG** có mục "Phạm vi & ranh giới" / "Gap ảnh hưởng" trong file TC → **đây KHÔNG phải
+  lỗi.** Thông tin đó thuộc `TEST_PLAN.md` và `DOC_GAP.md`. **Đừng gắn nhãn lỗi khi thiếu chúng.**
+- Các nhóm đánh số **liên tục từ 1** → sai → `[BAD_GROUP_NUMBERING]`. Thiếu một nhóm đáng lẽ có
+  → `[MISSING_GROUP]`.
+- Phân cấp `##` → `###` → `####` → sai → `[BAD_HEADING_LEVEL]`.
+- Mỗi TC đủ header + **4 section** (Preconditions · Test Data · Test Steps · Expected Result) →
+  thiếu → `[MISSING_SECTION]`; thiếu một trường metadata → `[MISSING_FIELD]`.
+- `Last updated` đúng `YYYY-MM-DD` → sai → `[BAD_DATE]`. `Status` ∈
+  {`Draft` | `Reviewed` | `Automated` | `Deprecated`}.
+- Dùng khuôn cũ (còn `#### Python Test Mapping`, còn `→ [Expected]` ở bước) → `[OLD_TEMPLATE]`.
+
+**Thứ tự nhóm trong file TC là CỐ ĐỊNH** *(B12)*:
+`GUI → Validation → Functional → Integration (qua UI) → NFR → E2E` cho file giao diện;
+`Endpoint → Integration API/DB/Kafka` cho file API. Sai thứ tự → `[BAD_GROUP_NUMBERING]`.
+
+## Nhóm 2 — Mã TC & Đặt tên
+
+- Prefix đúng nền/feature; số **3 chữ số**; **liên tục toàn file**, không đánh lại theo từng
+  nhóm → sai → `[WRONG_PREFIX]` / `[WRONG_FORMAT]`.
+- **Không trùng mã** → trùng → `[DUP_ID]`. *(Hay xảy ra sau một lần tách/đánh số lại bằng
+  script — xem `review-file-template.md` §dấu vết hỏng thầm lặng.)*
+- Tên TC **< 60 ký tự**, nêu được cả tình huống lẫn kết quả.
+- **Web và app là hai bộ TC ĐỘC LẬP**, mỗi nền một thư mục (`{qc_dir}/{TICKET-ID}/web/` vs
+  `/app/`). Kiểm:
+  - Không TC nào có `Module = App + Web` — phải đã chốt một nền → `[MODULE_NOT_SPLIT]`
+  - File của nền này không chứa TC chỉ-có-ở-nền-kia → `[APP_ONLY_IN_WEB]` / `[PLATFORM_MIX]`
+  - Trace BDD không trỏ chéo nền (file web không có `BDD App SCxx`) → `[CROSS_PLATFORM_TRACE]`
+
+  ⚠️ **Trùng logic giữa hai nền là CHỦ ĐÍCH, không phải lỗi trùng lặp.** Mỗi nền phải tự đạt
+  full coverage. Đừng gắn `[DUPLICATE]` cho cặp web/app cùng kiểm một luật.
+
+## Nhóm 4 — Tags & Mức độ
+
+- `smoke` = luồng chính / cốt lõi · `regression` = biên, âm, lỗi, ca ít gặp.
+- Mỗi TC **≥ 1 tag mức độ**; mức độ **khớp `Type`** → lệch → `[WRONG_LEVEL]`; thiếu →
+  `[MISSING_TAG]`.
+- TC giao diện trên mobile cần `@pytest.mark.flaky` trong Tags → thiếu → `[MISSING_FLAKY_MARK]`.
+
+## Nhóm 5 — Nội dung TC (phần KHÔNG có ở `review-file-template.md`)
+
+Phần lớn Nhóm 5 nằm ở `review-file-template.md` §*Kiểm tra cấu trúc TC* (ATOMIC · không ký tự
+`|` · cụm từ mơ hồ · teardown đúng chỗ · marker ≠ oracle). Bốn phép kiểm còn lại:
+
+- **Preconditions ≥1 điều cụ thể** và **Test Steps ≥2 bước**. Chỉ có một hành động → thêm bước
+  `[Verify]` quan sát kết quả → thiếu → `[TOO_FEW_STEPS]`.
+- **Test Data có giá trị thật + ghi chú kỹ thuật** (`EP: valid` · `BVA: biên trên` · `DT: rule 3`)
+  → thiếu → `[MISSING_DATA]`.
+- **Teardown THỪA** → `[REDUNDANT_TEARDOWN]`: TC chỉ đọc (GET), chỉ verify giao diện tĩnh, hoặc
+  chỉ cấu hình mock/intercept **không cần** Teardown — fixture `conftest.py` (scope=function) đã
+  tự dọn. Ghi *"Reset mock về default"* vào từng TC là thừa, không phải cẩn thận.
+- **Rủi ro flaky**:
+  | Dấu hiệu | Nhãn |
+  |---|---|
+  | Steps định vị element bằng **chỉ số / vị trí** (`nth(3)`, "nút thứ 2") thay vì test-id | `[FLAKY_RISK]` |
+  | TC nhìn thấy rõ là dễ flaky (animation · chờ mạng · thứ tự bất định) mà thiếu ghi chú `⚠️ Flaky:` | `[MISSING_FLAKY_NOTE]` |
+
+  *Định vị theo vị trí trượt ngay khi ai đó chèn thêm một element — và nó trượt **im lặng**, báo
+  "không tìm thấy" chứ không báo "spec đã đổi".*
+
+## Nhóm 6 — Coverage (phần dùng chung)
+
+- Mỗi tính năng **≥ 1 smoke**; có TC âm; có TC biên; có TC xử lý lỗi → thiếu → `[GAP]`.
+- Không trùng logic *(trừ cặp web/app — xem Nhóm 2)* → trùng → `[DUPLICATE]`.
+- Tỷ lệ `smoke` 50–70% · `regression` 30–50%; cân Positive vs Negative/Edge → lệch →
+  `[RATIO_WARN]`.
+- Logic điều kiện có bảng quyết định mà thiếu rule → `[DT_COVERAGE_GAP]`.
+- Giả định QA tự suy mà không ghi ra → `[MISSING_ASSUMPTION]`. Thiếu TC dạng error-guessing →
+  `[MISSING_EG]`.
+
+### 7 mẫu hay thiếu — đối chiếu lại BDD/PRD rồi soi bộ TC
+
+Đây là phần **đắt nhất** của cả nhóm 6: bảy chỗ mà bộ TC trông đầy đủ nhưng thực tế hụt.
+
+| Kiểm | Dấu hiệu thiếu | Nhãn |
+|---|---|---|
+| **Liệt kê biến thể** | Spec nêu *"Google/Facebook"*, *"Lớp 1–6"*, *"iOS/Android"* — bộ TC chỉ có **một** TC chung | `[MISSING_VARIANT]` |
+| **Định tuyến hai chiều** | Spec có *"bỏ qua UC nếu đủ điều kiện"* mà chỉ có TC *"vào UC"*, không có TC *"bỏ qua"* (hoặc ngược lại) | `[MISSING_ROUTING_BRANCH]` |
+| **Telemetry từng event** | Spec liệt kê **≥2** event analytics mà gộp trong một TC | `[EVENTS_NOT_SPLIT]` |
+| **Assertion âm / quyền riêng tư** | Spec có *"KHÔNG vào event"*, *"KHÔNG ghi PII"*, *"read-only"* mà **không TC nào** verify vế âm đó | `[MISSING_NEGATIVE_ASSERT]` |
+| **Nhánh con của AC** | AC dạng *"(1)… → …; (2)… → …"* mà chỉ có TC cho một nhánh | `[MISSING_AC_SUBCASE]` |
+| **Validation kế thừa** | Spec trỏ *"chuẩn hoá theo ACx"* / *"logic như UCy"* mà không TC nào phủ luật chuẩn-hoá của UC nguồn | `[MISSING_INHERITED_VALIDATION]` |
+| **Dòng `Examples`** | BDD có `Scenario Outline` + `Examples` với **N dòng hành vi khác nhau** mà chỉ có một TC | `[OUTLINE_NOT_EXPANDED]` |
+
+Mỗi `[GAP]` phát hiện → ghi vào bảng **Coverage gaps** của file review.
+
+> **Vì sao bảy mẫu này, không phải "hãy kiểm coverage cho kỹ".** Chúng đều là chỗ **bộ TC trông
+> đủ**: có TC, có trace, có Expected cụ thể — nên một lượt đọc bình thường sẽ cho qua. Chỉ khi
+> **đếm lại từ spec** (spec nêu mấy biến thể? mấy event? AC có mấy nhánh?) mới lộ ra. Đó là lý do
+> chúng phải là **danh sách kiểm**, không phải một lời nhắc chung.
+
+## Nhóm 7 — Traceability
+
+- Mỗi TC có `**Trace:**` về `BR-xx` *(hoặc `⚠️ Chưa có Business Rule`)* và
+  `**@trace.verifies:** {UC-ID}-SC{N}` — thiếu `@trace.verifies` thì kết quả chạy **không vào
+  được sổ trace**.
+- Nếu đã có `pages/` + `tests/`: mỗi TC có hàm test khớp mã · mỗi step có method Page Object ·
+  marker pytest khớp Tags · mobile có `@pytest.mark.flaky(reruns=2, reruns_delay=3)`.
+  Chưa sinh code → `[PENDING_IMPL]` *(không phải lỗi — là trạng thái)*.
+- TC bị chặn bởi gap có `🚫 Block: [GAP-UC{N}-{nnn}](../DOC_GAP.md)`; gap đã `Answered` mà TC vẫn
+  còn cờ chặn → `[ESCALATION_PENDING]`.
+
+---
+
+# Nền tảng ISTQB (CTFL v4.0) — reviewer phải nắm
+
+**7 nguyên tắc test:** ① Test chỉ chứng minh **CÓ** lỗi, không chứng minh **KHÔNG** lỗi ② Test
+toàn bộ là bất khả thi ③ Test sớm (shift-left) ④ Lỗi tụ cụm (Pareto) ⑤ Nghịch lý thuốc trừ sâu
+(test dùng mãi thì mòn → phải làm mới) ⑥ Phụ thuộc ngữ cảnh ⑦ Ảo tưởng "không lỗi" (không có bug
+≠ hệ thống đúng nhu cầu).
+
+> Nguyên tắc ① và ⑦ là nền của luật *"mặc định HOÀI NGHI"*: một kết luận *"APPROVED, 0 lỗi"*
+> không chứng minh file sạch — nó chỉ nói lượt soát này không tìm ra gì.
+
+**Confirmation vs Regression:** confirmation = chạy lại test đã trượt sau khi fix; regression =
+chạy lại cả bộ sau mỗi thay đổi (ứng viên số 1 cho tự động hoá / CI).
+
+**Test Pyramid:** Unit/Component (nhiều) > Integration (vừa) > E2E/UI (ít). Nên E2E chỉ dành cho
+luồng P0/P1 quan trọng; NFR và Integration nằm tầng trên, chạy ít / nightly.
+
+**Testing Quadrants:** Q1 unit/component (CI) · Q2 functional + API/integration · Q3
+exploratory/usability/UAT · Q4 smoke + NFR.
+
+**Báo cáo lỗi tối thiểu (B.5):** mã · tiêu đề · ngày + người + vai · đối tượng test & môi trường ·
+bối cảnh (TC/kỹ thuật/dữ liệu) · bước tái hiện + log/ảnh · expected vs actual · severity ·
+priority · status · tham chiếu.
+
+---
+
+# Anti-pattern cần tránh
+
+- **TC chung chung, không làm được** → mỗi TC phải chạy được **độc lập**.
+- **Expected dạng "hiển thị đúng"** → phải nêu element/nhãn/chuỗi/giá trị cụ thể → `[VAGUE_EXPECTED]`.
+- **Hardcode thông tin đăng nhập / URL** trong Test Data → dùng placeholder có tên rõ nghĩa
+  (`<valid_token_admin>`, không phải `<token>`).
+- **Field có ràng buộc mà thiếu EP + BVA**, hoặc logic AND/OR không có bảng quyết định.
+- **State machine có transition mà thiếu TC transition bị cấm.**
+- **Reviewer tự sửa file rồi tự duyệt** — bỏ mất cái cổng. Chỉ nhận xét và chấm điểm.
+
+---
+
+# Phase 3 — Coverage tổng thể
+
+Sau khi duyệt hết từng TC, kiểm **bộ TC** có đủ các nhóm không. Bảng kỳ vọng tối thiểu **khác
+nhau theo tầng** — xem mục `Phase 3` trong file tầng tương ứng.
+
+Nhóm nào thiếu → ghi vào bảng **Coverage gaps** của file review, kèm nhãn `[GAP]` và **mã TC đề
+xuất bổ sung**.
+
+> **Đừng dừng ở Phase 2.** Phase 2 duyệt *"từng TC có đúng không"*; Phase 3 hỏi *"bộ TC có đủ
+> không"*. Một bộ TC mà **mọi TC đều đạt** vẫn có thể **hụt cả một nhóm** — và đó là lỗi đắt hơn
+> mọi lỗi định dạng cộng lại, vì nó không lộ ra ở đâu cả.

package/core/skills/qc/qa-reviewer/shared/review-file-template.md

@@ -0,0 +1,228 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/shared/review-file-template.md
+upstream_sha: bd596393ecc016cbea106835681a4979c0a9ca0e
+---
+
+> **Khuôn file kết quả review — dùng chung cho mọi tầng** *(B13 phần 1)*.
+>
+> **Hai chỗ CỐ Ý khác upstream:**
+>
+> | | Upstream | Ở đây | Vì sao |
+> |---|---|---|---|
+> | Verdict | `APPROVE` / `REJECT` | **`APPROVED` / `NEEDS_FIX`** | Đây là từ vựng chung của framework — `/review-code` dùng đúng cặp này. Đổi theo upstream là làm ba lệnh review nói ba kiểu |
+> | Bảng Tổng quan | mỗi vòng **ghi đè** hàng của tầng đó | mỗi vòng **thêm một hàng** | Ghi đè thì mất điểm vòng trước, và **không ai thấy được điểm có tăng không**. Các bảng chi tiết vẫn ghi đè (chúng là trạng thái hiện tại, tích luỹ chỉ thành nhiễu) |
+
+# Khuôn file Review (dùng chung)
+
+## ⚠️ Nguyên tắc review (BẮT BUỘC — mặc định HOÀI NGHI)
+
+- **Không đóng dấu cho qua.** Kết luận *"APPROVED, 0 lỗi"* trên một khối lượng lớn thường là dấu
+  hiệu **chưa đào đủ**, không phải hoàn hảo — hãy giả định "có ít nhất vài vấn đề" và đi tìm cho
+  ra; nếu thật sự sạch thì **nêu rõ đã kiểm những gì** để loại.
+- **Đối chiếu số liệu nghiệp vụ / biên / trace với SPEC NGUỒN**, không tin nhãn của TC. Mở file
+  trong `{paths.specs_dir}` kiểm off-by-one, sai chiều so sánh, thiếu ca biên đối xứng, trace khống.
+- **Đọc đủ tài liệu** — lỗ hổng thường nằm ở vùng lượt trước CHƯA đọc (vd chỉ đọc BDD app mà bỏ
+  web/system, hoặc bỏ design-spec phần a11y). Review lần 2 thì đọc phần còn thiếu.
+  *Thủ tục nạp đủ nguồn: `read-doc-gap-inputs.md` cùng thư mục này.*
+- **Phân biệt rõ chặn vs không-chặn** để không thổi phồng mức độ: Blocker / Major / Minor. Lệch
+  giữa tài-liệu-nền-cũ và PRD đã duyệt là **lệch đồng bộ, KHÔNG chặn** — không phải mâu thuẫn
+  chặn. *(Khung "gap thật = QA KHÔNG tự quyết được" — xem `steps/gap-verify.md`.)*
+- **KHÔNG tự sửa** kịch bản hay code. Chỉ nhận xét, chấm điểm, và nêu cụ thể sửa gì. Người sửa là
+  trạm 3 (`/qc-design-test`) hoặc trạm 5 (`/qc-run-test`).
+
+## Kiểm tra cấu trúc TC (bắt buộc mỗi vòng)
+
+> Đây là **tầng thi hành** cho các luật mà `/qc-design-test` đặt ra *(B12)*. Luật ở
+> `qa-designer/shared/tc-metadata-format.md` + `precision-rules.md`; chỗ **kiểm** là ở đây.
+
+- **1 bullet Expected / TC (ATOMIC — đội QC chốt 2026-07-09):** mỗi TC có đúng **1**
+  `#### Expected Result` với **ĐÚNG 1 bullet**; Test Steps chỉ `[Action]`/`[Verify]`, **không**
+  còn `→ [Expected]` ở bước. Đếm nhanh: số header `### TC_` = số `#### Expected Result` = số
+  bullet Expected. **TC có ≥2 bullet → `NEEDS_FIX` `[MULTI_BULLET_EXPECTED]`**, yêu cầu tách
+  thành nhiều TC độc lập (mỗi TC 1 bullet, giữ full steps, đánh số lại tuần tự).
+- **Soi bullet 2-kết-cục ẩn (ATOMIC = 1 KẾT CỤC, không chỉ đếm bullet):** bullet nối bằng `;`
+  kiểu "khẳng-định + phủ-định" (grep bullet chứa `;` **và** `không/KHÔNG`, vd
+  *"Có lối Đăng nhập**;** KHÔNG có OTP"*) = 2 kết cục → cũng `[MULTI_BULLET_EXPECTED]`, tách
+  tiếp. Compound chỉ chấp nhận khi **cùng 1 kết cục** (vd *"chỉ 5 slide: đúng 5 dots; slide 6,7
+  không xuất hiện"*). **Đừng đóng dấu cho qua — tự grep tìm đúng chỗ.**
+- **KHÔNG có ký tự `|` trong file TC** *(luật B12)*. Bảng Markdown trong `*.Test.md` →
+  `[SHOULD_BE_LIST]`. ⚠️ Luật này **chỉ áp cho file TC** — file review này và mọi tài liệu khác
+  dùng bảng bình thường.
+- **Cụm từ mơ hồ** trong Expected Result → `[VAGUE_EXPECTED]`: *"hiển thị đúng"* ·
+  *"hoạt động bình thường"* · *"không lỗi"* · *"phù hợp"* … Danh sách 9 cụm bị cấm:
+  `qa-designer/shared/precision-rules.md` §1. Phép thử: **hai người soát đọc có ra cùng một kết
+  luận đỗ/trượt không?**
+- **Teardown đúng vị trí:** flow **TẠO bản ghi DB** (đăng ký / tạo tài khoản mới) phải có
+  `#### Teardown` **thành SECTION riêng** — không phải bullet của Expected. TC có Expected là
+  hành động dọn dữ liệu (*"Xoá tài khoản test…"*) → `[TEARDOWN_AS_TC]` (teardown bị nhét thành
+  oracle, nên steps ↔ expected mâu thuẫn và TC không đỗ/trượt được). Flow tạo tài khoản mà 0
+  Teardown → `[MISSING_TEARDOWN]`. Flow login trên dữ liệu seed **không cần** Teardown.
+- **Assertion loại-trừ không bị đánh rơi:** sau khi trạm 3 rút gọn hoặc dời bước (nhất là bằng
+  script cơ học), đối chiếu để chắc các oracle *"KHÔNG hiển thị / KHÔNG xảy ra"* vẫn còn trong
+  Expected Result. Đây là **mất mát thầm lặng hay gặp nhất** — bullet phủ định dễ bị bỏ nhất.
+- **Chế độ ATOMIC TỐI ĐA** *(cờ `--atomic-max` của trạm 3)*: danh sách completeness
+  (*"hiển thị **đủ** [A,B,C]"*) phải nổ **mỗi thành phần 1 TC**; đa-kết-cục tách hết. Ba rủi ro
+  riêng của chế độ này phải soi:
+  | | Rủi ro | Cách soi |
+  |---|---|---|
+  | **a** | **Mất assertion khi tách** | Cộng các TC con của một TC cha phải phủ **ĐỦ** Expected gốc — cha *"A và B và không C"* → đủ **3** con, không rơi C |
+  | **b** | **Tách vụn quá mức** | Predicate-định-nghĩa-một-khái-niệm (*"chưa bắt đầu & ≥10'"*) · ngưỡng (`≥44pt`) · exclusivity · qualifier **PHẢI giữ 1 TC**. Bị tách → cờ lỗi over-split |
+  | **c** | **Trùng nghĩa mới sinh ra** | Một vế bị nhân bản giữa hai TC |
+
+  Kiểm parity **web ↔ app** (chênh nhau chỉ ở nhóm NFR theo nền là hợp lý).
+  Chi tiết: `qa-designer/shared/precision-rules.md` §2.1.
+- **Marker ≠ oracle:** bullet `- Mobile: @pytest.mark.flaky(...)` nằm trong
+  `#### Expected Result` là **metadata**, không phải kết cục → **KHÔNG** tính là
+  `[MULTI_BULLET_EXPECTED]`, nhưng cờ `[MARKER_IN_EXPECTED]` (khuyến nghị dời ra Tags/meta).
+  Đếm nhầm nó là "bullet thứ 2" sẽ kết luận **SAI** rằng file cần tách.
+- **Sau mọi lần tách / đánh số lại bằng script — soi dấu vết hỏng thầm lặng** *(script chạy xong
+  không báo lỗi mà file đã hỏng)*: **(a)** ID trùng do remap hai lần · **(b)** mã master bị ghi
+  đè (diff tập master-ID với bản backup) · **(c)** dòng `>` note trong Expected bị nuốt ·
+  **(d)** dòng-trống-kép / nhiễu whitespace so với backup · **(e)** tiêu đề nhân đôi khi title
+  con = `<heading cha> — <bullet>` mà cha liệt kê nhiều vế · **(f)** chữ không nguyên văn với
+  nguồn. Tất cả không-chặn **trừ (a) và (b)**, nhưng phải nêu **mã TC cụ thể**.
+- **Oracle tự chứa và đúng nguồn:** chuỗi sao-nguyên-văn (tiêu đề · nhãn · chữ trên nút · thông
+  báo lỗi) mà TC assert phải ghi nguyên văn trong Expected Result **và** khớp design-spec/PRD của
+  **chính feature này**. Soi kỹ chuỗi **mượn nhầm từ feature anh em** (vd *"tạo tài khoản"* vs
+  *"tạo câu hỏi"*). Chuỗi chưa có nguồn chốt mà bị bịa oracle → `NEEDS_FIX`; đúng ra phải để
+  `Status: PENDING` hoặc gắn `🚫 Block: [GAP-UC{N}-{nnn}]`.
+
+## Thang điểm
+
+**Điểm chất lượng `XX/100`:** trừ **5đ** mỗi lỗi `FAIL`, trừ **2đ** mỗi `WARN`.
+
+| Điểm | Nghĩa |
+|---|---|
+| **≥ 80** | đạt |
+| 60–79 | cần cải thiện |
+| < 60 | không đạt |
+
+**Verdict suy ra được, không chấm cảm tính:**
+
+```
+điểm ≥ 80  VÀ  không còn lỗi FAIL chặn   →  APPROVED
+ngược lại                                 →  NEEDS_FIX
+```
+
+> **Vì sao là số, không phải chữ cái.** Framework trước đây ghi `Score: A / B / C / D` mà **không
+> có luật chấm** — nên hai người soát ra hai kết quả, và vòng 2 không so được với vòng 1. Một con
+> số có luật trừ điểm làm được cả ba: **so được các vòng** · **verdict suy ra được** · **hai
+> người soát ra cùng một số**.
+
+## Quy tắc ghi file
+
+File kết quả: **`{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng **cạnh** file TC mà nó
+soát:
+
+```
+{qc_artifact_dir}test-cases/
+├── TC_<FEATURE>.Test.md
+├── REVIEW_<FEATURE>.md            ← soát file trên
+├── TC_<FEATURE>_API.Test.md
+└── REVIEW_<FEATURE>_API.md        ← soát file trên
+```
+
+⚠️ **Tên file review KHÔNG có đuôi `.Test.md`.** Đuôi đó là của file test case; gắn vào file
+review sẽ làm `/qc-run-test` nhặt nó lên như một file test case rồi cố sinh script từ một bảng
+điểm.
+
+- **Chưa tồn tại** → `Write` toàn bộ khuôn bên dưới, điền hàng của tầng vừa soát, các tầng khác
+  để `—`.
+- **Đã tồn tại** → `Read` **toàn bộ** → `Edit` chỉ phần của tầng vừa soát; các tầng khác **giữ
+  nguyên**.
+- **Bảng Tổng quan: THÊM một hàng mỗi vòng**, không ghi đè — để thấy điểm có tăng không.
+  Các bảng chi tiết (Nhóm kiểm tra · Kết quả từng TC · Coverage gaps · Điều kiện để APPROVED) thì
+  **ghi đè** phần của tầng đó, vì chúng là trạng thái hiện tại.
+- **Hai vai ghi vào CÙNG một file.** Vai soát kịch bản (sau trạm 3) và vai soát code (sau trạm 5)
+  đều thêm hàng vào bảng Tổng quan, phân biệt bằng cột `Tầng`. Hai vai cách nhau một trạm — hàng
+  của vai sau **không được ghi đè** hàng của vai trước.
+
+---
+
+## Khuôn đầy đủ (dùng khi `Write` mới)
+
+```markdown
+# Review Report — <FEATURE>
+
+> Sinh bởi /qc-review. Cập nhật sau mỗi vòng soát. Bảng Tổng quan tích luỹ theo vòng.
+
+## Tổng quan
+
+| Tầng | Ngày soát | Vòng | Điểm | Verdict |
+|---|---|---|---|---|
+| Functional | — | — | — | — |
+| API | — | — | — | — |
+| Integration | — | — | — | — |
+| NFR | — | — | — | — |
+| E2E | — | — | — | — |
+| Exploratory | — | — | — | — |
+
+## Nhóm kiểm tra
+
+| Tầng | Nhóm | Kết quả | Số lỗi |
+|---|---|---|---|
+
+## Kết quả từng TC
+
+> **Trạng thái:** `Open` — lỗi mới · `Fixed` — đã sửa · `Waived` — chấp nhận không sửa
+
+| TC ID | Tầng | Trạng thái | Đạt/Chưa đạt | Lý do | Đề xuất sửa |
+|---|---|---|---|---|---|
+
+## Coverage gaps
+
+| Tầng | Kịch bản còn thiếu |
+|---|---|
+
+## Điều kiện để APPROVED (khi đang NEEDS_FIX)
+
+| Tầng | Điều kiện cần sửa |
+|---|---|
+```
+
+*Tên tầng khớp file kỹ năng: `test-case/functional.md` · `api.md` · `integration.md` ·
+`non-functional.md` · `e2e.md` · `exploratory.md`.*
+
+---
+
+## Bảng riêng theo tầng (thêm vào cuối file khi tầng đó được soát lần đầu)
+
+**Tầng API:**
+```markdown
+## Coverage endpoint (API)
+
+| Endpoint | Happy | Validation | Auth 401 | Auth 403 | 404 | Edge |
+|---|---|---|---|---|---|---|
+```
+
+**Tầng E2E:**
+```markdown
+## Coverage journey/path (E2E)
+
+| Journey / Path ID | Loại | TC ID | Đủ coverage? | Đủ isolation? |
+|---|---|---|---|---|
+```
+
+**Tầng NFR:**
+```markdown
+## Chi tiết NFR
+
+| Loại NFR | Kết quả | Thiếu ngưỡng | Cần môi trường riêng |
+|---|---|---|---|
+| Performance | — | — | — |
+| Security | — | — | — |
+| Accessibility | — | — | — |
+| i18n | — | — | — |
+| Compatibility | — | — | — |
+```
+
+**Tầng Integration:**
+```markdown
+## Coverage handshake (Integration)
+
+| Module A ↔ Module B | Happy | Failure | Timeout | Rollback |
+|---|---|---|---|---|
+```

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

@@ -1,7 +1,9 @@
 ---
 version: 1.0
-updated: 2026-06-11
+updated: 2026-09-04
 ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/e2e-test-reviewer.md
+upstream_sha: 276d0516f95421c726c8c55dc84c3c9244cf70e1
 ---
 
 # Review Test Case — E2E Journey
@@ -10,7 +12,7 @@ Review bộ TC end-to-end và đánh giá chất lượng.
 
 ## Khi nào trigger
 - "review TC E2E cho [Feature]" / "check coverage E2E"
-- Sau khi qa-designer/e2e/journey xong, trước khi qa-runner
+- Sau khi qa-designer/e2e/journey xong, trước khi /qc-run-test
 
 ## Khi KHÔNG trigger
 - Review TC functional 1 màn → `test-case/functional`
@@ -18,6 +20,33 @@ Review bộ TC end-to-end và đánh giá chất lượng.
 
 ---
 
+## Trọng tâm review — tầng E2E
+
+- **Journey đầy đủ**: mỗi TC phủ luồng cơ bản **và** có luồng thay thế / ngoại lệ tương ứng;
+  điều kiện trước và sau rõ. Thiếu nhánh ngoại lệ → `[GAP]`.
+- **State Transition theo vòng đời**: object nhiều trạng thái phải phủ các transition hợp lệ
+  (0-switch). *Vd lịch học: Sắp diễn ra → Đếm ngược → Đang diễn ra → Đã kết thúc / Đã huỷ.*
+- **Given/When/Then mạch lạc**, mỗi bước có điểm quan sát đo được.
+- **Test Pyramid — E2E phải ÍT**: chỉ tự động hoá path P0/P1. Tự động hoá cả luồng nhỏ →
+  `[RATIO_WARN]`, đề xuất đẩy xuống tầng API hoặc giao diện.
+- **Đa màn / đa API**: mỗi bước đi qua một màn hoặc một API phải verify được **kết quả trung
+  gian**, không chỉ kết quả cuối.
+- **Bảng quyết định cho độ phủ journey**: trục bao phủ có ≥2 điều kiện (vai × loại × bộ phận) →
+  dựng bảng đếm N journey tối thiểu; thiếu → `[DT_COVERAGE_GAP]`.
+- **Phân nhóm & `Type`** *(Nhóm 3 riêng của tầng này)*: journey thuộc nhóm **E2E**; `Type` khớp
+  nội dung — Happy Path · Positive · Negative · Edge. Sai nhóm → `[WRONG_GROUP]`; `Type` lệch →
+  `[WRONG_TYPE]`; một journey gánh nhiều mục tiêu nghiệp vụ → `[SPLIT_NEEDED]`.
+
+## 7 nhóm kiểm tra
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-check-groups.md`** — bộ xương 7 nhóm
+> chạy tuần tự · registry nhãn lỗi dùng chung · 7 mẫu-hay-thiếu của Nhóm 6 · nền tảng ISTQB ·
+> anti-pattern. Nhóm 5 (Nội dung TC) trỏ tiếp sang `shared/review-file-template.md`.
+>
+> Dưới đây chỉ là phần **riêng của tầng này**.
+
+---
+
 ## Phase 1 — Clarify
 
 1. Đọc tất cả TC E2E (ID dạng `E2E-<FEATURE>-NN`) trong folder chỉ định
@@ -49,25 +78,54 @@ C. INDEPENDENCE & PRECONDITION:
 D. FORMAT & TRACE:
 - ID đúng dạng `E2E-<FEATURE>-NN`?
 - Mỗi TC có `Trace: [BR-xx]`; nếu không có BR phải ghi `⚠️ Chưa có Business Rule`?
-- TC phụ thuộc gap có dòng `🚫 Block: [GAP-xx]`?
-- Cuối file có Trace matrix + bảng TC block?
+- TC phụ thuộc gap có dòng `🚫 Block: [GAP-UC{N}-{nnn}]`?
+- Cuối file có **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách** TC bị block — cả hai **dạng danh sách, KHÔNG bảng** (file TC không được có ký tự `|` — luật B12)?
 - Expected là 1 bullet tổng hợp (không `✅ PASS/❌ FAIL`, không "hoạt động bình thường")?
 
 ---
 
-## Checklist format file `.md`
+## Phase 3 — Coverage tổng thể
+
+**Theo journey:**
+
+| Journey (từ TEST_PLAN) | Loại | TC ID | Đủ tiêu chí phủ? | Đủ isolation? |
+|---|---|---|---|---|
+| `<tên journey>` | happy / alt / exception | `E2E-XXX-01` | ✅/❌ | ✅/❌ |
+| `<journey thiếu TC>` | — | — (thiếu) | — | — |
+
+**Theo path:**
+
+| Path ID | Loại | TC ID | Đi hết node? | Dữ liệu truyền đúng? | Đủ isolation? |
+|---|---|---|---|---|---|
+| `PATH-001` | HP | `E2E-XXX-01` | ✅/❌ | ✅/❌ | ✅/❌ |
+| `PATH-005` | ER | — (thiếu) | — | — | — |
 
-- **Metadata:** Title · Feature · Priority · Status(Draft) · Author · Tags · Trace · Block — mỗi trường 1 dòng.
-- **Test Data:** dạng list (không bảng); ghi cả tài khoản/role cần dùng.
-- **Steps:** phân biệt `[Action]`/`[Verify]`; KHÔNG có `- *Expected:* ...` sau từng bước.
-- **Expected:** 1 bullet; liệt kê chuỗi verify point rõ ràng.
-- **KHÔNG** có section `#### Python Test Mapping`.
+Điền kết quả vào bảng **Coverage journey/path (E2E)** ở cuối file review.
 
 ---
 
+## Kiểm tra cấu trúc file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-file-template.md`** §*Kiểm tra cấu trúc
+> TC* — luật ATOMIC 1-bullet · không ký tự `|` · 9 cụm từ mơ hồ · teardown đúng chỗ · marker ≠
+> oracle · 6 dấu vết hỏng sau khi chạy script tách. **Không lặp lại ở đây.**
+>
+> Luật gốc mà trạm 3 phải theo nằm ở `qa-designer/shared/tc-metadata-format.md` +
+> `precision-rules.md`. **Cổng và luật phải đọc từ cùng một chỗ** — giữ hai bản là tự tạo lại
+> chỗ chúng lệch nhau, và cổng lệch thì nó đánh trượt file làm đúng.
+
 ## Output
 
-Mỗi tiêu chí: ✅ PASS | ⚠️ PARTIAL | ❌ MISSING + evidence (TC ID / journey)
-Score: A (excellent) / B (good) / C (needs improvement) / D (redo)
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng cạnh file TC vừa soát.
+Nạp `../shared/review-file-template.md` để lấy khuôn + quy tắc ghi (tích luỹ theo vòng, chỉ sửa
+hàng của tầng mình, KHÔNG ghi đè tầng khác).
+
+Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID / journey)
+
+**Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
 Danh sách journey thiếu TC; TC cần sửa Expected; TC vi phạm isolation.
-Kết luận: sẵn sàng cho `qa-runner` chưa.
+Điền thêm bảng **Coverage journey/path (E2E)** ở cuối file review.
+
+**KHÔNG tự sửa file TC** — chỉ nhận xét, chấm điểm, nêu cụ thể sửa gì. Người sửa là `/qc-design-test`.