@educa-corp/sdd-framework 0.9.5 → 0.9.6

package/docs/explain/09-generate-code.md

@@ -14,14 +14,15 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 
 ## Vị trí & tiền đề
 
-- **Vị trí:** Phase Implementation, sau BDD + tech-docs.
+- **Vị trí:** Phase Implementation, sau BDD + tech-docs + [`/map-testids`](11-map-testids.md).
+- **Chạy song song với QC.** Hợp đồng test-id (§4.5.6) đã đóng băng trước bước này, nên FE gắn attribute còn QC dựng test **cùng lúc** trên cùng một bảng — không bên nào chờ bên nào, không bên nào tự đặt id.
 - **Gate vào:** cảnh báo mềm DS1 (BDD chưa approved), DS2 (design-spec), DS3 (tech-doc contract BE), **DS4** (client contract §4.5.4) + **DS5** (FE reuse gate) — DS4/DS5 chỉ khi wire API thật (`integration`/`fe_full`). Xem [Hành vi theo mode](#hành-vi-theo-mode-phase--platform).
 
 ---
 
 ## Input / Output
 
-**Input:** `.feature` (hoặc UC-ID) + tech-design §4 + CLAUDE.md §2/§3/§5 + `.trace/…/{UC-ID}-{platform}.tsv` + `_seams.tsv`.
+**Input:** `.feature` (hoặc UC-ID) + tech-design §4 + **hợp đồng test-id** (`@trace.testid_attr` ở header + §4.5.6 Test Selectors) + CLAUDE.md §2/§3/§5 + `.trace/…/{UC-ID}-{platform}.tsv` + `_seams.tsv`.
 
 **Output:** file code (tag `@trace` boundary) + trace row `.tsv` + cập nhật `_seams.tsv`.
 
@@ -64,7 +65,7 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 | **DS4** — client contract gate (§4.5.4) | ⏭️ cố ý | ✅ | ✅ | — |
 | **DS5** — FE component/service reuse gate | ⏭️ | ✅ | ✅ | — |
 | **Sinh UI** (Figma MCP, component, state) | ✅ | ⏭️ giữ UI cũ | ✅ | — |
-| **Test Selectors** (emit test-id) | ✅ | ⏭️ | ✅ | — |
+| **Test Selectors** (**đọc** §4.5.6 rồi emit, xem dưới) | ✅ | ⏭️ | ✅ | — |
 | **Mock API Layer** | ✅ | ⏭️ | ⏭️ | — |
 | **Integration Phase** (real API adapter) | ⏭️ | ✅ | ✅ | — |
 | **Wire-up API** | dùng **mock** | **lật** mock→real | wire **thẳng** real | — (BE là API) |
@@ -83,6 +84,29 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 
 ---
 
+### Test Selectors — ĐỌC hợp đồng, không tự đặt *(đổi ở đợt sửa hợp đồng test-id)*
+
+Trước đây lệnh này **tự sinh** test-id khi §4.5.6 rỗng. Đó là lỗi **im lặng**: QC đang viết script theo một bảng khác (hoặc không có bảng nào), và không ai báo cho ai.
+
+**Giá trị** test-id lấy từ §4.5.6:
+
+| Tình huống | Hành vi |
+|---|---|
+| §4.5.6 **có dòng** | Dùng đúng giá trị trong bảng |
+| §4.5.6 **rỗng** | ⚠️ **Cảnh báo mạnh rồi hỏi Y/N.** Đường đúng là dừng, chạy `/map-testids`. Tiếp tục là **quyết định của dev**, không phải mặc định của máy |
+
+**Tên thuộc tính** lấy từ `@trace.testid_attr` ở header tech-doc:
+
+| Tình huống | Hành vi |
+|---|---|
+| Header có field | Dùng đúng tên đó (`data-testid` · `data-test` · `testID` · `Key`…) |
+| Header **không có** | Cảnh báo mềm **nêu rõ rủi ro** → fallback theo `active_module`. Không im lặng hardcode |
+| `.feature` cũng khai attr và **lệch** header | In **cả hai** giá trị, để người quyết. Không tự chọn bên nào |
+
+> **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác**. Nó hỏng đúng ở ca field này sinh ra để phục vụ — 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 `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.
+
+---
+
 ## Checkpoint & Gate
 
 - 🛑 **Comprehension checkpoint** (Code Generation Plan) — điểm dừng chính; Dev xác nhận drift + scope đúng.
@@ -113,4 +137,6 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 
 ## Kết nối
 
-**Trước:** [`/review-tech-docs`](08-review-tech-docs.md) · **Sau:** lần đầu → [`/review-code`](10-review-code.md); gen lại → [`/dev-gen-test`](12-dev-gen-test.md).
+**Trước:** [`/map-testids`](11-map-testids.md) → [`/review-tech-docs`](08-review-tech-docs.md) · **Song song:** [`/qc-design-test`](17-qc-design-test.md) · **Sau:** lần đầu → [`/review-code`](10-review-code.md); gen lại → [`/dev-gen-test`](12-dev-gen-test.md).
+
+> Test-id sinh ra **không khớp code thật** → sửa bằng `/map-testids --from-code`, đừng sửa tay bảng. Lệnh đó tự hạ `qc_status` → `not_run` và `qc_run_at` → `—`, để QC biết test-script bám selector cũ đã hết hiệu lực.

package/docs/explain/10-review-code.md

@@ -1,4 +1,4 @@
-[← /generate-code](09-generate-code.md) · [Explain Home](README.md) · [Next: /map-testids →](11-map-testids.md)
+[← /generate-code](09-generate-code.md) · [Explain Home](README.md) · [Next: /dev-gen-test →](12-dev-gen-test.md)
 
 # 10 · `/review-code` — Review code (read-only, 4 dimension)
 

package/docs/explain/11-map-testids.md

@@ -1,70 +1,72 @@
-[← /review-code](10-review-code.md) · [Explain Home](README.md) · [Next: /dev-gen-test →](12-dev-gen-test.md)
-
-# 11 · `/map-testids` — Dán test-id ổn định cho UI (FE)
-
-> **Một câu.** Gắn **test-id ổn định** vào các element có hành động trên UI FE và ghi bản đồ selector vào tech-doc §4.5.6 — làm cầu nối để QC Playwright bám selector không vỡ.
-
----
-
-## Vấn đề giải quyết
-
-Test tự động (Playwright) vỡ khi selector đổi (class/text thay đổi). `/map-testids` chuẩn hoá **test-id ổn định** cho mọi element tương tác, đảm bảo component tái dùng forward được test-id, và ghi map để QC dùng — tách concern "làm UI test được" khỏi "viết test".
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase **Tech Design**, sau `/generate-tech-docs` và **TRƯỚC** `/review-tech-docs` — tức trước cả `/generate-code`. Chốt hợp đồng test-id ở đây để FE và QC đọc cùng một bản đã đóng băng rồi **chạy song song**.
-- **Hai chế độ:** mặc định (feature mới — nguồn là design-spec + BDD, **không đụng code**) · `--from-code` (brownfield — đọc/patch code đã có, chạy một lần mỗi UC cũ).
-- **Chặn cứng:** chỉ FE/App (platform guard) — BE không có UI.
-
----
-
-## Input / Output
-
-**Input:** design-spec (Component Inventory, màn hình) + step `When` của `.feature` FE + tech-doc §4.5.1 (cây component) + catalog component tái dùng. *Chế độ `--from-code` đọc thêm UI code FE.*
-
-**Output:** map §4.5.6 Test Selectors + `@trace.testid_attr` ở header tech-doc. *Chế độ `--from-code` còn patch test-id vào code FE.*
-
----
-
-## Các bước xử lý (chi tiết)
-
-| Step | Việc |
-|------|------|
-| **0 · Platform guard** | Chỉ FE/App; else STOP |
-| **1 · Thu thập element có action** | Quét UI tìm element người dùng tương tác (nút, ô nhập, link…) |
-| **2 · Phân giải test-id ổn định** | Đặt test-id ổn định (không phụ thuộc text/class dễ đổi) cho mỗi element |
-| **3 · Đảm bảo component tái dùng forward test-id** | Component dùng lại (catalog) phải cho phép truyền test-id xuống — sửa component nếu chưa |
-| **4 · Patch usage site** (chỉ EXTEND) | Gắn test-id vào nơi dùng, chỉ thêm (không viết đè) |
-| **5 · Ghi/làm mới map §4.5.6** | Ghi bảng Test Selectors vào tech-doc để QC bám |
-| **6 · Handoff** | Bàn giao cho QC (`/qc-*`) |
-
----
-
-## Checkpoint & Gate
-
-- Không gate chặn; EXTEND-only khi patch (an toàn).
-
----
-
-## Cơ chế đặc biệt
-
-- **Test-id ổn định** — chống test vỡ do đổi visual; nguyên tắc "selector là contract QC↔FE".
-- **Forward test-id qua component tái dùng** — sửa gốc component để test-id lan xuống, không hardcode từng chỗ.
-- **Map ở §4.5.6 tech-doc** — QC đọc từ một nguồn, không tự dò.
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Lệnh chốt hợp đồng FE↔QC** — vị trí **đã được chốt**: phase Tech Design, trước `/generate-code`. Trước đây vị trí mờ (tài liệu này từng nói 'giữa Tech Design & Code') nên lệnh hay bị bỏ qua; giờ `/generate-tech-docs` trỏ thẳng sang đây, và `/review-tech-docs` T6 không cho APPROVED nếu §4.5.6 rỗng.
-- **Phụ thuộc catalog component tái dùng** — nếu component không forward được prop test-id, Step 3 phát sinh sửa lan rộng.
-- **EXTEND-only** an toàn nhưng nếu test-id cũ sai thì không tự sửa.
-- **Đã vào golden path** — `/generate-tech-docs` → **`/map-testids`** → `/review-tech-docs` (T6 chặn nếu §4.5.6 rỗng). `lint-trace` T15/T16 canh bảng, T17/T18 canh bảng-vs-code.
-
----
-
-## Kết nối
-
-**Trước:** [`/generate-tech-docs`](08-generate-tech-docs.md) · **Sau:** [`/review-tech-docs`](07-review-tech-docs.md), rồi rẽ hai nhánh song song — [`/generate-code`](09-generate-code.md) (FE gắn attribute) ∥ [`/qc-design-test`](17-qc-design-test.md) (QC dựng test theo cùng hợp đồng).
+[← /generate-tech-docs](07-generate-tech-docs.md) · [Explain Home](README.md) · [Next: /review-tech-docs →](08-review-tech-docs.md)
+
+> **Số `11` là số file lịch sử, không phải thứ tự chạy.** Lệnh này chạy ở **Phase Design**, giữa `/generate-tech-docs` và `/review-tech-docs` — tức **trước** `/generate-code`. Giữ nguyên tên file để không gãy link cũ.
+
+# 11 · `/map-testids` — Dán test-id ổn định cho UI (FE)
+
+> **Một câu.** Gắn **test-id ổn định** vào các element có hành động trên UI FE và ghi bản đồ selector vào tech-doc §4.5.6 — làm cầu nối để QC Playwright bám selector không vỡ.
+
+---
+
+## Vấn đề giải quyết
+
+Test tự động (Playwright) vỡ khi selector đổi (class/text thay đổi). `/map-testids` chuẩn hoá **test-id ổn định** cho mọi element tương tác, đảm bảo component tái dùng forward được test-id, và ghi map để QC dùng — tách concern "làm UI test được" khỏi "viết test".
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase **Tech Design**, sau `/generate-tech-docs` và **TRƯỚC** `/review-tech-docs` — tức trước cả `/generate-code`. Chốt hợp đồng test-id ở đây để FE và QC đọc cùng một bản đã đóng băng rồi **chạy song song**.
+- **Hai chế độ:** mặc định (feature mới — nguồn là design-spec + BDD, **không đụng code**) · `--from-code` (brownfield — đọc/patch code đã có, chạy một lần mỗi UC cũ).
+- **Chặn cứng:** chỉ FE/App (platform guard) — BE không có UI.
+
+---
+
+## Input / Output
+
+**Input:** design-spec (Component Inventory, màn hình) + step `When` của `.feature` FE + tech-doc §4.5.1 (cây component) + catalog component tái dùng. *Chế độ `--from-code` đọc thêm UI code FE.*
+
+**Output:** map §4.5.6 Test Selectors + `@trace.testid_attr` ở header tech-doc. *Chế độ `--from-code` còn patch test-id vào code FE.*
+
+---
+
+## Các bước xử lý (chi tiết)
+
+| Step | Việc |
+|------|------|
+| **0 · Platform guard** | Chỉ FE/App; else STOP |
+| **1 · Thu thập element có action** | Quét UI tìm element người dùng tương tác (nút, ô nhập, link…) |
+| **2 · Phân giải test-id ổn định** | Đặt test-id ổn định (không phụ thuộc text/class dễ đổi) cho mỗi element |
+| **3 · Đảm bảo component tái dùng forward test-id** | Component dùng lại (catalog) phải cho phép truyền test-id xuống — sửa component nếu chưa |
+| **4 · Patch usage site** (chỉ EXTEND) | Gắn test-id vào nơi dùng, chỉ thêm (không viết đè) |
+| **5 · Ghi/làm mới map §4.5.6** | Ghi bảng Test Selectors vào tech-doc để QC bám |
+| **6 · Handoff** | Bàn giao cho QC (`/qc-*`) |
+
+---
+
+## Checkpoint & Gate
+
+- Không gate chặn; EXTEND-only khi patch (an toàn).
+
+---
+
+## Cơ chế đặc biệt
+
+- **Test-id ổn định** — chống test vỡ do đổi visual; nguyên tắc "selector là contract QC↔FE".
+- **Forward test-id qua component tái dùng** — sửa gốc component để test-id lan xuống, không hardcode từng chỗ.
+- **Map ở §4.5.6 tech-doc** — QC đọc từ một nguồn, không tự dò.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Lệnh chốt hợp đồng FE↔QC** — vị trí **đã được chốt**: phase Tech Design, trước `/generate-code`. Trước đây vị trí mờ (tài liệu này từng nói 'giữa Tech Design & Code') nên lệnh hay bị bỏ qua; giờ `/generate-tech-docs` trỏ thẳng sang đây, và `/review-tech-docs` T6 không cho APPROVED nếu §4.5.6 rỗng.
+- **Phụ thuộc catalog component tái dùng** — nếu component không forward được prop test-id, Step 3 phát sinh sửa lan rộng.
+- **EXTEND-only** an toàn nhưng nếu test-id cũ sai thì không tự sửa.
+- **Đã vào golden path** — `/generate-tech-docs` → **`/map-testids`** → `/review-tech-docs` (T6 chặn nếu §4.5.6 rỗng). `lint-trace` T15/T16 canh bảng, T17/T18 canh bảng-vs-code.
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-tech-docs`](07-generate-tech-docs.md) · **Sau:** [`/review-tech-docs`](08-review-tech-docs.md), rồi rẽ hai nhánh song song — [`/generate-code`](09-generate-code.md) (FE gắn attribute) ∥ [`/qc-design-test`](17-qc-design-test.md) (QC dựng test theo cùng hợp đồng).

