@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/docs/02-concepts/pipeline-steps/08-qc-automation.md

@@ -9,7 +9,7 @@
 |---|---|
 | **Giai đoạn** | QC Automation |
 | **Owner** | 👤 QA / Tester |
-| **Đầu vào** | UC-ID + spec (PRD/BDD) + code đã chạy |
+| **Đầu vào** | **Trạm 1–4:** spec (PRD/BDD `approved`) + **hợp đồng test-id §4.5.6** (đóng băng ở bước 5) — **chưa cần code**.<br/>**Trạm 5 `/qc-run-test` thêm:** code đã chạy được — **trạm duy nhất** cần |
 | **Đầu ra** | Test case, script Playwright, `qc_status`, evidence, product-gap |
 | **HITL** | 🟠 Vừa — cổng review case & script trước khi chạy |
 
@@ -22,7 +22,7 @@
 - Phân rã yêu cầu thành test case bám scenario, phát hiện **gap tài liệu**.
 - Chạy test thật, ghi **`qc_status` chính thức** + **evidence**.
   ⚠️ Nhưng `/qc-run-test` **đọc cột `status` trước khi ghi `pass`** *(GAPS-v4 G55)*: row `DRIFT`/`ORPHANED` + test xanh → hạ về `not_run`, và **không** đóng bug nào ở lần chạy đó. `fail`/`skip` ghi bình thường.
-- Phân loại FAIL: **script-bug** (sửa script) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
+- Phân loại FAIL thành **ba** nhãn — `script-bug` · `product-gap` · `flaky` — **sau khi đã chạy lại tối đa 2 lần**. Một test đỏ **một lần** chưa nói được nó đỏ vì cái gì.
 - Đẩy **product-gap** ngược về PO/Dev.
 
 ---
@@ -31,7 +31,8 @@
 
 - **UC-ID** + platform (QC pass khoá 1 platform).
 - Spec: PRD / `.feature` (từ spec repo, qua `spec_source`).
-- Code đã sinh & chạy được.
+- **Hợp đồng test-id**: `@trace.testid_attr` (header tech-doc, **tên** thuộc tính) + §4.5.6 Test Selectors (**giá trị** test-id, cột *Serves SC* là chỉ mục ngược). Đã chốt ở [bước 5](05-tech-docs.md) **trước khi có code**.
+- Code đã sinh & chạy được — **chỉ `/qc-run-test` cần**. Bốn trạm đầu (`/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review`) chạy **song song với FE** vì chỉ cần spec + hợp đồng test-id. Đó là chỗ hai nhánh của [bước 5](05-tech-docs.md) gặp lại.
 - `qc_dir` (working docs của QC) + module `qc-playwright`.
 
 ## Output (Đầu ra)
@@ -60,7 +61,8 @@
 - Yêu cầu phân rã thành những **test case** nào? Tài liệu có **gap** gì?
 - Rủi ro nào cao? Cần hỏi dev điều gì trước khi test?
 - Test case & script đã đủ tốt để **chạy** chưa (cổng review)?
-- SC nào **PASS/FAIL** chính thức (`qc_status`)? FAIL là **script-bug** hay **product-gap**?
+- SC nào **PASS/FAIL** chính thức (`qc_status`)? FAIL là **script-bug**, **product-gap**, hay chỉ **flaky**?
+- Có business rule nào BDD đã nhắc mà bản phân tích bỏ sót không? Có scenario nào **không** test case nào phủ không?
 
 ---
 
@@ -68,22 +70,65 @@
 
 Dây chuyền **6 trạm**, output trạm trước là input trạm sau:
 
