@educa-corp/sdd-framework 0.9.1 → 0.9.3

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)
@@ -225,7 +358,7 @@ Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_di
 | `qc_status` | Đọc cột `status` của row **TRƯỚC** — xem §Guard ngay dưới bảng. Row `OK`/`GAP`/`UNTRACKED`: `pass` nếu mọi QC test của SC này pass · `fail` nếu có cái fail · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó. Row **`DRIFT`/`ORPHANED`**: **không bao giờ ghi `pass`** — hạ về `not_run` |
 | `qc_run_at` | hôm nay `YYYY-MM-DD` |
 | `last_updated` | hôm nay `YYYY-MM-DD` |
-| `qc_owner` | **SC đang chờ ai** (view "pending" của PM/PO): `dev` nếu FAIL = product-gap (defect thật → dev fix) · `po` nếu `skip`/`not_run` vì một **`DOC_GAPS` 🔴 Blocker đang open** chặn test (PO phải làm rõ PRD/BDD) · `—` nếu `pass`, hoặc FAIL = script-bug (QC tự fix — tạm thời) |
+| `qc_owner` | **SC đang chờ ai** (view "pending" của PM/PO): `dev` nếu FAIL = product-gap (defect thật → dev fix) · `po` nếu `skip`/`not_run` vì một **`DOC_GAP` 🔴 Blocker đang open** chặn test (PO phải làm rõ PRD/BDD) · `—` nếu `pass`, hoặc FAIL = script-bug (QC tự fix — tạm thời) |
 | `qc_blocked_by` | artifact liên kết: `GAP-{id}` khi bị chặn bởi spec gap (set ở đây) · `BUG-{id}` khi `/report-bug` đã được file cho product-gap (backfill bởi `/report-bug`) · `—` ngược lại |
 
 Set `qc_owner`/`qc_blocked_by` cùng với `qc_status`. Khi `pass`, **clear** cả hai về `—` — nhưng **PHẢI chạy §Đóng bug đã verify bên dưới TRƯỚC**, vì `qc_blocked_by` chính là con trỏ tới bug và clear xong là mất đường về.

package/core/commands/refine-prd.md

@@ -1,4 +1,4 @@
-# /refine-prd — Phân tích PRD qua 3 lăng kính review
+# /refine-prd — Phân tích PRD qua 4 lăng kính review
 
 > **Ranh giới — lệnh này chỉ áp được fix cho vấn đề mà CHÍNH NÓ tìm ra.** Resume Mode Phase 2 tự
 > cấm đụng bất kỳ section nào không được một finding chấp nhận trỏ tới, và findings sinh từ việc soi
@@ -259,10 +259,11 @@ vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
 Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
-  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
+  (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check; `/qc-analyze` → 3 lăng kính quét gap).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
 - **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
 - **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
+- **VERIFY** *(tuỳ chọn, mặc định `off`)* — `on` chèn **Phase 2.5** (`steps/gap-verify.md`) giữa critic và dedup: mỗi finding phải mở lại tài liệu nguồn tự chứng minh trước khi được giữ. Không truyền → hành vi không đổi.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -381,6 +382,31 @@ Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
 
 ---
 