package/docs/explain/12-dev-gen-test.md

@@ -1,4 +1,4 @@
-[← /map-testids](11-map-testids.md) · [Explain Home](README.md) · [Next: /dev-run-test →](13-dev-run-test.md)
+[← /review-code](10-review-code.md) · [Explain Home](README.md) · [Next: /dev-run-test →](13-dev-run-test.md)
 
 # 12 · `/dev-gen-test` — Sinh bộ tự-kiểm của Dev
 

package/docs/explain/15-qc-analyze.md

@@ -26,7 +26,7 @@ QC chính thức cần hiểu yêu cầu **testable** trước khi viết test.
 
 **Input:** UC-ID + spec (PRD/BDD từ spec repo) + skill `qa-analyst`.
 
-**Output (per PRD × nền):** `{qc_dir}/{TICKET-ID}/{platform}/REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md` (11 cột, cột 2 là `UC`) + `{refinement_dir}/{TICKET-ID}-qa-findings.yaml`. Một lần chạy phủ **mọi UC có BDD `approved`** của PRD; UC còn nháp vào bảng *Phạm vi phân tích* với dấu `⏸ Chưa xét` (`--include-draft` để xét luôn).
+**Output (per PRD × nền):** `{qc_dir}/{TICKET-ID}/{platform}/REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md` (11 cột, cột 2 là `UC`) + `{refinement_dir}/{TICKET-ID}-qa-findings.yaml`. Một lần chạy phủ **mọi UC có BDD `approved`** của PRD; UC còn nháp vào bảng *Phạm vi phân tích* với dấu `⏸ Chưa xét` (`--force` để xét luôn).
 
 ---
 
