@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/core/commands/qc-plan.md

@@ -1,14 +1,14 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-plan — QC Test Plan & Risk Analysis
-
-> Stage 2 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-planner của team QC.
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-plan — QC Test Plan & Risk Analysis
+
+> Stage 2 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-planner của team QC.
+
+## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
 Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
@@ -160,196 +160,96 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
 - "N" → dừng, hỏi người dùng muốn thay đổi gì.
 - Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
   🔴/⚠️ (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 **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
+
+
+*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 đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
 `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 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:
-phân tích rủi ro, scenario what-if, scope/strategy test theo từng layer, và `questions-for-dev`
-cho mọi gap open/blocker. Bạn trả lời *"rủi ro ở đâu, phải hỏi gì?"* — bạn không
-thiết kế test case cụ thể (đó là qc-design-test).
-
-## Skills (`{paths.qc_skills_dir}/qa-planner/`)
-
-- `test-plan.md` — khung plan: scope theo từng test layer (functional / integration /
-  e2e / non-functional), what-if, entry/exit criteria, và danh sách questions-for-dev
-  suy ra từ `DOC_GAP.md`.
-- `risk-model.md` — **cách tính** mức rủi ro: 7 nguồn rủi ro · khả năng × thiệt hại → P0–P3 ·
-  và dùng mức đó chia **độ sâu** test. `test-plan.md` có khung bảng `§6`; file này là cách điền.
-  Nạp cùng lúc, không phải thay thế.
-
-## Output
-
-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
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+---
+
+## Phạm vi QC
+
+**BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,
+rồi mới tiếp tục phần bên dưới.
 
+Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
+Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
+cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
+
+> **Trạm này chạy CẢ PRD, đúng như trạm 1** *(B11)* — một `TEST_PLAN.md` cho mỗi (PRD × nền).
+> `qa-planner/test-plan.md` vốn viết *"Test Plan cho một **feature**"* và template của nó là
+> `# Test Plan – <Feature>` với metadata `Feature / Project / Module`: đây là quay về đúng
+> tầng mà skill gốc được viết cho.
+>
+> `uc_list` ở đây **phải khớp** bảng *Phạm vi phân tích* trong `DOC_GAP.md`. Lệch nhau nghĩa là
+> BDD đã đổi trạng thái sau lần chạy trạm 1 → nêu ra và khuyên chạy lại `/qc-analyze`, đừng
+> âm thầm lập plan cho một tập UC khác với tập đã phân tích.
+
+---
+
+## Role
+
+Bạn là **QC Planner** — stage 2. Từ output của qc-analyze, tạo TEST PLAN:
+phân tích rủi ro, scenario what-if, scope/strategy test theo từng layer, và `questions-for-dev`
+cho mọi gap open/blocker. Bạn trả lời *"rủi ro ở đâu, phải hỏi gì?"* — bạn không
+thiết kế test case cụ thể (đó là qc-design-test).
+
+## Skills (`{paths.qc_skills_dir}/qa-planner/`)
+
+- `test-plan.md` — khung plan: scope theo từng test layer (functional / integration /
+  e2e / non-functional), what-if, entry/exit criteria, và danh sách questions-for-dev
+  suy ra từ `DOC_GAP.md`.
+- `risk-model.md` — **cách tính** mức rủi ro: 7 nguồn rủi ro · khả năng × thiệt hại → P0–P3 ·
+  và dùng mức đó chia **độ sâu** test. `test-plan.md` có khung bảng `§6`; file này là cách điền.
+  Nạp cùng lúc, không phải thay thế.
+
+## Output
+
+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.
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mỗi dòng rủi ro neo được vào một `BR`/`AC`/`GAP` **có thật** trong
+  `REQUIREMENT_ANALYSIS.md`/`DOC_GAP.md` — không phải rủi ro chung chung tự nghĩ ra kiểu *"hiệu
+  năng có thể chậm"*? Mỗi `questions-for-dev` suy ra từ một gap cụ thể?
+- **Nhảy bước:** đã đọc **cả hai** file đầu vào (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) và lọc
+  theo cột `UC` — không chỉ đọc file thứ nhất?
+- **Số liệu:** `{risks}`/`{questions}` in ở report = đúng số dòng thật trong `TEST_PLAN.md` vừa
+  ghi, không phải đếm nhẩm?
+
+## Report
+
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
-Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
-
-```
-/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}
-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)
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/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}
+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ó}
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+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-report.md

@@ -1,14 +1,14 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-report — QC Test Report & Evidence
-
-> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ bước report của qa-runner team QC.
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-report — QC Test Report & Evidence
+
+> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ bước report của qa-runner team QC.
+
+## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
 Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
@@ -160,58 +160,74 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
 - "N" → dừng, hỏi người dùng muốn thay đổi gì.
 - Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
   🔴/⚠️ (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. Sinh report từ lần chạy `/qc-run-test` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
-
-## Context
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Sinh report từ lần chạy `/qc-run-test` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
+
+## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
 `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ỗ.
-
----
-
-## Role
-
-Bạn là stage **QC Report** — biến lần chạy gần nhất thành report + evidence chia sẻ được.
-
-## Skill (`{paths.qc_skills_dir}/qa-runner/report/`)
-
-- `report.md` — tự đủ: pytest-html (`--html=reports/<feature>/report.html
-  --self-contained-html`) + Playwright Trace (`test-results/<nodeid>/trace.zip`, xem qua
-  `python3 -m playwright show-trace <file>`), kèm screenshot/evidence đính trên FAIL/SKIP.
-
-## Procedure
-
-1. Định vị artifact của lần chạy gần nhất cho `{UC-ID}` (report pytest-html + trace).
-2. Sinh/làm mới `reports/<feature>/report.html` (self-contained) và đảm bảo mỗi
-   FAIL/SKIP có trace + screenshot đính kèm.
-3. Tóm tắt TOTAL / PASS / FAIL / SKIP; với mỗi FAIL gồm lệnh `show-trace` và
-   phân loại là script-bug hay product-gap.
-4. **Bàn giao product-gap về spec (có nhắc).** Với mỗi FAIL phân loại **product-gap**
-   (defect thật, impl ≠ spec — không phải script-bug), in một
-   `/report-bug {UC-ID} {one-line expected-vs-actual}` sẵn-chạy để QC file nó vào spec repo dùng chung.
-   BUG_FLOW của `/report-bug` rồi định tuyến root cause (Code / BDD / PRD / Design / Env). Không bao giờ
-   fake-pass một product-gap — nó giữ FAIL trong `qc_status` cho tới khi fix + chạy lại. **script-bug
-   KHÔNG được file** (QC fix script và chạy lại). Liệt kê các lệnh; đừng tự tạo report.
-
-## Report
-
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+---
+
+## Role
+
+Bạn là stage **QC Report** — biến lần chạy gần nhất thành report + evidence chia sẻ được.
+
+## Skill (`{paths.qc_skills_dir}/qa-runner/report/`)
+
+- `report.md` — tự đủ: pytest-html (`--html=reports/<feature>/report.html
+  --self-contained-html`) + Playwright Trace (`test-results/<nodeid>/trace.zip`, xem qua
+  `python3 -m playwright show-trace <file>`), kèm screenshot/evidence đính trên FAIL/SKIP.
+
+## Procedure
+
+1. Định vị artifact của lần chạy gần nhất cho `{UC-ID}` (report pytest-html + trace).
+2. Sinh/làm mới `reports/<feature>/report.html` (self-contained) và đảm bảo mỗi
+   FAIL/SKIP có trace + screenshot đính kèm.
+3. Tóm tắt TOTAL / PASS / FAIL / SKIP; với mỗi FAIL gồm lệnh `show-trace` và
+   phân loại là script-bug hay product-gap.
+4. **Bàn giao product-gap về spec (có nhắc).** Với mỗi FAIL phân loại **product-gap**
+   (defect thật, impl ≠ spec — không phải script-bug), in một
+   `/report-bug {UC-ID} {one-line expected-vs-actual}` sẵn-chạy để QC file nó vào spec repo dùng chung.
+   BUG_FLOW của `/report-bug` rồi định tuyến root cause (Code / BDD / PRD / Design / Env). Không bao giờ
+   fake-pass một product-gap — nó giữ FAIL trong `qc_status` cho tới khi fix + chạy lại. **script-bug
+   KHÔNG được file** (QC fix script và chạy lại). Liệt kê các lệnh; đừng tự tạo report.
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mọi con số trong báo cáo trích được về **một dòng cụ thể** của sổ trace / output
+  runner / bug report — không nội suy khi thiếu mẫu?
+- **Nhảy bước:** đã tổng hợp trên **toàn bộ** SC trong phạm vi, không chỉ những SC có kết quả
+  đẹp? Đã liệt kê cả SC `not_run` và `flaky`, không im lặng bỏ khỏi bảng?
+- **Số liệu:** mọi `%` là phép chia thật **và nói rõ mẫu số**? Chỗ thiếu dữ liệu ghi **"chưa đủ
+  dữ liệu"** thay vì điền một số cho đủ bảng?
+
+> **Trạm này là nơi số liệu đi ra khỏi đội QC.** Một con số sai ở các trạm trước còn người trong
+> đội nhìn thấy; sai ở đây là đi vào báo cáo cho Lead/PM. Nhóm 3 vì vậy là nhóm nặng nhất ở đây:
+> *"một bảng đầy số sai tệ hơn một bảng có ô trống ghi rõ lý do"*.
+
+## Report
+
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
-Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
-
-```
-/qc-report Hoàn tất — {UC-ID}
-Report: reports/<feature>/report.html   (TOTAL {N} · PASS {p} · FAIL {f} · SKIP {s})
-Trace : test-results/<nodeid>/trace.zip  (python3 -m playwright show-trace <file>)
-
-Product-gap cần file ({g}):   ← chạy các lệnh này để PO/Dev thấy trên /sync (script-bug bị loại)
-  /report-bug {UC-ID} {gap 1 — expected vs actual}
-  /report-bug {UC-ID} {gap 2 …}
-  (không có → skip)
-
-Next: /validate-traces {UC-ID}   ← làm mới Living Docs (qc_status), rồi tạo PR
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-report Hoàn tất — {UC-ID}
+Report: reports/<feature>/report.html   (TOTAL {N} · PASS {p} · FAIL {f} · SKIP {s})
+Trace : test-results/<nodeid>/trace.zip  (python3 -m playwright show-trace <file>)
+
+Product-gap cần file ({g}):   ← chạy các lệnh này để PO/Dev thấy trên /sync (script-bug bị loại)
+  /report-bug {UC-ID} {gap 1 — expected vs actual}
+  /report-bug {UC-ID} {gap 2 …}
+  (không có → skip)
+
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next: /validate-traces {UC-ID}   ← làm mới Living Docs (qc_status), rồi tạo PR
+```