+## Phase 2.5 — Thẩm định *(chỉ chạy khi `VERIFY = on`)*
+
+**Vì sao có bước này.** Phase 1 và Phase 2 chỉ có **một chiều lực**: fan-out mở rộng bề
+ngang, critic lặp cho tới khi không còn gì mới — cả hai đều hỏi *"còn thiếu gì nữa?"*.
+Không có gì hỏi ngược lại *"cái vừa tìm ra có thật không?"*. Nên quy trình này đẩy **recall**
+lên mà **không có gì kéo precision lại**, và càng lặp critic thì tỉ lệ finding bịa càng cao —
+đúng thứ nó tự sinh ra: khẳng định hành vi tài liệu không nêu, trích evidence sai, hoặc gắn
+nhãn vấn đề cho thứ thực ra là chuyện làm-kỹ-hơn.
+
+Chạy `steps/gap-verify.md` trên `ALL_FINDINGS` với:
+- `FINDINGS` = `ALL_FINDINGS` (sau Phase 2)
+- `EVIDENCE_ROOT` = `{paths.specs_dir}` — hoặc giá trị lệnh gọi chỉ định
+- `VERDICT_FIELD` = trường trạng thái của FINDINGS SCHEMA mà lệnh định nghĩa
+- `RERATE` = `on`
+
+Finding bị `❌ INVALID` / `⚠️ RECLASSIFY` / `🔁 MERGE` **không đi tiếp sang Phase 3** — nhưng
+**KHÔNG bị xoá**: chúng vào file findings với trạng thái đóng + lý do, để người đọc kiểm chứng
+được vì sao chúng bị loại. Ghi lại số liệu verdict cho report.
+
+> **Chạy TRƯỚC Phase 3, không phải sau.** Dedup và giải quyết xung đột là việc tốn suy luận;
+> làm nó trên một tập còn lẫn finding bịa là vừa phí, vừa nguy hiểm — một finding ảo có thể
+> "thắng" một finding thật ở bước giữ-cái-severity-cao-hơn.
+
+---
+
 ## Phase 3 — Dedup, giải quyết xung đột, merge
 
 Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ
@@ -412,7 +438,7 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
 
 ---
 
-## Phân tích — 3 lăng kính (fan out cả ba, rồi hội tụ)
+## Phân tích — 4 lăng kính (fan out cả bốn, rồi hội tụ)
 
 Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
 
@@ -431,22 +457,23 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
        - **`applied_to_version` có mặt VÀ `==` version PRD hiện tại** → PRD đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
        - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → PRD đã bị sửa bởi **actor khác** (lệnh `/review-context`, sửa tay…) sau lần resume này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"PRD đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
 
-**DIMENSIONS** = 3 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
+**DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
 toàn bộ PRD qua đúng lăng kính của nó:
 
-<!-- ─────────────────────────────────────────────────────────────────────────────
-  LĂNG KÍNH BỊ TẮT (DISABLED — KHÔNG dùng, KHÔNG fan-out agent cho lăng kính này):
-
-  - **Lăng kính QA (tầng nghiệm thu)**: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
+- **Lăng kính QA (tầng nghiệm thu)** *(bật lại 2026-08-25 — xem `docs/plans/qc-implementation-log.md` B8)*: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
 