@@ -37,7 +37,19 @@ QC chính thức cần hiểu yêu cầu **testable** trước khi viết test.
 3. **Role qa-analyst** — nạp skill `{qc_skills_dir}/qa-analyst/`.
 4. **Trace mapping (bắt buộc)** — map yêu cầu ↔ scenario ↔ SC.
 5. **DOC_GAP (bắt buộc)** — ghi chỗ tài liệu thiếu/mơ hồ chặn test (blocker 🔴 xử trước ở `/qc-plan`).
-6. **Output** REQUIREMENT_ANALYSIS.md + DOC_GAP.md.
+6. **Guard — BR-tag** *(mới)* — phép **đếm cơ học** chống bỏ sót business rule:
+
+   ```
+   A = mọi business rule mà .feature ĐÃ GẮN TAG (@trace.business_rules)
+   B = mọi rule bản phân tích VỪA SINH RA (REQUIREMENT_ANALYSIS.md)
+   A ∖ B  → rule BDD đã nhắc mà phân tích BỎ SÓT
+   ```
+
+   `A ∖ B` rỗng → in `Guard BR-tag: khớp {n}/{n}`. Không rỗng → **tự bổ sung từ PRD** rồi in danh sách đã bù. **In dòng này kể cả khi sạch** — guard im lặng khi sạch là guard không ai biết nó tồn tại.
+7. **Self-Review** — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+8. **Output** REQUIREMENT_ANALYSIS.md + DOC_GAP.md.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 

