@educa-corp/sdd-framework 0.9.2 → 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ó.
@@ -162,7 +165,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (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. **Phân giải `active_platform`** (QC pass khoá 1 platform): nếu `$ARGUMENTS` nêu platform → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi. Đọc output của qc-analyze + qc-plan (`REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`) từ `{paths.qc_dir}/{UC-ID}/{active_platform}/` 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.*
+*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
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -172,6 +175,76 @@ Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, gua
 `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ờ `--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
@@ -180,38 +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 `{paths.qc_dir}/{UC-ID}/{active_platform}/test-cases/`.
+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
 
@@ -219,8 +332,14 @@ Ghi các file `.Test.md` dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/test-
 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

@@ -162,7 +162,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (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. **Phân giải `active_platform`** (QC pass khoá 1 platform — artifact dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`): nếu `$ARGUMENTS` nêu platform (web/app/system) → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi platform nào. Đọc output của qc-analyze (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) từ `{paths.qc_dir}/{UC-ID}/{active_platform}/` và file `.feature` của đúng platform đó.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một **TICKET-ID** (mã PRD) — hoặc UC-ID / file feature, cả hai quy về TICKET-ID ở §Phạm vi QC. Đọc output của qc-analyze (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) từ `{qc_artifact_dir}` và file `.feature` của đúng nền đó.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -174,6 +174,27 @@ 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 chạy CẢ PRD, đúng như trạm 1** *(B11)* — một `TEST_PLAN.md` cho mỗi (PRD × nền).
+> `qa-planner/test-plan.md` vốn viết *"Test Plan cho một **feature**"* và template của nó là
+> `# Test Plan – <Feature>` với metadata `Feature / Project / Module`: đây là quay về đúng
+> tầng mà skill gốc được viết cho.
+>
+> `uc_list` ở đây **phải khớp** bảng *Phạm vi phân tích* trong `DOC_GAP.md`. Lệch nhau nghĩa là
+> BDD đã đổi trạng thái sau lần chạy trạm 1 → nêu ra và khuyên chạy lại `/qc-analyze`, đừng
+> âm thầm lập plan cho một tập UC khác với tập đã phân tích.
+
+---
+
 ## Role
 
 Bạn là **QC Planner** — stage 2. Từ output của qc-analyze, tạo TEST PLAN:
@@ -192,9 +213,18 @@ thiết kế test case cụ thể (đó là qc-design-test).
 
 ## Output
 
-Ghi test plan vào `{paths.qc_dir}/{UC-ID}/{active_platform}/TEST_PLAN.md`. Giới hạn plan trong
-các scenario của UC (`{UC-ID}-SC{N}` từ `.feature` của platform này) để qc-design-test thiết kế
-case theo từng scenario.
+Ghi **đúng MỘT** test plan cho cả PRD vào `{qc_artifact_dir}TEST_PLAN.md`
+(= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/TEST_PLAN.md`). Giới hạn plan trong các
+scenario của **các UC trong phạm vi** (`{UC-ID}-SC{N}` từ `.feature` của nền này) để
+qc-design-test thiết kế case theo từng scenario.
+
+Bắt buộc:
+- **Bảng `§3 Test items` có cột `UC`** — một plan giờ phủ nhiều UC, không có cột đó thì không
+  ai biết vùng test nào thuộc UC nào.
+- **`§2 Phạm vi`** liệt kê rõ UC `⏸ Chưa xét` ở phần *Out of scope*, kèm lý do (BDD chưa
+  approved). *Không có dòng này thì một UC bị bỏ trông giống một UC không có gì để test.*
+- **`§5 Entry criteria` chặn theo từng UC**, không chặn cả PRD: gap 🔴 Blocker ở UC3 không
+  dừng việc thiết kế test cho UC1. Ghi `Ready` / `Blocked` cho **mỗi** UC.
 
 ## Report
 
@@ -202,8 +232,11 @@ case theo từng scenario.
 Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
-/qc-plan Hoàn tất — {UC-ID}
+/qc-plan Hoàn tất — {TICKET-ID} ({active_platform})
+Phạm vi: {n} UC trong plan{nếu có: " · ⏸ {m} chưa xét"}
 Plan: {risks} rủi ro · {questions} câu hỏi mở cho dev · layers: {list}
-Next: /qc-design-test {UC-ID}   ← thiết kế test case
-      (gửi questions-for-dev cho PO/Dev nếu còn blocker)
+File: {paths.qc_dir}/{TICKET-ID}/{active_platform}/TEST_PLAN.md
+Sẵn sàng: {danh sách UC Ready} | Chặn: {danh sách UC Blocked + GAP-ID chặn nó}
+Next: /qc-design-test {UC-ID}   ← thiết kế test case, chạy cho từng UC đã Ready
+      (gửi questions-for-dev cho PO/Dev cho các UC còn Blocked)
 ```

package/core/commands/qc-review.md

@@ -162,7 +162,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (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. **Phân giải `active_platform`** (QC pass khoá 1 platform): nếu `$ARGUMENTS` nêu platform → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏ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ừ `{paths.qc_dir}/{UC-ID}/{active_platform}/` và source test/page-object đã sinh.*
+*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 đó**,
@@ -172,6 +172,26 @@ Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, gua
 `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ờ `--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.
+
+---
+
+
 ---
 
 ## Role
@@ -185,16 +205,61 @@ 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/`)
 
-Chọn theo mode + layer, nạp MỘT file:
-- Review test-case: `test-case/{functional,e2e,integration,non-functional,exploratory}.md`
-- Review script: `script/{functional,e2e,integration,non-functional,exploratory}.md`
+**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 (severity + vị trí + fix). Verdict APPROVED hoặc NEEDS_FIX.
+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.
 
 ## Report
 
@@ -202,8 +267,10 @@ Sinh findings (severity + vị trí + fix). Verdict APPROVED hoặc NEEDS_FIX.
 Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
-/qc-review Hoàn tất — {UC-ID} ({test-case | script} review)
-Verdict: {APPROVED | NEEDS_FIX} — {N} findings ({crit} critical)
+/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)
 Next (test-case APPROVED): /qc-run-test {UC-ID}
 Next (script APPROVED)   : /qc-report {UC-ID}  rồi tạo PR
      (NEEDS_FIX → fix artifact bị gắn cờ, rồi chạy lại /qc-review {UC-ID})

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

@@ -162,7 +162,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (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. **Phân giải `active_platform`** (QC pass khoá 1 platform): nếu `$ARGUMENTS` nêu platform → dùng; else glob `{paths.qc_dir}/{UC-ID}/*/` — đúng 1 folder platform → dùng nó, nhiều folder → hỏi. `active_platform` này CHÍNH LÀ platform của sổ trace sẽ ghi `qc_status` (`{UC-ID}-{active_platform}.tsv`) — nên `@trace.verifies={UC-ID}-SC{N}` resolve không nhập nhằng. Đọc `.Test.md` đã review từ `{paths.qc_dir}/{UC-ID}/{active_platform}/test-cases/`. Lệnh này dùng stack module **qc-playwright** (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — độc lập với module implementation của dev.*
+*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).  `active_platform` này CHÍNH LÀ platform của sổ trace sẽ ghi `qc_status` (`{UC-ID}-{active_platform}.tsv`) — nên `@trace.verifies={UC-ID}-SC{N}` resolve không nhập nhằng. Đọc `.Test.md` đã review từ `{qc_artifact_dir}test-cases/`. Lệnh này dùng stack module **qc-playwright** (`.agent/modules/qc-playwright/stack-profile.yaml`) — Python + pytest-playwright + Page Object — độc lập với module implementation của dev.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -172,6 +172,26 @@ Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, gua
 `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ờ `--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.
+
+---
+
+
 ---
 
 ## Role & stack (theo module qc-playwright)

package/core/commands/setup-ai-first.md

@@ -448,13 +448,13 @@ Hướng dẫn: "Mở `specs/domain-knowledge/core-entities.md` và định ngh
 
 ## Step 6 — Cài VS Code Extension (Khuyến nghị)
 
-Khuyến nghị user cài extension VS Code **Spec Driven Docs Tools** — nó cung cấp panel Review Board + Living Documentation tích hợp với workflow này.
+Khuyến nghị user cài extension VS Code **SDD Board** — nó cung cấp panel Review Board + Living Documentation tích hợp với workflow này.
 
 ```bash
-code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+code --install-extension EducaCorp.sdd-board
 ```
 
-Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → tìm **Spec Driven Docs Tools**.
+Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → tìm **SDD Board**.
 
 **Nó làm gì:**
 - 📋 **Review Board** — UI trực quan để review findings từ `/refine-prd`, `/review-context`, `/review-tech-docs`
@@ -557,7 +557,7 @@ Next:
   4. Điền specs/domain-knowledge/core-entities.md
   5. git add và commit 4 file đó
   6. Cài VS Code extension:
-     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+     code --install-extension EducaCorp.sdd-board
   7. /define-product để bắt đầu feature đầu tiên
 ```
 
@@ -591,7 +591,7 @@ Next:
   3. Điền specs/domain-knowledge/core-entities.md        ← entity glossary
   4. git add và commit các file đó
   5. Cài VS Code extension:
-     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+     code --install-extension EducaCorp.sdd-board
   6. /define-product để bắt đầu feature đầu tiên
 
 ⚠️  Nhắc handoff team dev:

package/core/commands/update-framework.md

@@ -193,7 +193,7 @@ Your content was preserved:
 Review & commit:
    git diff .agent/
    git add .agent/ .claude/commands/
-   git commit -m "chore: upgrade spec-driven-docs v{current} → v{latest}"
+   git commit -m "chore: upgrade sdd-framework v{current} → v{latest}"
    {umbrella mode: this is the umbrella root — service submodules need no framework update}
 
 ---

package/core/commands/validate-traces.md

@@ -1223,7 +1223,7 @@ Schema:
 - `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
 - `tech_doc_revision` / `fe_tech_doc_revision`: dùng integer; `0` nếu chưa sinh
 - `code_coverage_pct` / `test_coverage_pct`: làm tròn về integer gần nhất (0–100)
-- **`status` trong JSON CỐ TÌNH chỉ có 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — KHÔNG ghi `ORPHANED` vào field này. VS Code extension "Spec Driven Docs Tools" (sống **ngoài** repo này) switch trên `status`; thêm giá trị thứ 5 sẽ rơi vào nhánh không khớp và có thể làm row mất khỏi panel.
+- **`status` trong JSON CỐ TÌNH chỉ có 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — KHÔNG ghi `ORPHANED` vào field này. VS Code extension "SDD Board" (sống **ngoài** repo này) switch trên `status`; thêm giá trị thứ 5 sẽ rơi vào nhánh không khớp và có thể làm row mất khỏi panel.
   Row `ORPHANED` xuất ra JSON là: `"status": "DRIFT"` + `"orphaned": true`. Panel chưa hỗ trợ vẫn hiện nó như `DRIFT` — đủ đúng về nghĩa ("code không khớp spec, cần xử lý") và **không im lặng**; panel có đọc `orphaned` thì hiện nhãn riêng. Chi tiết đầy đủ luôn có ở `orphaned[]` và ở report terminal.
   **TSV giữ nguyên chữ `ORPHANED`** trong cột `status` — TSV là nguồn-sự-thật, JSON chỉ là bản xuất cho panel.
 - `orphaned` (boolean): `true` chỉ khi cột `status` của TSV là `ORPHANED`; mọi row khác ghi `false` (đừng bỏ trống — panel đọc field vắng dễ ra `undefined`).

package/core/modules/qc-playwright/stack-profile.yaml

@@ -19,11 +19,11 @@ architecture:
     - "Each test independent via pytest-playwright fixtures (page / logged_in_page / …)"
     - "Page Object extends slim BasePage; split 3 layers: locators _x(), actions verb_noun(), assertions assert_x() using expect()"
     - "Locator priority: data-testid → role → label/text → CSS → avoid XPath"
-    - "test-id values come from the FE tech-design §2b Test Selectors contract ({UC-ID}-tech-design-{platform}.md) — prefer them (no runtime scan); fall back to role/text only when an actionable element has no test-id there, and note the gap"
+    - "test-id values come from the FE tech-design §2b Test Selectors contract (tech-doc gộp cấp PRD: {TICKET-ID}-tech-design.md, bảng Test Selectors §4.5.6 — lọc theo cột "Serves SC") — prefer them (no runtime scan); fall back to role/text only when an actionable element has no test-id there, and note the gap"
     - "Group tests by (role, account) so login/logout never interleaves across roles"
     - "Cover 100% of TCs in the .Test.md — every TC ends Pass/Fail/Skip, none left Draft"
   folder_structure: |
-    {paths.qc_dir}/{UC-ID}/test-cases/   ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
+    {qc_artifact_dir}test-cases/   ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
     pages/                         ← Page Object Model
     │   ├── base_page.py           ← slim BasePage (click/fill/wait/screenshot)
     │   └── <feature>_page.py
@@ -42,7 +42,7 @@ coding_standards:
     test_function: "test_TC<NNN>_<snake_case>"
     page_object: "<feature>_page.py with <Feature>Page class extending BasePage"
     files:
-      test_case_md: "{paths.qc_dir}/{UC-ID}/test-cases/TC_<FEATURE>.Test.md"
+      test_case_md: "{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md"
       page_object: "pages/<feature>_page.py"
       test_script: "tests/<project>/test_<feature>.py"
   patterns:

package/core/rules/workflow.md

@@ -1,6 +1,6 @@
 # Workflow Rules
 
-> General AI behavior rules for all spec-driven-docs commands.
+> General AI behavior rules for all SDD Framework commands.
 > Loaded by `steps/context-loader.md` at the start of every command.
 
 ---