@educa-corp/sdd-framework 0.9.2 → 0.9.4

package/core/skills/qc/qa-reviewer/test-case/functional.md

@@ -1,7 +1,9 @@
 ---
 version: 1.0
-updated: 2026-06-11
+updated: 2026-09-04
 ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/ui-test-reviewer.md
+upstream_sha: 54f81eb6a132d3fb331f18ce0f1a7eb3a9cf19df
 ---
 
 # Review Test Case — Functional
@@ -10,7 +12,7 @@ Review bộ functional TC và đánh giá chất lượng.
  
 ## Khi nào trigger
 - "review TC cho [Feature]" / "check coverage"
-- Sau khi qa-designer xong, trước khi PO approve hoặc trước khi qa-runner
+- Sau khi qa-designer xong, trước khi PO approve hoặc trước khi /qc-run-test
  
 ## Khi KHÔNG trigger
 - Review Python script → dùng qa-reviewer
@@ -18,6 +20,32 @@ Review bộ functional TC và đánh giá chất lượng.
  
 ---
  
+## Trọng tâm review — tầng Functional / GUI
+
+- **Assertion hiển thị đo được**: cấm *"hiển thị đúng"* — phải nêu element / nhãn / chuỗi / màu
+  cụ thể. Thiếu → `[VAGUE_EXPECTED]`.
+- **EP + BVA từng field có ràng buộc**: mỗi phân vùng một TC; biên đủ 3 hoặc 4 giá trị tuỳ dạng
+  ràng buộc (`../../qa-designer/shared/precision-rules.md` §7). Thiếu → `[GAP]`.
+- **Bảng quyết định cho logic nhiều điều kiện**: có ≥2 điều kiện → **tự dựng bảng** để đếm N rule
+  tối thiểu (sau khi gộp don't-care); thiếu TC so với N → `[DT_COVERAGE_GAP]`.
+- **State Transition**: element có vòng đời phải phủ transition hợp lệ **và** transition bị cấm.
+  Thiếu nhánh cấm → `[GAP]`.
+- **Phân nhóm GUI vs Functional** *(Nhóm 3 riêng của tầng này)*: GUI = chỉ hiển thị tĩnh, không
+  đổi trạng thái · Functional = có hành động / validate / luồng. Sai nhóm → `[WRONG_GROUP]`;
+  một TC gánh cả hai → `[SPLIT_NEEDED]`.
+- **`Type` khớp nội dung**: Happy Path (luồng chính lý tưởng) · Positive (input hợp lệ → xử lý
+  đúng) · Negative (input sai → chặn & báo lỗi) · Edge (biên/cực trị). Lệch → `[WRONG_TYPE]`.
+
+## 7 nhóm kiểm tra
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-check-groups.md`** — bộ xương 7 nhóm
+> chạy tuần tự · registry nhãn lỗi dùng chung · 7 mẫu-hay-thiếu của Nhóm 6 · nền tảng ISTQB ·
+> anti-pattern. Nhóm 5 (Nội dung TC) trỏ tiếp sang `shared/review-file-template.md`.
+>
+> Dưới đây chỉ là phần **riêng của tầng này**.
+
+---
+
 ## Phase 1 — Clarify
  
 1. Đọc tất cả .Test.md trong folder được chỉ định
@@ -55,22 +83,42 @@ D. ANTI-PATTERN:
  
 ---
 
-## Checklist format file `.md` (đối chiếu skill layer qa-designer)
+## Phase 3 — Coverage tổng thể
+
+Sau khi duyệt hết từng TC, kiểm **bộ TC** có đủ bốn nhóm không:
 
-- **Metadata:** đủ Title, Feature, Priority, Status, Author, Tags, **Trace**; Priority `P0/P1/P2` (không emoji); Status `Draft` text thuần; mỗi trường 1 dòng riêng.
-- **Trace:** mỗi TC link `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)`; TC không có BR → phải có ⚠️ cảnh báo (không để trống/`—`).
-- **TC bị block:** TC phụ thuộc gap có dòng `🚫 Block: [GAP-xx]`; cuối file có **Trace matrix** (BR↔TC) + **bảng TC bị block** (Gap↔TC).
-- **Test Data:** dạng list (`- **Trường:** giá trị`), không dùng bảng.
-- **Test Steps:** phân biệt `[Action]`/`[Verify]`; KHÔNG có `- *Expected:* ...` sau mỗi bước.
-- **Expected Result:** 1 dòng bullet `-`, cụ thể; KHÔNG `✅ PASS/❌ FAIL`; không viết "hoạt động bình thường".
-- **KHÔNG** có section `#### Python Test Mapping`.
-- **1 concept/TC**; phân nhóm GUI / Functional.
+| Nhóm | Kỳ vọng tối thiểu |
+|---|---|
+| Display | Mỗi section / vùng giao diện có ≥1 TC |
+| Validation | Mỗi field có ràng buộc: required + BVA (3 hoặc 4 TC) + định dạng nếu có |
+| State | Mỗi element có ≥2 trạng thái: ≥1 TC trạng thái đầu + ≥1 TC chuyển trạng thái |
+| Interaction | Mỗi hành động (click / hover / bàn phím) ≥1 TC |
+
+Thiếu nhóm nào → bảng **Coverage gaps** của file review, kèm `[GAP]` + mã TC đề xuất bổ sung.
 
 ---
