@educa-corp/sdd-framework 0.9.2 → 0.9.3

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,140 @@ 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.
+
+
+> **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 +326,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 +345,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,139 @@ 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
+
+# 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.
+
+
+> **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

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,139 @@ 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
+
+# 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.
+
+
+> **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/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/skills/qc/qa-analyst/DOC_GAP.template.md

@@ -13,13 +13,18 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 > **Một chỗ CỐ Ý khác upstream:** mức nặng nhất dùng từ **`Blocker`**, không phải `Critical`.
 > Lý do: `/qc-run-test` đọc `🔴 Blocker` để đặt *"scenario đang chờ PO"* vào sổ kết quả trace.
 > Đổi từ là đứt liên kết đó. Ba mức còn lại giữ nguyên upstream.
+>
+> **Phạm vi: MỘT file cho cả (PRD × nền)** *(B11)*, không phải một file mỗi UC. Đây là quay về
+> đúng thiết kế upstream — chính ID `GAP-<UC>-…` của bản gốc chỉ có nghĩa khi một file chứa
+> nhiều UC, và file thật của đội QC (`DOC_GAP_FEAT-02-3.md`) cũng không có hậu tố UC. Đường
+> dẫn: `{paths.qc_dir}/{TICKET-ID}/{platform}/DOC_GAP.md`.
 
-# DOC GAP -- <UC>: <Tên UC>
+# DOC GAP -- <TICKET-ID> / <nền>: <Tên feature>
 
 | Trường | Giá trị |
 |---|---|
-| Feature | `<FEATURE>` |
-| UC | `<UC> — <Tên UC>` |
+| Feature | `<TICKET-ID>` — `<Tên feature>` |
+| Nền (platform) | `<web \| app \| system>` |
 | Tài liệu nguồn | `<đường dẫn PRD>` · `<đường dẫn BDD nếu có>` · `<các file inputs/ liên quan>` |
 | Ngày phân tích | `<YYYY-MM-DD>` |
 | Tổng số gap | `<N>` (Blocker: x · High: y · Medium: z · Low: w) |
@@ -27,6 +32,21 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 
 ---
 
+## Phạm vi phân tích
+
+> **Một file gap phủ CẢ PRD** — mỗi UC là các hàng trong bảng gap, phân biệt bằng cột `UC`.
+> Bảng dưới là **căn cứ độ phủ**: nó phân biệt *"đã xét, không thấy gap"* với *"chưa xét"*.
+> UC nào có BDD chưa `approved` thì ghi `⏸ Chưa xét` — **KHÔNG bỏ khỏi bảng**.
+
+| UC | Tên UC | `@trace.status` | Đã phân tích? | Số gap |
+|---|---|---|---|---|
+| `<UC-ID>` | … | `approved` | ✅ | `<n>` |
+| `<UC-ID>` | … | `draft` | `⏸ Chưa xét` | — |
+
+**Trong phạm vi: `<n>`/`<N>` UC.** Chưa xét: `<danh sách UC-ID>` — chạy lại sau khi BDD được duyệt, hoặc `--include-draft` để xét luôn bản nháp.
+
+---
+
 ## Tài liệu đầu vào đã đọc để phân tích
 
 > Liệt kê **đầy đủ** mọi file đã đọc để dựng phân tích gap (spec chính + mọi ref-link + transitive 1-hop). Đây là căn cứ độ phủ — mọi file đã mở đều phải có mặt, KHÔNG bỏ sót. Đường dẫn tính từ `{paths.specs_dir}`.
@@ -41,9 +61,14 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 
 ---
 
