@educa-corp/sdd-framework 0.7.0 → 0.7.1

package/docs/03-guides/tester-qa.md

@@ -1,81 +1,81 @@
-[← Docs Home](../README.md) · [Guides](./)
-
-# Guide · Tester / QA
-
-> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
-
----
-
-## Chuỗi bước của bạn (Your path)
-
-```mermaid
-flowchart LR
-    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
-    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
-    REP --> FB["/report-bug · /propose-scenario"]
-    FB --> SYNC["/sync"]
-```
-
----
-
-## Việc của bạn ở mỗi bước
-
-| Trạm | Bạn làm gì |
-|------|-----------|
-| [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu** |
-| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
-| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
-| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
-| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL |
-| `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
-| [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
-
-Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
-
----
-
-## Nguyên tắc sống còn cho QA
-
-1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
-2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
-3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
-4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
-5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-run-test` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
-   - Ngoại lệ: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**.
-6. **`/propose-scenario` dùng đúng bộ tag canonical** — `@trace.scenario` (placeholder `SC?`, `/generate-bdd` gán số khi chèn) · `@trace.sc_version: 1.0` · `@trace.business_rules`. AC ghi thành comment `# Covers:`, **không** phải trace key. Thiếu `@trace.scenario`/`sc_version` thì scenario vào BDD mà **không có row trace** → vô hình với coverage.
-7. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
-
----
-
-## Câu hỏi bạn cần trả lời được
-
-- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
-- Rủi ro nào cao? Cần hỏi dev gì?
-- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
-- Bug này gắn với scenario/spec nào?
-- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
-- Hành vi phát hiện được có **AC nào phủ** không? → quyết định Case A hay Case B:
-
-  | | Đi đâu | Ai xử |
-  |---|---|---|
-  | **Case A** — thiếu scenario cho AC **đã có** | `feedback/bdd-proposals/` | `/generate-bdd` tự chèn khi bạn đặt `Status: accepted` |
-  | **Case B** — requirement **MỚI**, không AC nào phủ | `feedback/prd-change-requests/` | PO chạy `/extend-prd` |
-
-  Case B **không tự vào BDD được** — scenario chưa có AC để trace tới. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót đó. `/validate-traces` sẽ nhắc lại kèm **số ngày chờ** chừng nào request còn `Open`.
-
----
-
-## Anti-pattern
-
-- ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
-- ❌ Chạy `/qc-run-test` khi chưa qua `/qc-review`.
-- ❌ Lẫn `qc_status` với `dev_selftest`.
-- ❌ Bug không gắn spec → khó truy vết, khó regression.
-
----
-
-## Lệnh của bạn (Your commands)
-
-`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
-
-→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Tester / QA
+
+> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
+    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
+    REP --> FB["/report-bug · /propose-scenario"]
+    FB --> SYNC["/sync"]
+```
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Trạm | Bạn làm gì |
+|------|-----------|
+| [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu** |
+| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
+| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
+| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
+| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL. **Đọc cột `status` trước khi ghi `pass`** — row `DRIFT`/`ORPHANED` + test xanh → `not_run`, và **không đóng bug nào** ở lần chạy đó *(đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai)* |
+| `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
+| [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
+
+Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
+
+---
+
+## Nguyên tắc sống còn cho QA
+
+1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
+2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
+3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
+4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
+5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-run-test` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
+   - Ngoại lệ: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**.
+6. **`/propose-scenario` dùng đúng bộ tag canonical** — `@trace.scenario` (placeholder `SC?`, `/generate-bdd` gán số khi chèn) · `@trace.sc_version: 1.0` · `@trace.business_rules`. AC ghi thành comment `# Covers:`, **không** phải trace key. Thiếu `@trace.scenario`/`sc_version` thì scenario vào BDD mà **không có row trace** → vô hình với coverage.
+7. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
+- Rủi ro nào cao? Cần hỏi dev gì?
+- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
+- Bug này gắn với scenario/spec nào?
+- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
+- Hành vi phát hiện được có **AC nào phủ** không? → quyết định Case A hay Case B:
+
+  | | Đi đâu | Ai xử |
+  |---|---|---|
+  | **Case A** — thiếu scenario cho AC **đã có** | `feedback/bdd-proposals/` | `/generate-bdd` tự chèn khi bạn đặt `Status: accepted` |
+  | **Case B** — requirement **MỚI**, không AC nào phủ | `feedback/prd-change-requests/` | PO chạy `/extend-prd` |
+
+  Case B **không tự vào BDD được** — scenario chưa có AC để trace tới. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót đó. `/validate-traces` sẽ nhắc lại kèm **số ngày chờ** chừng nào request còn `Open`.
+
+---
+
+## Anti-pattern
+
+- ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
+- ❌ Chạy `/qc-run-test` khi chưa qua `/qc-review`.
+- ❌ Lẫn `qc_status` với `dev_selftest`.
+- ❌ Bug không gắn spec → khó truy vết, khó regression.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)

package/docs/04-reference/commands.md

@@ -40,7 +40,7 @@ Mọi lệnh chạy chung một **Gate** (model check → target → context-loa
 > | **Đổi** một yêu cầu đang đúng cú pháp | **`/amend-prd`** | Edit **tại chỗ** — output **KHÔNG** phải superset; **không** đánh số mới, **không** xoá row |
 > | Sửa vấn đề **review đã soi ra** | `/refine-prd` → Review Board → `--resume` | Edit trong phạm vi finding |
 >
-> - `/generate-prd` chỉ có một cổng **chặn cứng** trên file đã có — gõ `Y` là nó vẫn ghi đè, và ghi đè sẽ mất changelog + **đánh số lại BR** ⇒ hỏng `@trace.business_rules` trong mọi BDD đã sinh.
+> - `/generate-prd` **DỪNG HẲN** trên file đã có — §Guard *"Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi Y/N"*, vì ghi đè mất changelog + **đánh số lại BR** ⇒ hỏng `@trace.business_rules` trong mọi BDD đã sinh, và cả ba mất mát đều không hoàn tác được từ trong lệnh.
 > - `/refine-prd` **không** thêm/đổi được theo ý định mới (nó tự cấm đụng section ngoài findings).
 > - `/extend-prd` **không** sửa được nội dung cũ, trừ một cửa **phái sinh**: khi phần THÊM làm một BR cũ sai (Bước 3.2).
 > - **Xoá hẳn** một BR/AC → không có lệnh, và **có chủ ý**: xoá row biến `@trace.business_rules` trong `.feature` thành `TRACE_ORPHAN` 🔴. Dùng `/amend-prd --retire {ID}` — nó khai tử **tại chỗ**, giữ nguyên row + ID.

package/docs/04-reference/trace-schema.md

@@ -17,7 +17,7 @@
 | Tag | Ý nghĩa | Bắt buộc |
 |-----|---------|:--------:|
 | `@trace.id` | UC-ID — `{TICKET-ID}-UC{N}` (vd `SEG01-UC1`) | ✅ |
-| `@trace.platform` | `web` / `app` / `system` — **mọi mode, kể cả umbrella** | ✅ |
+| `@trace.platform` | `web` / `app` / `system` / `webview` — **mọi mode, kể cả umbrella**. Đây là **delivery surface**, không phải tech stack: `webview` (bundle web nhúng trong app native — Phaser game, mini-app) là surface riêng, không phải `web` (browser) cũng không phải `app` (native) | ✅ |
 | `@trace.domain` | Domain nghiệp vụ | ✅ |
 | `@trace.prd` | TICKET-ID của PRD nguồn | ✅ |
 | `@trace.prd_version` | Version PRD lúc sinh BDD | ✅ |
@@ -172,6 +172,7 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 | Cờ | Nguồn | Nghĩa |
 |---|---|---|
+| `PRD_UNTRACKED_EDIT` 🔴 | Step 3.9 | **nội dung PRD đổi mà nhãn `Version` KHÔNG đổi** — có người sửa ngoài `/generate-prd` · `/extend-prd` · `/amend-prd` · `/refine-prd` · `/review-context`. So bằng `git diff` **và** `git status` với mốc `spec_baseline`. Cố ý **không** vào `gate.blocking` — xem dưới |
 | `PRD_DRIFT` | Step 4 | version PRD lệch **và** changelog **có** nêu UC này → nội dung đổi thật |
 | `PRD_STALE_REF` ⓘ | Step 4 | version lệch nhưng changelog **không** nêu UC này → chỉ con trỏ cũ. `--realign-prd-version` |
 | `BDD_DRIFT` | Step 5c | code mang `@trace.bdd_version` cũ hơn `.feature` |
@@ -186,6 +187,10 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 
 > 🔴 = **chặn PR**. Build xanh, test từng-UC xanh, coverage đẹp — nhưng luồng ghép chạy vào no-op hoặc code trỏ vào scenario đã bị xoá.
 >
+> 🔴 **`PRD_UNTRACKED_EDIT` là ngoại lệ có chủ ý — 🔴 nhưng KHÔNG chặn PR.** `gate.blocking` nghĩa hẹp là *code đang hỏng*; cờ này nói về **spec**, và code có thể đang hoàn toàn đúng. Thêm nữa: mọi project đang chạy đều đã có PRD sửa tay ⇒ một cờ chặn mới sẽ đỏ khắp nơi ở lần đầu ⇒ người ta **tắt cổng** ⇒ mất luôn 4 cờ chặn thật. Đó đúng là thất bại `self-check` R9(e) được viết ra để chống, chỉ đến bằng một cửa khác. Team đã dọn sạch nợ tồn thì tự thêm `prd_untracked_edit_count` vào `gate.blocking` (kèm `why`; R13(e) canh).
+>
+> **Đường ra tự lành, cố ý không có `--accept-edit`:** bump `Version` + ghi một row changelog nêu UC (tức đúng việc `/amend-prd` làm hộ) ⇒ `version != version_at_audit` ⇒ cờ tự tắt, và `PRD_DRIFT` bình thường tiếp quản. Một cờ escape sẽ là một đường **dán nhãn lên thay đổi chưa ai xem** — đúng cái ba rào của `--realign-*` tồn tại để chặn.
+>
 > ⓘ = **không phải lỗi.** Hai cờ `*_STALE_REF` tồn tại vì version PRD/tech-doc là **MỘT số cho cả tài liệu nhiều UC** — thêm một UC làm mọi UC cũ lệch số dù không đổi một chữ. Không lọc thì cả loạt UC ăn cờ đỏ oan, và làm theo hướng dẫn cũng không tắt được (`/generate-code` skip row đang `OK`). Sạch bằng `--realign-*`: chỉ sửa dòng `@trace.*`, **không đụng logic**, và **từ chối chạy** nếu UC đó đang thật sự `DRIFT`/`ORPHANED`.
 >
 > **Mọi cờ đều PHẢI có counter `{flag}_count`** trong Step 7 + `summary` của `trace-report.json` — `bin/self-check.js` R7 ép, không có ngoại lệ. Thiếu counter = cờ vô hình với dashboard.

package/docs/explain/02c-amend-prd.md

@@ -23,7 +23,7 @@ Ba lệnh có sẵn đều **từ chối đúng việc đó**:
 
 | Lệnh | Vì sao không dùng được |
 |---|---|
-| `/generate-prd` | Chỉ có một cổng **chặn cứng** rồi vẫn ghi đè. Ghi đè mất changelog và **đánh số lại BR** ⇒ phá `@trace.business_rules` trong mọi `.feature` đã sinh. Đường có mìn, không phải đường dùng được |
+| `/generate-prd` | **DỪNG HẲN** — §Guard *"Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi Y/N"*. Đúng vậy: ghi đè mất changelog và **đánh số lại BR** ⇒ phá `@trace.business_rules` trong mọi `.feature` đã sinh, cả ba đều không hoàn tác được từ trong lệnh |
 | `/extend-prd` | **Add-only.** Bước 5 §3 đòi output là *"superset chặt"* của bản cũ. Có **một** cửa sửa nội dung cũ (Bước 3.2 case 1, "mâu thuẫn rule") nhưng nó **phái sinh** — chỉ mở khi phần THÊM làm BR cũ sai |
 | `/refine-prd` | Resume Mode Phase 2 tự cấm đụng section nào không được một finding trỏ tới, và findings sinh từ việc soi PRD hiện có ⇒ **không có đường nào để một ý định MỚI của PO đi vào** |
 

package/docs/explain/06-generate-bdd.md

@@ -2,7 +2,7 @@
 
 # 06 · `/generate-bdd` — Sinh kịch bản BDD (.feature)
 
-> **Một câu.** Phân rã PRD thành các file `.feature` (Gherkin) mang `@trace.*`, theo platform (web/app/system), với fan-out per-UC và tổng hợp **System BDD** từ BDD FE/App.
+> **Một câu.** Phân rã PRD thành các file `.feature` (Gherkin) mang `@trace.*`, theo platform (web/app/webview/system), với fan-out per-UC và tổng hợp **System BDD** từ BDD FE/App.
 
 ---
 

package/docs/explain/13-dev-run-test.md

@@ -37,7 +37,21 @@ Sinh test chưa đủ — phải chạy và biết pass/fail. Command chạy tes
    | web-frontend | Vitest / Jest; E2E Playwright / Cypress |
    | mobile | Flutter test, React Native, iOS (xcodebuild), Android |
 3. **Analyze Failures** — chẩn lỗi theo platform (điều gì fail, tại sao).
-4. **Write Trace State** — set `dev_selftest` (pass/fail) trong `.tsv`.
+4. **Write Trace State** — **ĐỌC cột `status` của row TRƯỚC KHI GHI**, rồi set `dev_selftest`:
+
+   | `status` của row | Ghi gì |
+   |---|---|
+   | `OK` · `GAP` · `UNTRACKED` | `pass` / `fail` như thường |
+   | **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG ghi `pass`)* · test **fail** → **`fail`** như thường |
+   | **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` |
+
+   > **Vì sao (GAPS-v4 G55).** `pass` **không** mang nghĩa *"test đã chạy và xanh"* — nó mang nghĩa *"scenario này đã được nghiệm thu theo spec **hiện tại**"*. Trên row `DRIFT` nghĩa thứ nhất đúng và nghĩa thứ hai **sai**.
+   >
+   > Bản cũ ghi `pass` chỉ dựa vào *test có xanh không*, nên chuỗi này báo xanh sai: PO đổi AC → `/generate-bdd` đặt `status = DRIFT` và **hạ** `dev_selftest → not_run` → sáng sau dev chạy lệnh này theo thói quen (chưa `/generate-code`, chưa `/dev-gen-test`) → test cũ + code cũ xanh hết → ghi `pass` **kèm ngày hôm nay**. Tức lệnh kế tiếp trong vòng lặp dev bình thường **dựng lại** đúng tín hiệu vừa bị hạ.
+   >
+   > **Tin xấu luôn hợp lệ:** đây là guard cho lời khẳng định **DƯƠNG**, không phải lệnh *"bỏ qua kết quả khi DRIFT"*. `fail` vẫn được ghi — chặn cả `fail` là biến guard chống-báo-cáo-sai thành guard **che tin xấu**.
+   >
+   > **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt trạng thái này ở sổ thật (`status ∈ {DRIFT, ORPHANED}` mà `dev_selftest`/`qc_status = pass`), bất kể lệnh nào ghi ra — kể cả sổ sửa tay hoặc sổ sinh bởi version framework cũ.
 5. **Refresh Panel Mirror** — Living Docs local (umbrella).
 
 ---

package/docs/explain/19-qc-run-test.md

@@ -1,87 +1,91 @@
-[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
-
-# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
-
-> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
-
----
-
-## Vấn đề giải quyết
-
-Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
-- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
-
----
-
-## Input / Output
-
-**Input:** `.Test.md` đã review + skill `qa-runner` + bảng Test Selectors §4.5.6 (**giá trị** test-id, từ `/map-testids`) + **`@trace.testid_attr`** ở header tech-doc (**tên thuộc tính** chứa chúng).
-
-**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + panel mirror (`.trace-mirror/`).
-
-> **`@trace.testid_attr` — đọc, KHÔNG suy từ platform.** §4.5.6 cho **giá trị** test-id; field này cho **tên thuộc tính** chứa chúng. `get_by_test_id()` của Playwright mặc định dò `data-testid` **nhưng cấu hình được** — dự án dùng `data-test`/`data-qa` thì phải `set_test_id_attribute("{attr}")` trước, không thì **trượt 100% locator**.
->
-> Suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác** (`/map-testids` đã phân giải một lần cho cả feature, `/generate-code` đọc chính field đó để emit). Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail `element not found` — trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector. Thiếu field → **cảnh báo mềm nêu rõ rủi ro** rồi mới fallback.
-
----
-
-## Các bước xử lý (chi tiết)
-
-1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
-2. **Skills** — nạp một file skill `qa-runner` theo layer.
-3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
-4. **Chạy** — phân loại mỗi FAIL: **script-bug** (fix selector/logic) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
-5. **Write Trace State — `qc_status`** (kết quả QC chính thức) + `qc_run_at`, `qc_owner`, `qc_blocked_by`, `last_updated`.
-6. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
-7. **Refresh Panel Mirror** — Living Docs local.
-
----
-
-## Checkpoint & Gate
-
-- Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
-
----
-
-## Cơ chế đặc biệt
-
-- **`qc_status` là trục authoritative** — khác `dev_selftest`; có evidence.
-- **Không fake-pass** — product-gap giữ nguyên FAIL, đẩy về PO/Dev.
-- **Stack QC tách hẳn dev** — `@trace.verifies` nối script ↔ SC.
-- **`active_platform` khoá sổ trace** — `qc_status` ghi đúng `{UC-ID}-{platform}.tsv`.
-- **Chủ sở hữu bước `🟡 Fixed → 🟢 Closed`.** `/report-bug` mở bug (`🟢 Open`), `/fix-bug` đặt `🟡 Fixed`, và **chỉ QC re-verify mới đóng được** — dev không tự đóng bug của mình.
-
-### Vì sao đóng bug phải chạy TRƯỚC khi clear cột
-
-Khi `qc_status` flip `pass`, lệnh clear `qc_owner`/`qc_blocked_by` về `—`. Nhưng `qc_blocked_by` **chính là con trỏ tới `{BUG-ID}`** — clear xong là mất đường về, và đối chiếu tay cũng không làm được. Nên thứ tự bắt buộc: **đọc `qc_blocked_by` → đóng bug → rồi mới clear**.
-
-| `State` của bug | SC vừa `pass` → làm gì |
-|---|---|
-| `🟡 Fixed` | → `🟢 Closed` + dòng `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass` |
-| `🟢 Open` (chưa ai fix) | **KHÔNG đóng.** Giữ `Open` + ghi chú kiểm tra lại test |
-| `GAP-*` thay vì `BUG-*` | không đụng — spec-gap thuộc PO, không phải QC |
-
-> Ca `Open` là ngoại lệ **có chủ đích**: test pass trên một bug chưa ai 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**.
-
-Bug report đã đổi phải **commit + push** vào spec repo — file local là dead drop, PO/Dev chỉ thấy sau khi push.
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Trạm nặng nhất của QC** — sinh + chạy + phân loại + ghi trace. Chạy thật phụ thuộc môi trường (browser, data, service lên).
-- **Phân loại script-bug vs product-gap phụ thuộc AI/reviewer** — sai loại → hoặc giấu lỗi sản phẩm hoặc báo nhầm. Đáng có tiêu chí rõ.
-- **Selector phụ thuộc `/map-testids`** — nếu chưa map, script giòn.
-- **Chạy lại tốn tài nguyên** — cân nhắc scoped run như dev-run-test.
-
----
-
-## Kết nối
-
-**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).
+[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
+
+# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
+
+> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
+
+---
+
+## Vấn đề giải quyết
+
+Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
+- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
+
+---
+
+## Input / Output
+
+**Input:** `.Test.md` đã review + skill `qa-runner` + bảng Test Selectors §4.5.6 (**giá trị** test-id, từ `/map-testids`) + **`@trace.testid_attr`** ở header tech-doc (**tên thuộc tính** chứa chúng).
+
+**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + panel mirror (`.trace-mirror/`).
+
+> **`@trace.testid_attr` — đọc, KHÔNG suy từ platform.** §4.5.6 cho **giá trị** test-id; field này cho **tên thuộc tính** chứa chúng. `get_by_test_id()` của Playwright mặc định dò `data-testid` **nhưng cấu hình được** — dự án dùng `data-test`/`data-qa` thì phải `set_test_id_attribute("{attr}")` trước, không thì **trượt 100% locator**.
+>
+> Suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác** (`/map-testids` đã phân giải một lần cho cả feature, `/generate-code` đọc chính field đó để emit). Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail `element not found` — trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector. Thiếu field → **cảnh báo mềm nêu rõ rủi ro** rồi mới fallback.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+2. **Skills** — nạp một file skill `qa-runner` theo layer.
+3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
+4. **Chạy** — phân loại mỗi FAIL: **script-bug** (fix selector/logic) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
+5. **Write Trace State — `qc_status`** (kết quả QC chính thức) + `qc_run_at`, `qc_owner`, `qc_blocked_by`, `last_updated`.
+
+   ⚠️ **ĐỌC cột `status` TRƯỚC KHI GHI `pass`** *(GAPS-v4 G55, đối xứng `/dev-run-test`)*: row `DRIFT`/`ORPHANED` + test xanh → **`not_run`**, không bao giờ `pass`. `fail` và `skip` ghi bình thường — chỉ giá trị **khẳng định** cần giấy phép.
+
+   Và ở lệnh này hậu quả đi **xa hơn** `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify). Nên khi hạ về `not_run`, lệnh **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy bước đóng bug — đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai.
+6. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
+7. **Refresh Panel Mirror** — Living Docs local.
+
+---
+
+## Checkpoint & Gate
+
+- Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
+
+---
+
+## Cơ chế đặc biệt
+
+- **`qc_status` là trục authoritative** — khác `dev_selftest`; có evidence.
+- **Không fake-pass** — product-gap giữ nguyên FAIL, đẩy về PO/Dev.
+- **Stack QC tách hẳn dev** — `@trace.verifies` nối script ↔ SC.
+- **`active_platform` khoá sổ trace** — `qc_status` ghi đúng `{UC-ID}-{platform}.tsv`.
+- **Chủ sở hữu bước `🟡 Fixed → 🟢 Closed`.** `/report-bug` mở bug (`🟢 Open`), `/fix-bug` đặt `🟡 Fixed`, và **chỉ QC re-verify mới đóng được** — dev không tự đóng bug của mình.
+
+### Vì sao đóng bug phải chạy TRƯỚC khi clear cột
+
+Khi `qc_status` flip `pass`, lệnh clear `qc_owner`/`qc_blocked_by` về `—`. Nhưng `qc_blocked_by` **chính là con trỏ tới `{BUG-ID}`** — clear xong là mất đường về, và đối chiếu tay cũng không làm được. Nên thứ tự bắt buộc: **đọc `qc_blocked_by` → đóng bug → rồi mới clear**.
+
+| `State` của bug | SC vừa `pass` → làm gì |
+|---|---|
+| `🟡 Fixed` | → `🟢 Closed` + dòng `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass` |
+| `🟢 Open` (chưa ai fix) | **KHÔNG đóng.** Giữ `Open` + ghi chú kiểm tra lại test |
+| `GAP-*` thay vì `BUG-*` | không đụng — spec-gap thuộc PO, không phải QC |
+
+> Ca `Open` là ngoại lệ **có chủ đích**: test pass trên một bug chưa ai 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**.
+
+Bug report đã đổi phải **commit + push** vào spec repo — file local là dead drop, PO/Dev chỉ thấy sau khi push.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Trạm nặng nhất của QC** — sinh + chạy + phân loại + ghi trace. Chạy thật phụ thuộc môi trường (browser, data, service lên).
+- **Phân loại script-bug vs product-gap phụ thuộc AI/reviewer** — sai loại → hoặc giấu lỗi sản phẩm hoặc báo nhầm. Đáng có tiêu chí rõ.
+- **Selector phụ thuộc `/map-testids`** — nếu chưa map, script giòn.
+- **Chạy lại tốn tài nguyên** — cân nhắc scoped run như dev-run-test.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).