- 
+
+## Kiểm tra cấu trúc file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-file-template.md`** §*Kiểm tra cấu trúc
+> TC* — luật ATOMIC 1-bullet · không ký tự `|` · 9 cụm từ mơ hồ · teardown đúng chỗ · marker ≠
+> oracle · 6 dấu vết hỏng sau khi chạy script tách. **Không lặp lại ở đây.**
+>
+> Luật gốc mà trạm 3 phải theo nằm ở `qa-designer/shared/tc-metadata-format.md` +
+> `precision-rules.md`. **Cổng và luật phải đọc từ cùng một chỗ** — giữ hai bản là tự tạo lại
+> chỗ chúng lệch nhau, và cổng lệch thì nó đánh trượt file làm đúng.
+
 ## Output
- 
-Mỗi tiêu chí: ✅ PASS | ⚠️ PARTIAL | ❌ MISSING + evidence cụ thể
-Score: A (excellent) / B (good) / C (needs improvement) / D (redo)
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng cạnh file TC vừa soát.
+Nạp `../shared/review-file-template.md` để lấy khuôn + quy tắc ghi (tích luỹ theo vòng, chỉ sửa
+hàng của tầng mình, KHÔNG ghi đè tầng khác).
+
+Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể
+
+**Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
 Đề xuất TC cần thêm/sửa/xoá, sắp theo priority. Liệt kê TC thiếu Trace BR (⚠️) cần bổ sung.
 
+**KHÔNG tự sửa file TC** — chỉ nhận xét, chấm điểm, nêu cụ thể sửa gì. Người sửa là `/qc-design-test`.

package/core/skills/qc/qa-reviewer/test-case/integration.md

@@ -1,7 +1,9 @@
 ---
 version: 1.0
-updated: 2026-06-11
+updated: 2026-09-04
 ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/integration-test-reviewer.md
+upstream_sha: 639b54afb68df83b22168581c5c57b0f91d9cf6a
 ---
 
 # Review Test Case — Integration
@@ -10,7 +12,7 @@ Review bộ TC tích hợp (GUI↔Backend, API, DB) và đánh giá chất lư
 
 ## Khi nào trigger
 - "review TC integration cho [Feature]" / "check TC tích hợp"