-| 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 |
-|---|---|---|---|---|---|---|---|---|---|
-| GAP-<UC>-001 | MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION | Tiêu đề ngắn mô tả vấn đề | **Bối cảnh:** Ngữ cảnh dẫn đến gap này.<br/>**Vấn đề:** Điều gì chưa được spec hoặc mâu thuẫn.<br/>**Tại sao quan trọng:** Hậu quả nếu không làm rõ.<br/>**Gợi ý:** Ai cần làm gì để giải quyết. | `<đường dẫn file spec>` `<TÊN-BR hoặc AC gốc trong PRD, ví dụ FEAT-01-2-UC4-BR11>`: trích nguyên văn | Dev / PO / BA / Design | 🔴 Blocker | | Open | |
+> **ID gap mang UC** — `GAP-UC{N}-{nnn}` (vd `GAP-UC1-001`). Gap thuộc **cả PRD**, không riêng
+> UC nào → `GAP-GEN-{nnn}`. Đánh số **độc lập trong từng UC**: chạy lại phân tích cho UC1
+> KHÔNG được làm đổi số gap của UC2 — test case đã có đang trỏ `🚫 Block: [GAP-UC2-003]`, đổi
+> số là đứt liên kết đó trong im lặng.
+
+| 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 |
+|---|---|---|---|---|---|---|---|---|---|---|
+| GAP-UC1-001 | `<UC-ID>` | MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION | Tiêu đề ngắn mô tả vấn đề | **Bối cảnh:** Ngữ cảnh dẫn đến gap này.<br/>**Vấn đề:** Điều gì chưa được spec hoặc mâu thuẫn.<br/>**Tại sao quan trọng:** Hậu quả nếu không làm rõ.<br/>**Gợi ý:** Ai cần làm gì để giải quyết. | `<đường dẫn file spec>` `<TÊN-BR hoặc AC gốc trong PRD, ví dụ FEAT-01-2-UC4-BR11>`: trích nguyên văn | Dev / PO / BA / Design | 🔴 Blocker | | Open | |
 
 ---
 
@@ -51,13 +76,15 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 
 | Mức độ | Gap ID |
 |---|---|
-| 🔴 Blocker | GAP-<UC>-00x · ... |
-| 🟠 High | GAP-<UC>-00x · ... |
-| 🟡 Medium | GAP-<UC>-00x · ... |
-| ⚪ Low | GAP-<UC>-00x · ... |
+| 🔴 Blocker | GAP-UC1-00x · GAP-UC3-00x · ... |
+| 🟠 High | GAP-UC2-00x · ... |
+| 🟡 Medium | GAP-UC1-00x · ... |
+| ⚪ Low | GAP-GEN-00x · ... |
+
+*Xếp theo mức độ trước, KHÔNG theo UC — người đọc cần biết "chặn gì" trước "chặn ở đâu".*
 
 **Cần chốt trước khi viết test case:**
-- GAP-<UC>-00x: <lý do block>
+- GAP-UC1-00x (`<UC-ID>`): <lý do block>
 
 ---
 
@@ -99,16 +126,19 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 Trước khi lưu file gap, kiểm tra **từng hàng** trong bảng gap:
 
 - [ ] **Có section `Tài liệu đầu vào đã đọc để phân tích`** – bảng liệt kê **đầy đủ** mọi file đã đọc (spec chính + ref-link + transitive 1-hop), có đường dẫn `{paths.specs_dir}`, vai trò, phiên bản; ghi tổng số + trạng thái lane API. KHÔNG bỏ sót file nào đã mở.
