@educa-corp/sdd-framework 0.9.5 → 0.9.7

package/core/commands/{qc-run-test.md → qc-run-script.md}

@@ -1,14 +1,18 @@
----
-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-09-16
+ported_from: ai-automation-qc-base
+---
+
+# /qc-run-script — Chạy automation script (ghi qc_status)
+
+> Stage 7. Chạy script **đã `APPROVED`**, phân loại mỗi FAIL, rồi ghi `qc_status` **chính thức**
+> vào sổ trace. **Không sinh script** — đó là `/qc-design-script`.
+
+## Gate
+
+*Checkpoint: **không chặn** — lệnh CHẠY test và ghi cột sổ trace do chính nó sở hữu; mọi thứ nó ghi đều dựng lại được bằng cách chạy lại. Nó KHÔNG sinh/sửa file script.*
+
 # 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ó.
@@ -88,7 +92,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -96,6 +100,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.
@@ -160,200 +170,171 @@ 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` CHÍNH LÀ platform của sổ trace sẽ ghi `qc_status` (`{UC-ID}-{active_platform}.tsv`).*
+
+## 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.
+
+---
+
+## Tiền điều kiện — script phải `APPROVED`
+
+Đọc `{qc_artifact_dir}test-cases/REVIEW_SCRIPT_<FEATURE>.md`, tìm dòng `**Verdict:**`.
+
+| Đọc được | Làm gì |
+|---|---|
+| `APPROVED` | đi tiếp |
+| `NEEDS_FIX` | **DỪNG** — `❌ Script chưa đạt. Sửa rồi soát lại bằng /qc-review-script {UC-ID}.` |
+| Không có file | **DỪNG** — `❌ Chưa soát script. Chạy /qc-review-script {UC-ID} trước.` |
+
+> **Cổng này là lý do `/qc-review` phải tách đôi** (Đợt 2 · b1). Biên bản cũ không nói nó soát
+> test case hay soát script, nên câu hỏi trên không đặt được.
+
+## Chạy file nào — ĐỌC cột `Script file`, KHÔNG tự suy
+
+Đọc `{qc_artifact_dir}AUTOMATION_ASSESSMENT.md`, lấy cột `Script file` của từng TC
+`Automatable: Y`. **Đó là danh sách file phải chạy.**
+
+| Đọc được | Làm gì |
+|---|---|
+| Cột có đường dẫn | chạy đúng những file đó |
+| Cột còn `—` cho một TC `Y` | **báo ra**, đừng lặng lẽ bỏ: `⚠️ {TC} chưa có script — chạy /qc-design-script {TICKET-ID}` |
+| Không có file bảng | **DỪNG** — `❌ Chưa có AUTOMATION_ASSESSMENT.md. Chạy /qc-automation-assess {TICKET-ID} trước.` |
+
+> **Vì sao KHÔNG tự suy đường dẫn từ quy ước đặt tên.** Suy sai thì hoặc chạy sai bộ test,
+> hoặc **chạy 0 test mà vẫn báo xanh** — rồi con số đó đi thẳng vào `/qc-report` thành số liệu
+> người ta tin. Đây là kiểu hỏng tệ nhất: một báo cáo xanh trên một lần chạy **không tồn tại**.
+
+## Role & stack (theo module qc-playwright)
+
+Bạn là **QC Script Runner**. Chạy pytest-playwright script đã có, thu bằng chứng, phân loại FAIL,
+ghi kết quả theo từng scenario. **KHÔNG sửa script, KHÔNG sinh script.**
+
+## 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`.
+
+---
+
+## 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:
+
+| 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
+
+```
+❓ {UC-ID}-SC{N} FAIL — đề xuất: {script-bug | product-gap | flaky}
+   Bằng chứng: {trích từ trace/log}
+   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` → **mời Dev cùng xem trace**, đừng tự đoán.
+
+> **Vì sao chỗ này đáng chặn** — trong khi framework vốn đang cố giảm số cổng chặn: 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**. Gắn
+> nhầm `product-gap` cho lỗi test là mở bug sai, hoặc đi "sửa" một sản phẩm không có lỗi.
+>
+> **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 và cách ly
+> test. Nó là *"chưa kết luận được"*, không phải *"thôi bỏ đi"* — 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)
+
+Cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` — 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 vào **spec repo** và commit/push spec submodule.)*
+
+| Cột | Giá trị |
+|--------|-------|
+| `qc_status` | Đọc cột `status` của row **TRƯỚC** — xem §Guard. 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`/`product-gap` · `skip` nếu tất cả skip/xfail · `not_run` nếu không test nào phủ nó, **hoặc SC chỉ có kết quả `flaky`**. 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*; không nhất quán nghĩa là **chưa có** kết luận nào. Ghi `fail` còn đẩy việc sang dev trong khi việc đang thuộc QC |
+| `qc_run_at` · `last_updated` | hôm nay `YYYY-MM-DD` |
+| `qc_owner` | `dev` nếu FAIL = product-gap · `po` nếu `skip`/`not_run` vì một `DOC_GAP` 🔴 Blocker đang open · **`qc` nếu FAIL = flaky** · `—` nếu `pass`, hoặc FAIL = script-bug |
+| `qc_blocked_by` | `GAP-{id}` khi bị chặn bởi spec gap · `BUG-{id}` khi `/report-bug` đã file cho product-gap · `—` ngược lại |
+
+Khi `pass`, **clear** `qc_owner`/`qc_blocked_by` về `—` — nhưng **PHẢI chạy §Đóng bug đã verify TRƯỚC**, vì `qc_blocked_by` chính là con trỏ tới bug và clear xong là mất đường về.
+
+### 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`.*
+
+`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 — 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. 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 (G55).** `qc_status` trực giao với `status` về *kết quả chạy* thì đúng, nhưng **không** trực giao về *quyền được khẳng định*. Ở đây hậu quả đi xa hơn `/dev-run-test`: một `pass` sai còn **đóng một bug**. **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).
+
+## Đóng bug đã verify *(chạy TRƯỚC khi clear `qc_blocked_by`)*
+
+Lệnh này là **chủ sở hữu** bước `🟡 Fixed → 🟢 Closed`: `/report-bug` mở bug (`🟢 Open`), `/fix-bug` đặt `🟡 Fixed`, và chỉ QC re-verify mới được đóng.
+
+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` + `Verified: /qc-run-script {today} — {UC-ID}-SC{N} pass`.
+   - `State` đang `🟢 Open` (**chưa ai fix mà test đã pass**) → **KHÔNG đóng.** Giữ `Open` + 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. Tự đóng ở đây sẽ chôn một defect thật.)*
+   - Không tìm thấy file → bỏ qua im lặng.
+2. `GAP-*` → **không** đóng gì (spec-gap do PO xử lý).
+3. Commit + push bug report vừa đổi vào spec repo — file local là dead drop.
+
+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 +388,27 @@ 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`.
+
+- **Bịa:** mỗi phân loại FAIL trỏ được về bằng chứng **cụ thể** trong trace/log?
+- **Nhảy bước:** mọi FAIL đều đã chạy lại ×2 **và** được người xác nhận trước khi ghi?
+- **Số liệu:** số row vừa ghi = đếm thật trên sổ trace?
+
+## 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-script Hoàn tất — {UC-ID} ({active_platform})
+Chạy   : {n} test — pass {p} · fail {f} · skip {s}
+Phân loại FAIL: script-bug {a} · product-gap {b} · flaky {c}
+Trace  : ghi {k} row qc_status   ({d} row hạ not_run vì DRIFT/ORPHANED)
+Bug    : đóng {x} · giữ Open {y}
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý}
+Next   : /qc-run-manualtest {UC-ID}  (TC Automatable: N) → /qc-report {UC-ID}
+```