package/docs/explain/21-validate-traces.md

@@ -1,75 +1,79 @@
-[← /qc-report](20-qc-report.md) · [Explain Home](README.md) · [Next: /generate-spec-manifest →](22-generate-spec-manifest.md)
-
-# 21 · `/validate-traces` — Ma trận độ phủ spec ↔ code ↔ test
-
-> **Một câu.** Check **read-only** độ phủ giữa spec, code, test (gồm PRD version drift); phân loại mỗi SC và làm mới Living Docs. Không sửa gì.
-
----
-
-## Vấn đề giải quyết
-
-Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh toàn cục: SC nào có code, có test, hay còn hở — để không "tưởng xong mà chưa xong".
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase Trace Audit (xuyên suốt).
-- **Đặc biệt:** read-only — an toàn chạy bất kỳ lúc nào.
-
----
-
-## Input / Output
-
-**Input:** `.trace/…/{UC-ID}-{platform}.tsv` + spec + code + test.
-
-**Output:** ma trận coverage + `code_coverage`; `trace-report.json` (ghi đè) + **`trace-history.jsonl`** (append 1 dòng delta — **phải commit**, không regenerate được); làm mới Living Docs dashboard.
-
-**Flag:** `--realign-prd-version {UC-ID}` · `--realign-techdoc-revision {UC-ID}` — ngoại lệ có kiểm soát của "read-only": chỉ sửa **dòng `@trace.*`** trong code, **từ chối chạy** nếu UC đang `DRIFT`/`ORPHANED`.
-
----
-
-## Các bước xử lý (chi tiết)
-
-1. Quét trace `.tsv` + đối chiếu spec/code/test.
-2. Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
-   | # | Trạng thái | Điều kiện |
-   |---|-----------|-----------|
-   | 1 | UNTRACKED | `gen_ver == —` |
-   | 2 | DRIFT | có code + `spec_ver != gen_ver` |
-   | 3 | GAP | có code + `test_count == —/0` |
-   | 4 | OK | version khớp + có code + có test |
-3. Dựng dashboard: `dev_selftest` (DEV smoke) **và** `qc_status` (QC chính thức) hiển thị cạnh nhau — **không merge**; cột `qc_owner` + `qc_blocked_by` ("Waiting on"); và **hai trục chia nhóm**: **`by_service`** (coverage theo từng đội — cột `service`) · **`by_platform`** (coverage theo `web`/`app`/`system`).
-   > `by_platform` trả lời *"web xong bao nhiêu %, system xong bao nhiêu %"* — câu thường ngày khi làm FE và BE song song. Trước v0.5.1 không trả lời được **từ `summary`**: `by_service` là bảng chia nhóm duy nhất, mà cột `service` là `—` ở mọi row của dự án single-service ⇒ nó gộp tất cả vào một ô.
-4. **Lọc báo động oan (Step 4/5).** PRD và tech-doc là tài liệu **gộp** nhiều UC nhưng chỉ **một** số version — thêm UC7 làm mọi UC cũ lệch số dù không đổi một chữ. Đọc **scope của row changelog**: UC có trong danh sách → `PRD_DRIFT` 🟠 · không có → `PRD_STALE_REF` ⓘ (sạch bằng `--realign-*`) · row **mơ hồ** → 🟠 cho mọi UC (lưới an toàn).
-5. **Step 5d — design-spec drift** *(chỉ FE/App)*: 2 chiều, design-spec→BDD và design-spec→code.
-6. **Step 7b — hàng đợi**: đếm PRD change request còn `Open` kèm **số ngày chờ** (hàng đợi duy nhất không có lệnh nào quét lại mỗi lần chạy).
-7. **Step 8c — nhật ký**: append delta vào `trace-history.jsonl` → in khối `📈 So lần chạy trước` (đo **tốc độ**, không chỉ trạng thái).
-
----
-
-## Checkpoint & Gate
-
-- ⚪ Read-only, không gate.
-
----
-
-## Cơ chế đặc biệt
-
-- **DRIFT xét trước GAP** — code lỗi thời chưa test phải hiện DRIFT (regen) không phải GAP.
-- **`dev_selftest` ≠ `qc_status`** — hai cột riêng, không trộn.
-- **"Waiting on" column** — `qc_owner`/`qc_blocked_by` trả lời "case nào chờ ai".
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Chỉ báo cáo, không hành động** — hành động ở `/generate-code` (regen DRIFT) & QC (bù GAP). Chuỗi phụ thuộc người chạy tiếp.
-- **Nguồn sự thật của Living Docs** — chất lượng dashboard phụ thuộc `.tsv` được các lệnh code/test ghi đúng.
-- **Là "single pane" để PM/PO nhìn trạng thái** — ứng viên tốt cho UI viewer (blueprint có gợi ý).
-
----
-
-## Kết nối
-
-**Trước:** bất kỳ (đặc biệt sau [`/qc-report`](20-qc-report.md)) · **Sau:** DRIFT/UNTRACKED → [`/generate-code`](09-generate-code.md); GAP → [`/dev-gen-test`](12-dev-gen-test.md); OK → PR.
+[← /qc-report](20-qc-report.md) · [Explain Home](README.md) · [Next: /generate-spec-manifest →](22-generate-spec-manifest.md)
+
+# 21 · `/validate-traces` — Ma trận độ phủ spec ↔ code ↔ test
+
+> **Một câu.** Check **read-only** độ phủ giữa spec, code, test (gồm PRD version drift); phân loại mỗi SC và làm mới Living Docs. Không sửa gì.
+
+---
+
+## Vấn đề giải quyết
+
+Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh toàn cục: SC nào có code, có test, hay còn hở — để không "tưởng xong mà chưa xong".
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Trace Audit (xuyên suốt).
+- **Đặc biệt:** read-only — an toàn chạy bất kỳ lúc nào.
+
+---
+
+## Input / Output
+
+**Input:** `.trace/…/{UC-ID}-{platform}.tsv` + spec + code + test.
+
+**Output:** ma trận coverage + `code_coverage`; `trace-report.json` (ghi đè) + **`trace-history.jsonl`** (append 1 dòng delta — **phải commit**, không regenerate được); làm mới Living Docs dashboard.
+
+**Flag — phạm vi:** `--domain {d}` · `--prd {TICKET-ID}` · `--uc {UC-ID}`; không cờ nào = **toàn bộ**. Report mang field `scope`, và `gate-trace` **G2 fail** nếu `scope.kind !== "all"` — **không ngoại lệ**, không đếm số domain trên đĩa. Biên bản có scope **không bao giờ** là biên bản đầy đủ; muốn tạo PR thì phải có một lần audit toàn bộ đã commit. *(`/sync` Step 1e nói cho bạn biết scope là gì.)*
+
+**Flag — realign:** `--realign-prd-version {UC-ID}` · `--realign-techdoc-revision {UC-ID}` — ngoại lệ có kiểm soát của "read-only": chỉ sửa **dòng `@trace.*`** trong code, **từ chối chạy** nếu UC đang `DRIFT`/`ORPHANED` hoặc bị Step 4/5 xếp 🟠.
+
+**Cờ mới `PRD_UNTRACKED_EDIT`** 🔴 *(Step 3.9, chạy **trước** Step 4)* — nội dung PRD đổi mà nhãn `Version` **không** đổi ⇒ có người sửa ngoài `/generate-prd` · `/extend-prd` · `/amend-prd` · `/refine-prd` · `/review-context`. So bằng `git diff` **và** `git status` *(nguồn thứ hai bắt ca sửa **chưa** commit — ca thường gặp nhất)* với mốc `spec_baseline` mà Step 6b ghi. **Không chặn PR** có chủ ý, và **không có `--accept-edit`**: đường ra là bump `Version` + row changelog ⇒ cờ tự tắt.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. Quét trace `.tsv` + đối chiếu spec/code/test.
+2. Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+   | # | Trạng thái | Điều kiện |
+   |---|-----------|-----------|
+   | 1 | UNTRACKED | `gen_ver == —` |
+   | 2 | DRIFT | có code + `spec_ver != gen_ver` |
+   | 3 | GAP | có code + `test_count == —/0` |
+   | 4 | OK | version khớp + có code + có test |
+3. Dựng dashboard: `dev_selftest` (DEV smoke) **và** `qc_status` (QC chính thức) hiển thị cạnh nhau — **không merge**; cột `qc_owner` + `qc_blocked_by` ("Waiting on"); và **hai trục chia nhóm**: **`by_service`** (coverage theo từng đội — cột `service`) · **`by_platform`** (coverage theo `web`/`app`/`system`).
+   > `by_platform` trả lời *"web xong bao nhiêu %, system xong bao nhiêu %"* — câu thường ngày khi làm FE và BE song song. Trước v0.5.1 không trả lời được **từ `summary`**: `by_service` là bảng chia nhóm duy nhất, mà cột `service` là `—` ở mọi row của dự án single-service ⇒ nó gộp tất cả vào một ô.
+4. **Lọc báo động oan (Step 4/5).** PRD và tech-doc là tài liệu **gộp** nhiều UC nhưng chỉ **một** số version — thêm UC7 làm mọi UC cũ lệch số dù không đổi một chữ. Đọc **scope của row changelog**: UC có trong danh sách → `PRD_DRIFT` 🟠 · không có → `PRD_STALE_REF` ⓘ (sạch bằng `--realign-*`) · row **mơ hồ** → 🟠 cho mọi UC (lưới an toàn).
+5. **Step 5d — design-spec drift** *(chỉ FE/App)*: 2 chiều, design-spec→BDD và design-spec→code.
+6. **Step 7b — hàng đợi**: đếm PRD change request còn `Open` kèm **số ngày chờ** (hàng đợi duy nhất không có lệnh nào quét lại mỗi lần chạy).
+7. **Step 8c — nhật ký**: append delta vào `trace-history.jsonl` → in khối `📈 So lần chạy trước` (đo **tốc độ**, không chỉ trạng thái).
+
+---
+
+## Checkpoint & Gate
+
+- ⚪ Read-only, không gate.
+
+---
+
+## Cơ chế đặc biệt
+
+- **DRIFT xét trước GAP** — code lỗi thời chưa test phải hiện DRIFT (regen) không phải GAP.
+- **`dev_selftest` ≠ `qc_status`** — hai cột riêng, không trộn.
+- **"Waiting on" column** — `qc_owner`/`qc_blocked_by` trả lời "case nào chờ ai".
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chỉ báo cáo, không hành động** — hành động ở `/generate-code` (regen DRIFT) & QC (bù GAP). Chuỗi phụ thuộc người chạy tiếp.
+- **Nguồn sự thật của Living Docs** — chất lượng dashboard phụ thuộc `.tsv` được các lệnh code/test ghi đúng.
+- **Là "single pane" để PM/PO nhìn trạng thái** — ứng viên tốt cho UI viewer (blueprint có gợi ý).
+
+---
+
+## Kết nối
+
+**Trước:** bất kỳ (đặc biệt sau [`/qc-report`](20-qc-report.md)) · **Sau:** DRIFT/UNTRACKED → [`/generate-code`](09-generate-code.md); GAP → [`/dev-gen-test`](12-dev-gen-test.md); OK → PR.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"