-| # | Trạm | Việc |
-|---|------|------|
-| 1 | `/qc-analyze` | Phân rã yêu cầu + phát hiện **gap tài liệu** (`DOC_GAP.md`) |
-| 2 | `/qc-plan` | Đánh giá **rủi ro** + câu hỏi cho dev (`TEST_PLAN.md`) |
-| 3 | `/qc-design-test` | Thiết kế **test case** dạng Markdown (`*.Test.md`) |
-| 4 | `/qc-review` | 🛑 **Cổng review** hai chiều: test case & script trước khi chạy |
-| 5 | `/qc-run-test` | Sinh & chạy **pytest-playwright**, ghi **`qc_status`** chính thức |
-| 6 | `/qc-report` | Report + **evidence**, đẩy **product-gap** về PO/Dev |
+| # | Trạm | Việc | Phép kiểm cơ học |
+|---|------|------|---|
+| 1 | `/qc-analyze` | Phân rã yêu cầu + phát hiện **gap tài liệu** (`DOC_GAP.md`) | **Guard BR-tag** |
+| 2 | `/qc-plan` | Đánh giá **rủi ro** + câu hỏi cho dev (`TEST_PLAN.md`) | — |
+| 3 | `/qc-design-test` | Thiết kế **test case** dạng Markdown (`*.Test.md`) | **Guard SC coverage** |
+| 4 | `/qc-review` | 🛑 **Cổng review** hai chiều: test case & script trước khi chạy | — |
+| 5 | `/qc-run-test` | Sinh & chạy **pytest-playwright**, ghi **`qc_status`** chính thức | **chạy lại ×2 + 3 nhãn FAIL** |
+| 6 | `/qc-report` | Report + **evidence**, đẩy **product-gap** về PO/Dev | — |
+
+### Hai Guard cơ học — chống bỏ sót **im lặng**
+
+Trước đây sáu trạm này **không có phép kiểm cơ học nào**: bỏ sót một business rule, hay một scenario không có test case nào, đều xảy ra mà không ai biết. Hai guard đóng đúng hai lỗ đó:
+
+| Guard | Ở đâu | Đối chiếu cái gì | Khi lệch |
+|---|---|---|---|
+| **BR-tag** | `/qc-analyze` | Tập business rule mà `.feature` **đã gắn tag** (A) ↔ tập rule bản phân tích **sinh ra** (B) | `A ∖ B` ≠ rỗng → **tự bổ sung** từ PRD, in danh sách |
+| **SC coverage** | `/qc-design-test` | Mọi scenario **trong phạm vi** ↔ test case trỏ tới nó | Có SC chưa phủ → **viết bù TC ngay**, in danh sách |
+
+**Cả hai in dòng kết quả kể cả khi sạch** (`Guard BR-tag: khớp {n}/{n}`) — 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.
+
+> **SC coverage không có đường thoát.** Scenario bị gap chặn thì test case **vẫn viết đủ**, mang dấu `🚫 Block` trỏ tới `DOC_GAP.md` — gap là thứ được **ghi vào** test case, không phải cái cớ để không viết.
+
+### Ba nhãn FAIL — chống kết luận vội
+
+Một test đỏ có thể vì **script sai**, vì **sản phẩm sai**, hoặc vì **chạy hên xui**. Gộp ba thứ đó làm một là nói dối theo cả hai hướng: gắn nhầm `script-bug` cho lỗi sản phẩm thật là **giấu bug**; mở bug từ một lần chạy hên xui là **đốt thời gian dev**.
+
+```
+đỏ → đỏ → đỏ     ⇒ NHẤT QUÁN       → điều tra bằng evidence: 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ả | `qc_status` |
+|---|---|---|---|
+| `script-bug` | Sai locator / logic test / timing / dữ liệu | QC tự sửa, **không** mở bug | — (sửa rồi chạy lại) |
+| `product-gap` | Hành vi thật ≠ spec — defect thật | Mở bug qua `/report-bug`, giữ evidence | `fail` |
+| `flaky` | Không nhất quán qua các lần chạy lại | Cách ly + ghi **nghi vấn** nguyên nhân. **Không** mở bug | `not_run`, `qc_owner = 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.
+>
+> `flaky` → `not_run` chứ không phải một trạng thái mới: nó đú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.
+
+**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 phân loại.
+
+### Self-Review — mỗi trạm tự soát trước khi in report
+
+Cả sáu trạm nạp chung `skills/qc/_shared/self-review-principles.md` và chạy một lượt tự soát trước khi in report.
+
+> ⚠️ **Self-review KHÔNG thay Guard.** Guard là phép **đếm cơ học**, 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**. 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 — file đó ghi rõ ranh giới này ngay ở đầu.
 
 - Stack QC bắt buộc theo `modules/qc-playwright/stack-profile.yaml`: Python + pytest-playwright + Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+- **Locator lấy từ hợp đồng, không dò DOM**: thứ tự ưu tiên là §4.5.6 → `@trace.testid_attr` → mới tới các cách khác. Skill `qa-runner` đã bỏ hết chỉ dẫn "dò DOM trước".
 
 ---
 
 ## HITL / Gate
 
 - 🛑 `/qc-review` — **cổng review** case & script: không chạy test kém.
+- 🛑 **Xác nhận phân loại FAIL** — mỗi FAIL phải được người chốt nhãn trước khi ghi `qc_status`. Đây là cổng chặn hiếm hoi được **thêm vào** (framework vốn đang giảm số cổng), vì **cả hai hướng sai đều không đảo ngược rẻ**.
 - **Không fake-pass**: FAIL là product-gap → giữ nguyên FAIL + evidence, đẩy về PO/Dev.
 
 ---
@@ -93,6 +138,9 @@ Dây chuyền **6 trạm**, output trạm trước là input trạm sau:
 - ❌ Lẫn `qc_status` với `dev_selftest` — hai trục độc lập.
 - ❌ 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 cổng `/qc-review`.
+- ❌ **Kết luận từ một lần chạy đỏ** — chưa loại nhiễu thì chưa phân biệt được `flaky` với lỗi thật.
+- ❌ **Tự dò selector từ DOM** thay vì đọc §4.5.6 — script giòn, dev đổi một class là vỡ mà không ai báo.
+- ❌ Dùng self-review làm lý do **bỏ qua** một Guard.
 
 ---
 

package/docs/02-concepts/pipeline-steps/README.md

@@ -18,15 +18,16 @@ flowchart TD
     SP --> DS["3 · Design-Spec<br/>/generate-design-spec<br/><i>(chỉ FE/App)</i>"]
     SP --> B["4 · BDD<br/>/generate-bdd · /review-context"]
     DS --> B
-    B --> T["5 · Tech-Docs<br/>/generate-tech-docs · /review-tech-docs"]
+    B --> T["5 · Tech-Docs<br/>/generate-tech-docs · /map-testids · /review-tech-docs"]
     T --> C["6 · Code<br/>/generate-code · /review-code"]
