@educa-corp/sdd-framework 0.9.4 → 0.9.5

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

@@ -1,17 +1,17 @@
----
-version: 1.0
-updated: 2026-09-04
-ported_from: ai-automation-qc-base
----
-
-# /qc-design-test — QC Test-Case Design
-
-> Stage 3 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — Python đến sau ở /qc-run-test.
-
-## Gate
-
-*Checkpoint: **chặn thường** — lệnh ghi file test-case. `--yes` bỏ qua được (gate Bước 3a).*
-
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ai-automation-qc-base
+---
+
+# /qc-design-test — QC Test-Case Design
+
+> Stage 3 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — Python đến sau ở /qc-run-test.
+
+## Gate
+
+*Checkpoint: **chặn thường** — lệnh ghi file test-case. `--yes` bỏ qua được (gate Bước 3a).*
+
 # 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ó.
@@ -163,183 +163,247 @@ 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. Đọc output của qc-analyze + qc-plan (`REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`) từ `{qc_artifact_dir}` — **cả ba đều ở cấp PRD, lọc theo cột `UC`** để lấy phần của UC này — và file `.feature` của đúng platform đó (với `@trace.scenario` mỗi scenario). Với layer GUI, cũng đọc bảng **Test Selectors** §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này**) — các test-id ổn định mà QC sẽ định vị theo.*
-
-## Context
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Đọc output của qc-analyze + qc-plan (`REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`) từ `{qc_artifact_dir}` — **cả ba đều ở cấp PRD, lọc theo cột `UC`** để lấy phần của UC này — và file `.feature` của đúng platform đó (với `@trace.scenario` mỗi scenario). Với layer GUI, cũng đọ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**) — các test-id ổn định mà QC sẽ định vị theo.*
+
+## 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`).
 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.