-- Sau khi qa-designer/integration/* xong, trước khi qa-runner
+- Sau khi qa-designer/integration/* xong, trước khi /qc-run-test
 
 ## Khi KHÔNG trigger
 - Review TC functional 1 màn/endpoint → `test-case/functional`
@@ -18,6 +20,30 @@ Review bộ TC tích hợp (GUI↔Backend, API, DB) và đánh giá chất lư
 
 ---
 
+## Trọng tâm review — tầng Integration
+
+- **Verify CẢ HAI phía**: mỗi handshake phải assert trạng thái của **Module A và Module B** +
+  tầng dữ liệu (DB/cache nhất quán). Chỉ verify một phía → `[GAP]`.
+- **Phủ đủ chế độ lỗi**: happy → một bên lỗi (suy giảm mềm) → timeout / mất mạng → dữ liệu cũ /
+  tranh chấp → tương thích ngược. Thiếu nhánh lỗi → `[GAP]`.
+- **Di trú DB phải có TC rollback**, không chỉ chiều tiến. Thiếu → `[GAP]` **mức cao**.
+- **Chuỗi API**: phủ lỗi một-phần (bước 2 trượt khi bước 1 đã commit) + tính idempotent.
+- **Mock hợp lý**: **không mock cả hai bên** — mock hết thì TC không còn kiểm gì. Kỹ thuật
+  State Transition / bảng quyết định phải khớp loại integration.
+- **Phân nhóm & `Type`** *(Nhóm 3 riêng của tầng này)*: TC integration thuộc nhóm **Nghiệp vụ**,
+  **không có** nhóm GUI. `Type` khớp nội dung. Sai nhóm → `[WRONG_GROUP]`; `Type` lệch →
+  `[WRONG_TYPE]`; một TC gánh nhiều cặp module → `[SPLIT_NEEDED]`.
+
+## 7 nhóm kiểm tra
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-check-groups.md`** — bộ xương 7 nhóm
+> chạy tuần tự · registry nhãn lỗi dùng chung · 7 mẫu-hay-thiếu của Nhóm 6 · nền tảng ISTQB ·
+> anti-pattern. Nhóm 5 (Nội dung TC) trỏ tiếp sang `shared/review-file-template.md`.
+>
+> Dưới đây chỉ là phần **riêng của tầng này**.
+
+---
+
 ## Phase 1 — Clarify
 
 1. Đọc tất cả TC integration trong folder chỉ định; xác định loại: GUI↔Backend / API / DB
@@ -46,24 +72,50 @@ C. QUALITY:
 - TC concurrency: mô tả rõ 2+ request đồng thời + kết quả kỳ vọng?
 
 D. FORMAT & TRACE:
-- Metadata đủ; Trace `[BR-xx]` hoặc `⚠️ Chưa có Business Rule`; `🚫 Block: [GAP-xx]` nếu bị chặn?
-- Cuối file có Trace matrix + bảng TC block?
+- Metadata đủ; Trace `[BR-xx]` hoặc `⚠️ Chưa có Business Rule`; `🚫 Block: [GAP-UC{N}-{nnn}]` nếu bị chặn?
+- Cuối file có **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách** TC bị block — cả hai **dạng danh sách, KHÔNG bảng** (file TC không được có ký tự `|` — luật B12)?
 - Steps phân biệt `[Action]`/`[Verify]`; Expected 1 bullet; KHÔNG `✅/❌` inline.
 
 ---
 
-## Checklist format file `.md`
+## Phase 3 — Coverage tổng thể
+
+*(Bản gốc không có mục này cho tầng integration — bảng dưới suy ra từ chính các trục phủ ở
+§Trọng tâm review trên.)*
 
-- **Test Data:** dạng list; ghi rõ endpoint/payload/bảng cần kiểm tra.
-- **Expected (DB):** phải có dạng `bảng.cột = giá trị` + query kiểm tra + cleanup instruction.
-- **Expected (API):** ghi mã HTTP + cấu trúc response + downstream effect.
-- **Expected (GUI):** ghi API gọi + biểu hiện UI (message/state/list cập nhật).
+| Trục | Kỳ vọng tối thiểu |
+|---|---|
+| Happy | Mỗi cặp Module A ↔ Module B có ≥1 TC verify **cả hai phía** |
+| Failure | Mỗi cặp có ≥1 TC một-bên-lỗi (suy giảm mềm) |
+| Timeout | Mỗi lời gọi qua mạng có ≥1 TC timeout / mất mạng |
+| Rollback | Mỗi thao tác ghi có ≥1 TC rollback — **không chỉ chiều tiến** |
+
+Điền vào bảng **Coverage handshake (Integration)** ở cuối file review.
 
 ---
 
+## Kiểm tra cấu trúc file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-file-template.md`** §*Kiểm tra cấu trúc
+> TC* — luật ATOMIC 1-bullet · không ký tự `|` · 9 cụm từ mơ hồ · teardown đúng chỗ · marker ≠
+> oracle · 6 dấu vết hỏng sau khi chạy script tách. **Không lặp lại ở đây.**
+>
+> Luật gốc mà trạm 3 phải theo nằm ở `qa-designer/shared/tc-metadata-format.md` +
+> `precision-rules.md`. **Cổng và luật phải đọc từ cùng một chỗ** — giữ hai bản là tự tạo lại
+> chỗ chúng lệch nhau, và cổng lệch thì nó đánh trượt file làm đúng.
+
 ## Output
 
-Mỗi tiêu chí: ✅ PASS | ⚠️ PARTIAL | ❌ MISSING + evidence (TC ID / điểm tích hợp)
-Score: A (excellent) / B (good) / C (needs improvement) / D (redo)
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng cạnh file TC vừa soát.
+Nạp `../shared/review-file-template.md` để lấy khuôn + quy tắc ghi (tích luỹ theo vòng, chỉ sửa
+hàng của tầng mình, KHÔNG ghi đè tầng khác).
+
+Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID / điểm tích hợp)
+
+**Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
 Điểm tích hợp thiếu TC; TC Expected mờ nhạt; TC DB thiếu cleanup.
-Kết luận: sẵn sàng cho `qa-runner` chưa.
+Điền thêm bảng **Coverage handshake (Integration)** ở cuối file review.
+
+**KHÔNG tự sửa file TC** — chỉ nhận xét, chấm điểm, nêu cụ thể sửa gì. Người sửa là `/qc-design-test`.

package/core/skills/qc/qa-reviewer/test-case/non-functional.md

@@ -1,7 +1,9 @@
 ---
 version: 1.0
-updated: 2026-06-11
+updated: 2026-09-04
 ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/nfr-test-reviewer.md
+upstream_sha: 5747c7a6bdfaaea1ff3e958688b38b3aeaf9b15a
 ---
 
 # Review Test Case — Non-Functional
@@ -10,7 +12,7 @@ Review bộ TC phi chức năng (performance, security, accessibility, compatibi
 
 ## Khi nào trigger
 - "review TC non-functional cho [Feature]" / "check TC hiệu năng/bảo mật/accessibility"
-- Sau khi qa-designer/non-functional xong, trước khi qa-runner
+- Sau khi qa-designer/non-functional xong, trước khi /qc-run-test
 
 ## Khi KHÔNG trigger
 - Review TC chức năng → `test-case/functional`
@@ -18,6 +20,35 @@ Review bộ TC phi chức năng (performance, security, accessibility, compatibi
 
 ---
 
+## Trọng tâm review — tầng NFR
+
+- **Tiêu chí đo lường BẮT BUỘC**: mỗi TC có **ngưỡng + đơn vị + điều kiện môi trường**
+  (`P95 < X ms` · `error rate < Y%` · `contrast ≥ 4.5:1` · `Lighthouse a11y ≥ 90`).
+  Thiếu ngưỡng → `[VAGUE_EXPECTED]`. Đơn vị chuẩn theo domain:
+  `../../qa-designer/shared/precision-rules.md` §3.
+- **Đúng loại + đúng công cụ**: `Type` ∈ {Load · Stress · Spike · Security · A11y · i18n}; có
+  công cụ phù hợp (k6 / ZAP / axe-core…) + marker đúng
+  (`@pytest.mark.performance|security|a11y|i18n`).
+- **Phủ theo loại**: Performance có baseline + hồ sơ đồng thời · Security phủ OWASP áp dụng được
+  (A01/A03/A07…) · A11y phủ **bàn phím + trình đọc màn hình**, không chỉ axe-core tự động ·
+  i18n có tiếng Việt dấu đặc biệt (ộ/ề/ắ) + emoji + tràn chữ.
+- **Môi trường**: NFR không chạy CI thường → TC phải ghi rõ môi trường riêng (load-test /
+  staging) và lịch chạy (nightly / trước phát hành). Thiếu → `[MISSING_DATA]`.
+- **Phân nhóm & `Type`** *(Nhóm 3 riêng của tầng này)*: TC NFR thuộc nhóm **NFR**, **không có**
+  nhóm GUI. `Type` phải là một trong {Load · Stress · Spike · Security · A11y · i18n}. Sai nhóm →
+  `[WRONG_GROUP]`; `Type` không thuộc tập trên → `[WRONG_TYPE]`; một TC đo nhiều loại NFR →
+  `[SPLIT_NEEDED]`.
+
+## 7 nhóm kiểm tra
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-check-groups.md`** — bộ xương 7 nhóm
+> chạy tuần tự · registry nhãn lỗi dùng chung · 7 mẫu-hay-thiếu của Nhóm 6 · nền tảng ISTQB ·
+> anti-pattern. Nhóm 5 (Nội dung TC) trỏ tiếp sang `shared/review-file-template.md`.
+>
+> Dưới đây chỉ là phần **riêng của tầng này**.
+
+---
+
 ## Phase 1 — Clarify
 
 1. Đọc tất cả TC non-functional trong folder chỉ định; xác định loại: performance / security / accessibility / compatibility
@@ -49,25 +80,53 @@ C. ENVIRONMENT & DATA:
 - Cleanup / teardown sau mỗi TC (đặc biệt security test)?
 
 D. FORMAT & TRACE:
-- Metadata đủ; Trace `[BR-xx]` / SLA source rõ; `🚫 Block: [GAP-xx]` nếu bị chặn?
+- Metadata đủ; Trace `[BR-xx]` / SLA source rõ; `🚫 Block: [GAP-UC{N}-{nnn}]` nếu bị chặn?
 - Steps phân biệt `[Action]`/`[Verify]`; Expected 1 bullet; KHÔNG `✅/❌` inline?
-- Cuối file có Trace matrix + bảng TC block?
+- Cuối file có **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách** TC bị block — cả hai **dạng danh sách, KHÔNG bảng** (file TC không được có ký tự `|` — luật B12)?
 
 ---
 
-## Checklist format file `.md`
+## Phase 3 — Coverage tổng thể
 
-- **Expected:** PHẢI có `ngưỡng + đơn vị + công cụ đo` — không có → ❌ MISSING.
-- **Performance TC:** ghi `concurrent users`, `data volume`, `target response time`.
-- **Security TC:** ghi `attack vector`, `input payload`, `expected block/response`.
-- **Accessibility TC:** ghi `WCAG version + level`, `tool (axe/lighthouse)`.
-- **Compatibility TC:** ghi `browser/OS version + device/resolution`.
+*(Bản gốc không có mục này cho tầng NFR — bảng dưới suy ra từ chính các trục phủ ở §Trọng tâm
+review trên.)*
+
+| Loại NFR | Kỳ vọng tối thiểu |
+|---|---|
+| Performance | Có baseline + ≥1 hồ sơ tải đồng thời, cả hai có ngưỡng + đơn vị |
+| Security | Phủ các mục OWASP **áp dụng được** cho tính năng này (A01/A03/A07…) |
+| Accessibility | Bàn phím **và** trình đọc màn hình — không chỉ axe-core tự động |
+| i18n | Tiếng Việt dấu đặc biệt + emoji + tràn chữ |
+| Compatibility | Các nền / trình duyệt mà PRD nêu |
+
+Loại nào PRD **không** yêu cầu → ghi `N/A` kèm lý do, **đừng bỏ trống**: ô trống không phân biệt
+được *"không áp dụng"* với *"quên kiểm"*.
+Điền vào bảng **Chi tiết NFR** ở cuối file review.
 
 ---
 
+## Kiểm tra cấu trúc file TC
+
+> **Nạp `{paths.qc_skills_dir}/qa-reviewer/shared/review-file-template.md`** §*Kiểm tra cấu trúc
+> TC* — luật ATOMIC 1-bullet · không ký tự `|` · 9 cụm từ mơ hồ · teardown đúng chỗ · marker ≠
+> oracle · 6 dấu vết hỏng sau khi chạy script tách. **Không lặp lại ở đây.**
+>
+> Luật gốc mà trạm 3 phải theo nằm ở `qa-designer/shared/tc-metadata-format.md` +
+> `precision-rules.md`. **Cổng và luật phải đọc từ cùng một chỗ** — giữ hai bản là tự tạo lại
+> chỗ chúng lệch nhau, và cổng lệch thì nó đánh trượt file làm đúng.
+
 ## Output
 
-Mỗi tiêu chí: ✅ PASS | ⚠️ PARTIAL | ❌ MISSING + evidence (TC ID)
-Score: A (excellent) / B (good) / C (needs improvement) / D (redo)
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng cạnh file TC vừa soát.
+Nạp `../shared/review-file-template.md` để lấy khuôn + quy tắc ghi (tích luỹ theo vòng, chỉ sửa
+hàng của tầng mình, KHÔNG ghi đè tầng khác).
+
+Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID)
+
+**Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
 Danh sách TC Expected mờ nhạt (thiếu ngưỡng); loại non-functional thiếu coverage.
-Kết luận: sẵn sàng cho `qa-runner` chưa; ghi rõ TC nào cần môi trường đặc biệt.
+Ghi rõ TC nào cần môi trường đặc biệt. Điền thêm bảng **Chi tiết NFR** ở cuối file review.
+
+**KHÔNG tự sửa file TC** — chỉ nhận xét, chấm điểm, nêu cụ thể sửa gì. Người sửa là `/qc-design-test`.

package/core/skills/qc/qa-runner/e2e.md

@@ -26,7 +26,7 @@ Skill **tự chứa**: convert journey `.Test.md` → Python pytest + Playwright
 
 ## Phase 2 — Generate
 Mỗi journey → 1 test; bọc từng bước `with step("…")`; cuối journey verify đủ V1…Vn (tạo/mã/định tuyến/đồng bộ/danh sách).
-Journey còn phụ thuộc gap → tạo test `@pytest.mark.skip(reason="GAP-xx")` hoặc xfail.
+Journey còn phụ thuộc gap → tạo test `@pytest.mark.skip(reason="GAP-UC{N}-{nnn}")` hoặc xfail.
 
 ## Phase 3 — Verify
 `py_compile` + `pytest --collect-only -q` · chạy (môi trường staging + CRM) · cập nhật Status TC.

package/core/skills/qc/qa-runner/exploratory/session.md

@@ -33,4 +33,4 @@ Input: session note (#BUG + #IDEA).
 - **Weekly summary** (nếu yêu cầu): overview, top findings, coverage gap, recommendations.
 
 ## Output
-Mode 1: file session note. Mode 2: bug reports + file TC trong `{paths.qc_dir}/{UC-ID}/test-cases/` + summary.
+Mode 1: file session note. Mode 2: bug reports + file TC trong `{qc_artifact_dir}test-cases/` + summary.

package/core/steps/context-loader.md

@@ -35,7 +35,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 **Paths (nếu có):**
 - `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
 - `paths.refinement_dir` → thư mục output cho findings/review
-- `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_dir` → gốc artifact QC automation (ở top-level, gom theo **PRD**: `{qc_dir}/{TICKET-ID}/{platform}/` — một `DOC_GAP.md` / `TEST_PLAN.md` / `REQUIREMENT_ANALYSIS.md` cho cả PRD, các UC là mục bên trong. Xem `steps/qc-scope.md`)
 - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
 - `paths.product_definitions_dir` → gốc product definition
 - `paths.domain_knowledge_dir` → gốc domain knowledge

package/core/steps/qc-scope.md

@@ -0,0 +1,119 @@
+# 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.

package/core/templates/project-context.yaml

@@ -64,7 +64,9 @@ paths:
 
   # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
   # REQUIREMENT_ANALYSIS.md, DOC_GAP.md, TEST_PLAN.md, test-cases/*.Test.md).
-  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # Grouped by PRD: {qc_dir}/{TICKET-ID}/{platform}/ — ONE DOC_GAP.md / TEST_PLAN.md /
+  # REQUIREMENT_ANALYSIS.md per (PRD x platform), with the UCs as rows/sections inside
+  # (see steps/qc-scope.md). Default "docs" (the QC team's own
   # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
   # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
   qc_dir: "docs"

package/docs/02-concepts/pipeline-steps/08-qc-automation.md

@@ -38,7 +38,7 @@
 
 | Artifact | Nội dung |
 |----------|----------|
-| `docs/{UC-ID}/…` | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`, `test-cases/*.Test.md` |
+| `docs/{TICKET-ID}/{platform}/…` | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`, `test-cases/*.Test.md` — **mỗi loại đúng một file cho cả (PRD × nền)**, các UC là hàng/mục bên trong (cột `UC`) |
 | Script Python pytest-playwright | Sinh từ `.Test.md` đã review |
 | Cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` | Trạng thái QC **chính thức** |
 | Evidence + report | `/qc-report` — kèm product-gap đẩy về PO/Dev |

package/docs/02-concepts/pipeline-steps/09-validate-traces.md

@@ -40,7 +40,7 @@ Traceability chỉ có giá trị khi **kiểm được**. Bước này cho mộ
 | Artifact | Nội dung |
 |----------|----------|
 | Ma trận coverage spec ↔ code ↔ test | Trạng thái từng SC + `code_coverage` tổng |
-| `{trace_dir}/trace-report.json` | Bản máy đọc cho **panel VS Code** ("Spec Driven Docs Tools") — bị **ghi đè** mỗi lần chạy |
+| `{trace_dir}/trace-report.json` | Bản máy đọc cho **panel VS Code** ("SDD Board") — bị **ghi đè** mỗi lần chạy |
 | `{trace_dir}/trace-history.jsonl` | **Nhật ký append-only** — mỗi lần chạy ghi thêm 1 dòng *delta*. Đây là **dữ liệu**, không phải mirror: **phải commit**, mất là mất vĩnh viễn |
 | Cờ audit | 6 cờ drift + 4 cờ 🔴 chặn PR + `PRD_UNTRACKED_EDIT` 🔴 (không chặn) + 2 cờ ⓘ (bảng dưới) |
 | Hàng đợi | Đếm PRD change request còn `Open` kèm **số ngày chờ** (Step 7b) |