+    T -.->|"hợp đồng test-id §4.5.6"| Q
     C --> DV["7 · Dev self-test<br/>/dev-gen-test · /dev-run-test · /dev-smoke-test"]
     DV --> Q["8 · QC Automation<br/>/qc-analyze → … → /qc-report"]
     Q --> V["9 · Validate Traces<br/>/validate-traces"]
     V -.->|"report-bug · propose-scenario · learn"| SP
 ```
 
-**Đặc tính bất biến:** pipeline **một chiều** — output của bước N là input của bước N+1. Mỗi bước có **gate đầu vào** (validate) và **gate đầu ra** (findings/approval). Kênh feedback ngược (bước 10) **không tạo loop** mà để cải tiến spec và tri thức dự án.
+**Đặc tính bất biến:** pipeline **một chiều** — output của bước N là input của bước N+1. *(Đường nét đứt 5 → 8 **không** phải nhảy bước: đó là hợp đồng test-id §4.5.6 được chốt ở bước 5 để QC dựng test **song song** với FE, xem [Tech-Docs](05-tech-docs.md).)* Mỗi bước có **gate đầu vào** (validate) và **gate đầu ra** (findings/approval). Kênh feedback ngược (bước 10) **không tạo loop** mà để cải tiến spec và tri thức dự án.
 
 ---
 
@@ -39,7 +40,7 @@ flowchart TD
 | 2 | [Specification](02-specification.md) | `/generate-prd` · `/refine-prd` · `/review-context` | PO (+SA/Dev review) | 🔴 cao |
 | 3 | [Design-Spec](03-design-spec.md) | `/generate-design-spec` | PO/PM | 🟠 vừa *(chỉ FE/App)* |
 | 4 | [BDD](04-bdd.md) | `/generate-bdd` · `/review-context` | PO (+Dev) | 🔴 cao |
-| 5 | [Tech-Docs](05-tech-docs.md) | `/generate-tech-docs` · `/review-tech-docs` | SA/Lead | 🟠 vừa |
+| 5 | [Tech-Docs](05-tech-docs.md) | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` | SA/Lead | 🟠 vừa |
 | 6 | [Code](06-code.md) | `/generate-code` · `/review-code` · `/fix-bug` | Dev | 🟡 mỏng |
 | 7 | [Dev self-test](07-dev-selftest.md) | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` | Dev | 🟡 mỏng |
 | 8 | [QC Automation](08-qc-automation.md) | `/qc-analyze` … `/qc-report` | QA/Tester | 🟠 vừa |

package/docs/02-concepts/traceability.md

@@ -42,14 +42,14 @@ Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag expl
 | `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
 | `implemented_by` | `/generate-code` | File code hiện thực SC |
 | `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
-| `qc_status` | `/qc-run-test`, `/report-bug` | Trạng thái QC **chính thức** (Playwright) |
+| `qc_status` | `/qc-run-test`, `/report-bug`, **`/map-testids`** | Trạng thái QC **chính thức** (Playwright). `/map-testids` **chỉ hạ về `not_run`**, không bao giờ ghi giá trị khẳng định — xem ô "Làm mất hiệu lực" dưới |
 | `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
 | `service` *(cột 23)* | `/generate-bdd` | Đội/submodule sở hữu SC — nguồn của `by_service` trên dashboard |
 | `design_spec_version` *(cột 24)* | `/generate-bdd` | Version design-spec lúc sinh BDD *(FE/App; `—` cho backend)* |
 
 **24 cột.** TSV cũ thiếu cột mới → đọc thành giá trị rỗng, **không báo lỗi**; header tự nâng ở lần `/generate-bdd` gen lại kế tiếp. Đọc theo **tên cột ở header row**, không theo vị trí.
 