package/docs/explain/16-qc-plan.md

@@ -32,7 +32,10 @@ Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên te
 1. **Role qa-planner** — nạp `{qc_skills_dir}/qa-planner/`.
 2. Đọc analysis + gap → **đánh giá rủi ro** từng vùng.
 3. Nêu **câu hỏi cho dev** (điểm chưa rõ để test đúng).
-4. **Output** TEST_PLAN.md.
+4. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+5. **Output** TEST_PLAN.md.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 
@@ -46,6 +49,7 @@ Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên te
 
 - **Risk-based** — kế hoạch bám rủi ro, không phủ đều.
 - **Câu hỏi cho dev** — kênh QC ↔ Dev có hồ sơ trước khi viết test.
+- **Self-Review dùng chung** — sáu trạm QC nạp **cùng một** file nguyên tắc, không mỗi trạm một bản. Sáu bản sao thì sáu tháng sau sẽ là sáu luật khác nhau, **im lặng**.
 
 ---
 

package/docs/explain/17-qc-design-test.md

@@ -15,12 +15,13 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 ## Vị trí & tiền đề
 
 - **Vị trí:** Phase QC (trạm 3), sau `/qc-plan`.
+- **Không cần code.** Trạm này chỉ cần spec + **hợp đồng test-id §4.5.6** (đã chốt ở `/map-testids`, trước `/generate-code`). Nên nó chạy **song song với FE**.
 
 ---
 
 ## Input / Output
 
