@educa-corp/sdd-framework 0.9.5 → 0.9.6

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

@@ -1,14 +1,19 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-run-test — QC Script Generation & Run (ghi qc_status)
-
-> Stage 5 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-runner của team QC. Sinh & chạy Python pytest-playwright từ `.Test.md` đã review, rồi ghi `qc_status` **chính thức** vào trace TSV.
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-run-test — QC Script Generation & Run (ghi qc_status)
+
+> Stage 5 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-runner của team QC. Sinh & chạy Python pytest-playwright từ `.Test.md` đã review, rồi ghi `qc_status` **chính thức** vào trace TSV.
+
+## Gate
+
+*Checkpoint: **chặn CỨNG** — ghi đè script Python đã có → XOÁ bản sửa `script-bug` mà chính lệnh này bảo QC tự sửa bằng tay. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng chỉ áp khi **sinh lại** file script đã tồn tại. Chạy lại test trên script không đổi — việc thường nhất của trạm này — **không** chạm CHECKPOINT cứng. Xem §Chạy lại.*
+
 # 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ó.
@@ -160,200 +165,310 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
 - "N" → dừng, hỏi người dùng muốn thay đổi gì.
 - Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
   🔴/⚠️ (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 (`active_platform` + `qc_artifact_dir` do §Phạm vi QC phân giải).  `active_platform` này CHÍNH LÀ platform của sổ trace sẽ ghi `qc_status` (`{UC-ID}-{active_platform}.tsv`) — nên `@trace.verifies={UC-ID}-SC{N}` resolve không nhập nhằng. Đọc `.Test.md` đã review từ `{qc_artifact_dir}test-cases/`. Lệnh này dùng stack module **qc-playwright** (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — độc lập với module implementation của dev.*
-
-## Context
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID (`active_platform` + `qc_artifact_dir` do §Phạm vi QC phân giải).  `active_platform` này CHÍNH LÀ platform của sổ trace sẽ ghi `qc_status` (`{UC-ID}-{active_platform}.tsv`) — nên `@trace.verifies={UC-ID}-SC{N}` resolve không nhập nhằng. Đọc `.Test.md` đã review từ `{qc_artifact_dir}test-cases/`. Lệnh này dùng stack module **qc-playwright** (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — độc lập với module implementation của dev.*
+
+## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
 `project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi
-placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
-
-## Phạm vi QC
-
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+## Phạm vi QC
+
 **BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
-`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--force`).
 Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
-cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
-
-> **Trạm này vẫn gọi theo TỪNG UC** *(B11)* — thiết kế và chạy test **thật sự** làm tăng dần
-> theo UC, nên giữ khả năng làm UC1 khi UC3 chưa xong là đúng. Chỉ **chỗ đọc/ghi** đổi: mọi
-> artifact nằm chung ở `{qc_artifact_dir}` cấp PRD, không còn một thư mục mỗi UC.
->
-> Nên `DOC_GAP.md` / `TEST_PLAN.md` đọc được ở đây phủ **cả PRD**: **lọc theo cột `UC`** để lấy
-> phần của UC đang làm. Đừng coi toàn bộ bảng gap là của UC này — sẽ chặn oan.
-
----
-
-
----
-
-## Role & stack (theo module qc-playwright)
-
-Bạn là **QC Runner** — stage 5. Chuyển `.Test.md` đã review thành Python
-pytest-playwright script + Page Object, chạy chúng, và report kết quả theo từng scenario.
-
-Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
-- Markdown-first: không bao giờ sinh Python khi chưa có `.Test.md` đã review.
-- Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
-- **Locator từ test-id contract (không scan runtime).** Đọ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 "Phục vụ SC" khớp SC của UC này**) và dựng mỗi Page Object locator từ test-id ổn định của nó. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có action mà **không** có test-id trong §4.5.6 — và ghi chú để gap được thêm vào tech-design.
-
-- **TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.**
-  Đọc `@trace.testid_attr` từ **header tech-doc gộp** (do `/map-testids` ghi — nó đã phân giải một lần cho cả feature). Đây là **nửa QC của contract FE↔QC**: `/generate-code` đọc chính field này để emit thuộc tính lên element.
-
-  | Đọc được | Làm gì |
-  |---|---|
-  | web + attr ≠ `data-testid` (vd `data-test` · `data-qa`) | **BẮT BUỘC** cấu hình test-id attribute trước khi dùng `get_by_test_id()`: `playwright.selectors.set_test_id_attribute("{attr}")` (hoặc `testIdAttribute` trong config). Bỏ bước này thì `get_by_test_id()` vẫn dò `data-testid` mặc định → **trượt 100% locator**. |
-  | web + attr = `data-testid` | `get_by_test_id("...")` như thường (đúng mặc định Playwright). |
-  | RN / Flutter / native | Dùng đúng cơ chế mà `{attr}` mô tả (`testID` · `Key`/`Semantics(identifier:)` · `accessibilityIdentifier`). |
-  | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode:** `⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo platform ({attr mặc định}). Nếu FE dùng thuộc tính khác thì MỌI locator sẽ trượt. Chạy /map-testids {UC-ID} để ghi field này.` Rồi mới fallback. |
-
-  > **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã được ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống. Nó hỏng ở đúng ca field này tồn tại để phục vụ: dự án web dùng `data-test`/`data-qa` thay vì mặc định, hoặc một PRD trải ba platform với ba thuộc tính khác nhau. Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail với "element not found" — trông y hệt một bug sản phẩm, nên QC sẽ đi mở bug thay vì sửa selector.
-- pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không bao giờ xen kẽ.
-- Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
-- Phủ **100%** TC trong file — mỗi TC kết thúc Pass/Fail/Skip (không còn Draft).
-- Phân loại mỗi FAIL — **ba** nhãn, sau khi đã chạy lại (xem §Chạy lại trước khi kết luận): `script-bug` (fix selector/logic) · `product-gap` (giữ FAIL + evidence, **không bao giờ fake-pass**) · `flaky` (không nhất quán qua các lần chạy lại — chưa đủ căn cứ để kết luận hai cái kia).
-
-## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-runner/`)
-
-`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
-`non-functional.md`, `exploratory/session.md`.
-
-## Trace tag (bắt buộc)
-
-Mỗi pytest test được sinh ra mang scenario framework mà nó verify, lấy từ
-Trace matrix của `.Test.md`:
-
-```python
-# @trace.verifies={UC-ID}-SC{N}
-def test_TC_<FEATURE>_001_...(...): ...
-```
-
-## Chạy lại trước khi kết luận — rồi người xác nhận *(bắt buộc cho MỌI FAIL)*
-
-Một test đỏ **một lần** chưa nói được nó đỏ vì cái gì. Trước khi phân loại, phải loại nhiễu.
-
-### Bước 1 — Chạy lại riêng test đó, tối đa 2 lần
-
-```
-đỏ → đỏ → đỏ     ⇒ NHẤT QUÁN       → sang Bước 2, phân loại script-bug | product-gap
-đỏ → xanh        ⇒ KHÔNG NHẤT QUÁN → flaky
-đỏ → đỏ → xanh   ⇒ KHÔNG NHẤT QUÁN → flaky
-```
-
-**Đây KHÔNG phải `retries` trong config của test runner.** `retries` tự thử lại rồi báo
-*"passed on retry"* — nó **che** sự không nhất quán. Ở đây chạy **tách biệt từng lần** để
-**quan sát**, vì chính sự không nhất quán mới là thông tin cần.
-
-### Bước 2 — Điều tra bằng bằng chứng, KHÔNG đoán
-
-Đọc trace/video/log: timeline, DOM snapshot, network, console **tại thời điểm fail**. Rồi chọn
-một trong ba:
-
-| Nhãn | Khi nào | Hệ quả |
-|---|---|---|
-| `script-bug` | Sai locator / logic test / timing / dữ liệu test | QC tự sửa. **Không** mở bug |
-| `product-gap` | Hành vi thật ≠ spec (PRD/BDD/AC) — defect thật | Mở bug qua `/report-bug`. Giữ `fail` + evidence, **không bao giờ fake-pass** |
-| `flaky` | Không nhất quán ở Bước 1 — **chưa đủ căn cứ** | Cách ly + **ghi nghi vấn nguyên nhân**. **Không** mở bug từ một lần chạy hên xui |
-
-### Bước 3 — Người xác nhận TRƯỚC khi hành động
-
-In đề xuất kèm bằng chứng cụ thể, rồi **dừng chờ**:
-
-```
-❓ {UC-ID}-SC{N} FAIL — đề xuất: {script-bug | product-gap | flaky}
-   Bằng chứng: {trích từ trace/log — vd "locator #submit-btn không tồn tại, DOM đã đổi id"
-                hoặc "lần 1 đỏ, lần 2 xanh — không nhất quán"}
-   Xác nhận phân loại này? (script-bug / product-gap / flaky)
-```
-
-**KHÔNG ghi `qc_status` cho scenario nào còn FAIL chưa được xác nhận phân loại.**
-
-**Nếu QC không chắc** giữa `script-bug` và `product-gap` (bằng chứng mơ hồ, hành vi ở biên của
-spec) → **mời Dev cùng xem trace**, đừng tự đoán cho xong.
-
-> **Vì sao chỗ này đáng chặn** — trong khi framework vốn đang cố giảm số cổng chặn (G41): vì
-> **hai hướng sai đều không đảo ngược rẻ**. Gắn nhầm `script-bug` cho lỗi sản phẩm thật là
-> **giấu bug** — dev không bao giờ thấy nó. Gắn nhầm `product-gap` cho lỗi test là mở bug sai,
-> hoặc tệ hơn là đi "sửa" một sản phẩm không có lỗi. Đây không phải cổng hỏi cho có; nó là điểm
-> rẽ mà agent **không có quyền tự quyết**.
->
-> **Vì sao `flaky` không phải thùng rác.** Nhãn này **buộc** ghi nghi vấn nguyên nhân (thường:
-> thiếu cách ly dữ liệu · thiếu `storageState` · race condition thật) và cách ly test, không
-> phải chỉ đánh dấu rồi bỏ qua. Nó là *"chưa kết luận được"*, không phải *"thôi bỏ đi"* — và
-> một test nằm mãi ở `flaky` là một việc còn nợ, nhìn thấy được.
-
-## Write Trace State — qc_status (kết quả QC CHÍNH THỨC)
-
-Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` (`{active_platform}` đã phân giải ở Bước 1 — chính là platform của QC pass này; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{active_platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp
-`sc_id` qua tag `@trace.verifies={UC-ID}-SC{N}` của test). *(Umbrella + `spec_source`: `trace_dir` là `{spec_source}/.trace` — ghi update `qc_status` vào **spec repo** và commit/push spec submodule, giống `feedback/`.)*
-
-| Cột | Giá trị |
-|--------|-------|
-| `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 **đã xác nhận là `script-bug` hoặc `product-gap`** · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó, **hoặc SC chỉ có kết quả `flaky`** (xem hàng dưới). Row **`DRIFT`/`ORPHANED`**: **không bao giờ ghi `pass`** — hạ về `not_run` |
-| `qc_status` khi `flaky` | **`not_run`, KHÔNG phải `fail`.** `fail` ngụ ý *đã có kết luận*; kết quả không nhất quán qua các lần chạy lại nghĩa là **chưa có** kết luận nào. Ghi `fail` ở đây là khẳng định một điều chưa biết — và nó còn đẩy việc sang dev (xem `qc_owner`) trong khi việc đang thuộc QC |
-| `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) · **`qc` nếu FAIL = flaky** (QC phải điều tra nguyên nhân, **không** phải việc của dev) · `—` 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ề.
-Với FAIL product-gap, set `qc_owner=dev` ngay; `BUG-{id}` được backfill vào `qc_blocked_by`
-khi QC chạy `/report-bug` mà `/qc-report` nhắc.
-
-### Guard — ĐỌC `status` trước khi ghi `pass` *(bắt buộc)*
-
-*Contract: `bin/trace-schema.json` → `positive_assertion_guards`. Đối xứng hoàn toàn với `/dev-run-test`; dữ liệu đã có trong sổ, không phát sinh I/O.*
-
-`pass` **không** mang nghĩa *"QC test đã chạy và xanh"*. Nó mang nghĩa **"scenario này đã được nghiệm thu theo spec HIỆN TẠI"**.
-
-| `status` của row | `qc_status` ghi gì | `qc_run_at` |
-|---|---|---|
-| `OK` · `GAP` · `UNTRACKED` | như bảng trên | hôm nay |
-| **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG `pass`)* · **fail** → **`fail`** như thường · **skip** → `skip` như thường | `—` nếu ghi `not_run` |
-| **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` | `—` |
-
-**Chỉ `pass` bị chặn.** `fail` là tin xấu thật, `skip` là giá trị trung tính — cả hai không phải lời khẳng định nên ghi bình thường. Chặn chúng là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.
-
-Khi hạ về `not_run` vì `DRIFT`/`ORPHANED`, **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy §Đóng bug đã verify — hai bước đó chỉ dành cho `pass` **thật**. Đóng một bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai. In:
-```
-⚠️  {sc_id} — QC test XANH nhưng row đang {DRIFT | ORPHANED}, nên KHÔNG ghi pass.
-    Không bug nào được đóng ở lần chạy này cho SC đó.
-    Làm: /generate-code {UC-ID} → /qc-design-test lại → chạy lại lệnh này.
-```
-
-> **Vì sao (GAPS-v4 G55).** Bản cũ khai `qc_status` **trực giao** với `status` — trực giao về *kết quả chạy* thì đúng, nhưng **không** trực giao về *quyền được khẳng định*. `/generate-bdd` hạ `qc_status → not_run` khi spec đổi (kèm lý do *"cái này làm cờ nói dối"*), rồi lần `/qc-run-test` kế tiếp dựng lại `pass` với ngày mới. Ở đây hậu quả còn đi xa hơn `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify) — nên guard phải chặn cả nhánh đó.
->
-> **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt đúng trạng thái này ở sổ thật, bất kể lệnh nào ghi ra.
-
-Giữ nguyên mọi cột khác — **không bao giờ** đụng `dev_selftest`/`dev_selftest_at`
-(do `/dev-run-test` sở hữu; nó có guard riêng cùng loại). `qc_status` (QC chính thức) và
-`dev_selftest` (dev smoke) là hai tín hiệu riêng; cả hai trực giao với `status` về **kết quả
-chạy**, nhưng **KHÔNG** trực giao về **quyền khẳng định `pass`** — xem §Guard ở trên.
-
-## Đóng bug đã verify *(chạy TRƯỚC khi clear `qc_blocked_by`)*
-
-`/qc-run-test` là **chủ sở hữu** bước `🟡 Fixed → 🟢 Closed` của bug lifecycle: `/report-bug` mở bug (`🟢 Open`), `/fix-bug` Phase 5.5 đặt `🟡 Fixed`, và chỉ QC re-verify mới được đóng. Không có bước này thì mọi bug đứng vĩnh viễn ở `Fixed`.
-
-Với **mỗi** row mà `qc_status` **vừa chuyển thành `pass`**:
-
-1. **Đọc `qc_blocked_by` TRƯỚC khi clear.** Nếu khớp `BUG-*`:
-   - Mở `{paths.bug_reports_dir}/{BUG-ID}.md`.
-   - `State` đang `🟡 Fixed` → set `🟢 Closed` + thêm dòng: `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass`.
-   - `State` đang `🟢 Open` (**chưa ai fix mà test đã pass**) → **KHÔNG đóng.** Giữ `Open` và thêm ghi chú: `⚠️ {UC-ID}-SC{N} pass ngày {today} nhưng bug chưa có Resolution — kiểm tra test có phủ đúng behavior đã báo không.` *(Test pass trên một bug chưa fix là dấu hiệu test sai, không phải bug hết. Tự đóng ở đây sẽ chôn một defect thật.)*
-   - Không tìm thấy file → bỏ qua im lặng (bug có thể đã archive).
-2. Nếu khớp `GAP-*` → **không** đóng gì (spec-gap do PO xử lý, không phải QC).
-3. Commit + push các bug report vừa đổi vào spec repo (cùng cách push như `/report-bug` Step 6) — file local là dead drop, PO/Dev chỉ thấy sau khi push.
-
-Rồi mới clear `qc_owner`/`qc_blocked_by` về `—`.
-
-## Refresh Panel Mirror
+cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
+
+---
+
+## Stamp phiên bản nguồn
+
+**BẮT BUỘC — đọc `.agent/steps/qc-stamp.md` và thực thi phần áp cho lệnh này**,
+rồi mới tiếp tục phần bên dưới.
+
+Nó có **hai vế**: §1 **ghi** khối `Nguồn & phiên bản` vào artifact lệnh này sinh ra ·
+§2 **so** stamp của artifact lệnh này ĐỌC với version hiện tại của spec.
+Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp thành một con số không ai
+đọc — và một bộ TC lỗi thời sẽ chạy xanh rồi ghi `pass` **hợp lệ theo mọi phép kiểm**.
+
+> **Trạm này vẫn gọi theo TỪNG UC** *(B11)* — thiết kế và chạy test **thật sự** làm tăng dần
+> theo UC, nên giữ khả năng làm UC1 khi UC3 chưa xong là đúng. Chỉ **chỗ đọc/ghi** đổi: mọi
+> artifact nằm chung ở `{qc_artifact_dir}` cấp PRD, không còn một thư mục mỗi UC.
+>
+> Nên `DOC_GAP.md` / `TEST_PLAN.md` đọc được ở đây phủ **cả PRD**: **lọc theo cột `UC`** để lấy
+> phần của UC đang làm. Đừng coi toàn bộ bảng gap là của UC này — sẽ chặn oan.
+
+---
+
+
+---
+
+## Role & stack (theo module qc-playwright)
+
+Bạn là **QC Runner** — stage 5. Chuyển `.Test.md` đã review thành Python
+pytest-playwright script + Page Object, chạy chúng, và report kết quả theo từng scenario.
+
+Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
+- Markdown-first: không bao giờ sinh Python khi chưa có `.Test.md` đã review.
+- Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
+- **Locator từ test-id contract (không scan runtime).** Đọ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**) và dựng mỗi Page Object locator từ test-id ổn định của nó. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có action mà **không** có test-id trong §4.5.6 — và ghi chú để gap được thêm vào tech-design.
+
+- **TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.**
+  Đọc `@trace.testid_attr` từ **header tech-doc gộp** (do `/map-testids` ghi — nó đã phân giải một lần cho cả feature). Đây là **nửa QC của contract FE↔QC**: `/generate-code` đọc chính field này để emit thuộc tính lên element.
+
+  | Đọc được | Làm gì |
+  |---|---|
+  | web + attr ≠ `data-testid` (vd `data-test` · `data-qa`) | **BẮT BUỘC** cấu hình test-id attribute trước khi dùng `get_by_test_id()`: `playwright.selectors.set_test_id_attribute("{attr}")` (hoặc `testIdAttribute` trong config). Bỏ bước này thì `get_by_test_id()` vẫn dò `data-testid` mặc định → **trượt 100% locator**. |
+  | web + attr = `data-testid` | `get_by_test_id("...")` như thường (đúng mặc định Playwright). |
+  | RN / Flutter / native | Dùng đúng cơ chế mà `{attr}` mô tả (`testID` · `Key`/`Semantics(identifier:)` · `accessibilityIdentifier`). |
+  | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode:** `⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo platform ({attr mặc định}). Nếu FE dùng thuộc tính khác thì MỌI locator sẽ trượt. Chạy /map-testids {UC-ID} để ghi field này.` Rồi mới fallback. |
+
+  > **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã được ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống. Nó hỏng ở đúng ca field này tồn tại để phục vụ: dự án web dùng `data-test`/`data-qa` thay vì mặc định, hoặc một PRD trải ba platform với ba thuộc tính khác nhau. Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail với "element not found" — trông y hệt một bug sản phẩm, nên QC sẽ đi mở bug thay vì sửa selector.
+- pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không bao giờ xen kẽ.
+- Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
+- Phủ **100%** TC trong file — mỗi TC kết thúc Pass/Fail/Skip (không còn Draft).
+- Phân loại mỗi FAIL — **ba** nhãn, sau khi đã chạy lại (xem §Chạy lại trước khi kết luận): `script-bug` (fix selector/logic) · `product-gap` (giữ FAIL + evidence, **không bao giờ fake-pass**) · `flaky` (không nhất quán qua các lần chạy lại — chưa đủ căn cứ để kết luận hai cái kia).
+
+## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-runner/`)
+
+`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
+`non-functional.md`, `exploratory/session.md`.
+
+---
+
+## Guard — hợp đồng test-id, chân thứ tư *(phép so GIÁ TRỊ, một chiều)*
+
+`bin/trace-schema.json` canh **ba** chân của hợp đồng test-id: §4.5.6 ↔ `.feature` (**T15**) ·
+↔ header `@trace.testid_attr` (**T16**) · ↔ code (**T17/T18**). Chân thứ tư — §4.5.6 ↔ `*.Test.md`
+— **không máy nào canh**, và nó là chân duy nhất mà giá trị id bị **chép cứng vào một artifact bền**:
+
+```
+generate-code   → bake vào code          → T17/T18 canh
+qc-run-test     → dựng locator LÚC CHẠY  → đọc bảng tươi, tự cứu
+qc-design-test  → chép vào .Test.md      → KHÔNG AI CANH   ← chỗ này
+```
+
+**Phạm vi — đọc trước khi làm gì.** Không có block §4.5 client trong tech-doc (dự án backend-only,
+hoặc chưa từng chạy `/map-testids`) → **im lặng hoàn toàn**, không kiểm gì. Cùng điều khoản phạm vi
+với `testid_contract`: *"hai rule nói 'chỗ nào đã hứa thì phải giữ', KHÔNG nói 'mọi chỗ đều phải có
+hợp đồng'"*.
+
+**Phép so — MỘT chiều:**
+
+1. Gom mọi test-id được nhắc trong các `*.Test.md` của UC này.
+2. Gom id ở §4.5.6 (block `active_platform`), **lọc theo cột "Serves SC"** khớp SC của UC này.
+3. `TC ∖ bảng` = id TC nhắc mà hợp đồng không có → ⚠️.
+
+| Kết quả | Làm gì |
+|---|---|
+| Rỗng | **im lặng, đi tiếp** |
+| Có id lạ | `⚠️ Hợp đồng test-id: {k} id trong .Test.md không có ở §4.5.6: {danh sách}`<br/>kèm: `Chạy /map-testids {UC-ID} (đưa vào hợp đồng) hoặc /qc-design-test {UC-ID} (sửa TC theo hợp đồng).` |
+
+**Chiều ngược KHÔNG kiểm.** §4.5.6 có id mà không TC nào nhắc là **bình thường** — không phải element
+nào cũng cần một bước TC. Kiểm chiều đó là **ồn**, đúng bất đối xứng T17/T18 đã chọn.
+
+**Mức là `warn`, không chặn.** Id sai làm test **ĐỎ**, không làm test **xanh giả** — nên nó **không**
+thuộc lớp *"báo cáo sai"* và không đi cùng đường với `steps/qc-stamp.md` §2 (chặn `pass`). Chặn ở đây
+là chặn nhầm loại.
+
+> **Vì sao vẫn đáng cảnh báo dù test sẽ tự đỏ.** Vì nó đỏ **đội lốt thứ khác**. `testid_contract` ghi
+> đúng chữ: *"test đỏ 'element not found' **trông y hệt bug sản phẩm**"* — nên `/qc-report` phân loại
+> *product-gap* rồi in một `/report-bug` sẵn-chạy, và một lỗi **hợp đồng nội bộ** đi ra khỏi đội QC
+> thành phiếu lỗi gửi PO. Dòng ⚠️ này là chỗ duy nhất chặn được chuyến đi đó.
+
+## Output — lệnh này ghi những gì, ở đâu
+
+| Đường dẫn | Nội dung | Người sửa tay? |
+|---|---|:---:|
+| `tests/<project>/test_<feature>.py` | pytest script, 1-1 với `test-cases/` | ✅ **có** — `script-bug` |
+| `pages/<feature>_page.py` | Page Object (3 lớp + BasePage) | ✅ **có** — `script-bug` |
+| `{paths.trace_dir}/…/{UC-ID}-{platform}.tsv` | `qc_status` · `qc_run_at` | ❌ lệnh ghi |
+
+*(Đường dẫn theo `modules/qc-playwright/stack-profile.yaml` §layout.)*
+
+> **Vì sao mục này tồn tại** *(G77)*. Trước đó lệnh **không có §Output** — nó không khai mình ghi
+> cái gì, ở đâu; đường dẫn chỉ nằm trong `stack-profile.yaml` của module. Và một lệnh **không khai
+> mình ghi gì** thì không ai nghĩ tới việc **bảo vệ thứ nó ghi**. Cột *"người sửa tay?"* là câu hỏi
+> mà `bin/trace-schema.json` → `artifact_writers` giờ ép mọi lệnh phải trả lời.
+
+## Chạy lại — script đã tồn tại *(CHẠY, đừng sinh lại)*
+
+**Vòng đời của trạm này là CHẠY nhiều, SINH ít.** §Phân loại FAIL ngay dưới đây khai tường minh
+rằng QC **sửa tay** chính các file trên: *"`script-bug` … **QC tự sửa.** Không mở bug"*. Nên chuỗi
+bình thường là **sinh → chạy → đỏ → QC sửa tay → chạy lại**, và bước cuối **không được** là bước xoá.
+
+| Tình huống | Xử lý |
+|---|---|
+| Script đã có, TC không đổi | **CHẠY nó. KHÔNG sinh lại.** Không hỏi gì — đây là ca thường nhất |
+| TC mới xuất hiện trong `.Test.md` | Sinh **chỉ phần thiếu**; giữ nguyên file đã có |
+| Script có **thay đổi chưa commit** | **DỪNG** — xem dưới |
+
+**Nhận diện "đã sửa tay" bằng `git status` / `git diff`** trên các đường dẫn ở §Output. Không cần ai
+đánh dấu gì, và nó bắt được **mọi** lần sửa — kể cả lần người sửa quên đánh dấu.
+
+```
+❌ {n} file script có thay đổi chưa commit — có thể là bản sửa `script-bug` của bạn.
+   Sinh lại sẽ XOÁ chúng.
+   Files: {danh sách}
+   Cách đúng: commit bản sửa trước, rồi chạy lại.
+   Cố ý bỏ hết và sinh từ trắng: thêm --force
+```
+
+**KHÔNG đoán.** Thấy thay đổi chưa commit thì lệnh **không tự phân biệt** *"QC vừa sửa"* với *"lần
+sinh trước chưa commit"* — hai ca đó nhìn giống hệt nhau trên `git status`. **Dừng oan một lần rẻ
+hơn xoá nhầm một lần.**
+
+> **Vì sao dùng `git`, không dùng marker hay băm nội dung.** Marker (`# @qc.hand-fixed`) **dựa vào kỷ
+> luật** — đúng thứ đã bác ở G64 (*"dựa vào `Next` là dựa vào kỷ luật, không phải vào máy"*). Băm nội
+> dung **du nhập một lớp cơ chế mới**: `rules/workflow.md` ghi *"0 content hash trong toàn bộ
+> codebase"*, và G63 đã chọn không mở mặt trận đó.
+>
+> **Vì sao ca "không đổi gì" phải HOÀN TOÀN im lặng.** Chạy lại test là việc làm hàng chục lần một
+> ngày. Bản vá nào làm nó hỏi mỗi lần thì người dùng sẽ thêm `--force` vào alias — và lúc đó ta mất
+> sạch lớp bảo vệ này.
+
+Có `--force` → report **bắt buộc** khai:
+```
+⚠️ --force: sinh lại từ trắng — đã xoá {n} file script có thay đổi chưa commit: {danh sách}
+```
+
+## Trace tag (bắt buộc)
+
+Mỗi pytest test được sinh ra mang scenario framework mà nó verify, lấy từ
+Trace matrix của `.Test.md`:
+
+```python
+# @trace.verifies={UC-ID}-SC{N}
+def test_TC_<FEATURE>_001_...(...): ...
+```
+
+## Chạy lại trước khi kết luận — rồi người xác nhận *(bắt buộc cho MỌI FAIL)*
+
+Một test đỏ **một lần** chưa nói được nó đỏ vì cái gì. Trước khi phân loại, phải loại nhiễu.
+
+### Bước 1 — Chạy lại riêng test đó, tối đa 2 lần
+
+```
+đỏ → đỏ → đỏ     ⇒ NHẤT QUÁN       → sang Bước 2, phân loại script-bug | product-gap
+đỏ → xanh        ⇒ KHÔNG NHẤT QUÁN → flaky
+đỏ → đỏ → xanh   ⇒ KHÔNG NHẤT QUÁN → flaky
+```
+
+**Đây KHÔNG phải `retries` trong config của test runner.** `retries` tự thử lại rồi báo
+*"passed on retry"* — nó **che** sự không nhất quán. Ở đây chạy **tách biệt từng lần** để
+**quan sát**, vì chính sự không nhất quán mới là thông tin cần.
+
+### Bước 2 — Điều tra bằng bằng chứng, KHÔNG đoán
+
+Đọc trace/video/log: timeline, DOM snapshot, network, console **tại thời điểm fail**. Rồi chọn
+một trong ba:
+
+| Nhãn | Khi nào | Hệ quả |
+|---|---|---|
+| `script-bug` | Sai locator / logic test / timing / dữ liệu test | QC tự sửa. **Không** mở bug |
+| `product-gap` | Hành vi thật ≠ spec (PRD/BDD/AC) — defect thật | Mở bug qua `/report-bug`. Giữ `fail` + evidence, **không bao giờ fake-pass** |
+| `flaky` | Không nhất quán ở Bước 1 — **chưa đủ căn cứ** | Cách ly + **ghi nghi vấn nguyên nhân**. **Không** mở bug từ một lần chạy hên xui |
+
+### Bước 3 — Người xác nhận TRƯỚC khi hành động
+
+In đề xuất kèm bằng chứng cụ thể, rồi **dừng chờ**:
+
+```
+❓ {UC-ID}-SC{N} FAIL — đề xuất: {script-bug | product-gap | flaky}
+   Bằng chứng: {trích từ trace/log — vd "locator #submit-btn không tồn tại, DOM đã đổi id"
+                hoặc "lần 1 đỏ, lần 2 xanh — không nhất quán"}
+   Xác nhận phân loại này? (script-bug / product-gap / flaky)
+```
+
+**KHÔNG ghi `qc_status` cho scenario nào còn FAIL chưa được xác nhận phân loại.**
+
+**Nếu QC không chắc** giữa `script-bug` và `product-gap` (bằng chứng mơ hồ, hành vi ở biên của
+spec) → **mời Dev cùng xem trace**, đừng tự đoán cho xong.
+
+> **Vì sao chỗ này đáng chặn** — trong khi framework vốn đang cố giảm số cổng chặn (G41): vì
+> **hai hướng sai đều không đảo ngược rẻ**. Gắn nhầm `script-bug` cho lỗi sản phẩm thật là
+> **giấu bug** — dev không bao giờ thấy nó. Gắn nhầm `product-gap` cho lỗi test là mở bug sai,
+> hoặc tệ hơn là đi "sửa" một sản phẩm không có lỗi. Đây không phải cổng hỏi cho có; nó là điểm
+> rẽ mà agent **không có quyền tự quyết**.
+>
+> **Vì sao `flaky` không phải thùng rác.** Nhãn này **buộc** ghi nghi vấn nguyên nhân (thường:
+> thiếu cách ly dữ liệu · thiếu `storageState` · race condition thật) và cách ly test, không
+> phải chỉ đánh dấu rồi bỏ qua. Nó là *"chưa kết luận được"*, không phải *"thôi bỏ đi"* — và
+> một test nằm mãi ở `flaky` là một việc còn nợ, nhìn thấy được.
+
+## Write Trace State — qc_status (kết quả QC CHÍNH THỨC)
+
+Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` (`{active_platform}` đã phân giải ở Bước 1 — chính là platform của QC pass này; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{active_platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp
+`sc_id` qua tag `@trace.verifies={UC-ID}-SC{N}` của test). *(Umbrella + `spec_source`: `trace_dir` là `{spec_source}/.trace` — ghi update `qc_status` vào **spec repo** và commit/push spec submodule, giống `feedback/`.)*
+
+| Cột | Giá trị |
+|--------|-------|
+| `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 **đã xác nhận là `script-bug` hoặc `product-gap`** · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó, **hoặc SC chỉ có kết quả `flaky`** (xem hàng dưới). Row **`DRIFT`/`ORPHANED`**: **không bao giờ ghi `pass`** — hạ về `not_run` |
+| `qc_status` khi `flaky` | **`not_run`, KHÔNG phải `fail`.** `fail` ngụ ý *đã có kết luận*; kết quả không nhất quán qua các lần chạy lại nghĩa là **chưa có** kết luận nào. Ghi `fail` ở đây là khẳng định một điều chưa biết — và nó còn đẩy việc sang dev (xem `qc_owner`) trong khi việc đang thuộc QC |
+| `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) · **`qc` nếu FAIL = flaky** (QC phải điều tra nguyên nhân, **không** phải việc của dev) · `—` 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ề.
+Với FAIL product-gap, set `qc_owner=dev` ngay; `BUG-{id}` được backfill vào `qc_blocked_by`
+khi QC chạy `/report-bug` mà `/qc-report` nhắc.
+
+### Guard — ĐỌC `status` trước khi ghi `pass` *(bắt buộc)*
+
+*Contract: `bin/trace-schema.json` → `positive_assertion_guards`. Đối xứng hoàn toàn với `/dev-run-test`; dữ liệu đã có trong sổ, không phát sinh I/O.*
+
+`pass` **không** mang nghĩa *"QC test đã chạy và xanh"*. Nó mang nghĩa **"scenario này đã được nghiệm thu theo spec HIỆN TẠI"**.
+
+| `status` của row | `qc_status` ghi gì | `qc_run_at` |
+|---|---|---|
+| `OK` · `GAP` · `UNTRACKED` | như bảng trên | hôm nay |
+| **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG `pass`)* · **fail** → **`fail`** như thường · **skip** → `skip` như thường | `—` nếu ghi `not_run` |
+| **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` | `—` |
+
+**Chỉ `pass` bị chặn.** `fail` là tin xấu thật, `skip` là giá trị trung tính — cả hai không phải lời khẳng định nên ghi bình thường. Chặn chúng là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.
+
+Khi hạ về `not_run` vì `DRIFT`/`ORPHANED`, **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy §Đóng bug đã verify — hai bước đó chỉ dành cho `pass` **thật**. Đóng một bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai. In:
+```
+⚠️  {sc_id} — QC test XANH nhưng row đang {DRIFT | ORPHANED}, nên KHÔNG ghi pass.
+    Không bug nào được đóng ở lần chạy này cho SC đó.
+    Làm: /generate-code {UC-ID} → /qc-design-test lại → chạy lại lệnh này.
+```
+
+> **Vì sao (GAPS-v4 G55).** Bản cũ khai `qc_status` **trực giao** với `status` — trực giao về *kết quả chạy* thì đúng, nhưng **không** trực giao về *quyền được khẳng định*. `/generate-bdd` hạ `qc_status → not_run` khi spec đổi (kèm lý do *"cái này làm cờ nói dối"*), rồi lần `/qc-run-test` kế tiếp dựng lại `pass` với ngày mới. Ở đây hậu quả còn đi xa hơn `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify) — nên guard phải chặn cả nhánh đó.
+>
+> **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt đúng trạng thái này ở sổ thật, bất kể lệnh nào ghi ra.
+
+Giữ nguyên mọi cột khác — **không bao giờ** đụng `dev_selftest`/`dev_selftest_at`
+(do `/dev-run-test` sở hữu; nó có guard riêng cùng loại). `qc_status` (QC chính thức) và
+`dev_selftest` (dev smoke) là hai tín hiệu riêng; cả hai trực giao với `status` về **kết quả
+chạy**, nhưng **KHÔNG** trực giao về **quyền khẳng định `pass`** — xem §Guard ở trên.
+
+## Đóng bug đã verify *(chạy TRƯỚC khi clear `qc_blocked_by`)*
+
+`/qc-run-test` là **chủ sở hữu** bước `🟡 Fixed → 🟢 Closed` của bug lifecycle: `/report-bug` mở bug (`🟢 Open`), `/fix-bug` Phase 5.5 đặt `🟡 Fixed`, và chỉ QC re-verify mới được đóng. Không có bước này thì mọi bug đứng vĩnh viễn ở `Fixed`.
+
+Với **mỗi** row mà `qc_status` **vừa chuyển thành `pass`**:
+
+1. **Đọc `qc_blocked_by` TRƯỚC khi clear.** Nếu khớp `BUG-*`:
+   - Mở `{paths.bug_reports_dir}/{BUG-ID}.md`.
+   - `State` đang `🟡 Fixed` → set `🟢 Closed` + thêm dòng: `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass`.
+   - `State` đang `🟢 Open` (**chưa ai fix mà test đã pass**) → **KHÔNG đóng.** Giữ `Open` và thêm ghi chú: `⚠️ {UC-ID}-SC{N} pass ngày {today} nhưng bug chưa có Resolution — kiểm tra test có phủ đúng behavior đã báo không.` *(Test pass trên một bug chưa fix là dấu hiệu test sai, không phải bug hết. Tự đóng ở đây sẽ chôn một defect thật.)*
+   - Không tìm thấy file → bỏ qua im lặng (bug có thể đã archive).
+2. Nếu khớp `GAP-*` → **không** đóng gì (spec-gap do PO xử lý, không phải QC).
+3. Commit + push các bug report vừa đổi vào spec repo (cùng cách push như `/report-bug` Step 6) — file local là dead drop, PO/Dev chỉ thấy sau khi push.
+
+Rồi mới clear `qc_owner`/`qc_blocked_by` về `—`.
+
+## Refresh Panel Mirror
 # Làm mới panel mirror của Living Docs *(local)*
 
 > **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
@@ -407,40 +522,40 @@ một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (c
 `{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
 được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
 bên trong từng sub-agent.
-
-
-## Self-Review *(trước khi in Report)*
-
-Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
-
-- **Bịa:** mỗi đề xuất phân loại FAIL dựa trên bằng chứng **đọc thật** từ trace/video/log — trích
-  được dòng lỗi, tên locator, response code — không phải *"thường thì đây là script-bug"*?
-- **Nhảy bước:** **MỌI** FAIL đã qua chạy lại ×2 trước khi đề xuất — không có cái nào bị bỏ bước
-  vì "chắc chắn là gì rồi"? Guard `DRIFT`/`ORPHANED` đã áp cho **từng** row trước khi ghi `pass`,
-  không chỉ vài row?
-- **Số liệu:** `{pass}`/`{fail}`/`{skip}`/`{flaky}` = **đúng output của test runner**
-  (`--reporter=list` / summary), không phải đếm lại bằng mắt qua context?
-
-> Nhóm 3 ở trạm này là chỗ dễ sai nhất: kết quả chạy nằm trong output của runner, nhưng agent đã
-> đọc qua nó một lần rồi **nhớ lại** lúc viết report. Lấy lại từ nguồn, đừng nhớ.
-
-## Report
-
+
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mỗi đề xuất phân loại FAIL dựa trên bằng chứng **đọc thật** từ trace/video/log — trích
+  được dòng lỗi, tên locator, response code — không phải *"thường thì đây là script-bug"*?
+- **Nhảy bước:** **MỌI** FAIL đã qua chạy lại ×2 trước khi đề xuất — không có cái nào bị bỏ bước
+  vì "chắc chắn là gì rồi"? Guard `DRIFT`/`ORPHANED` đã áp cho **từng** row trước khi ghi `pass`,
+  không chỉ vài row?
+- **Số liệu:** `{pass}`/`{fail}`/`{skip}`/`{flaky}` = **đúng output của test runner**
+  (`--reporter=list` / summary), không phải đếm lại bằng mắt qua context?
+
+> Nhóm 3 ở trạm này là chỗ dễ sai nhất: kết quả chạy nằm trong output của runner, nhưng agent đã
+> đọc qua nó một lần rồi **nhớ lại** lúc viết report. Lấy lại từ nguồn, đừng nhớ.
+
+## 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-run-test Report — {UC-ID} ({qc-playwright})
-QC: ✅ {pass} pass | ❌ {fail} fail | ⏭️ {skip} skip | 🔄 {flaky} flaky   (TCs: {total})
-{chỉ khi có FAIL — ngược lại bỏ}
-Phân loại FAIL (người đã xác nhận): script-bug {a} · product-gap {b} · flaky {c} → cách ly
-   {với mỗi flaky: "🔄 {UC-ID}-SC{N} — nghi: {nguyên nhân}" }
-Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv updated (qc_status, qc_run_at)
-{chỉ khi có bug đổi trạng thái — ngược lại bỏ}
-🐞 Bugs: {BUG-ID} → 🟢 Closed (verified {UC-ID}-SC{N})
-   ⚠️ {BUG-ID} giữ 🟢 Open — SC pass nhưng bug chưa có Resolution, kiểm tra lại test
-Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
-Next: /qc-report {UC-ID}   ← sinh report + evidence
-      /qc-review {UC-ID}   ← review script đã sinh trước khi merge
-📊 Living Docs: chạy /validate-traces (hoặc /sync) để push qc_status lên dashboard spec-module.
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-run-test Report — {UC-ID} ({qc-playwright})
+QC: ✅ {pass} pass | ❌ {fail} fail | ⏭️ {skip} skip | 🔄 {flaky} flaky   (TCs: {total})
+{chỉ khi có FAIL — ngược lại bỏ}
+Phân loại FAIL (người đã xác nhận): script-bug {a} · product-gap {b} · flaky {c} → cách ly
+   {với mỗi flaky: "🔄 {UC-ID}-SC{N} — nghi: {nguyên nhân}" }
+Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv updated (qc_status, qc_run_at)
+{chỉ khi có bug đổi trạng thái — ngược lại bỏ}
+🐞 Bugs: {BUG-ID} → 🟢 Closed (verified {UC-ID}-SC{N})
+   ⚠️ {BUG-ID} giữ 🟢 Open — SC pass nhưng bug chưa có Resolution, kiểm tra lại test
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next: /qc-report {UC-ID}   ← sinh report + evidence
+      /qc-review {UC-ID}   ← review script đã sinh trước khi merge
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push qc_status lên dashboard spec-module.
+```