-> **Làm mất hiệu lực ≠ ghi đè.** Chủ sở hữu là người **duy nhất** ghi giá trị **khẳng định** (`pass`/`fail`/số lượng). Nhưng lệnh nào làm giá trị đó **hết đúng** (spec đổi, code đổi) **bắt buộc** hạ nó về `not_run`/`—`. Giữ một `pass` sinh ra từ spec đã bị sửa là **báo cáo sai**, không phải tôn trọng quyền sở hữu cột. Ngoại lệ có chủ ý: `qc_owner`/`qc_blocked_by` (con trỏ bug vẫn còn giá trị) và `test_count`/`test_classes` (test vẫn trên đĩa — **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
+> **Làm mất hiệu lực ≠ ghi đè.** Chủ sở hữu là người **duy nhất** ghi giá trị **khẳng định** (`pass`/`fail`/số lượng). Nhưng lệnh nào làm giá trị đó **hết đúng** (spec đổi, code đổi) **bắt buộc** hạ nó về `not_run`/`—`. Giữ một `pass` sinh ra từ spec đã bị sửa là **báo cáo sai**, không phải tôn trọng quyền sở hữu cột. Ví dụ mới nhất: `/map-testids` ghi lại §4.5.6 → mọi test-script bám selector cũ đã hết đúng → lệnh hạ `qc_status` về `not_run` và `qc_run_at` về `—`. Ngoại lệ có chủ ý: `qc_owner`/`qc_blocked_by` (con trỏ bug vẫn còn giá trị) và `test_count`/`test_classes` (test vẫn trên đĩa — **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
 | `gen_ver` | `/generate-code` | Version lúc sinh code (so với `spec_ver`) |
 | `test_count` | test | Số test phủ SC |
 | `last_updated` | nhiều | Mốc cập nhật |

package/docs/03-guides/architect.md

@@ -98,7 +98,7 @@ sprint thứ ba không ai làm.** Framework có hai lệnh CLI trả exit code
 
 | Lệnh | Chặn gì | Đặt ở đâu |
 |---|---|---|
-| `--lint-trace` | **Cấu trúc sổ** (13 rule): header lệch · row sai số ô · enum sai · `sc_id` trùng · marker conflict git · `.jsonl` hỏng. Cộng **T12 — nhất quán GIỮA các ô**: row vừa `status ∈ {DRIFT, ORPHANED}` vừa mang `dev_selftest`/`qc_status = pass`. Cộng hai điều kiện **cấu hình** ở mức ⚠️: thiếu luật merge · sổ bị gitignore | pre-push **và** CI |
+| `--lint-trace` | **Cấu trúc sổ** (18 rule, T1–T18): header lệch · row sai số ô · enum sai · `sc_id` trùng · marker conflict git · `.jsonl` hỏng. Cộng **T12 — nhất quán GIỮA các ô**: row vừa `status ∈ {DRIFT, ORPHANED}` vừa mang `dev_selftest`/`qc_status = pass`. Cộng hai điều kiện **cấu hình** ở mức ⚠️: thiếu luật merge · sổ bị gitignore. Cộng **T15–T18 — hợp đồng test-id**: T15 bảng §4.5.6 trỏ tới SC **không có** trong `.feature` · T16 doc có §4.5 client mà header **thiếu** `@trace.testid_attr` · T17 id **khai mà code không có** · T18 id **code có mà bảng không khai** (T17/T18 cần `--code`). Bốn rule này chỉ nói **ở nơi hợp đồng tồn tại** — dự án backend-only hay dự án chưa từng chạy `/map-testids` thì im lặng hoàn toàn | pre-push **và** CI |
 | `--gate-trace` | **Cấu hình** (nâng hai ⚠️ trên thành chặn) + **cờ 🔴**: `ORPHANED` · `TRACE_ORPHAN` · `SEAM_UNWIRED` · `STUB_UNRESOLVED` | CI (cần report tươi) |
 
 ```bash
@@ -166,6 +166,6 @@ danh sách chặn.
 
 ## Lệnh của bạn (Your commands)
 
-`/generate-architecture` · `/generate-tech-docs` · `/review-tech-docs` · `/refine-prd` (SA lens) · `/review-code` · `/generate-spec-manifest`
+`/generate-architecture` · `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` · `/refine-prd` (SA lens) · `/review-code` · `/generate-spec-manifest`
 
 → [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Architecture](../02-concepts/architecture.md)

package/docs/03-guides/developer.md

@@ -10,7 +10,8 @@
 
 ```mermaid
 flowchart LR
-    R["/refine-prd · /review-context<br/>🟡 DEV lens"] --> G["/generate-code<br/>🟢 Lead"]
+    R["/refine-prd · /review-context<br/>🟡 DEV lens"] --> M["§4.5.6 đã chốt<br/>(/map-testids, bước 5)"]
+    M --> G["/generate-code<br/>🟢 Lead"]
     G --> RC["/review-code<br/>🟡 read-only"]
     RC --> T["/dev-gen-test → /dev-run-test<br/>🟢 Lead"]
     T --> S["/dev-smoke-test<br/>🟢"]
@@ -24,7 +25,7 @@ flowchart LR
 | Bước | Bạn làm gì |
 |------|-----------|
 | Review upstream | Lăng kính **DEV** trong `/refine-prd` — bắt chỗ mơ hồ khó hiện thực |
-| [Code](../02-concepts/pipeline-steps/06-code.md) | Chạy `/generate-code`; xác nhận **comprehension checkpoint** (drift new/drifted/synced); đảm bảo build pass |
+| [Code](../02-concepts/pipeline-steps/06-code.md) | Chạy `/generate-code`; xác nhận **comprehension checkpoint** (drift new/drifted/synced); đảm bảo build pass. **Gắn test-id theo §4.5.6 — không tự đặt** |
 | Review code | `/review-code` (read-only) — soát kỹ, **không auto-fix** |
 | [Dev self-test](../02-concepts/pipeline-steps/07-dev-selftest.md) | `/dev-gen-test` → `/dev-run-test` (set `dev_selftest`) → `/dev-smoke-test` |
 | [Bug fix](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/fix-bug` — root cause → sửa → regression test |
@@ -38,6 +39,8 @@ flowchart LR
 3. **Scope Lock** — chỉ implement UC target; code UC khác trong file dùng chung là **bất khả xâm phạm**. Đọc `@trace.implements` để bảo toàn, đừng xoá.
 4. **Code CŨNG mang version** — `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` ghi *"tôi được sinh theo bản nào"*, còn spec giữ *"bản hiện tại"*. Sự **lệch nhau** giữa hai mốc chính là tín hiệu drift. Đừng "tối ưu" bằng cách gỡ chúng — `/validate-traces` đọc đúng các tag đó.
 5. **File phủ nhiều UC → lặp cả block theo từng method.** Không gộp header, không trỏ `@trace.source` vào thư mục.
+6. **Test-id là HỢP ĐỒNG, không phải chi tiết của bạn.** `@trace.testid_attr` (header tech-doc) nói gắn **thuộc tính nào**, §4.5.6 nói gắn **giá trị nào**. QC đang viết test-script theo đúng bảng đó **song song với bạn**. Nếu §4.5.6 rỗng, `/generate-code` sẽ **cảnh báo mạnh rồi hỏi Y/N** — đường đúng là dừng lại chạy `/map-testids`, đừng để AI tự bịa id.
+   - Id sinh ra **không khớp code thật** thì sửa bằng `/map-testids --from-code`, đừng sửa tay. Lệnh đó tự hạ `qc_status` → `not_run` để QC biết script cũ đã hết hiệu lực.
 6. **Sửa scenario thì bump `@trace.sc_version`** của chính SC đó — nếu bạn sửa `.feature` bằng tay. Quên bump = code cũ vĩnh viễn hiện `OK`.
 7. **Build phải pass** trước commit (`{conventions.build_command}`, ≤3 retry).
 8. `CLAUDE.md` (§2 layer/package, §3 coding standards, §5 error handling) là nguồn — AI *follow*, bạn giữ nó cập nhật.

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

@@ -10,23 +10,26 @@
 
 ```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"]
+    M["§4.5.6 đã chốt<br/>(/map-testids, bước 5)"] --> A
+    A["/qc-analyze<br/>Guard BR-tag"] --> P["/qc-plan"] --> D["/qc-design-test<br/>Guard SC coverage"]
+    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>chạy lại ×2 · 3 nhãn<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
     REP --> FB["/report-bug · /propose-scenario"]
     FB --> SYNC["/sync"]
 ```
 
+> **Ba trạm đầu KHÔNG chờ code.** Hợp đồng test-id (§4.5.6) được chốt ở bước Tech-Docs, **trước** `/generate-code`. Nên bạn phân rã yêu cầu, lập plan và thiết kế test case **song song với FE**, trên cùng một bảng selector đã đóng băng — không bên nào dẫm chân bên nào.
+
 ---
 
 ## 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-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**. **Guard BR-tag** đối chiếu rule BDD đã gắn tag ↔ rule bạn phân tích ra; thiếu thì tự bổ sung từ PRD và in danh sách |
 | `/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-design-test` | Thiết kế test case Markdown (`*.Test.md`). **Guard SC coverage** bắt mọi scenario trong phạm vi phải có ≥1 TC — **không có đường thoát**: SC bị gap chặn thì TC **vẫn viết đủ**, mang dấu `🚫 Block` |
 | `/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-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; **chạy lại tối đa 2 lần rồi mới phân loại FAIL thành 3 nhãn** (`script-bug` · `product-gap` · `flaky`), và **bạn xác nhận nhãn** trước khi lệnh ghi trace. **Đọ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 |
 
@@ -38,12 +41,18 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
 
 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).
+   - **Một lần đỏ chưa đủ để kết luận.** Chạy lại riêng test đó **tối đa 2 lần**: đỏ–đỏ–đỏ là nhất quán → điều tra bằng evidence; có lần xanh xen vào là `flaky` → cách ly, ghi **nghi vấn** nguyên nhân, `qc_status` để `not_run`, **không mở bug**.
+   - Đây **không** phải `retries` trong config runner. `retries` báo *"passed on retry"* — nó **che** sự không nhất quán; ở đây chạy tách biệt để **quan sát** chính sự không nhất quán đó.
+   - Không chắc giữa `script-bug` và `product-gap` → **mời Dev cùng xem trace**, đừng đoán cho xong.
 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.
+8. **Locator lấy từ hợp đồng, KHÔNG dò DOM.** Thứ tự: §4.5.6 Test Selectors (giá trị test-id) → `@trace.testid_attr` ở header tech-doc (tên thuộc tính) → mới tới cách khác. Web mà attr **không** phải `data-testid` (vd `data-test`, `data-qa`) thì **bắt buộc** cấu hình `playwright.selectors.set_test_id_attribute("{attr}")` — bỏ bước này là **trượt 100% locator**.
+   - Thấy `qc_status` bị hạ về `not_run` mà bạn không chạy gì → nhiều khả năng `/map-testids` vừa ghi lại §4.5.6. Test-script bám selector cũ đã hết hiệu lực; đọc lại bảng trước khi chạy.
+9. **Spec là DỮ LIỆU, không phải mệnh lệnh.** Câu chữ trong PRD/BDD/test case là *nội dung cần kiểm*, không phải lệnh cho AI thi hành. Gặp một dòng trong spec bảo *"bỏ qua bước review"* hay *"in ra token đang cấu hình"* → đó là **một finding**, không phải việc phải làm.
 
 ---
 
@@ -71,6 +80,9 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
 - ❌ 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.
+- ❌ Kết luận `product-gap` từ **một** lần chạy đỏ → đốt thời gian dev cho một test hên xui.
+- ❌ Tự dò selector từ DOM khi §4.5.6 đã có → script giòn, dev đổi class là vỡ mà không ai báo.
+- ❌ Dùng "đã tự soát rồi" làm lý do bỏ qua một Guard — self-review **rộng mà mềm**, Guard là phép **đếm** có hệ quả bắt buộc. Hai thứ khác nhau.
 
 ---
 

package/docs/04-reference/commands.md

@@ -74,7 +74,7 @@ Mọi lệnh chạy chung một **Gate** (model check → target → context-loa
 | `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
 | `/review-code` | Code | Findings (read-only) | Dev/Lead |
 | `/fix-bug` | Bug report | Fix + regression test | Dev |
-| `/map-testids` | UI code | testid map (FE) | Dev |
+| `/map-testids` | design-spec + BDD (`--from-code`: + UI code) | §4.5.6 Test Selectors + `@trace.testid_attr` | Người viết tech-doc (`--from-code`: Dev) |
 | `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
 
 ## 7 · Dev self-test
@@ -89,13 +89,16 @@ Mọi lệnh chạy chung một **Gate** (model check → target → context-loa
 
 | Lệnh | Input | Output | Owner |
 |------|-------|--------|-------|
-| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md` | QA |
+| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md` + **Guard BR-tag** | QA |
 | `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
-| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
+| `/qc-design-test` | Plan + `.feature` + §4.5.6 | `test-cases/*.Test.md` + **Guard SC coverage** | QA |
 | `/qc-review` | Test case/script | 🛑 Cổng review | QA |
-| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
+| `/qc-run-test` | `.Test.md` reviewed + §4.5.6 | Script Playwright + `qc_status`. **Chạy lại ×2 → 3 nhãn FAIL** (`script-bug`·`product-gap`·`flaky`), 🛑 người xác nhận nhãn | QA |
 | `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
 
+> **Cả sáu trạm chạy một lượt Self-Review trước khi in report**, theo `skills/qc/_shared/self-review-principles.md` (một file dùng chung, không sáu bản sao).
+> Self-review **rộng mà mềm**; Guard là phép **đếm** có hệ quả bắt buộc. Không bao giờ dùng self-review làm lý do gỡ một Guard.
+
 ## 9 · Quality & Trace
 
 | Lệnh | Input | Output | Owner |

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

@@ -94,6 +94,44 @@ public ScoreDto calculate(...) { }
 | `@trace.revision` | integer, bump mỗi lần sửa — nguồn của `TECHDOC_DRIFT` |
 | `@trace.status` | `draft` / `in-review` / `approved` — cổng của `/generate-code` DS3 |
 | `@trace.api_source` | `existing` → chế độ reverse-document, bỏ cổng T7 |
+| `@trace.testid_attr` | **TÊN THUỘC TÍNH** chứa test-id (`data-testid` · `data-test` · `testID` · `ValueKey`…) — **một** giá trị cho cả doc. Khác **GIÁ TRỊ** test-id từng element, cái đó ở §4.5.6. Ghi bởi `/map-testids`; đọc bởi `/generate-code` (emit lên element) và các lệnh `qc-*` (cấu hình locator). |
+
+### Hợp đồng test-id — được máy canh (`testid_contract`)
+
+Bảng **§4.5.6 Test Selectors** trong tech-doc là hợp đồng FE↔QC: **3 lệnh đọc**
+(`generate-code`, `qc-run-test`, `qc-design-test`), **2 lệnh ghi** (`generate-tech-docs`,
+`map-testids`). Hai rule của `lint-trace` canh nó:
+
+| Rule | Kiểm gì | Mức |
+|---|---|:---:|
+| **T15** | Mọi SC ở cột *"Serves SC"* phải có thật trong `.feature` của nền đó | 🔴 error |
+| **T16** | Có block §4.5 (nền client) mà header thiếu hẳn `@trace.testid_attr` | 🔴 error |
+| | …có nhưng còn ở dạng placeholder `{…}` (chưa chạy `/map-testids`) | ⚠️ warn |
+| **T17** | Id đã khai ở §4.5.6 mà **không có trong code** — FE chưa gắn / gắn sai / element đã đổi *(cần `--code`)* | ⚠️ warn |
+| **T18** | Id nằm trong code mà **không có trong §4.5.6 nào** — gắn ngoài hợp đồng *(cần `--code`)* | ⚠️ warn |
+
+> **T17/T18 là WARN, không ERROR.** Id đoán từ thiết kế không sống sót 100%: lúc implement, dev
+> có thể gộp hai element thành một component hoặc tách một thành hai. Đây là **nợ cần thấy**,
+> không phải cái sai chặn người.
+>
+> T18 là **lưới bắt phía sau** cho quyết định ở `/generate-code`: khi §4.5.6 rỗng, lệnh đó cảnh
+> báo rồi **để người quyết** thay vì chặn cứng — chính vì có T18 bắt những id tạm sinh ra ở đó,
+> nên "vẫn sinh" không tạo nợ vô hình.
+>
+> Thiếu `--code` → in `T17/T18 BỎ QUA` tường minh, **không im lặng báo sạch**. Code chưa có id
+> nào của thuộc tính đó (UI chưa viết) → im lặng, không phán "FE chưa gắn" cho cả bảng.
+
+> **Phạm vi neo vào sự tồn tại của hợp đồng.** Doc không có §4.5 client → **không kiểm gì**.
+> Dự án backend-only, hay dự án chưa từng chạy `/map-testids`, im lặng hoàn toàn. Hai rule nói
+> *"chỗ nào đã hứa thì phải giữ"*, không nói *"mọi chỗ đều phải có hợp đồng"*. Dòng mẫu của
+> template (còn `{…}`) cũng được bỏ qua — nếu không thì tech-doc vừa sinh ra đã đỏ.
+>
+> **Không vào `gate.blocking`** — đây là nợ cần thấy, không phải cái sai chặn PR. Cùng nhóm với
+> `TECHDOC_DRIFT` / `BDD_DRIFT`; 13/17 cờ audit hiện tại cũng không chặn.
+
+Khối `testid_contract` trong `bin/trace-schema.json` khai hai rule này kèm `why`, và
+`self-check` **R8e** báo lỗi nếu `lint-trace.js` không thực sự phát ra chúng — nửa *"máy canh"*
+của luật *"khai tường minh + để máy canh"*.
 
 ---
 

package/docs/explain/07-generate-tech-docs.md

@@ -1,4 +1,4 @@
-[← /generate-bdd](06-generate-bdd.md) · [Explain Home](README.md) · [Next: /review-tech-docs →](08-review-tech-docs.md)
+[← /generate-bdd](06-generate-bdd.md) · [Explain Home](README.md) · [Next: /map-testids →](11-map-testids.md)
 
 # 07 · `/generate-tech-docs` — Sinh Technical Design (full-stack, gộp/PRD)
 
@@ -31,7 +31,9 @@
 
 1. **Bước 1 · Fresh vs Append** — chưa có doc → **FRESH**; đã có → **APPEND** (tăng dần, **không regenerate** để khỏi mất chỉnh tay + sign-off). Đọc §10 UC Coverage → `covered_ucs`; mỗi UC batch phân loại `add-new` / `extend-platform` / `refresh` (hỏi Y/N) / `skip`.
 2. **Bước 2 · Cổng Chất lượng** — mỗi feature: tìm `{uc-id}-{platform}-review-bdd-findings.yaml`; còn critical `pending` → **DỪNG** (chạy `--fix`/`--resume` trước); `@trace.status ≠ approved` → cảnh báo mềm Y/N.
-3. **Bước 3 · Điều kiện tiên quyết Client** (batch có web/app) — nạp design-spec cho §4.5 (component, Figma map, state, selector); thiếu → §4.5 degraded `[DRAFT — no design-spec]`.
+3. **Bước 3 · Điều kiện tiên quyết Client** (batch có web/app) — nạp design-spec cho §4.5 (component, Figma map, state); thiếu → §4.5 degraded `[DRAFT — no design-spec]`.
+
+   > **Lệnh này KHÔNG ghi §4.5.6 Test Selectors** *(đổi ở đợt sửa hợp đồng test-id)*. Nó dựng **khung** §4.5.6 rồi để trống — bảng đó do [`/map-testids`](11-map-testids.md) điền, và header `@trace.testid_attr` cũng vậy. Một bảng, **một** người ghi: hai lệnh cùng ghi một bảng thì bản nào thắng là chuyện may rủi, và không ai biết bản nào đang đúng.
 4. **Bước 4 · Brownfield** — `@trace.api_source: existing` → **reverse-document** (mô tả as-is, ghi gap vs BDD, không thiết kế mới); else **greenfield** (thiết kế từ scenario).
 5. **CHECKPOINT** — trình kế hoạch (mode, batch, platform, API mode, section sẽ sinh) → chờ Y.
 6. **Sinh** doc 12 section: §1 Overview · §2 Architecture · §3 Data Model · §4 API Contracts (+§4.5 client design) · §5 Key Flows (sequence, lane 5.A system/5.B web/5.C app) · §6 Integration · §7 Security · §8 Error Handling · §9 Design Decisions · **§10 UC Coverage** (khoá theo platform×SC) · §11 Cross-cutting · **§12 GAP Register** (ẩn số chưa chốt).
@@ -68,4 +70,4 @@
 
 ## Kết nối
 
-**Trước:** [`/generate-bdd`](06-generate-bdd.md) + [`/review-context {feature}`](04-review-context.md) · **Sau:** [`/review-tech-docs`](08-review-tech-docs.md).
+**Trước:** [`/generate-bdd`](06-generate-bdd.md) + [`/review-context {feature}`](04-review-context.md) · **Sau:** [`/map-testids`](11-map-testids.md) (chốt hợp đồng test-id) → [`/review-tech-docs`](08-review-tech-docs.md).

package/docs/explain/08-review-tech-docs.md

@@ -1,4 +1,4 @@
-[← /generate-tech-docs](07-generate-tech-docs.md) · [Explain Home](README.md) · [Next: /generate-code →](09-generate-code.md)
+[← /map-testids](11-map-testids.md) · [Explain Home](README.md) · [Next: /generate-code →](09-generate-code.md)
 
 # 08 · `/review-tech-docs` — Review Technical Design (8 dimension + ký T7)
 
@@ -39,9 +39,20 @@ Chạy 8 dimension (mỗi cái phân loại severity + auto-fixable):
 | **T3b** | **BDD Freshness** | Doc dựng từ BDD **version nào**, BDD giờ ở version nào — so từng entry của map `@trace.bdd_versions` với `.feature` tương ứng | 2 ca (thêm/xoá entry) |
 | **T4** | Cross-PRD Endpoint Conflict | grep endpoint/entity ở doc PRD khác, **load-on-hit**; va chạm shape/behavior → critical | ❌ |
 | **T5** | Internal Consistency | Sequence vs mô tả, API spec vs code sketch, ref không định nghĩa | một phần |
-| **T6** | Structural Completeness | Section chuẩn có mặt & không rỗng | ✅ thêm skeleton |
+| **T6** | Structural Completeness | Section chuẩn có mặt & không rỗng · **+ hợp đồng test-id** (dưới) | ✅ thêm skeleton — **trừ** hai ca test-id |
 | **T7** | Cross-Team API Contract | **Cổng ký liên team** — chỉ khi doc có backend (system) + không phải `api_source: existing` | sign-off block auto-fix |
 
+**T6 · hợp đồng test-id** *(mới)* — hai ca **Major** và **không tự sửa được**:
+
+| Điều kiện | Severity | Auto-fix |
+|---|---|---|
+| **§4.5.6 Test Selectors rỗng** (doc có platform client) | **Major** | ❌ — phải chạy `/map-testids` |
+| Header **thiếu** `@trace.testid_attr` | **Major** | ❌ — phải chạy `/map-testids` |
+
+> **Vì sao KHÔNG auto-fix.** Tự điền một bảng test-id là **bịa hợp đồng** — mà hợp đồng này có hai bên tiêu thụ (FE gắn attribute, QC viết script). Thêm skeleton rỗng thì lần review sau nó "có mặt & không rỗng" và cổng tự tắt, trong khi bảng vẫn vô nghĩa.
+>
+> **Vì sao cổng nằm ở đây.** Đây là chỗ **cuối cùng còn chặn được trước khi có code**. Trôi qua đây thì `/generate-code` phải tự xoay xở với một bảng rỗng, và QC thì không có gì để bám.
+
 **T3b chi tiết** — T3 kiểm *nội dung* khớp, T3b kiểm *độ tươi*:
 
 | Điều kiện | Severity | Auto-fix |
@@ -66,6 +77,7 @@ Sau phân tích → ghi findings; **Resume Mode** áp finding `accepted`/`modifi
 ## Checkpoint & Gate
 
 - 🔒 **T7 sign-off** — contract liên team chưa ký đủ (be/fe/app/sa) → chưa mở khoá code phía tiêu thụ.
+- 🟠 **T6 test-id** — §4.5.6 rỗng hoặc thiếu `@trace.testid_attr` → Major, không tự sửa. Đường ra là chạy [`/map-testids`](11-map-testids.md), không phải bấm qua.
 - 🟡 **T3b (chặn mềm)** — còn finding T3b Major `open` → CHECKPOINT `Y/N` trước khi đặt `approved`.
 - Read-only — không tự sửa; findings qua Board → `--resume`.
 
@@ -91,4 +103,4 @@ Sau phân tích → ghi findings; **Resume Mode** áp finding `accepted`/`modifi
 
 ## Kết nối
 
-**Trước:** [`/generate-tech-docs`](07-generate-tech-docs.md) · **Sau:** đủ ký T7 → [`/generate-code {feature}`](09-generate-code.md).
+**Trước:** [`/generate-tech-docs`](07-generate-tech-docs.md) → [`/map-testids`](11-map-testids.md) · **Sau:** đủ ký T7 + §4.5.6 đã chốt → **hai nhánh song song**: [`/generate-code {feature}`](09-generate-code.md) (FE gắn attribute) ∥ [`/qc-design-test`](17-qc-design-test.md) (QC dựng test theo cùng bảng).

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,4 +1,6 @@
-[← /review-code](10-review-code.md) · [Explain Home](README.md) · [Next: /dev-gen-test →](12-dev-gen-test.md)
+[← /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)
 
@@ -14,16 +16,17 @@ Test tự động (Playwright) vỡ khi selector đổi (class/text thay đổi)
 
 ## Vị trí & tiền đề
 
-- **Vị trí:** Phase Tech Design / Implementation (FE), giữa code FE và QC.
+- **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:** UI code FE (element có action) + catalog component tái dùng + tech-doc §4.5.
+**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:** code FE được patch test-id + map §4.5.6 Test Selectors trong tech-doc.
+**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.*
 
 ---
 
@@ -57,13 +60,13 @@ Test tự động (Playwright) vỡ khi selector đổi (class/text thay đổi)
 
 ## 👓 Góc nhìn tối ưu
 
-- **Lệnh cầu nối FE→QC** — vị trí pipeline hơi mờ (giữa Tech Design & Code). Chạy sớm quá thì UI chưa xong, muộn quá thì QC phải chờ. Đáng làm rõ thời điểm 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.
-- **Không bắt buộc trong golden path** — dễ bị bỏ qua, khiến QC selector giòn. Cân nhắc tích hợp vào `/generate-code --phase=ui`.
+- **Đã 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-code`](09-generate-code.md) (UI FE) · **Sau:** [`/qc-*`](15-qc-analyze.md) dùng selector đã map.
+**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.
+
 
 ---