-**Input:** TEST_PLAN.md + skill `qa-designer` (chọn layer, nạp MỘT file).
+**Input:** TEST_PLAN.md + skill `qa-designer` (chọn layer, nạp MỘT file) + `.feature` (nguồn scenario cho Guard) + **§4.5.6 Test Selectors**.
 
 **Output:** `{qc_dir}/{TICKET-ID}/{platform}/test-cases/*.Test.md` (trace mapping bắt buộc). Gọi theo **từng UC**, ghi vào thư mục test-case dùng chung cấp PRD.
 
@@ -31,13 +32,31 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 1. **Role qa-designer** — chọn layer, nạp một file skill (không nạp cả bộ → tiết kiệm context).
 2. **Conventions** — theo quy ước test-case của QC team.
 3. **Trace mapping (bắt buộc)** — mỗi test case ↔ SC.
-4. **Output** `.Test.md`.
+4. **Guard — SC coverage** *(mới)* — phép **đếm cơ học**, không phải lượt đọc lại:
+
+   ```
+   1. Thu SC — mọi @trace.scenario trong .feature của uc_list (đúng nền).
+               LOẠI SC của UC mà qc-scope đã lọc ra (⏸ BDD chưa approved).
+   2. Thu V  — mọi @trace.verifies trong các file *.Test.md VỪA GHI.
+   3. Đếm    — mỗi SC ∈ tập bước 1 phải có ≥ 1 TC trỏ tới.
+   ```
+
+   | Kết quả | Hành vi |
+   |---|---|
+   | Mọi SC đều có ≥1 TC | in `Guard SC coverage: khớp {K}/{K}` |
+   | Có SC chưa phủ | **viết bù TC ngay**, rồi in `⚠️ Guard SC coverage: {K}/{total} — đã bù {m} SC: {…}` |
+
+   **In dòng này kể cả khi sạch** — guard im lặng khi sạch là guard không ai biết nó tồn tại, nên cũng không ai phát hiện khi nó hỏng.
+
+5. **Self-Review** — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+6. **Output** `.Test.md`.
 
 ---
 
 ## Checkpoint & Gate
 
