@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/core/commands/qc-plan.md

@@ -180,10 +180,22 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 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.
 
+---
+
+## 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 chạy CẢ PRD, đúng như trạm 1** *(B11)* — một `TEST_PLAN.md` cho mỗi (PRD × nền).
 > `qa-planner/test-plan.md` vốn viết *"Test Plan cho một **feature**"* và template của nó là
 > `# Test Plan – <Feature>` với metadata `Feature / Project / Module`: đây là quay về đúng
@@ -226,6 +238,45 @@ Bắt buộc:
 - **`§5 Entry criteria` chặn theo từng UC**, không chặn cả PRD: gap 🔴 Blocker ở UC3 không
   dừng việc thiết kế test cho UC1. Ghi `Ready` / `Blocked` cho **mỗi** UC.
 
+### Chạy lại — ghi đè ở đây AN TOÀN, và đây là lý do
+
+*(Ba trạm QC khác — `/qc-analyze` · `/qc-design-test` · `/qc-run-test` — đều ở mức **chặn CỨNG** kèm
+§Chạy lại. Trạm này **không**, và đó là kết luận có chủ ý, không phải chỗ sót.)*
+
+`TEST_PLAN.md` **không có ô nào người nhập tay**: `questions-for-dev` là danh sách **gửi đi** — câu
+trả lời quay về qua `DOC_GAP.md` hoặc kênh chat, **không ai điền ngược vào file này**; stamp phiên
+bản và cột `Ready`/`Blocked` đều do lệnh **tự tính** từ `DOC_GAP.md`. Nên chạy lại = lập lại, không
+mất gì.
+
+*Khai máy đọc: `bin/trace-schema.json` → `artifact_writers.enrolled.qc-plan.has_human_content = false`
+— và **R18 ép khai `why`** chính vì một ngoại lệ có chủ ý trông y hệt một chỗ sót.*
+
+> **⚠️ Khai lại nếu điều này hết đúng.** Có ai bắt đầu điền tay vào `TEST_PLAN.md` — một cột quyết
+> định, một ghi chú duyệt, một câu trả lời dán vào — thì lệnh này **phải** lên `checkpoint_levels.hard`
+> và có §Chạy lại như `/qc-analyze`. Đánh giá "an toàn" ở trên đúng **hôm nay**, không đúng vĩnh viễn.
+
+  > **`Blocked` là mức ƯU TIÊN, KHÔNG phải lệnh cấm** *(G66)*. Nó nghĩa *"UC này chưa sẵn sàng
+  > để **nghiệm thu**"*, không phải *"chưa được **thiết kế**"*. `/qc-design-test` vẫn chạy được và
+  > **nên** chạy — TC chạm gap mang dấu `🚫 Block` trỏ về hàng gap, và cơ chế đó chỉ có nghĩa khi
+  > trạm 3 thực sự chạy trên UC `Blocked`.
+  >
+  > Cái bị chặn là **chạy test**, không phải **viết test**. Chờ PO trả lời mất ngày tới tuần; cấm
+  > thiết kế trong lúc chờ là ném đi đúng phần song song mà `/map-testids` mở ra. Và đây là cùng
+  > lập luận đã dùng ngay ở gạch trên — chặn theo UC chứ không theo PRD — chỉ áp thêm một bậc:
+  > một blocker trong UC1 cũng không dừng việc thiết kế **phần còn lại** của UC1.
+
+## 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 dòng rủi ro neo được vào một `BR`/`AC`/`GAP` **có thật** trong
+  `REQUIREMENT_ANALYSIS.md`/`DOC_GAP.md` — không phải rủi ro chung chung tự nghĩ ra kiểu *"hiệu
+  năng có thể chậm"*? Mỗi `questions-for-dev` suy ra từ một gap cụ thể?
+- **Nhảy bước:** đã đọc **cả hai** file đầu vào (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) và lọc
+  theo cột `UC` — không chỉ đọc file thứ nhất?
+- **Số liệu:** `{risks}`/`{questions}` in ở report = đúng số dòng thật trong `TEST_PLAN.md` vừa
+  ghi, không phải đếm nhẩm?
+
 ## Report
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
@@ -237,6 +288,9 @@ Phạm vi: {n} UC trong plan{nếu có: " · ⏸ {m} chưa xét"}
 Plan: {risks} rủi ro · {questions} câu hỏi mở cho dev · layers: {list}
 File: {paths.qc_dir}/{TICKET-ID}/{active_platform}/TEST_PLAN.md
 Sẵn sàng: {danh sách UC Ready} | Chặn: {danh sách UC Blocked + GAP-ID chặn nó}
