@educa-corp/sdd-framework 0.9.5 → 0.9.7

package/core/commands/qc-review-testcase.md

@@ -0,0 +1,409 @@
+---
+version: 1.0
+updated: 2026-09-16
+ported_from: ai-automation-qc-base
+---
+
+# /qc-review-testcase — QC Review Gate: test case
+
+> Stage 4 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test →
+> **qc-review-testcase** → qc-design-script → qc-run-script → qc-report). Soát `.Test.md` do
+> `/qc-design-test` sinh: coverage · độ rõ · trace. Cặp với `/qc-review-script` — hai lệnh, hai vai.
+
+## Gate
+
+*Checkpoint: **không chặn** — lệnh ghi `REVIEW_<FEATURE>.md`, là BIÊN BẢN của một lượt soát: sinh lại = soát lại, không trạng thái nào tích luỹ. 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ó.
+
+## Bước 0 — Kiểm tra chế độ Sub-Agent
+
+Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
+
+1. Thử parse `$ARGUMENTS` dưới dạng JSON.
+2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
+   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
+   - Đặt target file = `payload.target_file`
+   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
+   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
+   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
+   - Đi thẳng tới phần logic riêng của lệnh.
+3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
+
+## Bước 0-B — Ghi nhận Model *(KHÔNG chặn)*
+
+*Bỏ qua nếu `_agent_mode: true` (sub-agent — orchestrator đã ghi nhận rồi).*
+
+Ghi lại **model mà bạn — agent đang chạy lệnh này — thực sự đang dùng**, rồi mang nó vào
+dòng `Model:` của report cuối (xem `report-footer`). Nếu bạn biết mình **không** phải một
+model Opus, gắn thêm cảnh báo ngay ở dòng đó.
+
+**KHÔNG hỏi người dùng. KHÔNG chờ. KHÔNG dừng.**
+
+> **Vì sao bước này từng là prompt chặn, và vì sao bỏ (GAPS-v3 G41):** bản cũ hiện khối
+> `⚙️ MODEL CHECK` rồi chờ `Y/S/N`. Ba vấn đề cùng chỉ một hướng:
+> **(1)** nó hỏi người dùng thứ mà **agent đã biết chính xác**;
+> **(2)** câu trả lời **không kiểm chứng được** — gõ `Y` xong vẫn đang chạy Haiku thì không
+> gì phát hiện;
+> **(3)** **cả `Y` lẫn `S` đều đi tiếp** — cách duy nhất để nó dừng là tự nguyện gõ `N`.
+> Tức nó **không chặn được ai**, mà tốn một lần chặn ở **mọi** lệnh. Một feature đi hết
+> pipeline dùng 20 lệnh; 30/32 lệnh chạy gate. Hai mươi lần bấm cho một tín hiệu tự-khai
+> không kiểm chứng được — và chính cái giá đó làm mòn CHECKPOINT ở Bước 3, cổng có giá trị thật.
+>
+> Khai báo trong report **mạnh hơn** hỏi: đúng nguồn (agent, không phải người), và nằm
+> **cạnh kết quả** để cân nhắc, thay vì nằm trước khi có kết quả để bấm cho xong.
+
+**Vẫn khuyến nghị Opus:** phân tích spec, review kiến trúc và sinh code đòi hỏi suy luận sâu;
+model nhỏ hơn dễ bỏ sót edge case và vi phạm kiến trúc. Đổi: `/model` → chọn Opus.
+
+## Bước 1 — Xác định Target File
+
+0. **Tách cờ trước khi resolve target.** `$ARGUMENTS` có thể lẫn các `--flag` (vd `--phase=integration`, `--comment`, `--fix`). **Loại bỏ mọi token bắt đầu bằng `--`** ra khỏi phần dùng để tìm target — chỉ giữ phần path/UC-ID/ticket. (Các flag đó do phần logic riêng của lệnh parse ở bước sau, KHÔNG phải tên file.)
+1. Nếu `$ARGUMENTS` (đã tách cờ) được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
+2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
+   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
+   - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
+   - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+
+   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
+3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
+   - Chờ người dùng chọn rồi mới tiếp tục.
+
+## Bước 2 — Chạy Context Loader
+
+Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
+Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
+
+## Bước 3 — CHECKPOINT
+
+*Bỏ qua nếu `_agent_mode: true`.*
+
+### 3a — Lệnh này có phải chặn không?
+
+| Mức | Lệnh nào | `--yes` bỏ qua đượ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ờ** |
+
+`--yes` trong `$ARGUMENTS` → bỏ qua CHECKPOINT mức *chặn thường*. (Bước 1 đã tách mọi token
+`--` 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ì**.
+> Nguồn máy đọc: `bin/trace-schema.json` → `gate.checkpoint_levels`; `self-check` **R11** fail
+> build nếu nhãn trong file lệnh lệch với schema, hoặc nếu một lệnh `hard`/`none` thiếu nhãn.
+> *(Lệnh không có dòng nào = mức **chặn thường**, mặc định.)*
+
+> **Mức *không chặn* là thực thi đúng miễn trừ mà `rules/workflow.md` đã cấp từ trước** —
+> trước G41 file đó viết *"read-only commands may skip CHECKPOINT"* còn gate thì luôn đòi.
+> Hai file cùng được nạp vào mọi lệnh mà nói ngược nhau; agent theo cái nào là tuỳ lúc.
+
+### 3b — In gì
+
+**KHÔNG lặp lại những gì `[CTX LOADED]` vừa in.** Recap của context-loader (Bước 7) đã hiện
+Stack · Platform · Layers · CLAUDE.md · Dict · Entities · Lessons · Service · Status ngay phía
+trên. CHECKPOINT chỉ thêm **một** thông tin mới là `Target`.
+
+**Mọi thứ sạch** — recap báo `Status: FULL`, không cờ nào bật → in đúng hai dòng:
+
+```
+CHECKPOINT — Target: {resolved file path}
+Tiếp tục? (Y/N)
+```
+
+**Có bất thường** → thêm một dòng cho **mỗi** trạng thái, nặng nhất lên đầu:
+
+```
+CHECKPOINT
+🔴 Service  : unresolved — {lý do context-loader đã ghi}
+⚠️ CLAUDE.md: service overlay THIẾU — dùng root (code sinh ra có thể sai stack)
+⚠️ Target   : resolve bằng wildcard — {n} file khớp, chọn {file}
+⚠️ Module   : not configured — code sinh ra sẽ dùng default
+   Status   : PARTIAL — thiếu: {danh sách}
+   Target   : {resolved file path}
+Tiếp tục? (Y/N)
+```
+
+### 3c — Cờ nào bật, cờ nào KHÔNG
+
+Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader đã tính rồi** — không phát minh
+điều kiện mới, chỉ mang thứ đang bị giấu lên chỗ người dùng phải quyết định:
+
+| Bật cờ khi | Nguồn | Mức |
+|---|---|:---:|
+| `active_service = unresolved` | context-loader Bước 2b/2c/Fallback | 🔴 |
+| `Status = MINIMAL` | recap Bước 7 | 🔴 |
+| `Status = PARTIAL` | recap Bước 7 | ⚠️ |
+| CLAUDE.md thiếu, hoặc service overlay thiếu | context-loader Bước 3 | ⚠️ |
+| Target resolve qua wildcard, hoặc nhiều file khớp mà lệnh tự chọn | Bước 1 ở trên | ⚠️ |
+| `module` không cấu hình | recap Bước 7 | ⚠️ |
+
+**KHÔNG bật cờ cho:** `Lessons: chưa có` · `Dict: missing` · `Entities: missing`. Đó là
+*"dự án chưa điền"*, không phải *"có gì đó sai"* — chúng ở lại trong recap.
+
+> **Nguyên tắc một câu:** cờ dành cho thứ **framework không chắc chắn hoặc đã phải đoán**,
+> không dành cho thứ **người dùng chưa làm**. Đẩy hết mọi thứ lên thì CHECKPOINT lại đầy như
+> cũ, và ta quay về đúng chỗ xuất phát: một cổng luôn giống nhau thì bị lướt qua.
+
+### 3d — Chờ trả lời
+
+- "Y" → tiếp tục sang các bước riêng của lệnh.
+- "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). Đọc `.Test.md` từ `{qc_artifact_dir}test-cases/`. **KHÔNG** đi tìm file code test — đó là việc của `/qc-review-script`.*
+
+## 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
+
+**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ờ `--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.
+>
+> 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 — vai test case**. Soát `.Test.md` sau `/qc-design-test`.
+
+> **Vì sao lệnh này tồn tại tách riêng** *(Đợt 2 · b1)*. Trước đây `/qc-review` làm **cả hai vai**
+> và **tự đoán** đang ở vai nào bằng cách so ngày sửa file. Ba hậu quả: (1) so ngày là phép đo
+> thời gian, không phải ý định — sửa một dòng script hôm nay rồi gọi soát test case sẽ chọn sai
+> vai; (2) người chạy chỉ biết mình gọi vai nào **sau khi** đọc kết quả; (3) **nặng nhất** — trạm
+> sau không đặt được điều kiện tiên quyết, vì `REVIEW_<FEATURE>.md` không nói nó là kết quả của
+> vai nào.
+
+**KHÔNG tự sửa** file TC. Chỉ nhận xét, chấm điểm, ra verdict — người sửa là `/qc-design-test`.
+*Reviewer tự sửa rồi tự duyệt là bỏ mất cái cổng.*
+
+## Skills (`{paths.qc_skills_dir}/qa-reviewer/`)
+
+**Nạp trước:**
+
+| File | Cho gì |
+|---|---|
+| `shared/read-doc-gap-inputs.md` | 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` | 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 đó | 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` | **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 |
+
+**Rồi chọn theo tầng, nạp MỘT file:**
+`test-case/{functional,e2e,integration,non-functional,exploratory}.md`
+
+> ⚠️ **KHÔNG nạp `script/*.md`.** Bộ đó kiểm code; áp vào `.Test.md` là gắn nhãn lỗi cho thứ
+> đáng lẽ không có ở đó. Đó là việc của `/qc-review-script`.
+
+---
+
+## 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-script   → 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
+```
+
+*(Chân này do **lệnh này** canh — `bin/trace-schema.json` → `testid_fourth_leg.checked_by`. Khi
+`/qc-review` tách đôi, vai canh về `-testcase` vì phép so chạy trên `.Test.md`; `-script` không
+thừa hưởng nó.)*
+
+**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
+
+- 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).
+
+Sinh findings (mức độ + vị trí + cách sửa), chấm điểm, ra verdict.
+
+## 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   (lệnh này)
+├── TC_<FEATURE>_API.Test.md
+└── REVIEW_<FEATURE>_API.md        ← soát file trên   (lệnh này)
+```
+
+⚠️ **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 trạm sau nhặt nó lên như một file test case rồi cố sinh script từ một bảng điểm.
+
+> **Biên bản soát SCRIPT nằm ở file KHÁC** — `REVIEW_SCRIPT_<FEATURE>.md`, do `/qc-review-script`
+> ghi. Trước Đợt 2 hai vai ghi chung một file và phân biệt bằng cột `Tầng`; tách file là để hai
+> lượt soát cách nhau vài trạm **không đè lên nhau**, và để trạm sau đọc được verdict của **đúng**
+> vai nó cần.
+
+### Verdict — hợp đồng máy đọc được
+
+File **phải** chứa đúng một dòng theo khuôn này, ở §Tổng quan:
+
+```
+**Verdict:** APPROVED
+```
+hoặc
+```
+**Verdict:** NEEDS_FIX
+```
+
+`APPROVED` khi **điểm `≥80` VÀ không còn `FAIL` chặn**; ngược lại `NEEDS_FIX`.
+
+> **Đây là contract, không phải định dạng cho đẹp.** `/qc-automation-assess` (Đợt 2 · b3) **loại**
+> khỏi lượt mọi TC chưa `APPROVED`. Đổi chuỗi này là làm trạm đó mù — nên nếu phải đổi, đổi ở cả
+> hai nơi trong cùng một commit.
+
+### 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-design-script` — đề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-testcase.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`. Hai điều bắt buộc:
+
+- **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. Verdict **suy ra được** theo luật ở trên.
+- **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 vòng mình.
+
+> **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 `.Test.md` đ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 **7 nhóm kiểm tra**, không bỏ nhóm nào? 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 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 trạm script sinh code 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-testcase Hoàn tất — {UC-ID} 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 (APPROVED) : /qc-design-script {UC-ID}
+     (NEEDS_FIX → sửa TC bị gắn cờ bằng /qc-design-test {UC-ID}, rồi chạy lại lệnh này)
+```