-- Không gate ở đây; gate là `/qc-review` kế tiếp.
+- Không gate chặn người ở đây; gate là `/qc-review` kế tiếp.
+- Nhưng Guard SC coverage **có hệ quả bắt buộc**: thiếu thì lệnh **viết bù** rồi mới báo, không phải chỉ cảnh báo.
 
 ---
 
@@ -46,6 +65,8 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 - **Markdown-first** — test case là tài liệu review được trước khi thành code.
 - **Nạp MỘT file skill theo layer** — tối ưu context (chỉ layer cần).
 - **Trace mapping** — giữ test case gắn SC để về sau ghi `qc_status` đúng.
+- **Guard SC coverage KHÔNG có đường thoát.** SC bị gap chặn **vẫn** phải có TC — viết đủ, mang dấu `🚫 Block: [GAP-UC{N}-{nnn}] — lý do`. Gap là thứ được **ghi vào** test case, không phải cái cớ để không viết. Cho phép "bỏ trống có lý do" là dạy hai luật trái nhau trong cùng một lệnh, và cho agent một câu-lý-do-cho-qua.
+- **Guard ≠ Self-Review.** Guard là phép **đếm**, có hệ quả bắt buộc. Self-review là lượt đọc lại rộng hơn nhưng mềm hơn. Không bao giờ dùng self-review làm lý do gỡ Guard.
 
 ---
 
