@educa-corp/sdd-framework 0.9.3 → 0.9.4

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

@@ -1,6 +1,6 @@
 ---
 version: 1.0
-updated: 2026-06-11
+updated: 2026-09-04
 ported_from: ai-automation-qc-base
 ---
 
@@ -9,6 +9,9 @@ ported_from: ai-automation-qc-base
 > 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ó.
@@ -174,136 +177,73 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ## Phạm vi QC
 
-# QC Scope — phân giải phạm vi cho mọi lệnh `qc-*`
-
-**Chạy TRƯỚC phần logic riêng của lệnh, và SAU `steps/gate.md`.** Bước này chốt bốn thứ mà
-cả 6 trạm QC đều cần, để chúng không tự suy mỗi trạm một kiểu:
-
-| Biến | Là gì |
-|---|---|
-| `TICKET-ID` | mã PRD — **thư mục artifact QC mang tên này** |
-| `active_platform` | `web` \| `app` \| `system` \| … — một QC pass khoá đúng MỘT nền |
-| `qc_artifact_dir` | `{paths.qc_dir}/{TICKET-ID}/{active_platform}/` |
-| `uc_list` | các UC của (PRD × nền) này, kèm trạng thái BDD từng UC |
-
-> **Vì sao gom về một chỗ.** Luật phân giải nền từng được copy-paste ở 5 lệnh và câu chữ đã
-> lệch nhau. Năm bản của một luật là nơi drift sống: sửa bốn, quên một, và trạm bị quên ghi
-> artifact vào sai thư mục **trong im lặng**.
-
----
-
-## 1 — `TICKET-ID`
-
-Artifact QC gom theo **PRD**, không theo UC. Nên mọi trạm phải quy được về `TICKET-ID`:
-
-| `$ARGUMENTS` là | Cách lấy |
-|---|---|
-| **UC-ID** (`{TICKET-ID}-UC{N}`) | phần **trước** `-UC` — đúng luật `steps/gate.md` Bước 1 dùng để tìm tech-doc gộp |
-| **TICKET-ID** | dùng trực tiếp |
-| một **path file** (`.feature` / PRD / design-spec) | phân giải `{domain}` + `{prd-slug}` theo luật `context-loader` Bước 1, rồi lấy `TICKET-ID` từ tên file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder |
-
-Đối chiếu: `TICKET-ID` suy ra phải khớp tên file PRD thật. Lệch → **DỪNG**, in cả hai giá
-trị. (Suy sai `TICKET-ID` là ghi cả một PRD vào sai thư mục — không có bước nào phía sau bắt được.)
-
----
-
-## 2 — `active_platform`
-
-> **PHẢI phân giải TRƯỚC mọi phép đọc `.feature`.** `{UC-ID}-SC{N}` chỉ độc nhất trong
-> (UC × nền), nên một UC đa nền có **nhiều file `.feature`** — `bdd/web/`, `bdd/app/`,
-> `bdd/system/` — và mỗi file mang `@trace.status` **riêng**: bản web có thể `approved`
-> trong khi bản app còn `draft`. Đọc "file `.feature` của UC" khi chưa biết nền là đọc một
-> file **bất kỳ trong ba**: báo `approved` trong khi bản đang dùng còn nháp, hoặc chặn oan
-> một bản đã duyệt.
-
-Theo thứ tự, dừng ở cái đầu tiên khớp:
-
-1. `$ARGUMENTS` nêu nền (`web`/`app`/`system`/…) → dùng.
-2. Target là một file `.feature` → đọc `# @trace.platform` của nó.
-3. Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/*/` — **đúng một** thư mục nền → dùng nó.
-4. Glob `{paths.qc_dir}/{TICKET-ID}/*/` — **đúng một** thư mục nền đã có artifact → dùng nó.
-   *(chỉ dùng cho trạm 2–6; trạm `/qc-analyze` là trạm tạo ra thư mục đó nên không có gì để soi.)*
-5. Nhiều nền mà không suy được → hỏi *"QC pass này cho nền nào? (web/app/system)"*.
-   **Có `--yes`:** không hỏi — DỪNG với lỗi rõ ràng, vì đoán bừa nền là ghi artifact vào sai
-   thư mục và ghi `qc_status` vào sai sổ trace:
-   ```
-   ❌ {TICKET-ID} có {n} nền ({list}) — không suy được nền nào cho QC pass này.
-      Chạy headless thì phải nêu tường minh: /{lệnh} {TICKET-ID} web --yes
-   ```
-
-Lưu `active_platform`. Từ đây, **mọi** phép đọc `.feature` chỉ đọc thư mục
-`bdd/{active_platform}/` — không trộn SC chéo nền.
-
----
-
-## 3 — `qc_artifact_dir`
-
-```
-qc_artifact_dir = {paths.qc_dir}/{TICKET-ID}/{active_platform}/
-```
-
-Chứa: `REQUIREMENT_ANALYSIS.md` · `DOC_GAP.md` · `TEST_PLAN.md` · `test-cases/*.Test.md`
-— **mỗi loại đúng MỘT file cho cả PRD**, các UC là mục/hàng bên trong.
+**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.
 
-`{paths.qc_dir}` là folder top-level **nhìn thấy** trong repo QC (mặc định `docs/`, **không**
-phải `.agent/` ẩn) để đội QC mở và xử lý output dễ dàng. Spec chính thức ở lại spec submodule
-của PO — đừng ghi artifact QC vào đó.
+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.
 
-> **Sổ trace KHÔNG theo layout này.** Nó vẫn là `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv`
-> — một sổ cho mỗi (UC × nền), vì mỗi hàng là một scenario. Liên kết giữa hai bên đi qua
-> **cột `UC`** của bảng gap, không qua đường dẫn file.
+> **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.
 
 ---
 
-## 4 — `uc_list`
+## Cờ — chọn tầng nào, tách mịn đến đâu
 
-Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/*.feature`. Mỗi file → một
-UC: đọc `# @trace.id` (mã UC) và `# @trace.status` từ header.
-
-Chia hai nhóm:
-
-| Nhóm | Điều kiện | Xử lý |
+| Cờ | Ghi file | Nhóm |
 |---|---|---|
-| **Trong phạm vi** | `@trace.status: approved` | phân tích / thiết kế / chạy bình thường |
-| **Chưa xét** | khác `approved` | **KHÔNG** phân tích; vẫn ghi một hàng vào bảng phạm vi kèm trạng thái thật |
+| *(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) |
 
-In bảng phạm vi ra trước khi làm gì:
-```
-Phạm vi QC — {TICKET-ID} / {active_platform}
-  ✅ {UC-ID}  {tên UC}                     approved
-  ⏸  {UC-ID}  {tên UC}                     draft   → chưa xét
-  → {n} UC trong phạm vi · {m} chưa xét
-```
+**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`.
 
-**Cờ `--include-draft`:** phân tích cả UC chưa duyệt, nhưng **vẫn in bảng trên** và đánh dấu
-trong artifact là dựa trên BDD nháp.
+> **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ũ.
 
-**Không UC nào `approved` và không có `--include-draft` → DỪNG:**
-```
-❌ {TICKET-ID} ({active_platform}): 0/{n} UC có BDD approved — không có gì để chạy.
-   Cách đúng: người duyệt đặt `# @trace.status: approved` rồi chạy lại.
-   Muốn chạy sớm trên BDD nháp (prototype): thêm --include-draft
-```
+### `--atomic-max` — tách tới mức nhỏ nhất
 
-> **Vì sao có `--include-draft` chứ không chặn cứng.** QC sớm trên BDD nháp là một cách dùng
-> **cố ý được cho phép** từ trước (guard cũ là cảnh báo mềm, không phải chặn). Bỏ hẳn nó là
-> lấy đi một năng lực đang có mà không ai khai. Còn để mặc định `approved`-only thì cái
-> thường gặp là cái an toàn, và cái sớm phải nói ra.
+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.
 
-> **Vì sao `--yes` không thay được `--include-draft`.** `--yes` nghĩa *"tôi không ngồi đây để
-> trả lời"*; `--include-draft` nghĩa *"tôi biết BDD còn nháp và vẫn muốn chạy"*. Gộp hai cái
-> là để một lần chạy headless âm thầm phân tích spec chưa chốt rồi bàn giao như thể đã chốt.
+`--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)*:
 
-> **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.
+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.
 
 ---
 
@@ -313,44 +253,78 @@ Bạn là **QC Designer** — stage 3. Sinh/bảo trì các file test-case Markd
 (`.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 — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-designer/`)
+## 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:**
 
-| Layer | File |
+| Khi nào | Nạp |
 |---|---|
-| 1 màn hình | `functional/gui-screen.md` |
-| Feature đa-màn | `functional/gui-feature.md` |
-| API endpoint | `functional/api.md` |
-| Integration | `integration/{api,db,gui,kafka}.md` |
-| End-to-end journey | `e2e/journey.md` |
-| Non-functional | `non-functional.md` |
-| Exploratory | `exploratory/{charter,explore-to-functional}.md` |
+| **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.
-- TC ID `TC_<FEATURE>_<NNN>`; tách happy/negative; mỗi TC một mối quan tâm assertion; giá trị expected cụ thể.
-- Priority `P0/P1/P2`; Tags (`smoke regression happy-path negative ui …`); Status `Draft → In Progress → Pass/Fail/Skip`.
-- Một TC bị block bởi gap vẫn được viết + đánh dấu `🚫 Block: GAP-xx`.
 - **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).
-- **Ghi `@trace.testid_attr` vào đầu `.Test.md`.** Đọc field này từ header tech-doc gộp (do `/map-testids` ghi) và ghi lại một dòng ở phần metadata của file test-case: `Test-ID attribute: {attr}`. Lý do: §4.5.6 chỉ cho **giá trị** test-id, còn đây là **tên thuộc tính** chứa chúng — `/qc-run-test` cần nó để cấu hình locator, và `/qc-review` cần nó để biết selector trong script có đúng contract không. Thiếu field trong tech-doc → ghi `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)` thay vì bỏ trống hoặc tự đoán.
-- Cuối file: Trace matrix + bảng TC bị block.
+- **Đọ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:
-`@trace.verifies={UC-ID}-SC{N}` (từ `@trace.scenario` của `.feature`). Thêm một cột **Trace SC**
-vào Trace matrix. Một SC có thể map nhiều TC. Đây là join key cho phép
-qc-run-test ghi `qc_status` theo từng scenario.
+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 các file `.Test.md` dưới `{qc_artifact_dir}test-cases/`
-(= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/test-cases/`) — **một thư mục test-case dùng
-chung cho cả PRD**. Tên file mang `<FEATURE>` nên các UC không đâm nhau; cột **Trace SC** là
-chỗ phân biệt TC thuộc UC nào.
+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**.
 
-Dòng `🚫 Block: [GAP-UC{N}-{nnn}](DOC_GAP.md)` trỏ **liên kết tương đối một cấp lên**
-(`DOC_GAP.md` nằm ở thư mục cha của `test-cases/`) — đúng như trước, layout đổi không ảnh hưởng.
+`🚫 Block` trỏ `../DOC_GAP.md` — lên một cấp, vì file gap ở thư mục cha của `test-cases/`.
 
 ## Report
 
@@ -358,8 +332,14 @@ Dòng `🚫 Block: [GAP-UC{N}-{nnn}](DOC_GAP.md)` trỏ **liên kết tương đ
 Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
-/qc-design-test Hoàn tất — {UC-ID}
-Test cases: {N} TC qua {layers} · {blocked} bị block bởi gap
-Trace: {N} TC map tới {K}/{total} scenario
-Next: /qc-review {UC-ID}   ← review test case trước khi sinh script
+/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
 ```

package/core/commands/qc-plan.md

@@ -176,126 +176,13 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ## Phạm vi QC
 
-# QC Scope — phân giải phạm vi cho mọi lệnh `qc-*`
-
-**Chạy TRƯỚC phần logic riêng của lệnh, và SAU `steps/gate.md`.** Bước này chốt bốn thứ mà
-cả 6 trạm QC đều cần, để chúng không tự suy mỗi trạm một kiểu:
-
-| Biến | Là gì |
-|---|---|
-| `TICKET-ID` | mã PRD — **thư mục artifact QC mang tên này** |
-| `active_platform` | `web` \| `app` \| `system` \| … — một QC pass khoá đúng MỘT nền |
-| `qc_artifact_dir` | `{paths.qc_dir}/{TICKET-ID}/{active_platform}/` |
-| `uc_list` | các UC của (PRD × nền) này, kèm trạng thái BDD từng UC |
-
-> **Vì sao gom về một chỗ.** Luật phân giải nền từng được copy-paste ở 5 lệnh và câu chữ đã
-> lệch nhau. Năm bản của một luật là nơi drift sống: sửa bốn, quên một, và trạm bị quên ghi
-> artifact vào sai thư mục **trong im lặng**.
-
----
-
-## 1 — `TICKET-ID`
-
-Artifact QC gom theo **PRD**, không theo UC. Nên mọi trạm phải quy được về `TICKET-ID`:
-
-| `$ARGUMENTS` là | Cách lấy |
-|---|---|
-| **UC-ID** (`{TICKET-ID}-UC{N}`) | phần **trước** `-UC` — đúng luật `steps/gate.md` Bước 1 dùng để tìm tech-doc gộp |
-| **TICKET-ID** | dùng trực tiếp |
-| một **path file** (`.feature` / PRD / design-spec) | phân giải `{domain}` + `{prd-slug}` theo luật `context-loader` Bước 1, rồi lấy `TICKET-ID` từ tên file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder |
-
-Đối chiếu: `TICKET-ID` suy ra phải khớp tên file PRD thật. Lệch → **DỪNG**, in cả hai giá
-trị. (Suy sai `TICKET-ID` là ghi cả một PRD vào sai thư mục — không có bước nào phía sau bắt được.)
-
----
-
-## 2 — `active_platform`
-
-> **PHẢI phân giải TRƯỚC mọi phép đọc `.feature`.** `{UC-ID}-SC{N}` chỉ độc nhất trong
-> (UC × nền), nên một UC đa nền có **nhiều file `.feature`** — `bdd/web/`, `bdd/app/`,
-> `bdd/system/` — và mỗi file mang `@trace.status` **riêng**: bản web có thể `approved`
-> trong khi bản app còn `draft`. Đọc "file `.feature` của UC" khi chưa biết nền là đọc một
-> file **bất kỳ trong ba**: báo `approved` trong khi bản đang dùng còn nháp, hoặc chặn oan
-> một bản đã duyệt.
-
-Theo thứ tự, dừng ở cái đầu tiên khớp:
-
-1. `$ARGUMENTS` nêu nền (`web`/`app`/`system`/…) → dùng.
-2. Target là một file `.feature` → đọc `# @trace.platform` của nó.
-3. Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/*/` — **đúng một** thư mục nền → dùng nó.
-4. Glob `{paths.qc_dir}/{TICKET-ID}/*/` — **đúng một** thư mục nền đã có artifact → dùng nó.
-   *(chỉ dùng cho trạm 2–6; trạm `/qc-analyze` là trạm tạo ra thư mục đó nên không có gì để soi.)*
-5. Nhiều nền mà không suy được → hỏi *"QC pass này cho nền nào? (web/app/system)"*.
-   **Có `--yes`:** không hỏi — DỪNG với lỗi rõ ràng, vì đoán bừa nền là ghi artifact vào sai
-   thư mục và ghi `qc_status` vào sai sổ trace:
-   ```
-   ❌ {TICKET-ID} có {n} nền ({list}) — không suy được nền nào cho QC pass này.
-      Chạy headless thì phải nêu tường minh: /{lệnh} {TICKET-ID} web --yes
-   ```
-
-Lưu `active_platform`. Từ đây, **mọi** phép đọc `.feature` chỉ đọc thư mục
-`bdd/{active_platform}/` — không trộn SC chéo nền.
-
----
-
-## 3 — `qc_artifact_dir`
-
-```
-qc_artifact_dir = {paths.qc_dir}/{TICKET-ID}/{active_platform}/
-```
-
-Chứa: `REQUIREMENT_ANALYSIS.md` · `DOC_GAP.md` · `TEST_PLAN.md` · `test-cases/*.Test.md`
-— **mỗi loại đúng MỘT file cho cả PRD**, các UC là mục/hàng bên trong.
-
-`{paths.qc_dir}` là folder top-level **nhìn thấy** trong repo QC (mặc định `docs/`, **không**
-phải `.agent/` ẩn) để đội QC mở và xử lý output dễ dàng. Spec chính thức ở lại spec submodule
-của PO — đừng ghi artifact QC vào đó.
-
-> **Sổ trace KHÔNG theo layout này.** Nó vẫn là `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv`
-> — một sổ cho mỗi (UC × nền), vì mỗi hàng là một scenario. Liên kết giữa hai bên đi qua
-> **cột `UC`** của bảng gap, không qua đường dẫn file.
-
----
-
-## 4 — `uc_list`
-
-Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/*.feature`. Mỗi file → một
-UC: đọc `# @trace.id` (mã UC) và `# @trace.status` từ header.
-
-Chia hai nhóm:
-
-| Nhóm | Điều kiện | Xử lý |
-|---|---|---|
-| **Trong phạm vi** | `@trace.status: approved` | phân tích / thiết kế / chạy bình thường |
-| **Chưa xét** | khác `approved` | **KHÔNG** phân tích; vẫn ghi một hàng vào bảng phạm vi kèm trạng thái thật |
-
-In bảng phạm vi ra trước khi làm gì:
-```
-Phạm vi QC — {TICKET-ID} / {active_platform}
-  ✅ {UC-ID}  {tên UC}                     approved
-  ⏸  {UC-ID}  {tên UC}                     draft   → chưa xét
-  → {n} UC trong phạm vi · {m} chưa xét
-```
-
-**Cờ `--include-draft`:** phân tích cả UC chưa duyệt, nhưng **vẫn in bảng trên** và đánh dấu
-trong artifact là dựa trên BDD nháp.
-
-**Không UC nào `approved` và không có `--include-draft` → DỪNG:**
-```
-❌ {TICKET-ID} ({active_platform}): 0/{n} UC có BDD approved — không có gì để chạy.
-   Cách đúng: người duyệt đặt `# @trace.status: approved` rồi chạy lại.
-   Muốn chạy sớm trên BDD nháp (prototype): thêm --include-draft
-```
-
-> **Vì sao có `--include-draft` chứ không chặn cứng.** QC sớm trên BDD nháp là một cách dùng
-> **cố ý được cho phép** từ trước (guard cũ là cảnh báo mềm, không phải chặn). Bỏ hẳn nó là
-> lấy đi một năng lực đang có mà không ai khai. Còn để mặc định `approved`-only thì cái
-> thường gặp là cái an toàn, và cái sớm phải nói ra.
-
-> **Vì sao `--yes` không thay được `--include-draft`.** `--yes` nghĩa *"tôi không ngồi đây để
-> trả lời"*; `--include-draft` nghĩa *"tôi biết BDD còn nháp và vẫn muốn chạy"*. Gộp hai cái
-> là để một lần chạy headless âm thầm phân tích spec chưa chốt rồi bàn giao như thể đã chốt.
+**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 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à