-Next: /qc-design-test {UC-ID}   ← thiết kế test case, chạy cho từng UC đã Ready
-      (gửi questions-for-dev cho PO/Dev cho các UC còn Blocked)
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next: /qc-design-test {UC-ID}   ← thiết kế test case, từng UC một
+      Ưu tiên UC `Ready`. UC `Blocked` VẪN thiết kế được — TC chạm gap mang dấu
+      🚫 Block và chưa chạy tới khi gap Answered.
+      (song song: gửi questions-for-dev cho PO/Dev để gỡ blocker)
 ```

package/core/commands/qc-report.md

@@ -1,14 +1,14 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-report — QC Test Report & Evidence
-
-> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ bước report của qa-runner team QC.
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-report — QC Test Report & Evidence
+
+> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ bước report của qa-runner team QC.
+
+## Gate
 # 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,58 +160,74 @@ 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. Sinh report từ lần chạy `/qc-run-test` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
-
-## Context
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Sinh report từ lần chạy `/qc-run-test` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
+
+## 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ỗ.
-
----
-
-## Role
-
-Bạn là stage **QC Report** — biến lần chạy gần nhất thành report + evidence chia sẻ được.
-
-## Skill (`{paths.qc_skills_dir}/qa-runner/report/`)
-
-- `report.md` — tự đủ: pytest-html (`--html=reports/<feature>/report.html
-  --self-contained-html`) + Playwright Trace (`test-results/<nodeid>/trace.zip`, xem qua
-  `python3 -m playwright show-trace <file>`), kèm screenshot/evidence đính trên FAIL/SKIP.
-
-## Procedure
-
-1. Định vị artifact của lần chạy gần nhất cho `{UC-ID}` (report pytest-html + trace).
-2. Sinh/làm mới `reports/<feature>/report.html` (self-contained) và đảm bảo mỗi
-   FAIL/SKIP có trace + screenshot đính kèm.
-3. Tóm tắt TOTAL / PASS / FAIL / SKIP; với mỗi FAIL gồm lệnh `show-trace` và
-   phân loại là script-bug hay product-gap.
-4. **Bàn giao product-gap về spec (có nhắc).** Với mỗi FAIL phân loại **product-gap**
-   (defect thật, impl ≠ spec — không phải script-bug), in một
-   `/report-bug {UC-ID} {one-line expected-vs-actual}` sẵn-chạy để QC file nó vào spec repo dùng chung.
-   BUG_FLOW của `/report-bug` rồi định tuyến root cause (Code / BDD / PRD / Design / Env). Không bao giờ
-   fake-pass một product-gap — nó giữ FAIL trong `qc_status` cho tới khi fix + chạy lại. **script-bug
-   KHÔNG được file** (QC fix script và chạy lại). Liệt kê các lệnh; đừng tự tạo report.
-
-## Report
-
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+---
+
+## Role
+
+Bạn là stage **QC Report** — biến lần chạy gần nhất thành report + evidence chia sẻ được.
+
+## Skill (`{paths.qc_skills_dir}/qa-runner/report/`)
+
+- `report.md` — tự đủ: pytest-html (`--html=reports/<feature>/report.html
+  --self-contained-html`) + Playwright Trace (`test-results/<nodeid>/trace.zip`, xem qua
+  `python3 -m playwright show-trace <file>`), kèm screenshot/evidence đính trên FAIL/SKIP.
+
+## Procedure
+
+1. Định vị artifact của lần chạy gần nhất cho `{UC-ID}` (report pytest-html + trace).
+2. Sinh/làm mới `reports/<feature>/report.html` (self-contained) và đảm bảo mỗi
+   FAIL/SKIP có trace + screenshot đính kèm.
+3. Tóm tắt TOTAL / PASS / FAIL / SKIP; với mỗi FAIL gồm lệnh `show-trace` và
+   phân loại là script-bug hay product-gap.
+4. **Bàn giao product-gap về spec (có nhắc).** Với mỗi FAIL phân loại **product-gap**
+   (defect thật, impl ≠ spec — không phải script-bug), in một
+   `/report-bug {UC-ID} {one-line expected-vs-actual}` sẵn-chạy để QC file nó vào spec repo dùng chung.
+   BUG_FLOW của `/report-bug` rồi định tuyến root cause (Code / BDD / PRD / Design / Env). Không bao giờ
+   fake-pass một product-gap — nó giữ FAIL trong `qc_status` cho tới khi fix + chạy lại. **script-bug
+   KHÔNG được file** (QC fix script và chạy lại). Liệt kê các lệnh; đừng tự tạo 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 con số trong báo cáo trích được về **một dòng cụ thể** của sổ trace / output
+  runner / bug report — không nội suy khi thiếu mẫu?
+- **Nhảy bước:** đã tổng hợp trên **toàn bộ** SC trong phạm vi, không chỉ những SC có kết quả
+  đẹp? Đã liệt kê cả SC `not_run` và `flaky`, không im lặng bỏ khỏi bảng?
+- **Số liệu:** mọi `%` là phép chia thật **và nói rõ mẫu số**? Chỗ thiếu dữ liệu ghi **"chưa đủ
+  dữ liệu"** thay vì điền một số cho đủ bảng?
+
+> **Trạm này là nơi số liệu đi ra khỏi đội QC.** Một con số sai ở các trạm trước còn người trong
+> đội nhìn thấy; sai ở đây là đi vào báo cáo cho Lead/PM. Nhóm 3 vì vậy là nhóm nặng nhất ở đây:
+> *"một bảng đầy số sai tệ hơn một bảng có ô trống ghi rõ lý do"*.
+
+## 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-report Hoàn tất — {UC-ID}
-Report: reports/<feature>/report.html   (TOTAL {N} · PASS {p} · FAIL {f} · SKIP {s})
-Trace : test-results/<nodeid>/trace.zip  (python3 -m playwright show-trace <file>)
-
-Product-gap cần file ({g}):   ← chạy các lệnh này để PO/Dev thấy trên /sync (script-bug bị loại)
-  /report-bug {UC-ID} {gap 1 — expected vs actual}
-  /report-bug {UC-ID} {gap 2 …}
-  (không có → skip)
-
-Next: /validate-traces {UC-ID}   ← làm mới Living Docs (qc_status), rồi tạo PR
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-report Hoàn tất — {UC-ID}
+Report: reports/<feature>/report.html   (TOTAL {N} · PASS {p} · FAIL {f} · SKIP {s})
+Trace : test-results/<nodeid>/trace.zip  (python3 -m playwright show-trace <file>)
+
+Product-gap cần file ({g}):   ← chạy các lệnh này để PO/Dev thấy trên /sync (script-bug bị loại)
+  /report-bug {UC-ID} {gap 1 — expected vs actual}
+  /report-bug {UC-ID} {gap 2 …}
+  (không có → skip)
+
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next: /validate-traces {UC-ID}   ← làm mới Living Docs (qc_status), rồi tạo PR
+```