-  CÁCH THÊM LẠI QA (khi cần bật lại giai đoạn sau):
-    1. Chuyển bullet QA ở trên ra khỏi block comment này, đặt lên đầu danh sách DIMENSIONS.
-    2. Đổi "3 lăng kính"/"cả ba" → "4 lăng kính"/"cả bốn" ở: dòng tiêu đề (# /refine-prd),
-       heading "## Phân tích", câu "DIMENSIONS = N lăng kính", và steps/review-fanout.md.
-    3. Thêm "QA" lại vào enum của `lens:` trong FINDINGS SCHEMA + vào `by_lens`.
-    4. Thêm "QA" lại vào ghi chú "phán đoán DEV/SA/PO" ở LƯU Ý của schema.
-    5. Rebuild: node bin/build.js
-───────────────────────────────────────────────────────────────────────────── -->
+> **Phạm vi lăng kính QA — hẹp có chủ ý, đừng nới.** Nó hỏi về **HÌNH THỨC** của AC (*"phát biểu này kiểm chứng được không?"* · *"có lặp tầng không?"*), **KHÔNG** về **NỘI DUNG** (*"còn thiếu gì?"*).
+>
+> Lý do là thời điểm: ở đây **chỉ có PRD** — design-spec, BDD, tech-doc đều chưa tồn tại. Nên không thể phân biệt *"PRD thiếu X"* với *"PRD cố ý để X cho design-spec"*, và phép kiểm *"đã trả lời ở tài liệu khác chưa?"* **không có tài liệu khác để tra**.
+>
+> Số liệu thật (14 lần chạy ở repo QC): review chỉ-đọc-PRD ra **14 gap** trung bình, review đủ 4 nguồn ra **9,4** — khoảng 5 gap chênh lệch là câu hỏi mà tài liệu sau **trả lời hộ**. Nới lăng kính này sang câu hỏi nội dung là cố tình sinh ra 5 gap đó rồi gửi PO.
+>
+> Câu hỏi nội dung thuộc `/qc-analyze` (3 lăng kính: xử lý lỗi · giao diện · dữ liệu & cấu hình), nơi đã có đủ 4 nguồn để tra.
+>
+> **CÁCH TẮT LẠI QA** *(nếu cần)*: gỡ bullet QA ở trên · đổi `4 lăng kính`/`cả bốn` → `3`/`cả ba` ở
+> dòng tiêu đề, heading `## Phân tích`, câu `DIMENSIONS = N lăng kính`, và `steps/review-fanout.md` ·
+> gỡ `QA` khỏi enum `lens:` + `by_lens` + ghi chú `phán đoán QA/DEV/SA/PO` · sửa
+> `docs/explain/03-refine-prd.md` cho khớp · rebuild `node bin/build.js`.
 
 > **Nguyên tắc chung cho DEV & SA — đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ.**
 > Hai lăng kính này dùng con mắt kỹ thuật để **phát hiện chỗ nghiệp vụ mô tả thiếu/mơ hồ/mâu thuẫn đến mức sẽ chặn triển khai** — mục tiêu là **làm rõ vấn đề nghiệp vụ để sau này xử lý được về mặt kỹ thuật**. **KHÔNG** đưa góc nhìn kỹ thuật vào PRD, **KHÔNG** đề xuất giải pháp/cơ chế kỹ thuật. Mọi `finding` và `suggestion` phải **thuần nghiệp vụ** (tuân Business Language Guard): mô tả *cái nghiệp vụ còn thiếu/chưa rõ* và *hỏi cần làm rõ gì*, chứ không nói *làm thế nào về kỹ thuật*.
@@ -483,7 +510,7 @@ status: "pending_review"
 
 findings:
   - id: "F001"
-    lens: "DEV"          # DEV | SA | PO
+    lens: "DEV"          # QA | DEV | SA | PO
     severity: "major"    # critical | major | minor
     section: "§2. Acceptance Criteria"   # nhãn heading/section dạng người đọc
     uc_id: "{TICKET-ID}-UC{N}"           # UC mà finding thuộc về; "" nếu PRD-global (scope, metrics, problem statement)
@@ -499,8 +526,8 @@ findings:
     # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
     # false = cần human đọc kỹ và ghi quyết định trước khi accept
     # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
-    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 3 lăng kính
-    #   là phán đoán DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
+    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 4 lăng kính
+    #   là phán đoán QA/DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
     #   quick-accept cho Board, KHÔNG để máy tự áp.
     status: "pending"
     applied_via: ""
@@ -516,7 +543,7 @@ findings:
 summary:
   total_findings: {N}
   by_severity: { critical: {N}, major: {N}, minor: {N} }
-  by_lens: { DEV: {N}, SA: {N}, PO: {N} }
+  by_lens: { QA: {N}, DEV: {N}, SA: {N}, PO: {N} }
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
   # Rule: critical ≥ 1                       → BLOCKED
   #       critical = 0, major ≥ 1            → NEEDS_REVISION

package/core/commands/report-bug.md

@@ -1,7 +1,7 @@
 # /report-bug — File một Bug có trace-spec (cho Tester & QC)
 
 Dành cho **tester và QC** — gồm cả **product-gap** lòi ra từ pipeline `/qc-*`
-(`/qc-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAPS` từ
+(`/qc-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAP` từ
 `/qc-analyze`). Sinh một bug report có cấu trúc với đầy đủ spec context, phân loại layer
 khả nghi, và lưu lại để handoff cho team dev.
 

package/core/commands/review-context.md

@@ -267,10 +267,11 @@ vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
 Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
-  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
+  (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check; `/qc-analyze` → 3 lăng kính quét gap).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
 - **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
 - **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
+- **VERIFY** *(tuỳ chọn, mặc định `off`)* — `on` chèn **Phase 2.5** (`steps/gap-verify.md`) giữa critic và dedup: mỗi finding phải mở lại tài liệu nguồn tự chứng minh trước khi được giữ. Không truyền → hành vi không đổi.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -389,6 +390,31 @@ Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
 
 ---
 
+## Phase 2.5 — Thẩm định *(chỉ chạy khi `VERIFY = on`)*
+
+**Vì sao có bước này.** Phase 1 và Phase 2 chỉ có **một chiều lực**: fan-out mở rộng bề
+ngang, critic lặp cho tới khi không còn gì mới — cả hai đều hỏi *"còn thiếu gì nữa?"*.
+Không có gì hỏi ngược lại *"cái vừa tìm ra có thật không?"*. Nên quy trình này đẩy **recall**
+lên mà **không có gì kéo precision lại**, và càng lặp critic thì tỉ lệ finding bịa càng cao —
+đúng thứ nó tự sinh ra: khẳng định hành vi tài liệu không nêu, trích evidence sai, hoặc gắn
+nhãn vấn đề cho thứ thực ra là chuyện làm-kỹ-hơn.
+
+Chạy `steps/gap-verify.md` trên `ALL_FINDINGS` với:
+- `FINDINGS` = `ALL_FINDINGS` (sau Phase 2)
+- `EVIDENCE_ROOT` = `{paths.specs_dir}` — hoặc giá trị lệnh gọi chỉ định
+- `VERDICT_FIELD` = trường trạng thái của FINDINGS SCHEMA mà lệnh định nghĩa
+- `RERATE` = `on`
+
+Finding bị `❌ INVALID` / `⚠️ RECLASSIFY` / `🔁 MERGE` **không đi tiếp sang Phase 3** — nhưng
+**KHÔNG bị xoá**: chúng vào file findings với trạng thái đóng + lý do, để người đọc kiểm chứng
+được vì sao chúng bị loại. Ghi lại số liệu verdict cho report.
+
+> **Chạy TRƯỚC Phase 3, không phải sau.** Dedup và giải quyết xung đột là việc tốn suy luận;
+> làm nó trên một tập còn lẫn finding bịa là vừa phí, vừa nguy hiểm — một finding ảo có thể
+> "thắng" một finding thật ở bước giữ-cái-severity-cao-hơn.
+
+---
+
 ## Phase 3 — Dedup, giải quyết xung đột, merge
 
 Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ

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

@@ -0,0 +1,147 @@
+---
+version: 1.0
+updated: 2026-08-25
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/spec-issue-reporter/DOC_GAPS.template.md
+upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
+---
+
+> **Template DUY NHẤT cho file gap của `/qc-analyze`** *(B9 — hợp nhất 2026-08-25)*.
+> Bản 9 cột cũ đã bỏ: nó thiếu đúng hai thứ PO cần — cột *Giao cho đội* và ô câu hỏi 4 phần.
+> Giữ một bản kém hơn làm mặc định là để người không biết có cờ nhận bản kém.
+>
+> **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 -- <TICKET-ID> / <nền>: <Tên feature>
+
+| Trường | Giá trị |
+|---|---|
+| 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) |
+| Trạng thái chung | 🔴 Blocked / 🟠 Cần làm rõ / 🟢 Đủ rõ để thiết kế TC |
+
+---
+
+## 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}`.
+
+| # | Đường dẫn (từ `{paths.specs_dir}`) | Vai trò | Phiên bản |
+|---|---|---|---|
+| 1 | `<đường dẫn spec chính>` | **Spec chính** | `<vX.Y>` |
+| 2 | `<đường dẫn ref>` | Ref bắt buộc — `<lý do>` | `—` |
+| ... | ... | Transitive 1-hop — `<feature liền kề / dịch vụ tiêu thụ>` | `—` |
+
+**Tổng: `<N>` tài liệu.** Lane API: `<có → liệt kê openapi.yaml/*.dbml/tdd | không có → SKIP, không đọc, không bịa endpoint>` *(chỉ áp khi framework đã nhận trục lane — xem B5)*. Không dùng làm evidence: Change log · Appendix · mục Giả định AI.
+
+---
+
+> **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 | |
+
+---
+
+## Ưu tiên xử lý
+
+| Mức độ | Gap ID |
+|---|---|
+| 🔴 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-UC1-00x (`<UC-ID>`): <lý do block>
+
+---
+
+## Chú thích (Legend)
+
+### Loại Gap
+
+| Loại | Mô tả |
+|---|---|
+| MISSING | Thông tin, chức năng, quy tắc, hoặc kịch bản chưa được mô tả trong bất kỳ tài liệu nào trong `{paths.specs_dir}`. |
+| AMBIGUOUS | Mô tả mơ hồ, có thể hiểu theo nhiều cách, hoặc thiếu chi tiết để viết kịch bản kiểm thử. |
+| CONTRADICTORY | Hai hoặc nhiều tài liệu trong `{paths.specs_dir}` mô tả cùng một hành vi nhưng mâu thuẫn nhau. |
+| ASSUMPTION | Giả định do nhóm QA tự suy luận từ tài liệu trong `{paths.specs_dir}`, chưa được PO/Dev xác nhận tường minh. |
+
+### Mức độ
+
+| Mức | Ý nghĩa |
+|---|---|
+| 🔴 Blocker | Chặn viết kịch bản kiểm thử hoặc lập trình — không thể tiến hành nếu chưa có câu trả lời. |
+| 🟠 High | Ảnh hưởng đến nhiều kịch bản kiểm thử hoặc logic nghiệp vụ chính — cần giải quyết trước khi viết test case. |
+| 🟡 Medium | Ảnh hưởng đến một số kịch bản cụ thể — cần giải quyết trước sprint kiểm thử. |
+| ⚪ Low | Ít ảnh hưởng — có thể ghi giả định tạm thời và xử lý trong sprint review. |
+
+### Giao cho đội
+
+| Ký hiệu | Đội |
+|---|---|
+| Dev | Đội phát triển (Frontend + Backend) |
+| Architect | Kiến trúc sư hệ thống |
+| PO | Product Owner |
+| BA | Business Analyst |
+| Design | Đội thiết kế UX/UI |
+| Analytics | Nhóm dữ liệu / phân tích |
+
+---
+
+## ⚠️ Checklist bắt buộc trước khi lưu file
+
+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ở.
+- [ ] **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 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`
+- [ ] **Có đủ 3 section cuối**: Ưu tiên xử lý · Chú thích (Legend) với bảng đầy đủ
+- [ ] **KHÔNG có section "Change log"** và **KHÔNG có section "AI Assumptions"**
+- [ ] **Evidence chỉ từ `{paths.specs_dir}`** – không dùng file trong `{paths.qc_dir}` nội bộ (TC_*.md, REQUIREMENT_ANALYSIS*.md, DOC_GAP*.md khác)

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

@@ -1,7 +1,9 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/acceptance-criteria.md
+upstream_sha: 516f35cf78102d27aa5639bfb2818274399800c0
 ---
 
 # Acceptance Criteria — Sinh tiêu chí chấp nhận
@@ -51,8 +53,8 @@ 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`
-(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.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)
   và scenario chính thức `{UC-ID}-SC{N}` của `.feature`.

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

@@ -1,7 +1,9 @@
 ---
 version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
+updated: 2026-08-25
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/business-rules.md
+upstream_sha: 0d5f01257c30182d1c98835303640775d360a3da
 ---
 
 # Business Rules — Trích xuất luật nghiệp vụ
@@ -25,6 +27,38 @@ Trích xuất và liệt kê toàn bộ business rule, điều kiện và ràng
 1. Đọc spec đã bóc tách (output của spec-breakdown) hoặc tài liệu gốc.
 2. Quét tìm: điều kiện ("nếu… thì…"), ràng buộc field, giới hạn (min/max, rate limit),
    quy tắc phân quyền, công thức tính, quy tắc trạng thái, default value.
+3. **Checklist ràng buộc field — kiểm tra TẤT CẢ field (kể cả tuỳ chọn / optional):**
+   - [ ] `minlength` / `maxlength` — PRD có nêu không? Nếu không → GAP (MISSING)
+   - [ ] Ký tự được phép — chữ, số, tiếng Việt có dấu, ký tự đặc biệt, khoảng trắng?
+   - [ ] Trim khoảng trắng đầu/cuối — có hay không?
+   - [ ] Format đặc biệt — email, SĐT, ngày tháng, v.v.
+   > ⚠️ **Field tuỳ chọn (optional) vẫn phải kiểm tra đủ 4 mục trên.** "Không bắt buộc nhập" KHÔNG đồng nghĩa với "không có ràng buộc". Đây là nguồn gốc hay bị bỏ sót khi phân tích.
+
+4. **Checklist đặc biệt — hay bị bỏ sót khi đọc BDD/PRD:**
+
+   **a. Routing table — đọc cả 2 chiều:**
+   - [ ] Với MỖI rule "nếu đủ điều kiện → bỏ qua / nếu thiếu → vào": đánh dấu cả 2 nhánh cần test
+   - [ ] Routing table N loại tài khoản × M màn → duyệt từng ô, không bỏ dòng nào
+
+   **b. Liệt kê hết variant:**
+   - [ ] Spec đề cập nhiều provider/platform/giá trị liệt kê (Google/Facebook, Lớp 1-6...)? → ghi từng variant ra
+   - [ ] Với mỗi variant: behavior hoặc content có khác nhau không? Nếu có → đánh dấu cần TC riêng
+
+   **c. Telemetry/event analytics:**
+   - [ ] Liệt kê TẤT CẢ event name được nhắc trong BDD/PRD cho UC này
+   - [ ] Với mỗi event: trigger khác nhau? → cần TC riêng
+   - [ ] Có field nhạy cảm (SĐT, PII) KHÔNG ĐƯỢC vào event? → cần TC verify âm riêng
+
+   **d. Privacy/security assertions âm:**
+   - [ ] Spec có nói "KHÔNG ghi", "KHÔNG hiển thị", "chỉ đọc", "KHÔNG vào event"? → ghi ra, cần TC riêng
+   - [ ] "Read-only + che X/hiện Y" → 2 TC riêng: (1) hiển thị đúng che/hiện, (2) không chỉnh sửa được
+
+   **e. Validation kế thừa từ UC/AC khác:**
+   - [ ] Spec có reference "chuẩn hoá theo ACx", "logic tương tự UCy", "validation như màn Z"? → đọc UC/AC đó
+   - [ ] Liệt kê TẤT CẢ scenario normalization của UC nguồn chưa có trong UC hiện tại
+
+   **f. AC có sub-cases:**
+   - [ ] Mỗi AC dạng "(1)...→...; (2)...→...; (3)...→..." → đếm số sub-cases, mỗi sub-case 1 TC
 
 ---
 
@@ -49,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`
-(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.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_GAPS.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

@@ -1,7 +1,9 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/data-flow.md
+upstream_sha: fc0fc3d0f8010e3fb266c16b132eff1b23641a8f
 ---
 
 # Data Flow — Phân tích luồng dữ liệu
@@ -52,8 +54,8 @@ 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`
-(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.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.
 - Danh sách integration point + state change + failure point.
@@ -61,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_GAPS.md` (loại MISSING / OPEN QUESTION).
+ghi vào `{qc_artifact_dir}DOC_GAP.md` (loại MISSING / OPEN QUESTION).