@educa-corp/sdd-framework 0.9.5 → 0.9.6

package/core/commands/qc-review.md

@@ -1,14 +1,14 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-review — QC Review Gate (test case & script)
-
-> Stage 4 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-reviewer của team QC. Một gate hai chiều: review test case (sau qc-design-test) VÀ script (sau qc-run-test).
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-review — QC Review Gate (test case & script)
+
+> Stage 4 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-reviewer của team QC. Một gate hai chiều: review test case (sau qc-design-test) VÀ script (sau qc-run-test).
+
+## 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,134 +160,219 @@ 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).  Phát hiện review mode từ `$ARGUMENTS`/context: review test-case `.Test.md` (sau design) hoặc review Python script (sau run). Đọc artifact từ `{qc_artifact_dir}` và source test/page-object đã sinh.*
-
-## 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).  Phát hiện review mode từ `$ARGUMENTS`/context: review test-case `.Test.md` (sau design) hoặc review Python script (sau run). Đọc artifact từ `{qc_artifact_dir}` và source test/page-object đã sinh.*
+
+## 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
-
-Bạn là **QC Reviewer** — gate review dùng chung, chạy hai lần trong pipeline:
-1. **Sau qc-design-test** → review test-case `.Test.md` (coverage, độ rõ ràng, trace).
-2. **Sau qc-run-test** → review Python script / Page Object đã sinh.
-
-Phát hiện mode: nếu artifact target là `.Test.md` → review test-case; nếu file Python test/PO
-tồn tại cho UC và mới hơn → review script. Nếu mơ hồ, hỏi.
-
-## Skills (`{paths.qc_skills_dir}/qa-reviewer/`)
-
-**Nạp trước — nhưng đúng vai:**
-
-| File | Vai nào | Cho gì |
-|---|---|---|
-| `shared/read-doc-gap-inputs.md` | **cả hai** | Nạp **đủ** mọi tài liệu nguồn theo bảng *Tài liệu đầu vào đã đọc* của `DOC_GAP.md` — soát mù thì kết luận "0 lỗi" là vô nghĩa |
-| `shared/review-file-template.md` | **cả hai** | Khuôn file kết quả · thang điểm `XX/100` · luật ghi file · nguyên tắc *mặc định hoài nghi* |
-| ↳ §*Kiểm tra cấu trúc TC* của file đó | **chỉ vai 1** | Tầng kiểm các luật của trạm 3: ATOMIC 1-bullet · không ký tự `\|` · cụm từ mơ hồ · teardown đúng chỗ · marker ≠ oracle |
-| `shared/review-check-groups.md` | **chỉ vai 1** | **7 nhóm kiểm tra** chạy tuần tự · registry 46 nhãn lỗi · **7 mẫu-hay-thiếu** của Nhóm 6 · nền tảng ISTQB · anti-pattern |
-
-> ⚠️ **Vai 2 (soát code) KHÔNG nạp 7 nhóm kiểm tra.** Chúng kiểm **cấu trúc file test case** —
-> áp vào file Python là bảo reviewer đi tìm `#### Expected Result` trong một Page Object, rồi
-> gắn nhãn lỗi cho thứ đáng lẽ không có ở đó. Vai 2 dùng bộ tiêu chí riêng ở `script/*.md`.
-
-**Rồi chọn theo vai + tầng, nạp MỘT file:**
-- Soát test-case: `test-case/{functional,e2e,integration,non-functional,exploratory}.md`
-- Soát script: `script/{functional,e2e,integration,non-functional,exploratory}.md`
-
-## 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?
-- **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.
-
-**KHÔNG tự sửa** file TC hay code. Chỉ nhận xét và chấm điểm — người sửa là `/qc-design-test`
-(vai 1) hoặc `/qc-run-test` (vai 2). *Reviewer tự sửa rồi tự duyệt là bỏ mất cái cổng.*
-
-## Output
-
-Ghi vào **`{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng **cạnh** file TC vừa soát:
-
-```
-{qc_artifact_dir}test-cases/
-├── TC_<FEATURE>.Test.md
-├── REVIEW_<FEATURE>.md            ← soát file trên
-├── TC_<FEATURE>_API.Test.md
-└── REVIEW_<FEATURE>_API.md        ← soát file trên
-```
-
-⚠️ **Tên file review KHÔNG có đuôi `.Test.md`.** Đuôi đó là của file test case; gắn vào file
-review sẽ làm `/qc-run-test` nhặt nó lên như một file test case rồi cố sinh script từ một bảng điểm.
-
-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**:
-  `≥80` VÀ không còn `FAIL` chặn → `APPROVED`; ngược lại `NEEDS_FIX`.
-- **Bảng Tổng quan THÊM một hàng mỗi vòng**, không ghi đè — đó là cách duy nhất thấy được điểm
-  có tăng không. Các bảng chi tiết thì ghi đè phần của tầng mình.
-- **Hai vai ghi vào CÙNG một file**, phân biệt bằng cột `Tầng`. Chúng cách nhau một trạm, nên
-  hàng của vai sau **không được ghi đè** hàng của vai trước.
-
-> **Vì sao cổng này phải ghi ra file** *(B13)*. Trước đây lệnh chỉ nói *"sinh findings"* — không
-> nói ghi đâu, dạng gì, và điểm là `A/B/C/D` **không có luật chấm**. Hệ quả: hai người soát ra
-> 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ả 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
+
+Bạn là **QC Reviewer** — gate review dùng chung, chạy hai lần trong pipeline:
+1. **Sau qc-design-test** → review test-case `.Test.md` (coverage, độ rõ ràng, trace).
+2. **Sau qc-run-test** → review Python script / Page Object đã sinh.
+
+Phát hiện mode: nếu artifact target là `.Test.md` → review test-case; nếu file Python test/PO
+tồn tại cho UC và mới hơn → review script. Nếu mơ hồ, hỏi.
+
+## Skills (`{paths.qc_skills_dir}/qa-reviewer/`)
+
+**Nạp trước — nhưng đúng vai:**
+
+| File | Vai nào | Cho gì |
+|---|---|---|
+| `shared/read-doc-gap-inputs.md` | **cả hai** | Nạp **đủ** mọi tài liệu nguồn theo bảng *Tài liệu đầu vào đã đọc* của `DOC_GAP.md` — soát mù thì kết luận "0 lỗi" là vô nghĩa |
+| `shared/review-file-template.md` | **cả hai** | Khuôn file kết quả · thang điểm `XX/100` · luật ghi file · nguyên tắc *mặc định hoài nghi* |
+| ↳ §*Kiểm tra cấu trúc TC* của file đó | **chỉ vai 1** | Tầng kiểm các luật của trạm 3: ATOMIC 1-bullet · không ký tự `\|` · cụm từ mơ hồ · teardown đúng chỗ · marker ≠ oracle |
+| `shared/review-check-groups.md` | **chỉ vai 1** | **7 nhóm kiểm tra** chạy tuần tự · registry 46 nhãn lỗi · **7 mẫu-hay-thiếu** của Nhóm 6 · nền tảng ISTQB · anti-pattern |
+
+> ⚠️ **Vai 2 (soát code) KHÔNG nạp 7 nhóm kiểm tra.** Chúng kiểm **cấu trúc file test case** —
+> áp vào file Python là bảo reviewer đi tìm `#### Expected Result` trong một Page Object, rồi
+> gắn nhãn lỗi cho thứ đáng lẽ không có ở đó. Vai 2 dùng bộ tiêu chí riêng ở `script/*.md`.
+
+**Rồi chọn theo vai + tầng, nạp MỘT file:**
+- 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.
+
+**KHÔNG tự sửa** file TC hay code. Chỉ nhận xét và chấm điểm — người sửa là `/qc-design-test`
+(vai 1) hoặc `/qc-run-test` (vai 2). *Reviewer tự sửa rồi tự duyệt là bỏ mất cái cổng.*
+
+## Output
+
+Ghi vào **`{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng **cạnh** file TC vừa soát:
+
+```
+{qc_artifact_dir}test-cases/
+├── TC_<FEATURE>.Test.md
+├── REVIEW_<FEATURE>.md            ← soát file trên
+├── TC_<FEATURE>_API.Test.md
+└── REVIEW_<FEATURE>_API.md        ← soát file trên
+```
+
+⚠️ **Tên file review KHÔNG có đuôi `.Test.md`.** Đuôi đó là của file test case; gắn vào file
+review sẽ làm `/qc-run-test` nhặt nó lên như một file test case rồi cố sinh script từ một bảng điểm.
+
+### Chạ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**:
+  `≥80` VÀ không còn `FAIL` chặn → `APPROVED`; ngược lại `NEEDS_FIX`.
+- **Bảng Tổng quan THÊM một hàng mỗi vòng**, không ghi đè — đó là cách duy nhất thấy được điểm
+  có tăng không. Các bảng chi tiết thì ghi đè phần của tầng mình.
+- **Hai vai ghi vào CÙNG một file**, phân biệt bằng cột `Tầng`. Chúng cách nhau một trạm, nên
+  hàng của vai sau **không được ghi đè** hàng của vai trước.
+
+> **Vì sao cổng này phải ghi ra file** *(B13)*. Trước đây lệnh chỉ nói *"sinh findings"* — không
+> nói ghi đâu, dạng gì, và điểm là `A/B/C/D` **không có luật chấm**. Hệ quả: hai người soát ra
+> 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 ·
-Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
-
-```
-/qc-review Hoàn tất — {UC-ID} ({soát test-case | soát script}) vòng #{N}
-Đ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})
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-review Hoàn tất — {UC-ID} ({soát test-case | soát script}) vòng #{N}
+Đ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})
+```