package/core/commands/qc-review.md

@@ -178,10 +178,22 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 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.
 
+---
+
+## 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.
@@ -222,9 +234,63 @@ tồn tại cho UC và mới hơn → review script. Nếu mơ hồ, hỏi.
 - Soát test-case: `test-case/{functional,e2e,integration,non-functional,exploratory}.md`
 - Soát script: `script/{functional,e2e,integration,non-functional,exploratory}.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 đó.
+
 ## Review focus
 
 - **Test-case:** mọi `{UC-ID}-SC{N}` đã phủ? happy + negative + boundary? expected cụ thể? trace (`BR-xx` + `@trace.verifies` SC) có mặt? không có TC orphan?
+- **`🚫 Block` còn hiệu lực không?** Mỗi TC mang `🚫 Block: [GAP-UC{N}-{nnn}]` → mở `../DOC_GAP.md`,
+  đọc `Trạng thái` của hàng gap đó. **Gap đã `Answered` mà TC vẫn mang dấu ⇒ FINDING.**
+
+  > **Vì sao là finding chứ không phải chuyện nhỏ** *(G66)*. Một TC mang `🚫 Block` là một TC có
+  > `Expected Result` dựa trên **giả định chưa ai xác nhận**. Khi gap được trả lời, quy trình
+  > `tc-metadata-format.md` §*Quy trình khi gap được giải quyết* đòi **cập nhật lại Expected Result**
+  > — giả định có thể đã sai. Bỏ qua thì TC chạy với oracle sai, fail, rồi `/qc-report` phân loại
+  > *product-gap* và in một `/report-bug`: một lỗ hổng **tài liệu** đi ra ngoài đội QC thành **phiếu
+  > lỗi sản phẩm** gửi PO.
+  >
+  > `/qc-design-test` §Guard 🚫 Block **tự gỡ** các dấu này khi chạy lại. Trạm này là **lưới bắt phía
+  > sau** cho ca guard đó không chạy (TC sửa tay, hoặc gap được trả lời sau lần chạy trạm 3 cuối).
 - **Script:** khớp `.Test.md` 1-1? Page Object 3 lớp + BasePage gọn? `expect()` không phải bare assert? không hard-code URL/cred/timeout, không `time.sleep`, không Allure? selector theo priority (data-testid→role→…)? 100% TC đã script (không còn Draft)?
 
 Sinh findings (mức độ + vị trí + cách sửa), chấm điểm, ra verdict.
@@ -247,6 +313,25 @@ Ghi vào **`{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng **c
 ⚠️ **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ạy lại — ghi đè ở đây AN TOÀN, và đây là lý do
+
+*(Ba trạm QC khác — `/qc-analyze` · `/qc-design-test` · `/qc-run-test` — đều ở mức **chặn CỨNG** kèm
+§Chạy lại. Trạm này **không**, và đó là kết luận có chủ ý, không phải chỗ sót.)*
+
+`REVIEW_<FEATURE>.md` là **biên bản của một lần soát**. Sinh lại = **soát lại**, đúng bản chất của
+nó — không có trạng thái nào tích luỹ qua các lần chạy, không ô nào người điền tay vào sau.
+
+*Khai máy đọc: `bin/trace-schema.json` → `artifact_writers.enrolled.qc-review.has_human_content = false`
+— và **R18 ép khai `why`** chính vì một ngoại lệ có chủ ý trông y hệt một chỗ sót.*
+
+> **⚠️ Khai lại nếu điều này hết đúng.** Có ai bắt đầu ghi vào biên bản thứ **không sinh lại được** —
+> chữ ký duyệt, một quyết định *"chấp nhận rủi ro"*, ghi chú thảo luận với dev — thì lệnh này **phải**
+> lên `checkpoint_levels.hard` và có §Chạy lại như `/qc-analyze`.
+>
+> *Lưu ý ngược lại: file TC mà trạm này **soát** thì **có** phần người làm tay, và `/qc-design-test`
+> đã ở mức `hard` vì đúng lý do đó (G78). Trạm này chỉ an toàn ở phần nó **ghi**, không phải phần nó
+> **đọc**.*
+
 Khuôn đầy đủ + quy tắc ghi: `shared/review-file-template.md`. Ba điều bắt buộc:
 
 - **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. Verdict **suy ra được**:
@@ -261,6 +346,21 @@ Khuôn đầy đủ + quy tắc ghi: `shared/review-file-template.md`. Ba điề
 > hai kết quả, và **vòng 2 không so được với vòng 1** — tức không ai biết sửa xong có tốt lên
 > không. Một cổng không để lại dấu vết đo được thì không phải cổng, nó là một lượt đọc.
 
+## 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 finding trỏ được về **dòng cụ thể** trong artifact đang soát — không phải nhận xét
+  chung chung? Và **cấm dùng chính field `quote` của finding làm bằng chứng cho nó** — mở lại file
+  đọc lại đoạn đó.
+- **Nhảy bước:** đã đi hết bộ tiêu chí của **đúng vai** (test-case hay script), không trộn hai
+  bộ? Verdict `APPROVED` phát ra **sau** khi soát đủ, không phải vì "trông ổn"?
+- **Số liệu:** số finding theo mức (critical/major/minor) = đếm thật trên file findings vừa ghi?
+
+> **Verdict của lệnh này là cổng cho trạm sau.** Một `APPROVED` phát ra sớm không chỉ sai ở đây —
+> nó mở đường cho `/qc-run-test` sinh script từ một bộ TC chưa đạt. Đây là chỗ self-review đắt
+> nhất nếu bỏ qua.
+
 ## Report
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
@@ -271,6 +371,7 @@ Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 Điểm  : {XX}/100  ({fail} FAIL × −5đ · {warn} WARN × −2đ){nếu có vòng trước: "   ← vòng #{N-1}: {YY}/100"}
 Verdict: {APPROVED | NEEDS_FIX} — {n} findings ({crit} chặn)
 File  : {qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md (thêm 1 hàng vào bảng Tổng quan)
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
 Next (test-case APPROVED): /qc-run-test {UC-ID}
 Next (script APPROVED)   : /qc-report {UC-ID}  rồi tạo PR
      (NEEDS_FIX → fix artifact bị gắn cờ, rồi chạy lại /qc-review {UC-ID})

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

@@ -9,6 +9,11 @@ ported_from: ai-automation-qc-base
 > 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ó.
@@ -178,10 +183,22 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 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.
 
+---
+
+## 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.
@@ -218,13 +235,111 @@ Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml
 - 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: script-bug (fix selector/logic) vs product-gap (giữ FAIL + evidence, không bao giờ fake-pass).
+- 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ừ
@@ -235,6 +350,60 @@ Trace matrix của `.Test.md`:
 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
@@ -242,10 +411,11 @@ Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_di
 
 | 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 · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó. Row **`DRIFT`/`ORPHANED`**: **không bao giờ ghi `pass`** — hạ về `not_run` |
+| `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) · `—` nếu `pass`, hoặc FAIL = script-bug (QC tự fix — tạm thời) |
+| `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ề.
@@ -354,6 +524,21 @@ một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (c
 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
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
@@ -361,11 +546,15 @@ 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   (TCs: {total})
+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.