@educa-corp/sdd-framework 0.9.2 → 0.9.3

package/core/skills/qc/qa-analyst/business-rules.md

@@ -83,11 +83,11 @@ Với rule có nhiều điều kiện kết hợp → gợi ý dựng **Decision
 
 ## Output
 
-Ghi vào **mục Business Rules** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+Ghi vào **mục Business Rules** của `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`
 (KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Bảng business rule có ID (BR-xx) để TC trace ngược về.
 - Gợi ý các rule cần Decision Table / BVA khi sang qa-designer.
 
-Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md`
+Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{qc_artifact_dir}DOC_GAP.md`
 (loại CONTRADICTORY / AMBIGUOUS, cột "Ảnh hưởng" trỏ BR-xx).

package/core/skills/qc/qa-analyst/data-flow.md

@@ -54,7 +54,7 @@ Thể hiện luồng dạng bước tuần tự hoặc sơ đồ text:
 
 ## Output
 
-Ghi vào **mục Data Flow** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+Ghi vào **mục Data Flow** của `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`
 (KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Sơ đồ/list luồng dữ liệu cho mỗi kịch bản chính.
@@ -63,4 +63,4 @@ Ghi vào **mục Data Flow** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.
 - Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho qa-runner.
 
 Chặng nào luồng/hành vi chưa rõ (vd lỗi xử lý ra sao, retry, partial commit) →
-ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md` (loại MISSING / OPEN QUESTION).
+ghi vào `{qc_artifact_dir}DOC_GAP.md` (loại MISSING / OPEN QUESTION).

package/core/skills/qc/qa-analyst/spec-breakdown.md

@@ -49,7 +49,7 @@ F. GIẢ ĐỊNH & CÂU HỎI MỞ: điều suy ra được vs điều cần dev
 ## Output
 
 ⚠️ `/qc-analyze` chỉ ghi **ĐÚNG 2 FILE** cho mỗi UC, đặt trong thư mục QC **lộ ra ngoài**
-`{paths.qc_dir}/{UC-ID}/` (mặc định `docs/{UC-ID}/` — KHÔNG để trong `.agent/` ẩn):
+`{qc_artifact_dir}` (mặc định `docs/{TICKET-ID}/{platform}/` — gom theo **PRD**, KHÔNG để trong `.agent/` ẩn):
 `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`. KHÔNG tách mỗi bước phân tích thành file riêng.
 
 Phần spec-breakdown là **mục đầu tiên** của `REQUIREMENT_ANALYSIS.md`:
@@ -57,7 +57,7 @@ Phần spec-breakdown là **mục đầu tiên** của `REQUIREMENT_ANALYSIS.md`
 - Sơ đồ/list luồng chính & phụ
 - Danh sách giả định và câu hỏi mở (đánh dấu rõ điều CHƯA chắc)
 
-Đồng thời ghi mọi khoảng trống phát hiện vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md`
+Đồng thời ghi mọi khoảng trống phát hiện vào `{qc_artifact_dir}DOC_GAP.md`
 (theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`), mỗi gap có ID `GAP-xx`.
 
 Kết thúc bằng gợi ý: feature đã đủ rõ để chuyển sang `qa-planner` (phân tích rủi ro) chưa.

package/core/skills/qc/qa-analyst/spec-issue-reporter.md

@@ -14,6 +14,9 @@ có cấu trúc, đủ thông tin để người nhận trả lời được nga
 > **`/qc-analyze` nạp file này** *(B9 — hợp nhất 2026-08-25)*. Nó là luật viết cho
 > `DOC_GAP.template.md` — template **duy nhất** của file gap. Bản 9 cột cũ đã bỏ.
 >
+> **Một file gap phủ CẢ PRD** *(B11)* — `{paths.qc_dir}/{TICKET-ID}/{platform}/DOC_GAP.md`,
+> mỗi UC là các hàng phân biệt bằng cột `UC`. Không còn một-file-mỗi-UC.
+>
 > **Một chỗ cố ý khác upstream:** mức nặng nhất dùng `🔴 Blocker`, không phải `Critical` —
 > `/qc-run-test` đọc đúng từ đó để đặt *"scenario đang chờ PO"* vào sổ trace.
 
@@ -38,8 +41,11 @@ Một file gap gồm:
    transitive 1-hop): `# | Đường dẫn | Vai trò | Phiên bản`, kèm tổng số.
    KHÔNG bỏ sót file nào đã mở — đây là **căn cứ độ phủ**: không có nó thì không ai phân biệt
    được *"đã đọc và không thấy"* với *"chưa đọc"*.
-2. **Bảng gap 10 cột**, đúng thứ tự:
-   `ID | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
+2. **Bảng gap 11 cột**, đúng thứ tự:
+   `ID | UC | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
+3. **Section `Phạm vi phân tích`** — BẮT BUỘC, giữa metadata và section trên. Mỗi UC của
+   (PRD × nền) một hàng, kèm `@trace.status` + đã phân tích chưa + số gap. UC có BDD chưa
+   `approved` **vẫn có hàng**, ghi `⏸ Chưa xét`.
 
 ## Quy tắc
 
@@ -56,6 +62,12 @@ Một file gap gồm:
   do bước phân tích tự đánh số lại (vd `BR-UC4-12`). Hai hệ ID khác nhau; trộn vào là người
   đọc không tra ngược được về PRD.
 - **Mức độ bắt buộc có emoji**: `🔴 Blocker` · `🟠 High` · `🟡 Medium` · `⚪ Low`.
+- **ID gap mang UC**: `GAP-UC{N}-{nnn}` (vd `GAP-UC1-001`); gap thuộc cả PRD → `GAP-GEN-{nnn}`.
+  Đánh số **độc lập trong từng UC** — phân tích lại UC1 KHÔNG được làm đổi số gap của UC2,
+  vì test case đã có đang trỏ `🚫 Block: [GAP-UC2-003]` và đổi số là đứt liên kết trong im lặng.
+  **Không dùng `GAP-01` phẳng.**
+- **Cột `UC`** ghi mã UC đầy đủ (`{TICKET-ID}-UC{N}`), hoặc `— (toàn PRD)` cho `GAP-GEN-`.
+  Mọi UC xuất hiện ở đây phải khớp một hàng `✅` trong bảng *Phạm vi phân tích*.
 - **Pipe trong cell**: escape thành `\|` (vd `{a\|b\|c}`), nếu không sẽ vỡ bảng.
 - **Thêm hàng vào bảng đã có**: nối **ngay liền sau hàng cuối**, TUYỆT ĐỐI không chèn dòng
   trắng giữa các hàng — dòng trắng làm Markdown tách thành hai bảng riêng và các gap mới

package/core/skills/qc/qa-designer/e2e/journey.md

@@ -37,5 +37,5 @@ Mỗi journey → 1 TC bám Format; Expected = chuỗi verify point; chuẩn b
 **Journey phụ thuộc gap vẫn viết + 🚫 Block: GAP-xx**, định tuyến ghi "dự kiến theo BR". Trace BR.
 
 ## Output
-File TC e2e (hoặc nhóm E2E trong file feature) trong `{paths.qc_dir}/{UC-ID}/test-cases/`.
+File TC e2e (hoặc nhóm E2E trong file feature) trong `{qc_artifact_dir}test-cases/`.
 In bảng `E2E-ID | Journey | Pri | Trace | Block` + bảng TC block. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/exploratory/explore-to-functional.md

@@ -37,7 +37,7 @@ Chuyển draft → TC chính thức bám **format file `TC_<FEATURE>.md`**:
   **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có BR → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx]` nếu chặn.
 - **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet cụ thể.
 - Phân nhóm GUI/Functional · cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
-- Đặt file `{paths.qc_dir}/{UC-ID}/test-cases/TC_<FEATURE>.md`.
+- Đặt file `{qc_artifact_dir}test-cases/TC_<FEATURE>.md`.
 
 ## Output
 File TC functional + bảng `TC_ID | Title | Priority | Technique | Trace`. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/functional/api.md

@@ -41,5 +41,5 @@ response (schema thành công + các mã lỗi 4xx/5xx + body lỗi) · side-eff
 - Mỗi TC bám khối Format; Expected ghi status code + phần body verify; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC (`TC_<FEATURE>_API.md` hoặc gộp trong file feature) trong `{paths.qc_dir}/{UC-ID}/test-cases/`.
+File TC (`TC_<FEATURE>_API.md` hoặc gộp trong file feature) trong `{qc_artifact_dir}test-cases/`.
 In bảng TC + Trace matrix. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/functional/gui-feature.md

@@ -42,5 +42,5 @@ Liệt kê các màn/route + thứ tự điều hướng · state/dữ liệu tr
 - Mỗi TC bám khối Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File `TC_<FEATURE>.md` trong `{paths.qc_dir}/{UC-ID}/test-cases/`. In bảng TC + Trace matrix + bảng TC block.
+File `TC_<FEATURE>.md` trong `{qc_artifact_dir}test-cases/`. In bảng TC + Trace matrix + bảng TC block.
 Bàn giao `qa-reviewer` (test-case).

package/core/skills/qc/qa-designer/functional/gui-screen.md

@@ -48,5 +48,5 @@ chức năng (input/action/display/nav) · constraint (required/min-max/format/e
 - Mỗi TC bám khối Format trên; trace BR; TC chặn bởi gap → 🚫 Block.
 
 ## Output
-File `TC_<FEATURE>.md` trong `{paths.qc_dir}/{UC-ID}/test-cases/`. In bảng `TC_ID | Title | Priority | Tags | Trace`
+File `TC_<FEATURE>.md` trong `{qc_artifact_dir}test-cases/`. In bảng `TC_ID | Title | Priority | Tags | Trace`
 + Trace matrix + bảng TC block. Bàn giao `qa-reviewer` (test-case).

package/core/skills/qc/qa-designer/integration/api.md

@@ -39,4 +39,4 @@ Nhóm TC: happy (dữ liệu đúng đầu→cuối) → contract negative (inpu
 → concurrency → điều kiện đồng bộ (đổ/không đổ). Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC integration trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Ưu tiên P0 cho định tuyến & tiền-dữ liệu. Bàn giao `qa-reviewer`.
+File TC integration trong `{qc_artifact_dir}test-cases/`. Ưu tiên P0 cho định tuyến & tiền-dữ liệu. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/integration/db.md

@@ -35,5 +35,5 @@ Nhóm TC: ghi đúng giá trị (happy) → default/null đúng → update khôn
 → audit log → ràng buộc/unique (negative). Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Ghi rõ query kiểm tra DB + yêu cầu cleanup;
+File TC trong `{qc_artifact_dir}test-cases/`. Ghi rõ query kiểm tra DB + yêu cầu cleanup;
 không hardcode ID, chuẩn bị/dọn data qua fixture. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/integration/gui.md

@@ -37,4 +37,4 @@ Nhóm TC: UI render đúng dữ liệu backend (happy) → empty state → lỗi
 Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC nêu API liên quan + biểu hiện UI. Bàn giao `qa-reviewer`.
+File TC trong `{qc_artifact_dir}test-cases/`. Mỗi TC nêu API liên quan + biểu hiện UI. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/integration/kafka.md

@@ -37,4 +37,4 @@ Nhóm TC: phát đúng topic+payload (happy) → điều kiện không phát →
 Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC ghi topic, key, payload cần verify + hành vi consumer. Bàn giao `qa-reviewer`.
+File TC trong `{qc_artifact_dir}test-cases/`. Mỗi TC ghi topic, key, payload cần verify + hành vi consumer. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/non-functional.md

@@ -37,4 +37,4 @@ Mỗi TC bám Format; **Expected có ngưỡng pass + công cụ đo**; đánh d
 Trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC non-functional trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC ghi tiêu chí đo + ngưỡng + công cụ. Bàn giao `qa-reviewer`.
+File TC non-functional trong `{qc_artifact_dir}test-cases/`. Mỗi TC ghi tiêu chí đo + ngưỡng + công cụ. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-planner/test-plan.md

@@ -8,11 +8,14 @@ upstream_sha: f259b4d123c565a42ba6c6ec96980a8e4c66284f
 
 # Lập Test Plan
 
-Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
+Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature — tức **một plan cho cả
+(PRD × nền)**, các UC là các hàng bên trong.
 
 **Đầu vào (bắt buộc, chỉ 2 nguồn — đúng 2 file qa-analyst trả ra):**
-1. `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md` — chức năng, BR-xx, AC-xx, data flow (qa-analyst).
-2. `{paths.qc_dir}/{UC-ID}/DOC_GAP.md` — bảng gap GAP-xx, mức độ, gap Blocker (qa-analyst).
+1. `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md` — chức năng, BR-xx, AC-xx, data flow của **mọi UC
+   trong phạm vi**, kèm mục *Mâu thuẫn chéo UC* (qa-analyst).
+2. `{qc_artifact_dir}DOC_GAP.md` — bảng gap 11 cột `GAP-UC{N}-{nnn}`, mức độ, gap Blocker, và
+   bảng *Phạm vi phân tích* (qa-analyst). **Lọc cột `UC`** khi cần phần của một UC cụ thể.
 
 ## Khi nào trigger
 - "lập test plan cho [Feature]" / "viết test plan"
@@ -56,14 +59,16 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
 
 ## Output — Template `TEST_PLAN.md`
 
-Đặt tại `{paths.qc_dir}/{UC-ID}/TEST_PLAN.md`:
+Đặt tại `{qc_artifact_dir}TEST_PLAN.md`:
 
 ```markdown
-# Test Plan – <Feature>
+# Test Plan – <TICKET-ID> <Tên feature> / <nền>
 
 | Trường | Giá trị |
 |---|---|
-| Feature / Project / Module | … |
+| Feature / Project / Module | `<TICKET-ID>` — … |
+| Nền (platform) | `<web \| app \| system>` |
+| UC trong phạm vi | `<UC-ID>` · `<UC-ID>` … (`⏸ chưa xét`: `<UC-ID>`) |
 | Người lập | qa-planner |
 | Ngày / Phiên bản | … |
 | Nguồn | REQUIREMENT_ANALYSIS · DOC_GAP |
@@ -72,16 +77,20 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
 Mục tiêu test của feature (1–3 câu).
 
 ## 2. Phạm vi
-- **In scope:** chức năng/BR được test.
-- **Out of scope:** phần để tài liệu/feature khác; nội dung gạch ngang đã loại.
+- **In scope:** chức năng/BR được test, **theo từng UC** (`<UC-ID>`: …).
+- **Out of scope:** phần để tài liệu/feature khác; nội dung gạch ngang đã loại; và **UC
+  `⏸ Chưa xét`** (BDD chưa `approved`) — liệt kê rõ mã UC + lý do. *Không ghi ra thì một UC bị
+  bỏ trông giống một UC không có gì để test.*
 
 ## 3. Test items theo vùng & độ ưu tiên
 Bảng — mỗi vùng kèm rule chi tiết + metadata:
 
-| # | Vùng test | Rule chi tiết | Layer (qa-designer) | Loại test | Pri | Ước lượng |
-|---|---|---|---|---|---|---|
-| ① | <vùng> | **BR-xx:** … <br>**BR-yy:** … | functional/gui-screen | Functional/Negative | P0 | n |
-| … | … | … | … | … | … | … |
+| # | UC | Vùng test | Rule chi tiết | Layer (qa-designer) | Loại test | Pri | Ước lượng |
+|---|---|---|---|---|---|---|---|
+| ① | `<UC-ID>` | <vùng> | **BR-xx:** … <br>**BR-yy:** … | functional/gui-screen | Functional/Negative | P0 | n |
+| … | … | … | … | … | … | … | … |
+
+*Cột `UC` bắt buộc — một plan phủ nhiều UC, không có nó thì không ai biết vùng test nào của UC nào.*
 
 > Tổng ước lượng sơ bộ: ~N test case (+ E2E).
 
@@ -98,7 +107,9 @@ Kỹ thuật áp dụng: EP+BVA, Decision Table (cho logic điều kiện), stat
 integration, negative/exploratory; tự động hoá theo `CLAUDE.md` (Playwright + pytest-playwright + Trace + pytest-html).
 
 ## 5. Tiêu chí Vào / Ra
-- **Entry:** gap Blocker (trong DOC_GAP) đã Answered; doc phụ thuộc sẵn sàng; môi trường + tài khoản role.
+- **Entry (chấm theo TỪNG UC, không chấm cả PRD):** gap 🔴 Blocker của **UC đó** (lọc cột `UC`
+  trong DOC_GAP) đã Answered; doc phụ thuộc sẵn sàng; môi trường + tài khoản role.
+  Ghi `Ready`/`Blocked` cho mỗi UC — blocker ở UC3 không dừng thiết kế test UC1.
 - **Exit:** pass P0=100%, P1≥95%; không còn defect Blocker/Critical; mọi BR/AC được trace; báo cáo pytest-html + Playwright Trace.
 
 ## 6. Rủi ro (risk-based)

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 |