-- [ ] **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`
-- [ ] **Cột 3 = `Vấn đề cần confirm`** – KHÔNG viết tắt thành `Vấn đề`
-- [ ] **Cột 4 = `Câu hỏi / Lý do cần confirm & Gợi ý`** – bắt buộc có đủ 4 phần, tách bằng `<br/>`:
+- [ ] **Có section `Phạm vi phân tích`** – bảng mỗi UC một hàng kèm `@trace.status` + Đã phân tích? + Số gap. UC chưa duyệt vẫn có hàng, ghi `⏸ Chưa xét`. Thiếu bảng này thì không ai phân biệt được *"đã xét, không thấy gap"* với *"chưa xét"*.
+- [ ] **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`
+- [ ] **Cột 2 = `UC`** – mã UC đầy đủ (`<TICKET-ID>-UC{N}`), hoặc `— (toàn PRD)` cho gap `GAP-GEN-`. Mọi UC có gap phải khớp một hàng `✅` ở bảng *Phạm vi phân tích*.
+- [ ] **ID dạng `GAP-UC{N}-{nnn}`** (hoặc `GAP-GEN-{nnn}`) – KHÔNG dùng `GAP-01` phẳng: số phẳng sẽ bị đánh lại khi phân tích lại một UC, làm đứt `🚫 Block: [GAP-xx]` trong test case đã có.
+- [ ] **Cột 4 = `Vấn đề cần confirm`** – KHÔNG viết tắt thành `Vấn đề`
+- [ ] **Cột 5 = `Câu hỏi / Lý do cần confirm & Gợi ý`** – bắt buộc có đủ 4 phần, tách bằng `<br/>`:
   ```
   **Bối cảnh:** ...<br/>**Vấn đề:** ...<br/>**Tại sao quan trọng:** ...<br/>**Gợi ý:** ...
   ```
   Không viết 4 mục liên tiếp trên cùng một dòng.
-- [ ] **Cột 5 = `Trích đoạn tài liệu (Evidence)`** – KHÔNG viết tắt thành `Evidence`; dẫn nguyên văn + đường dẫn file `{paths.specs_dir}`; **dùng PRD source ID** (ví dụ `FEAT-01-2-UC4-BR11`), KHÔNG dùng internal analysis ID (ví dụ `BR-UC4-12`)
-- [ ] **Cột Mức độ** (cột 7) – bắt buộc dùng emoji: `🔴 Blocker` / `🟠 High` / `🟡 Medium` / `⚪ Low`. Không được ghi text thuần.
-- [ ] **Cột Giao cho đội** (cột 6) – dùng: `Dev` / `PO` / `BA` / `Design` / `Architect` / `Analytics` hoặc kết hợp. Nếu thấy "Open" ở đây → đang bị lệch cột.
+- [ ] **Cột 6 = `Trích đoạn tài liệu (Evidence)`** – KHÔNG viết tắt thành `Evidence`; dẫn nguyên văn + đường dẫn file `{paths.specs_dir}`; **dùng PRD source ID** (ví dụ `FEAT-01-2-UC4-BR11`), KHÔNG dùng internal analysis ID (ví dụ `BR-UC4-12`)
+- [ ] **Cột Mức độ** (cột 8) – bắt buộc dùng emoji: `🔴 Blocker` / `🟠 High` / `🟡 Medium` / `⚪ Low`. Không được ghi text thuần.
+- [ ] **Cột Giao cho đội** (cột 7) – dùng: `Dev` / `PO` / `BA` / `Design` / `Architect` / `Analytics` hoặc kết hợp. Nếu thấy "Open" ở đây → đang bị lệch cột.
 - [ ] **Cột Người trả lời = vai trò** (PO / BA / Dev / Design / ...). Nếu thấy "Open" ở đây → đang bị lệch cột.
 - [ ] **Cột Trạng thái** = `Open` / `Resolved` / `Out of Scope` / `Re-scoped → Covered`
 - [ ] **Trạng thái chung** trong metadata có emoji: `🔴 Blocked` / `🟠 Cần làm rõ` / `🟢 Đủ rõ để thiết kế TC`

package/core/skills/qc/qa-analyst/acceptance-criteria.md

@@ -53,7 +53,7 @@ Mỗi AC gắn mã trace: chức năng + BR-xx để TC sau này map 1-1.
 
 ## Output
 
-Ghi vào **mục Acceptance Criteria** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+Ghi vào **mục Acceptance Criteria** 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`):
 
 - Danh sách AC dạng Given/When/Then, có mã trace về chức năng, business rule (BR-xx)