package/core/commands/refine-prd.md

@@ -88,7 +88,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -96,6 +96,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.

package/core/commands/report-bug.md

@@ -1,7 +1,7 @@
 # /report-bug — File một Bug có trace-spec (cho Tester & QC)
 
 Dành cho **tester và QC** — gồm cả **product-gap** lòi ra từ pipeline `/qc-*`
-(`/qc-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAP` từ
+(`/qc-run-script` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAP` từ
 `/qc-analyze`). Sinh một bug report có cấu trúc với đầy đủ spec context, phân loại layer
 khả nghi, và lưu lại để handoff cho team dev.
 
@@ -91,7 +91,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -99,6 +99,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.
@@ -275,7 +281,7 @@ Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (trong spec repo dùng chung)
 
 Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
-State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` bởi /fix-bug, `Closed` sau khi /qc-run-test re-verify pass)
+State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` bởi /fix-bug, `Closed` sau khi /qc-run-script re-verify pass)
 
 Spec context
   PRD      : {prd_path} (v{prd_version})

package/core/commands/review-code.md

@@ -4,7 +4,7 @@
 
 ## Gate
 
-*Checkpoint: **không chặn** — read-only. Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+*Checkpoint: **không chặn** — **không phải vì read-only**: lệnh CÓ ghi `{lessons_path}` qua §Capture Lesson (`steps/capture-lesson.md`). Nó không chặn vì thao tác ghi đó nằm sau một câu hỏi `(Y/N)` tường minh — điều kiện ấy ĐÃ là một cổng, thêm CHECKPOINT nữa là hỏi hai lần cho một hành động. Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -85,7 +85,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -93,6 +93,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.
@@ -263,7 +269,7 @@ Critical: {X} | Major: {Y} | Minor: {Z}
 ### Minor
 | # | File | Line | Issue | Suggested Fix |
 
-Output Artifacts: none (read-only)
+Output Artifacts: none — TRỪ khi trả lời Y ở §Capture Lesson: updated {lessons_path}
 
 Verdict: APPROVED ✅ | NEEDS_FIX ❌
   (Bất kỳ finding critical nào ở lăng kính 5 → NEEDS_FIX, KỂ CẢ khi build xanh