@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/core/commands/qc-run-test.md

@@ -1,14 +1,14 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-run-test — QC Script Generation & Run (ghi qc_status)
-
-> Stage 5 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-runner của team QC. Sinh & chạy Python pytest-playwright từ `.Test.md` đã review, rồi ghi `qc_status` **chính thức** vào trace TSV.
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-run-test — QC Script Generation & Run (ghi qc_status)
+
+> Stage 5 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-runner của team QC. Sinh & chạy Python pytest-playwright từ `.Test.md` đã review, rồi ghi `qc_status` **chính thức** vào trace TSV.
+
+## 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,258 +160,200 @@ 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 (`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
+
+
+*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 đó**,
 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 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)
-
-Bạn là **QC Runner** — stage 5. Chuyển `.Test.md` đã review thành Python
-pytest-playwright script + Page Object, chạy chúng, và report kết quả theo từng scenario.
-
-Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
-- Markdown-first: không bao giờ sinh Python khi chưa có `.Test.md` đã review.
-- Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
-- **Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này**) và dựng mỗi Page Object locator từ test-id ổn định của nó. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có action mà **không** có test-id trong §4.5.6 — và ghi chú để gap được thêm vào tech-design.
-
-- **TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.**
-  Đọc `@trace.testid_attr` từ **header tech-doc gộp** (do `/map-testids` ghi — nó đã phân giải một lần cho cả feature). Đây là **nửa QC của contract FE↔QC**: `/generate-code` đọc chính field này để emit thuộc tính lên element.
-
-  | Đọc được | Làm gì |
-  |---|---|
-  | web + attr ≠ `data-testid` (vd `data-test` · `data-qa`) | **BẮT BUỘC** cấu hình test-id attribute trước khi dùng `get_by_test_id()`: `playwright.selectors.set_test_id_attribute("{attr}")` (hoặc `testIdAttribute` trong config). Bỏ bước này thì `get_by_test_id()` vẫn dò `data-testid` mặc định → **trượt 100% locator**. |
-  | web + attr = `data-testid` | `get_by_test_id("...")` như thường (đúng mặc định Playwright). |
-  | RN / Flutter / native | Dùng đúng cơ chế mà `{attr}` mô tả (`testID` · `Key`/`Semantics(identifier:)` · `accessibilityIdentifier`). |
-  | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode:** `⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo platform ({attr mặc định}). Nếu FE dùng thuộc tính khác thì MỌI locator sẽ trượt. Chạy /map-testids {UC-ID} để ghi field này.` Rồi mới fallback. |
-
-  > **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã được ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống. Nó hỏng ở đúng ca field này tồn tại để phục vụ: dự án web dùng `data-test`/`data-qa` thay vì mặc định, hoặc một PRD trải ba platform với ba thuộc tính khác nhau. Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail với "element not found" — trông y hệt một bug sản phẩm, nên QC sẽ đi mở bug thay vì sửa selector.
-- pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không bao giờ xen kẽ.
-- Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
-- Phủ **100%** TC trong file — mỗi TC kết thúc Pass/Fail/Skip (không còn Draft).
-- Phân loại mỗi FAIL: script-bug (fix selector/logic) vs product-gap (giữ FAIL + evidence, không bao giờ fake-pass).
-
-## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-runner/`)
-
-`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
-`non-functional.md`, `exploratory/session.md`.
-
-## Trace tag (bắt buộc)
-
-Mỗi pytest test được sinh ra mang scenario framework mà nó verify, lấy từ
-Trace matrix của `.Test.md`:
-
-```python
-# @trace.verifies={UC-ID}-SC{N}
-def test_TC_<FEATURE>_001_...(...): ...
-```
-
-## Write Trace State — qc_status (kết quả QC CHÍNH THỨC)
-
-Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` (`{active_platform}` đã phân giải ở Bước 1 — chính là platform của QC pass này; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{active_platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp
-`sc_id` qua tag `@trace.verifies={UC-ID}-SC{N}` của test). *(Umbrella + `spec_source`: `trace_dir` là `{spec_source}/.trace` — ghi update `qc_status` vào **spec repo** và commit/push spec submodule, giống `feedback/`.)*
-
-| Cột | Giá trị |
-|--------|-------|
-| `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_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ề.
-Với FAIL product-gap, set `qc_owner=dev` ngay; `BUG-{id}` được backfill vào `qc_blocked_by`
-khi QC chạy `/report-bug` mà `/qc-report` nhắc.
-
-### Guard — ĐỌC `status` trước khi ghi `pass` *(bắt buộc)*
-
-*Contract: `bin/trace-schema.json` → `positive_assertion_guards`. Đối xứng hoàn toàn với `/dev-run-test`; dữ liệu đã có trong sổ, không phát sinh I/O.*
-
-`pass` **không** mang nghĩa *"QC test đã chạy và xanh"*. Nó mang nghĩa **"scenario này đã được nghiệm thu theo spec HIỆN TẠI"**.
-
-| `status` của row | `qc_status` ghi gì | `qc_run_at` |
-|---|---|---|
-| `OK` · `GAP` · `UNTRACKED` | như bảng trên | hôm nay |
-| **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG `pass`)* · **fail** → **`fail`** như thường · **skip** → `skip` như thường | `—` nếu ghi `not_run` |
-| **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` | `—` |
-
-**Chỉ `pass` bị chặn.** `fail` là tin xấu thật, `skip` là giá trị trung tính — cả hai không phải lời khẳng định nên ghi bình thường. Chặn chúng là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.
-
-Khi hạ về `not_run` vì `DRIFT`/`ORPHANED`, **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy §Đóng bug đã verify — hai bước đó chỉ dành cho `pass` **thật**. Đóng một bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai. In:
-```
-⚠️  {sc_id} — QC test XANH nhưng row đang {DRIFT | ORPHANED}, nên KHÔNG ghi pass.
-    Không bug nào được đóng ở lần chạy này cho SC đó.
-    Làm: /generate-code {UC-ID} → /qc-design-test lại → chạy lại lệnh này.
-```
-
-> **Vì sao (GAPS-v4 G55).** Bản cũ khai `qc_status` **trực giao** với `status` — trực giao về *kết quả chạy* thì đúng, nhưng **không** trực giao về *quyền được khẳng định*. `/generate-bdd` hạ `qc_status → not_run` khi spec đổi (kèm lý do *"cái này làm cờ nói dối"*), rồi lần `/qc-run-test` kế tiếp dựng lại `pass` với ngày mới. Ở đây hậu quả còn đi xa hơn `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify) — nên guard phải chặn cả nhánh đó.
->
-> **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt đúng trạng thái này ở sổ thật, bất kể lệnh nào ghi ra.
-
-Giữ nguyên mọi cột khác — **không bao giờ** đụng `dev_selftest`/`dev_selftest_at`
-(do `/dev-run-test` sở hữu; nó có guard riêng cùng loại). `qc_status` (QC chính thức) và
-`dev_selftest` (dev smoke) là hai tín hiệu riêng; cả hai trực giao với `status` về **kết quả
-chạy**, nhưng **KHÔNG** trực giao về **quyền khẳng định `pass`** — xem §Guard ở trên.
-
-## Đóng bug đã verify *(chạy TRƯỚC khi clear `qc_blocked_by`)*
-
-`/qc-run-test` là **chủ sở hữu** bước `🟡 Fixed → 🟢 Closed` của bug lifecycle: `/report-bug` mở bug (`🟢 Open`), `/fix-bug` Phase 5.5 đặt `🟡 Fixed`, và chỉ QC re-verify mới được đóng. Không có bước này thì mọi bug đứng vĩnh viễn ở `Fixed`.
-
-Với **mỗi** row mà `qc_status` **vừa chuyển thành `pass`**:
-
-1. **Đọc `qc_blocked_by` TRƯỚC khi clear.** Nếu khớp `BUG-*`:
-   - Mở `{paths.bug_reports_dir}/{BUG-ID}.md`.
-   - `State` đang `🟡 Fixed` → set `🟢 Closed` + thêm dòng: `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass`.
-   - `State` đang `🟢 Open` (**chưa ai fix mà test đã pass**) → **KHÔNG đóng.** Giữ `Open` và thêm ghi chú: `⚠️ {UC-ID}-SC{N} pass ngày {today} nhưng bug chưa có Resolution — kiểm tra test có phủ đúng behavior đã báo không.` *(Test pass trên một bug chưa fix là dấu hiệu test sai, không phải bug hết. Tự đóng ở đây sẽ chôn một defect thật.)*
-   - Không tìm thấy file → bỏ qua im lặng (bug có thể đã archive).
-2. Nếu khớp `GAP-*` → **không** đóng gì (spec-gap do PO xử lý, không phải QC).
-3. Commit + push các bug report vừa đổi vào spec repo (cùng cách push như `/report-bug` Step 6) — file local là dead drop, PO/Dev chỉ thấy sau khi push.
-
-Rồi mới clear `qc_owner`/`qc_blocked_by` về `—`.
+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.
 
-## Refresh Panel Mirror
+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 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)
+
+Bạn là **QC Runner** — stage 5. Chuyển `.Test.md` đã review thành Python
+pytest-playwright script + Page Object, chạy chúng, và report kết quả theo từng scenario.
+
+Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
+- Markdown-first: không bao giờ sinh Python khi chưa có `.Test.md` đã review.
+- Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
+- **Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (nếu có — bảng gộp mọi UC của platform, **lọc theo cột "Phục vụ SC" khớp SC của UC này**) và dựng mỗi Page Object locator từ test-id ổn định của nó. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có action mà **không** có test-id trong §4.5.6 — và ghi chú để gap được thêm vào tech-design.
+
+- **TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.**
+  Đọc `@trace.testid_attr` từ **header tech-doc gộp** (do `/map-testids` ghi — nó đã phân giải một lần cho cả feature). Đây là **nửa QC của contract FE↔QC**: `/generate-code` đọc chính field này để emit thuộc tính lên element.
+
+  | Đọc được | Làm gì |
+  |---|---|
+  | web + attr ≠ `data-testid` (vd `data-test` · `data-qa`) | **BẮT BUỘC** cấu hình test-id attribute trước khi dùng `get_by_test_id()`: `playwright.selectors.set_test_id_attribute("{attr}")` (hoặc `testIdAttribute` trong config). Bỏ bước này thì `get_by_test_id()` vẫn dò `data-testid` mặc định → **trượt 100% locator**. |
+  | web + attr = `data-testid` | `get_by_test_id("...")` như thường (đúng mặc định Playwright). |
+  | RN / Flutter / native | Dùng đúng cơ chế mà `{attr}` mô tả (`testID` · `Key`/`Semantics(identifier:)` · `accessibilityIdentifier`). |
+  | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode:** `⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo platform ({attr mặc định}). Nếu FE dùng thuộc tính khác thì MỌI locator sẽ trượt. Chạy /map-testids {UC-ID} để ghi field này.` Rồi mới fallback. |
+
+  > **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã được ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống. Nó hỏng ở đúng ca field này tồn tại để phục vụ: dự án web dùng `data-test`/`data-qa` thay vì mặc định, hoặc một PRD trải ba platform với ba thuộc tính khác nhau. Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail với "element not found" — trông y hệt một bug sản phẩm, nên QC sẽ đi mở bug thay vì sửa selector.
+- pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không bao giờ xen kẽ.
+- Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
+- Phủ **100%** TC trong file — mỗi TC kết thúc Pass/Fail/Skip (không còn Draft).
+- Phân loại mỗi FAIL — **ba** nhãn, sau khi đã chạy lại (xem §Chạy lại trước khi kết luận): `script-bug` (fix selector/logic) · `product-gap` (giữ FAIL + evidence, **không bao giờ fake-pass**) · `flaky` (không nhất quán qua các lần chạy lại — chưa đủ căn cứ để kết luận hai cái kia).
+
+## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-runner/`)
+
+`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
+`non-functional.md`, `exploratory/session.md`.
+
+## Trace tag (bắt buộc)
+
+Mỗi pytest test được sinh ra mang scenario framework mà nó verify, lấy từ
+Trace matrix của `.Test.md`:
+
+```python
+# @trace.verifies={UC-ID}-SC{N}
+def test_TC_<FEATURE>_001_...(...): ...
+```
+
+## Chạy lại trước khi kết luận — rồi người xác nhận *(bắt buộc cho MỌI FAIL)*
+
+Một test đỏ **một lần** chưa nói được nó đỏ vì cái gì. Trước khi phân loại, phải loại nhiễu.
+
+### Bước 1 — Chạy lại riêng test đó, tối đa 2 lần
+
+```
+đỏ → đỏ → đỏ     ⇒ NHẤT QUÁN       → sang Bước 2, phân loại script-bug | product-gap
+đỏ → xanh        ⇒ KHÔNG NHẤT QUÁN → flaky
+đỏ → đỏ → xanh   ⇒ KHÔNG NHẤT QUÁN → flaky
+```
+
+**Đây KHÔNG phải `retries` trong config của test runner.** `retries` tự thử lại rồi báo
+*"passed on retry"* — nó **che** sự không nhất quán. Ở đây chạy **tách biệt từng lần** để
+**quan sát**, vì chính sự không nhất quán mới là thông tin cần.
+
+### Bước 2 — Điều tra bằng bằng chứng, KHÔNG đoán
+
+Đọc trace/video/log: timeline, DOM snapshot, network, console **tại thời điểm fail**. Rồi chọn
+một trong ba:
+
+| Nhãn | Khi nào | Hệ quả |
+|---|---|---|
+| `script-bug` | Sai locator / logic test / timing / dữ liệu test | QC tự sửa. **Không** mở bug |
+| `product-gap` | Hành vi thật ≠ spec (PRD/BDD/AC) — defect thật | Mở bug qua `/report-bug`. Giữ `fail` + evidence, **không bao giờ fake-pass** |
+| `flaky` | Không nhất quán ở Bước 1 — **chưa đủ căn cứ** | Cách ly + **ghi nghi vấn nguyên nhân**. **Không** mở bug từ một lần chạy hên xui |
+
+### Bước 3 — Người xác nhận TRƯỚC khi hành động
+
+In đề xuất kèm bằng chứng cụ thể, rồi **dừng chờ**:
+
+```
+❓ {UC-ID}-SC{N} FAIL — đề xuất: {script-bug | product-gap | flaky}
+   Bằng chứng: {trích từ trace/log — vd "locator #submit-btn không tồn tại, DOM đã đổi id"
+                hoặc "lần 1 đỏ, lần 2 xanh — không nhất quán"}
+   Xác nhận phân loại này? (script-bug / product-gap / flaky)
+```
+
+**KHÔNG ghi `qc_status` cho scenario nào còn FAIL chưa được xác nhận phân loại.**
+
+**Nếu QC không chắc** giữa `script-bug` và `product-gap` (bằng chứng mơ hồ, hành vi ở biên của
+spec) → **mời Dev cùng xem trace**, đừng tự đoán cho xong.
+
+> **Vì sao chỗ này đáng chặn** — trong khi framework vốn đang cố giảm số cổng chặn (G41): vì
+> **hai hướng sai đều không đảo ngược rẻ**. Gắn nhầm `script-bug` cho lỗi sản phẩm thật là
+> **giấu bug** — dev không bao giờ thấy nó. Gắn nhầm `product-gap` cho lỗi test là mở bug sai,
+> hoặc tệ hơn là đi "sửa" một sản phẩm không có lỗi. Đây không phải cổng hỏi cho có; nó là điểm
+> rẽ mà agent **không có quyền tự quyết**.
+>
+> **Vì sao `flaky` không phải thùng rác.** Nhãn này **buộc** ghi nghi vấn nguyên nhân (thường:
+> thiếu cách ly dữ liệu · thiếu `storageState` · race condition thật) và cách ly test, không
+> phải chỉ đánh dấu rồi bỏ qua. Nó là *"chưa kết luận được"*, không phải *"thôi bỏ đi"* — và
+> một test nằm mãi ở `flaky` là một việc còn nợ, nhìn thấy được.
+
+## Write Trace State — qc_status (kết quả QC CHÍNH THỨC)
+
+Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` (`{active_platform}` đã phân giải ở Bước 1 — chính là platform của QC pass này; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{active_platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp
+`sc_id` qua tag `@trace.verifies={UC-ID}-SC{N}` của test). *(Umbrella + `spec_source`: `trace_dir` là `{spec_source}/.trace` — ghi update `qc_status` vào **spec repo** và commit/push spec submodule, giống `feedback/`.)*
+
+| Cột | Giá trị |
+|--------|-------|
+| `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 **đã xác nhận là `script-bug` hoặc `product-gap`** · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó, **hoặc SC chỉ có kết quả `flaky`** (xem hàng dưới). Row **`DRIFT`/`ORPHANED`**: **không bao giờ ghi `pass`** — hạ về `not_run` |
+| `qc_status` khi `flaky` | **`not_run`, KHÔNG phải `fail`.** `fail` ngụ ý *đã có kết luận*; kết quả không nhất quán qua các lần chạy lại nghĩa là **chưa có** kết luận nào. Ghi `fail` ở đây là khẳng định một điều chưa biết — và nó còn đẩy việc sang dev (xem `qc_owner`) trong khi việc đang thuộc QC |
+| `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_GAP` 🔴 Blocker đang open** chặn test (PO phải làm rõ PRD/BDD) · **`qc` nếu FAIL = flaky** (QC phải điều tra nguyên nhân, **không** phải việc của dev) · `—` 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ề.
+Với FAIL product-gap, set `qc_owner=dev` ngay; `BUG-{id}` được backfill vào `qc_blocked_by`
+khi QC chạy `/report-bug` mà `/qc-report` nhắc.
+
+### Guard — ĐỌC `status` trước khi ghi `pass` *(bắt buộc)*
+
+*Contract: `bin/trace-schema.json` → `positive_assertion_guards`. Đối xứng hoàn toàn với `/dev-run-test`; dữ liệu đã có trong sổ, không phát sinh I/O.*
+
+`pass` **không** mang nghĩa *"QC test đã chạy và xanh"*. Nó mang nghĩa **"scenario này đã được nghiệm thu theo spec HIỆN TẠI"**.
+
+| `status` của row | `qc_status` ghi gì | `qc_run_at` |
+|---|---|---|
+| `OK` · `GAP` · `UNTRACKED` | như bảng trên | hôm nay |
+| **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG `pass`)* · **fail** → **`fail`** như thường · **skip** → `skip` như thường | `—` nếu ghi `not_run` |
+| **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` | `—` |
+
+**Chỉ `pass` bị chặn.** `fail` là tin xấu thật, `skip` là giá trị trung tính — cả hai không phải lời khẳng định nên ghi bình thường. Chặn chúng là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.
+
+Khi hạ về `not_run` vì `DRIFT`/`ORPHANED`, **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy §Đóng bug đã verify — hai bước đó chỉ dành cho `pass` **thật**. Đóng một bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai. In:
+```
+⚠️  {sc_id} — QC test XANH nhưng row đang {DRIFT | ORPHANED}, nên KHÔNG ghi pass.
+    Không bug nào được đóng ở lần chạy này cho SC đó.
+    Làm: /generate-code {UC-ID} → /qc-design-test lại → chạy lại lệnh này.
+```
+
+> **Vì sao (GAPS-v4 G55).** Bản cũ khai `qc_status` **trực giao** với `status` — trực giao về *kết quả chạy* thì đúng, nhưng **không** trực giao về *quyền được khẳng định*. `/generate-bdd` hạ `qc_status → not_run` khi spec đổi (kèm lý do *"cái này làm cờ nói dối"*), rồi lần `/qc-run-test` kế tiếp dựng lại `pass` với ngày mới. Ở đây hậu quả còn đi xa hơn `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify) — nên guard phải chặn cả nhánh đó.
+>
+> **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt đúng trạng thái này ở sổ thật, bất kể lệnh nào ghi ra.
+
+Giữ nguyên mọi cột khác — **không bao giờ** đụng `dev_selftest`/`dev_selftest_at`
+(do `/dev-run-test` sở hữu; nó có guard riêng cùng loại). `qc_status` (QC chính thức) và
+`dev_selftest` (dev smoke) là hai tín hiệu riêng; cả hai trực giao với `status` về **kết quả
+chạy**, nhưng **KHÔNG** trực giao về **quyền khẳng định `pass`** — xem §Guard ở trên.
+
+## Đóng bug đã verify *(chạy TRƯỚC khi clear `qc_blocked_by`)*
+
+`/qc-run-test` là **chủ sở hữu** bước `🟡 Fixed → 🟢 Closed` của bug lifecycle: `/report-bug` mở bug (`🟢 Open`), `/fix-bug` Phase 5.5 đặt `🟡 Fixed`, và chỉ QC re-verify mới được đóng. Không có bước này thì mọi bug đứng vĩnh viễn ở `Fixed`.
+
+Với **mỗi** row mà `qc_status` **vừa chuyển thành `pass`**:
+
+1. **Đọc `qc_blocked_by` TRƯỚC khi clear.** Nếu khớp `BUG-*`:
+   - Mở `{paths.bug_reports_dir}/{BUG-ID}.md`.
+   - `State` đang `🟡 Fixed` → set `🟢 Closed` + thêm dòng: `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass`.
+   - `State` đang `🟢 Open` (**chưa ai fix mà test đã pass**) → **KHÔNG đóng.** Giữ `Open` và thêm ghi chú: `⚠️ {UC-ID}-SC{N} pass ngày {today} nhưng bug chưa có Resolution — kiểm tra test có phủ đúng behavior đã báo không.` *(Test pass trên một bug chưa fix là dấu hiệu test sai, không phải bug hết. Tự đóng ở đây sẽ chôn một defect thật.)*
+   - Không tìm thấy file → bỏ qua im lặng (bug có thể đã archive).
+2. Nếu khớp `GAP-*` → **không** đóng gì (spec-gap do PO xử lý, không phải QC).
+3. Commit + push các bug report vừa đổi vào spec repo (cùng cách push như `/report-bug` Step 6) — file local là dead drop, PO/Dev chỉ thấy sau khi push.
+
+Rồi mới clear `qc_owner`/`qc_blocked_by` về `—`.
+
+## Refresh Panel Mirror
 # Làm mới panel mirror của Living Docs *(local)*
 
 > **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
@@ -465,21 +407,40 @@ một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (c
 `{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
 được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
 bên trong từng sub-agent.
-
-
-## 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 đề xuất phân loại FAIL dựa trên bằng chứng **đọc thật** từ trace/video/log — trích
+  được dòng lỗi, tên locator, response code — không phải *"thường thì đây là script-bug"*?
+- **Nhảy bước:** **MỌI** FAIL đã qua chạy lại ×2 trước khi đề xuất — không có cái nào bị bỏ bước
+  vì "chắc chắn là gì rồi"? Guard `DRIFT`/`ORPHANED` đã áp cho **từng** row trước khi ghi `pass`,
+  không chỉ vài row?
+- **Số liệu:** `{pass}`/`{fail}`/`{skip}`/`{flaky}` = **đúng output của test runner**
+  (`--reporter=list` / summary), không phải đếm lại bằng mắt qua context?
+
+> Nhóm 3 ở trạm này là chỗ dễ sai nhất: kết quả chạy nằm trong output của runner, nhưng agent đã
+> đọc qua nó một lần rồi **nhớ lại** lúc viết report. Lấy lại từ nguồn, đừng nhớ.
+
+## 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-run-test Report — {UC-ID} ({qc-playwright})
-QC: ✅ {pass} pass | ❌ {fail} fail | ⏭️ {skip} skip   (TCs: {total})
-Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv updated (qc_status, qc_run_at)
-{chỉ khi có bug đổi trạng thái — ngược lại bỏ}
-🐞 Bugs: {BUG-ID} → 🟢 Closed (verified {UC-ID}-SC{N})
-   ⚠️ {BUG-ID} giữ 🟢 Open — SC pass nhưng bug chưa có Resolution, kiểm tra lại test
-Next: /qc-report {UC-ID}   ← sinh report + evidence
-      /qc-review {UC-ID}   ← review script đã sinh trước khi merge
-📊 Living Docs: chạy /validate-traces (hoặc /sync) để push qc_status lên dashboard spec-module.
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-run-test Report — {UC-ID} ({qc-playwright})
+QC: ✅ {pass} pass | ❌ {fail} fail | ⏭️ {skip} skip | 🔄 {flaky} flaky   (TCs: {total})
+{chỉ khi có FAIL — ngược lại bỏ}
+Phân loại FAIL (người đã xác nhận): script-bug {a} · product-gap {b} · flaky {c} → cách ly
+   {với mỗi flaky: "🔄 {UC-ID}-SC{N} — nghi: {nguyên nhân}" }
+Trace: {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv updated (qc_status, qc_run_at)
+{chỉ khi có bug đổi trạng thái — ngược lại bỏ}
+🐞 Bugs: {BUG-ID} → 🟢 Closed (verified {UC-ID}-SC{N})
+   ⚠️ {BUG-ID} giữ 🟢 Open — SC pass nhưng bug chưa có Resolution, kiểm tra lại test
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next: /qc-report {UC-ID}   ← sinh report + evidence
+      /qc-review {UC-ID}   ← review script đã sinh trước khi merge
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push qc_status lên dashboard spec-module.
+```

package/core/commands/review-tech-docs.md

@@ -316,9 +316,29 @@ Kiểm tra tất cả section chuẩn có mặt và không rỗng:
 | Data Model Changes (nếu entity đổi) | Major |
 | Error Handling Strategy | Major |
 | Open Questions / Assumptions | Minor |
+| **§4.5.6 Test Selectors rỗng** (chỉ khi doc có block `### 4.5 — {platform}` client) | **Major** |
+| **Header thiếu `@trace.testid_attr`** (cùng điều kiện trên) | **Major** |
 
 → Mọi finding section-thiếu T6 đều **auto-fixable**: AI thêm skeleton section kèm prompt.
 
+> **HAI DÒNG CUỐI KHÔNG auto-fixable — đừng tự điền.** Chúng là **hợp đồng test-id FE↔QC**, và
+> nội dung phải đến từ design-spec + BDD qua `/map-testids`, không phải từ reviewer đoán. Finding
+> ghi:
+>
+> ```
+> Tech-doc có phần UI (§4.5 {platform}) nhưng chưa khai Test Selectors.
+> FE sẽ không biết gắn id nào, QC sẽ không có gì để bám → mỗi bên tự làm một kiểu.
+> Sửa: /map-testids {UC-ID} rồi review lại.
+> ```
+>
+> **Vì sao Major (chặn APPROVED).** Một tech-doc có phần UI mà không khai test selector thì
+> **chưa viết xong** — như có §4 API mà không khai endpoint. Và `/review-tech-docs` APPROVED
+> chính là cổng mở đường cho `/generate-code`; cho qua ở đây là để FE bắt đầu gắn id mà không
+> có hợp đồng nào.
+>
+> *Doc chỉ phủ platform `system` (backend-only) → không có §4.5 → hai dòng này **không áp dụng**,
+> đừng tạo finding.*
+
 ### T7 — Cross-Team API Contract Review
 
 *Chỉ áp dụng khi TẤT CẢ điều sau đúng:*

package/core/commands/setup-ai-first.md

@@ -448,13 +448,13 @@ Hướng dẫn: "Mở `specs/domain-knowledge/core-entities.md` và định ngh
 
 ## Step 6 — Cài VS Code Extension (Khuyến nghị)
 
-Khuyến nghị user cài extension VS Code **Spec Driven Docs Tools** — nó cung cấp panel Review Board + Living Documentation tích hợp với workflow này.
+Khuyến nghị user cài extension VS Code **SDD Board** — nó cung cấp panel Review Board + Living Documentation tích hợp với workflow này.
 
 ```bash
-code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+code --install-extension EducaCorp.sdd-board
 ```
 
-Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → tìm **Spec Driven Docs Tools**.
+Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → tìm **SDD Board**.
 
 **Nó làm gì:**
 - 📋 **Review Board** — UI trực quan để review findings từ `/refine-prd`, `/review-context`, `/review-tech-docs`
@@ -557,7 +557,7 @@ Next:
   4. Điền specs/domain-knowledge/core-entities.md
   5. git add và commit 4 file đó
   6. Cài VS Code extension:
-     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+     code --install-extension EducaCorp.sdd-board
   7. /define-product để bắt đầu feature đầu tiên
 ```
 
@@ -591,7 +591,7 @@ Next:
   3. Điền specs/domain-knowledge/core-entities.md        ← entity glossary
   4. git add và commit các file đó
   5. Cài VS Code extension:
-     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+     code --install-extension EducaCorp.sdd-board
   6. /define-product để bắt đầu feature đầu tiên
 
 ⚠️  Nhắc handoff team dev:

package/core/commands/update-framework.md

@@ -193,7 +193,7 @@ Your content was preserved:
 Review & commit:
    git diff .agent/
    git add .agent/ .claude/commands/
-   git commit -m "chore: upgrade spec-driven-docs v{current} → v{latest}"
+   git commit -m "chore: upgrade sdd-framework v{current} → v{latest}"
    {umbrella mode: this is the umbrella root — service submodules need no framework update}
 
 ---

package/core/commands/validate-traces.md

@@ -1223,7 +1223,7 @@ Schema:
 - `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
 - `tech_doc_revision` / `fe_tech_doc_revision`: dùng integer; `0` nếu chưa sinh
 - `code_coverage_pct` / `test_coverage_pct`: làm tròn về integer gần nhất (0–100)
-- **`status` trong JSON CỐ TÌNH chỉ có 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — KHÔNG ghi `ORPHANED` vào field này. VS Code extension "Spec Driven Docs Tools" (sống **ngoài** repo này) switch trên `status`; thêm giá trị thứ 5 sẽ rơi vào nhánh không khớp và có thể làm row mất khỏi panel.
+- **`status` trong JSON CỐ TÌNH chỉ có 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — KHÔNG ghi `ORPHANED` vào field này. VS Code extension "SDD Board" (sống **ngoài** repo này) switch trên `status`; thêm giá trị thứ 5 sẽ rơi vào nhánh không khớp và có thể làm row mất khỏi panel.
   Row `ORPHANED` xuất ra JSON là: `"status": "DRIFT"` + `"orphaned": true`. Panel chưa hỗ trợ vẫn hiện nó như `DRIFT` — đủ đúng về nghĩa ("code không khớp spec, cần xử lý") và **không im lặng**; panel có đọc `orphaned` thì hiện nhãn riêng. Chi tiết đầy đủ luôn có ở `orphaned[]` và ở report terminal.
   **TSV giữ nguyên chữ `ORPHANED`** trong cột `status` — TSV là nguồn-sự-thật, JSON chỉ là bản xuất cho panel.
 - `orphaned` (boolean): `true` chỉ khi cột `status` của TSV là `ORPHANED`; mọi row khác ghi `false` (đừng bỏ trống — panel đọc field vắng dễ ra `undefined`).

package/core/modules/qc-playwright/stack-profile.yaml

@@ -19,7 +19,7 @@ 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 (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"
+    - "test-id values come from the FE tech-design 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 'Phục vụ 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: |