-
----
-
-## Cờ — chọn tầng nào, tách mịn đến đâu
-
-| Cờ | Ghi file | Nhóm |
-|---|---|---|
-| *(không cờ)* | `TC_<FEATURE>.Test.md` | 1 GUI · 2 Validation · 3 Functional · 4 Integration (qua UI) · 5 NFR · 6 E2E |
-| `--api` | `TC_<FEATURE>_API.Test.md` | 1 Endpoint · 2 Integration API/DB/Kafka |
-| `--all` | **cả hai file** | như trên, hai file riêng biệt |
-| `--atomic-max` | — | bật chế độ tách tối đa (xem dưới) |
-
-**Câu hỏi phân file:** *"TC này verify được mà **không cần UI** không?"* → **có** = file API ·
-**không** = file giao diện. Đây đúng là Bước 2 của
-`{paths.qc_skills_dir}/qa-designer/shared/skill-decision-tree.md`.
-
-> **Vì sao hai file riêng chứ không một file rồi ghi từng nhóm** *(B12)*. `--api` chạy sau khi
-> file giao diện đã tồn tại là chuyện thường. Nếu chung một file, lần chạy `--api` phải **giữ
-> nguyên** năm nhóm kia — mà viết-lại-cả-file là đúng thứ agent hay làm. Hai file thì hai chế
-> độ **không bao giờ chạm nhau**, và không cần tin vào việc agent nhớ giữ phần cũ.
-
-### `--atomic-max` — tách tới mức nhỏ nhất
-
-Mặc định đã là ATOMIC (mỗi TC đúng một kết cục), nhưng **cho phép** bullet compound khi cả hai
-vế nói về **cùng một** kết cục — ví dụ *"form hiển thị đủ 3 trường"* vẫn là 1 TC.
-
-`--atomic-max` **nổ danh sách completeness thành từng thành phần**: thẻ hiển thị đủ 5 thông tin
-→ **5 TC**. Ở đội QC, một tính năng đi từ 82 lên 130 TC.
-
-**⛔ Thủ tục bắt buộc TRƯỚC khi ghi** *(theo `shared/precision-rules.md` §2.1)*:
-
-1. **Chốt ranh giới completeness** — hai mức có quy mô rất khác nhau:
-   | Giá trị | Nghĩa |
-   |---|---|
-   | `--atomic-max=keep-completeness` | giữ danh sách completeness là 1 TC (~95 TC ở ví dụ thật) |
-   | `--atomic-max=explode` | nổ từng thành phần (~130 TC) |
-
-   Không nêu giá trị → **HỎI** trước khi ghi, vì đây là quyết định quy mô của người chủ, không
-   phải của agent. **Có `--yes`:** không hỏi — **DỪNG** với lỗi rõ ràng:
-   ```
-   ❌ --atomic-max cần nêu ranh giới ở chế độ headless (quy mô chênh ~35%).
-      Chạy: /qc-design-test {UC-ID} --atomic-max=explode --yes
-        hoặc --atomic-max=keep-completeness --yes
-   ```
-   *(Một cổng chỉ chặn được khi có người ngồi đó thì ở chế độ headless nó không phải cổng, nó
-   là treo — cùng bài học với `steps/qc-scope.md` §2.)*
-
-2. **Dựng bản đồ tách trước khi ghi** — mỗi TC cha tách ra mấy mảnh. Đừng để agent con tự suy
-   trong lúc ghi; đó là chỗ sinh ra TC cắt cụt.
-3. **GIỮ 1 TC** cho bốn loại này kể cả ở chế độ tối đa: *predicate đa-điều-kiện định-nghĩa-một-
-   khái-niệm* · *ngưỡng* (`≥44pt`, `WCAG AA ≥4.5:1`) · *exclusivity* chọn-một · *qualifier*.
-4. **Verify bằng DIFF, không tin lời đếm của agent** — ID liên tục · mỗi Expected 1 bullet ·
-   0 ký tự `|` · Trace matrix không còn ID chết · P0/P1 khớp tag.
-
----
-
-## Role
-
-Bạn là **QC Designer** — stage 3. Sinh/bảo trì các file test-case Markdown
-(`.Test.md`) từ requirement đã phân tích + plan. Output feed vào qc-run-test (Python) và
-qc-review. Bạn **không** viết Python.
-
-## Skills (`{paths.qc_skills_dir}/qa-designer/`)
-
-**Luật dùng chung — nạp theo tầng, không nạp hết mỗi lần:**
-
-| Khi nào | Nạp |
-|---|---|
-| **Luôn** | `shared/tc-metadata-format.md` — khuôn TC · luật ATOMIC · phân nhóm · hai file `.Test.md` · Trace · `🚫 Block` · `Test-ID attribute` |
-| **Luôn** | `shared/precision-rules.md` — cấm 9 cụm mơ hồ · đơn vị theo domain · toán tử · BVA 3-hay-4 giá trị · phủ đủ ô decision table · 3 mức teardown |
-| **Luôn** | `shared/action-keywords-glossary.md` — một hành động một từ (Click/Tap/Enter/Select…) |
-| **Luôn** | `shared/implicit-scenarios.md` — 7 tình huống bắt buộc nghĩ tới, áp cho mọi nhóm |
-| Đầu phiên, một lần | `shared/read-doc-gap-inputs.md` — đọc **đủ** mọi file trong bảng *Tài liệu đầu vào đã đọc* của `DOC_GAP.md`, không chỉ đọc bản tóm tắt gap |
-| Không chắc chọn tầng nào | `shared/skill-decision-tree.md` — cây quyết định UI / Integration-GUI / E2E / Integration |
-| Thêm TC vào file đã có | `shared/duplicate-check-procedure.md` — grep trước khi viết; và **trùng chéo UC** giờ mới thực sự xảy ra vì mọi UC dùng chung một thư mục |
-| `--api` / `--all` | `api/endpoint.md` · `api/auth-chain.md` · `api/http-status-codes.md` · `api/common-headers.md` · `api/crud-sequence.md` · `api/auth-sequence.md` |
-
-**Rồi chọn tầng, nạp MỘT file:**
-
-| Layer | File | Ghi vào |
-|---|---|---|
-| 1 màn hình | `functional/gui-screen.md` | file giao diện |
-| Feature đa-màn | `functional/gui-feature.md` | file giao diện |
-| API endpoint | `functional/api.md` | **file API** |
-| Integration qua UI | `integration/gui.md` | file giao diện |
-| Integration API/DB/Kafka | `integration/{api,db,kafka}.md` | **file API** |
-| End-to-end journey | `e2e/journey.md` | file giao diện |
-| Non-functional | `non-functional.md` | theo câu hỏi phân file |
-| Exploratory | `exploratory/{charter,explore-to-functional}.md` | file giao diện |
-
-## Conventions
-
-*Khuôn TC, luật ATOMIC, phân nhóm, không-dùng-bảng, Trace, `🚫 Block`, `Test-ID attribute` —
-đều ở `shared/tc-metadata-format.md`. **Đừng lặp lại ở đây.** Dưới đây chỉ là thứ riêng của trạm:*
-
-- Markdown-first; đừng design khi requirement chưa rõ — đẩy ngược về qc-plan/qc-analyze.
-- **Tham chiếu test-id, không phải gợi ý hình ảnh.** Với mỗi step GUI tác động lên một element, trích test-id ổn định từ bảng §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") để qc-run-test dựng locator từ contract. Nếu một element có action không có test-id trong §4.5.6, ghi chú lại (qc-run-test sẽ fallback về locator role/text chậm hơn).
-- **Đọc `@trace.testid_attr` từ header tech-doc gộp** (do `/map-testids` ghi) và ghi lại một
-  dòng `Test-ID attribute: {attr}` ở metadata đầu file `.Test.md`. §4.5.6 chỉ cho **giá trị**
-  test-id; `@trace.testid_attr` là **tên thuộc tính** chứa chúng — `/qc-run-test` cần nó để cấu
-  hình locator, `/qc-review` cần nó để biết selector trong script có đúng contract không.
-  Không đọc được `@trace.testid_attr` → ghi
-  `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`; **đừng bỏ trống, đừng
-  tự đoán theo platform** — đoán sai thì mọi locator trượt 100%, vì một lý do không liên quan
-  gì tới thứ đang được test. *(Dạng dòng metadata: `shared/tc-metadata-format.md`.)*
-- Một TC bị block bởi gap **vẫn viết đủ** + `🚫 Block: [GAP-UC{N}-{nnn}](../DOC_GAP.md) — lý do`.
-  Chặn theo **UC ở cột `UC` của hàng gap đó**, không chặn cả PRD.
-
-## Trace mapping (bắt buộc)
-
-Ngoài trace `BR-xx`, mỗi TC ghi scenario framework mà nó verify — **dạng trường danh sách,
-không phải cột bảng** (file TC không có ký tự `|`):
-
-```
-- **@trace.verifies:** {UC-ID}-SC{N}
-```
-
-Lấy từ `@trace.scenario` của `.feature`. Một SC map được nhiều TC. Đây là **join key** cho phép
-qc-run-test ghi `qc_status` theo từng scenario vào sổ trace — **thiếu nó thì test vẫn chạy,
-vẫn pass/fail, nhưng kết quả không vào được sổ và không ai biết nó phủ kịch bản nào.**
-
-Cuối file: **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách TC bị block** — cả hai dạng danh sách.
-
-## Output
-
-Ghi dưới `{qc_artifact_dir}test-cases/`
-(= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/test-cases/`) — **một thư mục dùng chung cho cả
-PRD**. Tên file mang `<FEATURE>` nên các UC không đâm nhau; `@trace.verifies` là chỗ phân biệt
-TC thuộc UC nào.
-
-**Đuôi bắt buộc là `.Test.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`; ghi ra
-`TC_<FEATURE>.md` là ghi ra thứ **không trạm nào tìm thấy**, và **không có gì báo lỗi**.
-
-`🚫 Block` trỏ `../DOC_GAP.md` — lên một cấp, vì file gap ở thư mục cha của `test-cases/`.
-
-## Report
-
+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.
+
+---
+
+## Cờ — chọn tầng nào, tách mịn đến đâu
+
+| Cờ | Ghi file | Nhóm |
+|---|---|---|
+| *(không cờ)* | `TC_<FEATURE>.Test.md` | 1 GUI · 2 Validation · 3 Functional · 4 Integration (qua UI) · 5 NFR · 6 E2E |
+| `--api` | `TC_<FEATURE>_API.Test.md` | 1 Endpoint · 2 Integration API/DB/Kafka |
+| `--all` | **cả hai file** | như trên, hai file riêng biệt |
+| `--atomic-max` | — | bật chế độ tách tối đa (xem dưới) |
+
+**Câu hỏi phân file:** *"TC này verify được mà **không cần UI** không?"* → **có** = file API ·
+**không** = file giao diện. Đây đúng là Bước 2 của
+`{paths.qc_skills_dir}/qa-designer/shared/skill-decision-tree.md`.
+
+> **Vì sao hai file riêng chứ không một file rồi ghi từng nhóm** *(B12)*. `--api` chạy sau khi
+> file giao diện đã tồn tại là chuyện thường. Nếu chung một file, lần chạy `--api` phải **giữ
+> nguyên** năm nhóm kia — mà viết-lại-cả-file là đúng thứ agent hay làm. Hai file thì hai chế
+> độ **không bao giờ chạm nhau**, và không cần tin vào việc agent nhớ giữ phần cũ.
+
+### `--atomic-max` — tách tới mức nhỏ nhất
+
+Mặc định đã là ATOMIC (mỗi TC đúng một kết cục), nhưng **cho phép** bullet compound khi cả hai
+vế nói về **cùng một** kết cục — ví dụ *"form hiển thị đủ 3 trường"* vẫn là 1 TC.
+
+`--atomic-max` **nổ danh sách completeness thành từng thành phần**: thẻ hiển thị đủ 5 thông tin
+→ **5 TC**. Ở đội QC, một tính năng đi từ 82 lên 130 TC.
+
+**⛔ Thủ tục bắt buộc TRƯỚC khi ghi** *(theo `shared/precision-rules.md` §2.1)*:
+
+1. **Chốt ranh giới completeness** — hai mức có quy mô rất khác nhau:
+   | Giá trị | Nghĩa |
+   |---|---|
+   | `--atomic-max=keep-completeness` | giữ danh sách completeness là 1 TC (~95 TC ở ví dụ thật) |
+   | `--atomic-max=explode` | nổ từng thành phần (~130 TC) |
+
+   Không nêu giá trị → **HỎI** trước khi ghi, vì đây là quyết định quy mô của người chủ, không
+   phải của agent. **Có `--yes`:** không hỏi — **DỪNG** với lỗi rõ ràng:
+   ```
+   ❌ --atomic-max cần nêu ranh giới ở chế độ headless (quy mô chênh ~35%).
+      Chạy: /qc-design-test {UC-ID} --atomic-max=explode --yes
+        hoặc --atomic-max=keep-completeness --yes
+   ```
+   *(Một cổng chỉ chặn được khi có người ngồi đó thì ở chế độ headless nó không phải cổng, nó
+   là treo — cùng bài học với `steps/qc-scope.md` §2.)*
+
+2. **Dựng bản đồ tách trước khi ghi** — mỗi TC cha tách ra mấy mảnh. Đừng để agent con tự suy
+   trong lúc ghi; đó là chỗ sinh ra TC cắt cụt.
+3. **GIỮ 1 TC** cho bốn loại này kể cả ở chế độ tối đa: *predicate đa-điều-kiện định-nghĩa-một-
+   khái-niệm* · *ngưỡng* (`≥44pt`, `WCAG AA ≥4.5:1`) · *exclusivity* chọn-một · *qualifier*.
+4. **Verify bằng DIFF, không tin lời đếm của agent** — ID liên tục · mỗi Expected 1 bullet ·
+   0 ký tự `|` · Trace matrix không còn ID chết · P0/P1 khớp tag.
+
+---
+
+## Role
+
+Bạn là **QC Designer** — stage 3. Sinh/bảo trì các file test-case Markdown
+(`.Test.md`) từ requirement đã phân tích + plan. Output feed vào qc-run-test (Python) và
+qc-review. Bạn **không** viết Python.
+
+## Skills (`{paths.qc_skills_dir}/qa-designer/`)
+
+**Luật dùng chung — nạp theo tầng, không nạp hết mỗi lần:**
+
+| Khi nào | Nạp |
+|---|---|
+| **Luôn** | `shared/tc-metadata-format.md` — khuôn TC · luật ATOMIC · phân nhóm · hai file `.Test.md` · Trace · `🚫 Block` · `Test-ID attribute` |
+| **Luôn** | `shared/precision-rules.md` — cấm 9 cụm mơ hồ · đơn vị theo domain · toán tử · BVA 3-hay-4 giá trị · phủ đủ ô decision table · 3 mức teardown |
+| **Luôn** | `shared/action-keywords-glossary.md` — một hành động một từ (Click/Tap/Enter/Select…) |
+| **Luôn** | `shared/implicit-scenarios.md` — 7 tình huống bắt buộc nghĩ tới, áp cho mọi nhóm |
+| Đầu phiên, một lần | `shared/read-doc-gap-inputs.md` — đọc **đủ** mọi file trong bảng *Tài liệu đầu vào đã đọc* của `DOC_GAP.md`, không chỉ đọc bản tóm tắt gap |
+| Không chắc chọn tầng nào | `shared/skill-decision-tree.md` — cây quyết định UI / Integration-GUI / E2E / Integration |
+| Thêm TC vào file đã có | `shared/duplicate-check-procedure.md` — grep trước khi viết; và **trùng chéo UC** giờ mới thực sự xảy ra vì mọi UC dùng chung một thư mục |
+| `--api` / `--all` | `api/endpoint.md` · `api/auth-chain.md` · `api/http-status-codes.md` · `api/common-headers.md` · `api/crud-sequence.md` · `api/auth-sequence.md` |
+
+**Rồi chọn tầng, nạp MỘT file:**
+
+| Layer | File | Ghi vào |
+|---|---|---|
+| 1 màn hình | `functional/gui-screen.md` | file giao diện |
+| Feature đa-màn | `functional/gui-feature.md` | file giao diện |
+| API endpoint | `functional/api.md` | **file API** |
+| Integration qua UI | `integration/gui.md` | file giao diện |
+| Integration API/DB/Kafka | `integration/{api,db,kafka}.md` | **file API** |
+| End-to-end journey | `e2e/journey.md` | file giao diện |
+| Non-functional | `non-functional.md` | theo câu hỏi phân file |
+| Exploratory | `exploratory/{charter,explore-to-functional}.md` | file giao diện |
+
+## Conventions
+
+*Khuôn TC, luật ATOMIC, phân nhóm, không-dùng-bảng, Trace, `🚫 Block`, `Test-ID attribute` —
+đều ở `shared/tc-metadata-format.md`. **Đừng lặp lại ở đây.** Dưới đây chỉ là thứ riêng của trạm:*
+
+- Markdown-first; đừng design khi requirement chưa rõ — đẩy ngược về qc-plan/qc-analyze.
+- **Tham chiếu test-id, không phải gợi ý hình ảnh.** Với mỗi step GUI tác động lên một element, trích test-id ổn định từ bảng §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") để qc-run-test dựng locator từ contract. Nếu một element có action không có test-id trong §4.5.6, ghi chú lại (qc-run-test sẽ fallback về locator role/text chậm hơn).
+- **Đọc `@trace.testid_attr` từ header tech-doc gộp** (do `/map-testids` ghi) và ghi lại một
+  dòng `Test-ID attribute: {attr}` ở metadata đầu file `.Test.md`. §4.5.6 chỉ cho **giá trị**
+  test-id; `@trace.testid_attr` là **tên thuộc tính** chứa chúng — `/qc-run-test` cần nó để cấu
+  hình locator, `/qc-review` cần nó để biết selector trong script có đúng contract không.
+  Không đọc được `@trace.testid_attr` → ghi
+  `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`; **đừng bỏ trống, đừng
+  tự đoán theo platform** — đoán sai thì mọi locator trượt 100%, vì một lý do không liên quan
+  gì tới thứ đang được test. *(Dạng dòng metadata: `shared/tc-metadata-format.md`.)*
+- Một TC bị block bởi gap **vẫn viết đủ** + `🚫 Block: [GAP-UC{N}-{nnn}](../DOC_GAP.md) — lý do`.
+  Chặn theo **UC ở cột `UC` của hàng gap đó**, không chặn cả PRD.
+
+## Trace mapping (bắt buộc)
+
+Ngoài trace `BR-xx`, mỗi TC ghi scenario framework mà nó verify — **dạng trường danh sách,
+không phải cột bảng** (file TC không có ký tự `|`):
+
+```
+- **@trace.verifies:** {UC-ID}-SC{N}
+```
+
+Lấy từ `@trace.scenario` của `.feature`. Một SC map được nhiều TC. Đây là **join key** cho phép
+qc-run-test ghi `qc_status` theo từng scenario vào sổ trace — **thiếu nó thì test vẫn chạy,
+vẫn pass/fail, nhưng kết quả không vào được sổ và không ai biết nó phủ kịch bản nào.**
+
+Cuối file: **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách TC bị block** — cả hai dạng danh sách.
+
+## Guard — SC coverage *(phép ĐẾM cơ học, chạy SAU khi ghi file, TRƯỚC CHECKPOINT)*
+
+Dòng `Trace:` ở report cuối đã đòi con số `{K}/{total}` từ trước. Guard này là **phép tính sinh
+ra con số đó**, và là **hệ quả khi `K < total`** — trước đây có số mà không có phép tính nào
+đứng sau, nên nó là ước lượng, và `K < total` không dẫn tới việc gì.
+
+### Ba bước
+
+1. **Thu SC** — mọi `@trace.scenario` trong `.feature` của `uc_list` (đúng `active_platform`).
+   **Loại** SC của UC mà `qc-scope` đã lọc ra (`⏸ chưa xét` — BDD chưa approved): chúng nằm
+   ngoài phạm vi lần chạy này, không phải bỏ sót.
+2. **Thu V** — mọi `@trace.verifies` trong các file `*.Test.md` **vừa ghi**.
+3. **Đếm** — mỗi SC ∈ tập ở bước 1 phải có **≥ 1** TC trỏ tới.
+
+### Xử lý
+
+| Kết quả | Làm gì |
+|---|---|
+| Mọi SC đều có ≥1 TC | in `Guard SC coverage: khớp {K}/{K}` |
+| Có SC chưa phủ | **viết bù TC ngay**, rồi in `⚠️ Guard SC coverage: {K}/{total} — đã bù {m} SC: {danh sách}` |
+
+**Không có đường "bỏ trống có lý do".** Đây là chỗ dễ làm sai nhất, và quy ước ở §Conventions
+đã trả lời: *"Một TC bị block bởi gap **vẫn viết đủ** + `🚫 Block: [GAP-UC{N}-{nnn}](../DOC_GAP.md)`"*.
+Nghĩa là **gap không phải cái cớ để không viết TC** — nó là thứ được **ghi vào TC**. SC bị chặn
+vẫn có TC, vẫn được đếm là đã phủ.
+
+Nên chỉ còn đúng hai trạng thái, và cả hai đều không cho phép bỏ trống:
+
+- SC **trong** phạm vi → phải có TC (bị gap chặn thì TC mang dấu `🚫 Block`).
+- SC **ngoài** phạm vi → đã bị `qc-scope` lọc ở bước 1, không tính vào mẫu số.
+
+Nếu bạn thấy một SC "không thể viết TC" mà không thuộc hai loại trên, thì **đó là một gap** —
+mở gap trong `DOC_GAP.md`, viết TC kèm `🚫 Block` trỏ tới nó. Đừng viết một câu lý do rồi đi
+tiếp: guard viết lỏng thì lần sau sẽ có một câu lý do cho qua, và phép đếm mất nghĩa.
+
+**In dòng `Guard SC coverage:` kể cả khi sạch** — guard im lặng khi sạch là guard không ai biết
+nó tồn tại, và không ai phát hiện được khi nó chết.
+
+> **Vì sao đếm ở đây mà không đợi báo cáo cuối.** `/qc-report` (Đợt 3 của đợt mổ QC) sẽ tính
+> **design coverage** bằng **đúng phép đếm này**. Khác nhau ở thời điểm: guard đếm **lúc thiết
+> kế** — còn kịp viết bù; báo cáo đếm **ở cuối** — chỉ còn kịp báo. Phát hiện "design coverage
+> 68%" ở phút cuối là lúc không còn thời gian viết bù 32%.
+>
+> **Vì sao "chưa có TC" khác "có TC nhưng chưa chạy".** Hai trạng thái này dẫn tới hai việc khác
+> nhau hoàn toàn — viết test, so với chạy test. Nhưng nhìn vào sổ trace thì giống nhau: cả hai
+> đều là `qc_status = not_run`. Guard này là chỗ duy nhất phân biệt được.
+
+## Output
+
+Ghi dưới `{qc_artifact_dir}test-cases/`
+(= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/test-cases/`) — **một thư mục dùng chung cho cả
+PRD**. Tên file mang `<FEATURE>` nên các UC không đâm nhau; `@trace.verifies` là chỗ phân biệt
+TC thuộc UC nào.
+
+**Đuôi bắt buộc là `.Test.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`; ghi ra
+`TC_<FEATURE>.md` là ghi ra thứ **không trạm nào tìm thấy**, và **không có gì báo lỗi**.
+
+`🚫 Block` trỏ `../DOC_GAP.md` — lên một cấp, vì file gap ở thư mục cha của `test-cases/`.
+
+## 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 TC kiểm một hành vi **spec có nêu** — không phải hành vi tôi cho là hợp lý? Mỗi
+  `Expected` là **giá trị cụ thể** (*"hiển thị text 'Tên lớp: Toán 6A'"*), không phải *"hiển thị
+  đúng"* / *"hoạt động bình thường"*?
+- **Nhảy bước:** đã áp luật ATOMIC cho **mọi** TC (không chỉ vài TC đầu), và đã chạy
+  §duplicate-check trước khi thêm TC mới?
+- **Số liệu:** `{n}` TC mỗi file = `grep -cE "^#{2,4} *TC_"` thật? Các con số phân nhóm (GUI /
+  Validation / Functional / …) cộng lại đúng bằng tổng TC?
+
+> Guard SC coverage ở trên là **phép đếm cơ học**, không phải self-review — nó đối chiếu với
+> `.feature`, một nguồn khác. Đừng coi self-review đã bao nó. Xem §Ranh giới trong file skill.
+
+## 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-design-test Hoàn tất — {UC-ID} ({active_platform})
-Chế độ: {giao diện | API | cả hai}{nếu --atomic-max: " · tách tối đa ({explode|keep-completeness})"}
-Files: {qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md      — {n} TC
-       {nếu có: "…_API.Test.md   — {m} TC"}
-Nhóm : GUI {a} · Validation {b} · Functional {c} · Integration {d} · NFR {e} · E2E {f}
-       {nếu file API: "Endpoint {g} · Integration API/DB/Kafka {h}"}
-Trùng: {k} TC bỏ vì trùng ({j} trùng chéo UC — trỏ trace về UC nguồn thay vì viết lại)
-Block: {blocked} TC bị chặn bởi gap — theo UC: {UC1: n · UC2: n}
-Trace: {N} TC map tới {K}/{total} scenario của {UC-ID}
-Next : /qc-review {UC-ID}   ← review test case trước khi sinh script
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-design-test Hoàn tất — {UC-ID} ({active_platform})
+Chế độ: {giao diện | API | cả hai}{nếu --atomic-max: " · tách tối đa ({explode|keep-completeness})"}
+Files: {qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md      — {n} TC
+       {nếu có: "…_API.Test.md   — {m} TC"}
+Nhóm : GUI {a} · Validation {b} · Functional {c} · Integration {d} · NFR {e} · E2E {f}
+       {nếu file API: "Endpoint {g} · Integration API/DB/Kafka {h}"}
+Trùng: {k} TC bỏ vì trùng ({j} trùng chéo UC — trỏ trace về UC nguồn thay vì viết lại)
+Block: {blocked} TC bị chặn bởi gap — theo UC: {UC1: n · UC2: n}
+Trace: {N} TC map tới {K}/{total} scenario của {UC-ID}
+Guard SC coverage: {khớp {K}/{K} | ⚠️ {K}/{total} — đã bù {m} SC: {danh sách SC}}
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next : /qc-review {UC-ID}   ← review test case trước khi sinh script
+```