@@ -53,6 +74,8 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 
 - **Tách design ↔ script** thêm một trạm nhưng cho phép review sớm — đánh đổi giữa số bước và chất lượng gate.
 - **Phụ thuộc convention QC team** — cần đồng bộ khi convention đổi.
+- **Guard đếm sớm, ở chỗ còn sửa được.** `/qc-report` cũng tính design coverage bằng **đúng phép đếm này**, nhưng ở **cuối** — lúc đó chỉ còn kịp báo, không còn kịp viết bù. Cùng một phép đếm, giá trị khác hẳn theo thời điểm.
+- Con số `{K}/{total}` vốn **đã in** ở report từ trước, nhưng **không có phép tính nào đứng sau nó**. Một con số trong báo cáo không chứng minh có phép đo.
 
 ---
 

package/docs/explain/18-qc-review.md

@@ -29,8 +29,11 @@ Không chạy test kém. Trạm này chặn: (1) test case chưa đủ tốt tr
 ## Các bước xử lý (chi tiết)
 
 1. **Role qa-reviewer** — nạp `{qc_skills_dir}/qa-reviewer/`.
-2. **Review focus** — kiểm test case (đủ phủ, đúng SC) hoặc script (đúng logic, selector, không fake-pass).
-3. Verdict: APPROVED → đi tiếp; NEEDS_FIX → sửa rồi review lại.
+2. **Review focus** — kiểm test case (đủ phủ, đúng SC) hoặc script (đúng logic, **selector bám §4.5.6 chứ không dò DOM**, không fake-pass).
+3. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+4. Verdict: APPROVED → đi tiếp; NEEDS_FIX → sửa rồi review lại.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 
@@ -44,6 +47,7 @@ Không chạy test kém. Trạm này chặn: (1) test case chưa đủ tốt tr
 
 - **Một lệnh, hai vai** — review case và review script dùng chung skill, khác focus.
 - **Gate thật của QC** — điểm HITL chính trong dây chuyền tự động.
+- **Review script thì soát cả nguồn selector** — script lấy locator từ §4.5.6 Test Selectors, hay tự dò DOM? Dò DOM là script giòn: dev đổi một class là vỡ, và **không ai báo**.
 
 ---
 

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

@@ -36,20 +36,41 @@
 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**).
+4. **Chạy.** Test đỏ **một lần** chưa nói được nó đỏ vì cái gì → **chạy lại riêng test đó, tối đa 2 lần**, rồi mới phân loại thành **ba** nhãn:
+
+   ```
+   đỏ → đỏ → đỏ     ⇒ NHẤT QUÁN       → sang bước điều tra: script-bug | product-gap
+   đỏ → xanh        ⇒ KHÔNG NHẤT QUÁN → flaky
+   đỏ → đỏ → xanh   ⇒ KHÔNG NHẤT QUÁN → flaky
+   ```
+
+   | 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 — 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 chạy lại — **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 |
+
+   **Đ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**. Không chắc giữa `script-bug` và `product-gap` → **mời Dev cùng xem trace**.
+
+   🛑 **Người xác nhận TRƯỚC khi hành động** — lệnh in đề xuất kèm evidence cụ thể rồi **dừng chờ**. **Không ghi `qc_status`** cho scenario nào còn FAIL chưa được xác nhận nhãn.
 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.
+   `flaky` → `qc_status = not_run`, `qc_owner = qc`. Không tạo trạng thái mới: `not_run` đúng nghĩa *"chưa có kết luận"*, và `qc_owner = qc` để nó không rơi vào khoảng không ai nhận.
+6. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+7. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
+8. **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.
+- 🛑 **Xác nhận nhãn FAIL** — cổng chặn được **thêm vào**, trong khi framework vốn đang giảm số cổng chặn (G41). Lý do: **cả 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** cho tới khi khách gặp; mở bug từ một lần chạy hên xui là **đốt thời gian dev** và làm mòn niềm tin vào QC.
+
+> **Đây KHÔNG phải `retries` trong config 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.
 
 ---
 
@@ -57,6 +78,7 @@
 
 - **`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.
+- **Chạy lại để QUAN SÁT, không để cho qua** — ba nhãn FAIL tách *chưa đủ căn cứ* (`flaky`) ra khỏi *đã đủ căn cứ* (`script-bug` / `product-gap`). Trước đây hai nhãn gộp cả ba tình huống, nên một test hên xui hoặc bị gán bừa `script-bug` (giấu bug), hoặc thành một bug ma gửi cho 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.
@@ -80,9 +102,10 @@ Bug report đã đổi phải **commit + push** vào spec repo — file local l
 ## 👓 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.
+- **Phân loại vẫn phụ thuộc người đọc evidence** — nhưng giờ có **tiêu chí và thứ tự bắt buộc**: chạy lại ×2 → đọc trace/log → đề xuất nhãn → **người xác nhận**. Chỗ mềm còn lại là ranh giới `script-bug` ↔ `product-gap` khi hành vi nằm ở **biên của spec**; đường ra đã ghi rõ là **mời Dev cùng xem trace**, không đoán cho xong.
+- **Selector bám hợp đồng `/map-testids`** — §4.5.6 đã được chốt **trước** `/generate-code`, nên trạm này có bảng selector sẵn. Ca còn lại: §4.5.6 rỗng (dự án cũ chưa từng chạy `/map-testids`) → script quay về dò DOM và **giòn**.
+- **Chạy lại tốn tài nguyên** — ×2 cho mỗi FAIL là chi phí thật. Đánh đổi có chủ đích: rẻ hơn nhiều so với một bug ma gửi cho dev, hoặc một defect thật bị gán `script-bug` rồi chôn.
+- **`flaky` không có cột riêng trong sổ trace** — nó nằm ở `qc_status = not_run` + `qc_owner = qc` + nghi vấn ghi trong report. Cố ý: thêm một giá trị enum mới sẽ kéo theo sửa schema, lint, mọi lệnh đọc cột đó — trong khi `not_run` đã đúng nghĩa *chưa có kết luận*. Cái giá là **không truy được lịch sử flaky bằng máy**, phải đọc report.
 
 ---
 

package/docs/explain/20-qc-report.md

@@ -30,8 +30,11 @@ Kết quả chạy cần được trình bày có bằng chứng và **định t
 
 1. **Role qa-runner/report** — nạp skill report.
 2. **Procedure** — tổng hợp kết quả run (pass/fail per SC), đính evidence.
-3. Tách **product-gap** → định tuyến về PO/Dev (có thể thành `/report-bug`).
-4. **Output** report.
+3. Tách **product-gap** → định tuyến về PO/Dev (có thể thành `/report-bug`). Scenario mang nhãn **`flaky`** **không** thành bug — nó là *chưa có kết luận*, `qc_status` để `not_run`.
+4. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+5. **Output** report.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 

package/docs/explain/README.md

@@ -98,12 +98,15 @@ Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (f
 - [05 · `/generate-design-spec`](05-generate-design-spec.md)
 - [06 · `/generate-bdd`](06-generate-bdd.md)
 - [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
+- [**11** · `/map-testids`](11-map-testids.md) ← **chốt hợp đồng test-id, TRƯỚC code**
 - [08 · `/review-tech-docs`](08-review-tech-docs.md)
 
+> Danh sách này xếp theo **thứ tự chạy**, không theo số file. `/map-testids` giữ số `11` vì lý do lịch sử — giữ tên file để không gãy link cũ.
+> §4.5.6 chốt ở đây là lý do **Phase Implementation** và **Phase QC Automation** chạy được **song song**.
+
 ### Phase Implementation
 - [09 · `/generate-code`](09-generate-code.md)
 - [10 · `/review-code`](10-review-code.md)
-- [11 · `/map-testids`](11-map-testids.md)
 
 ### Phase Dev Self-Test
 - [12 · `/dev-gen-test`](12-dev-gen-test.md)

package/package.json

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