@educa-corp/sdd-framework 0.9.4 → 0.9.5

package/docs/plans/qc-surgery/exec-d0-b3-sua-skill-probe-dom.md

@@ -0,0 +1,173 @@
+---
+buoc: Đợt 0 — Bước 3
+title: Sửa 2 skill qa-runner đang dạy dò DOM ngược với command
+phu_thuoc: không (chạy song song b1/b2 được)
+trang_thai: đã làm
+---
+
+# Đợt 0 · Bước 3 — Command nói "đừng dò DOM", skill nói "dò DOM đi"
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+> ✅ **Đã làm rồi.** File này là bản **ĐỊNH làm**. Cái **ĐÃ xảy ra** — gồm chỗ lệch
+> so với kế hoạch này và lý do — ghi ở [`buoc/0-03-skill-thoi-day-do-dom.md`](buoc/0-03-skill-thoi-day-do-dom.md).
+
+> **Đây là nguyên nhân gốc của câu hỏi chị QC** *("có thể dùng prompt trích xuất element/locator
+> từ source code thành 1 file không?")*. Đội QC tin là phải tự dò selector, vì **framework đang
+> dạy họ làm vậy**.
+
+## 1. Vì sao
+
+Framework có hai tầng chỉ dẫn cho cùng một việc:
+
+```
+commands/qc-run-test.tmpl   ← lệnh, agent đọc đầu tiên
+        └─ nạp ──→ skills/qc/qa-runner/functional/gui-screen.md   ← skill, agent đọc khi làm
+```
+
+Lệnh nói: lấy locator từ hợp đồng, **không** dò runtime.
+Skill nói: **dò DOM thật trước khi viết selector**.
+
+Agent đọc lệnh rồi nạp skill để làm việc. Skill là thứ nó đọc **sau** và **gần lúc viết code
+nhất** — nên skill thắng. Kết quả: QC dò DOM, ghi selector kiểu `.login-form__submit`, và mọi
+người kết luận "framework không có gì để dựa vào".
+
+Cái giá của việc dò DOM: dev đổi tên class là test vỡ. Mà dev **không hề hứa** giữ tên class —
+họ chỉ hứa giữ `data-testid` (nếu có hợp đồng). Selector dò được là selector không ai bảo hành.
+
+## 2. Tình trạng hiện tại
+
+**Lệnh nói không dò** — `commands/qc-run-test.tmpl:43`:
+
+> *"**Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §4.5.6
+> (block platform) của tech-doc gộp … và dựng mỗi Page Object locator từ test-id ổn định của
+> nó. **Ưu tiên map; fallback** về role/label/text/CSS (scan chậm hơn) chỉ cho một element có
+> action mà **không** có test-id trong §4.5.6 — và ghi chú để gap được thêm vào tech-design."*
+
+**Skill nói dò** — `skills/qc/qa-runner/functional/gui-screen.md:26`:
+
+> *"**Probe DOM thật trước khi viết selector** (SPA không `data-testid`): dump class/
+> `aria-label`/role bằng script Playwright tạm → ghi selector đúng (BEM `feature__el`; element
+> interactive có thể `role="tab/menuitem"` + class `--active`)."*
+
+**Và skill thứ hai cũng vậy** — `skills/qc/qa-runner/functional/gui-feature.md:25`:
+
+> *"**Probe DOM thật trước khi viết selector** (SPA React/Next không `data-testid`): dump class/
+> `aria-label`/role → BEM `feature__el`, carousel dot thường `role="tab"` + class `--active`
+> (không `aria-selected`)."*
+
+Cả hai câu nằm ở **Phase 1 — Clarify**, tức là **bước đầu tiên** của việc viết script. Không
+phải fallback, không phải "nếu thiếu test-id thì" — mà là việc đầu tiên phải làm.
+
+Chú ý cụm trong ngoặc: *"(SPA không `data-testid`)"*. Câu này được viết cho **hoàn cảnh không có
+hợp đồng test-id**, và ở hoàn cảnh đó nó **hợp lý**. Vấn đề là nó được viết như **mặc định**,
+không như ngoại lệ — nên nó áp cả cho dự án đã có §4.5.6 đầy đủ.
+
+## 3. Sẽ đổi thành gì
+
+Đảo thứ tự, giữ lại kiến thức kỹ thuật (phần BEM / `role="tab"` là kinh nghiệm thật, đáng giữ),
+nhưng đặt nó đúng vị trí là **fallback có ghi chú**:
+
+```
+Phase 1 — Clarify
+Đọc `.Test.md` (confirm Reviewed) · platform · Page Object đã có chưa · fixture setup data?
+
+**Locator: đọc hợp đồng TRƯỚC, dò DOM là bước cuối.**
+1. Mở bảng §4.5.6 Test Selectors của tech-doc gộp, lọc theo cột "Serves SC" khớp SC của UC này
+   → dựng locator từ test-id. Đọc `@trace.testid_attr` ở header để biết TÊN thuộc tính.
+2. Element có action mà §4.5.6 KHÔNG có test-id → thử role + accessible name
+   (`getByRole('button', { name: 'Đăng nhập' })`).
+3. Vẫn không định vị được → MỚI dò DOM (dump class/`aria-label`/role bằng script Playwright
+   tạm; BEM `feature__el`; element interactive có thể `role="tab/menuitem"` + class `--active`).
+   Mỗi lần phải dò tới bước này là **ghi một gap**: element nào, màn nào, thiếu test-id.
+   Đề nghị chạy `/map-testids {UC-ID}` để dev bổ sung, đừng im lặng sống với selector giòn.
+```
+
+Điểm quan trọng của cách viết mới: **dò DOM không bị cấm** — nó vẫn cần cho dự án brownfield
+chưa có hợp đồng. Nhưng mỗi lần dò là một **tín hiệu được ghi lại**, thay vì một thói quen. Nhờ
+vậy số lần dò giảm dần theo thời gian (dev bổ sung test-id), chứ không giữ nguyên mãi.
+
+Ở pipeline mới (Đợt 2), gap này thành `IMPROVE-{date}-{NN}` và được đẩy về spec repo cho dev —
+nhưng câu chữ ở bước này chưa cần nhắc `IMPROVE`, vì lệnh đó chưa tồn tại.
+
+## 3b. Ba ca dễ bị gộp nhầm — bậc 3 CHỈ dành cho ca B
+
+Câu hỏi trong lúc review bước này: *"tự select locator này sẽ phục vụ QC trong việc có code, lấy
+test-id nhưng trong bảng chưa có, đúng không?"* — **gần đúng, nhưng đó là ca A, không phải việc
+của bậc 3.** Ba ca đi ba đường khác nhau:
+
+| | Code có test-id? | §4.5.6 có? | Đường đúng |
+|---|:---:|:---:|---|
+| **A** | ✅ **có** | ❌ chưa | **`/map-testids`** — nhánh `existing` (`map-testids.tmpl:40`): *"Nếu element **đã** có test-id → **reverse-document** nó (dùng lại as-is)"*. Đưa id vào bảng rồi quay lại **bậc 1** |
+| **B** | ❌ **không có gì** (chỉ class/role) | ❌ chưa | **Bậc 3** — dò DOM, ghi gap, đề nghị dev gắn test-id |
+| **C** | ✅ có | ✅ có nhưng **LỆCH** | Không phải bậc 3 — là ca đối chiếu, người quyết bên nào đúng ([`exec-d0-b6`](exec-d0-b6-contract-truoc-code.md) §3.7) |
+
+**Vì sao phải tách A khỏi B.** Bản nháp đầu của bước này viết bậc 3 thành một khối, nên nó sẽ
+**nuốt luôn ca A mà không ai biết**:
+
+```
+§4.5.6 rỗng → bậc 1 trượt → bậc 2 trượt → bậc 3 dump DOM
+                                          → thấy data-testid="login-submit-btn" → dùng luôn
+```
+
+Trông có vẻ ổn (script vẫn bám test-id ổn định), nhưng mất ba thứ:
+
+1. **Id không bao giờ vào §4.5.6** → lần sau lại phải đi khám phá lại từ đầu.
+2. **Không ai review id đó** → nó không thành hợp đồng, dev chưa hề hứa giữ nó.
+3. **Ca A bị nguỵ trang thành ca B** → nhìn script không phân biệt được "id từ hợp đồng" với
+   "id nhặt từ DOM".
+
+Nên bậc 3 tách thành **3a** (đã có test-id → DỪNG, đẩy ngược về `/map-testids`) và **3b** (không
+có gì → dùng class/role + ghi gap). Khác biệt thực tế: 3a **đẩy việc ngược về hợp đồng**, 3b
+chấp nhận selector giòn nhưng để lại dấu vết.
+
+> **Về thời điểm:** ở bước này `/map-testids` chưa có cờ `--from-code` (cờ đó thuộc
+> [`exec-d0-b6`](exec-d0-b6-contract-truoc-code.md) §3.3), nhưng nhánh xử lý ca A **đã tồn tại
+> sẵn** trong lệnh (`map-testids.tmpl:34-40`, phân loại `reused`/`existing`/`new`). Nên skill
+> trỏ `/map-testids {UC-ID}` chung chung là chạy đúng ngay bây giờ; b6 sẽ làm nó tường minh hơn.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `skills/qc/qa-runner/functional/gui-screen.md` | Dòng `:26` — viết lại Phase 1 theo thứ tự 3 bậc ở trên |
+| `skills/qc/qa-runner/functional/gui-feature.md` | Dòng `:25` — tương tự |
+
+Rà thêm cho chắc (grep, sửa nếu cùng lỗi):
+
+```bash
+grep -rn "Probe DOM\|probe DOM\|dump class" skills/qc/
+grep -rn "data-testid" skills/qc/qa-designer/ skills/qc/qa-reviewer/
+```
+
+Hai chỗ đã biết là **không** cùng lỗi, chỉ là tiêu chí review, giữ nguyên:
+- `skills/qc/qa-reviewer/script/functional.md:34` — *"XPath dài/phức tạp → đề xuất data-testid
+  / role"*
+- `skills/qc/qa-reviewer/shared/review-check-groups.md:110` — *"định vị element bằng chỉ số /
+  vị trí (`nth(3)`) thay vì test-id → `[FLAKY_RISK]`"*
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+# 1. Không còn chỉ dẫn dò DOM ở vị trí "việc đầu tiên"
+grep -n "Probe DOM" skills/qc/qa-runner/functional/gui-screen.md skills/qc/qa-runner/functional/gui-feature.md
+#    → nếu còn, phải nằm ở bậc 3 của thứ tự ưu tiên, kèm câu "ghi một gap"
+
+# 2. Build + máy tự kiểm (R16(d) canh ref skill vẫn tồn tại)
+node bin/build.js && node bin/self-check.js && node test/run.js
+```
+
+Kiểm bằng tay — trên một UC **đã có** §4.5.6 đầy đủ:
+
+Chạy `/qc-run-test {UC-ID}` và đọc script sinh ra. Locator phải là `getByTestId('...')` với giá
+trị **trùng khớp** bảng §4.5.6. Nếu thấy `page.locator('.some-class')` hoặc thấy agent chạy
+script dump DOM trong khi §4.5.6 có sẵn id cho element đó → chưa xong.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Bước 1 và 2 sửa được **hợp đồng**, nhưng QC vẫn không dùng hợp đồng — vì skill vẫn bảo dò DOM.
+Tức là làm b1 + b2 mà bỏ b3 thì đầu tư vào hợp đồng không thu lại gì: §4.5.6 đầy đủ, header có
+`@trace.testid_attr`, và script vẫn bám class BEM.
+
+Xa hơn: Đợt 2 sinh script tự động ở quy mô lớn hơn (`/qc-design-script` cho cả web + mobile).
+Nếu thói quen dò DOM còn nguyên, ta chỉ đang **nhân bản selector giòn nhanh hơn**.

package/docs/plans/qc-surgery/exec-d0-b4-may-canh-4-5-6.md

@@ -0,0 +1,168 @@
+---
+buoc: Đợt 0 — Bước 4
+title: Thêm máy canh cho bảng §4.5.6 Test Selectors
+phu_thuoc: d0-b1, d0-b2
+trang_thai: đã làm
+---
+
+# Đợt 0 · Bước 4 — Bảng hợp đồng hiện không ai canh
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+> ✅ **Đã làm rồi.** File này là bản **ĐỊNH làm**. Cái **ĐÃ xảy ra** — gồm chỗ lệch
+> so với kế hoạch này và lý do — ghi ở [`buoc/0-04-may-canh-hop-dong.md`](buoc/0-04-may-canh-hop-dong.md).
+
+## 1. Vì sao
+
+Framework có một nguyên tắc đã học đúng 4 lần (G1, G28, G41, G55), và lần nào cũng cùng một
+hình dạng:
+
+> **Luật ĐÚNG, viết RÕ, và KHÔNG AI CANH.**
+
+Bốn lần đó đều được chữa bằng cùng một cách: *khai tường minh + để máy canh*. Bảng §4.5.6 là
+trường hợp thứ năm, chưa được chữa.
+
+Ba kiểu hỏng có thể xảy ra hôm nay mà không có gì báo:
+
+| Kiểu hỏng | Chuyện gì xảy ra | Ai phát hiện |
+|---|---|---|
+| **Bảng thiếu row** | Màn hình có 8 nút, bảng chỉ ghi 5. QC viết test cho 3 nút còn lại bằng cách dò DOM → 3 test giòn | Không ai. Đến khi test vỡ vài tuần sau |
+| **Row trỏ SC không tồn tại** | Cột "Phục vụ SC" ghi `UC1 · SC7` nhưng `.feature` chỉ có SC1–SC5 (SC7 đã bị xoá/gộp) | Không ai. QC lọc theo cột này → không khớp row nào → tưởng element không có test-id |
+| **Có §4.5 mà header thiếu attr** | Bảng có giá trị test-id đầy đủ, nhưng không ai biết *tên thuộc tính* chứa chúng | Không ai — cho tới khi test đỏ hàng loạt (xem `exec-d0-b1`) |
+
+Điểm chung: cả ba đều hỏng **im lặng**, và cả ba đều **kiểm được bằng máy** — không cần agent
+"để ý", chỉ cần đếm và so khớp.
+
+## 2. Tình trạng hiện tại
+
+**Không có script nào biết đến §4.5.6:**
+
+```bash
+grep -n "testid\|test_id\|4.5.6" bin/*.js
+# → 0 kết quả  (build.js, gate-trace.js, index.js, lint-trace.js, self-check.js)
+```
+
+**Các lệnh review cũng không kiểm:**
+
+```bash
+grep -n "Selector\|testid\|4.5.6" commands/review-tech-docs.tmpl commands/validate-traces.tmpl
+# → 0 kết quả
+```
+
+Tức là bảng này được **3 lệnh đọc** (`generate-code`, `qc-run-test`, `qc-design-test`) và
+**2 lệnh ghi** (`generate-tech-docs`, `map-testids`), nhưng **0 nơi kiểm**.
+
+## 3. Sẽ đổi thành gì
+
+> ⚠️ **Ba chỗ dưới đây đã được sửa lại lúc triển khai (2026-09-11)** — bản gốc viết trước khi
+> đọc kỹ `bin/lint-trace.js`. Giữ lại nguyên văn phần cũ để thấy vì sao đổi.
+>
+> **(1) Bỏ rule thứ ba.** Bản gốc đề xuất T15 = *"element có action trong step `When` mà không
+> có row §4.5.6 → WARN"*. **Đã bỏ.** Nhận diện "element có action" từ văn xuôi Gherkin tiếng
+> Việt là suy luận, không phải phép đếm — sẽ hoặc bỏ sót gần hết, hoặc báo loạn; mà báo loạn thì
+> người ta thêm `--warn-only` vào CI và mất luôn hai rule kia. Ca nó nhắm đã có hai lớp phủ tốt
+> hơn: [`exec-d0-b3`](exec-d0-b3-sua-skill-probe-dom.md) (skill bậc 3b bắt ghi gap mỗi lần phải
+> dò DOM) và [`exec-d0-b6`](exec-d0-b6-contract-truoc-code.md) (`TESTID_UNDECLARED` so bảng với
+> **code thật**). Phần còn lại — element không có id ở đâu cả — **không kiểm được bằng máy** ở
+> tầng này (phải parse JSX/Vue/Flutter); câu trả lời đúng là gate `/review-tech-docs` ở b6.
+> → Còn **2 rule**, đánh số **T15** (SC có thật) và **T16** (header attr).
+>
+> **(2) Không cần cờ `--tech-docs`.** `templates/project-context.yaml:100` khai
+> `tech_docs_dir: "specs"` — trùng `specs_dir` trong layout feature-package. Cờ `--specs` sẵn có
+> là đủ.
+>
+> **(3) T16 có HAI mức, không phải một.** Thiếu hẳn field → ERROR; field có nhưng còn placeholder
+> `{…}` → **WARN**. Sau `exec-d0-b1`, tech-doc mới sinh ra **có** field ở dạng placeholder — đó
+> là *"chưa chạy `/map-testids`"*, một trạng thái hợp lệ trong quy trình, không phải *"thiếu"*.
+> Báo ERROR ở đó là làm mọi tech-doc mới đỏ ngay khi vừa tạo.
+>
+> **Hai chi tiết phát hiện lúc viết code:**
+> - **`lint-trace` thoát sớm khi không có sổ trace** (`bin/lint-trace.js:881`). Hai rule mới
+>   không cần sổ → phải chạy ở **pass riêng, trước** khối đó, và sửa câu thông báo *"chưa có gì
+>   để kiểm"* → *"bỏ qua T1–T14"*.
+> - **Dòng mẫu của template phải được bỏ qua.** Mọi tech-doc mang
+>   `| {uc}-{screen}-{element}-{type} | … | {UC1 · SC1, UC1 · SC3} |`. Không bỏ qua thì doc mới
+>   tinh đỏ ngay vì *"SC1 của UC1 không tồn tại"*.
+> - **Biến thể định dạng → im lặng, không báo oan.** Cột "Phục vụ SC" parse được hai dạng
+>   (`UC1 · SC1` rút gọn và `FT-101-UC1-SC1` đầy đủ). Không parse được token nào → **bỏ qua**,
+>   không đoán.
+
+*(Bản gốc, giữ để đối chiếu:)* Thêm 3 rule vào **`bin/lint-trace.js`**, đặt tên tiếp số hiện có
+(T1–T14) → **T15, T16, T17**.
+
+### Vì sao chọn `lint-trace.js` chứ không phải `self-check.js`
+
+Hai file có phân vai rõ, ghi sẵn trong doc-comment của `self-check.js:47-49`:
+
+- `self-check.js` canh **CONTRACT** — đọc file nguồn của framework, hỏi "lệnh có gọi đúng tên
+  cột không". Nó **không mở file dữ liệu của dự án**.
+- `lint-trace.js` canh **DỮ LIỆU** — mở sổ `.tsv` thật, `.feature` thật của dự án.
+
+§4.5.6 là dữ liệu của dự án → thuộc `lint-trace.js`.
+
+Thuận lợi: `lint-trace.js` **đã** nhận `--specs DIR` (`bin/lint-trace.js:61`, mặc định `specs`)
+và đã đọc `.feature` cho rule T9 (sổ mồ côi). Nên không phải dựng hạ tầng mới.
+
+### Ba rule
+
+| Rule | Kiểm gì | Mức | Vì sao mức đó |
+|---|---|---|---|
+| **T15** | Mỗi element có action xuất hiện trong step `When` của `.feature` phải có ≥1 row §4.5.6 trỏ tới SC đó | **WARN** | Nhận diện "element có action" từ prose Gherkin là **suy luận**, không phải phép đếm chắc chắn → WARN để không chặn oan. Vẫn in ra để người thấy |
+| **T16** | Mọi giá trị trong cột "Phục vụ SC" của §4.5.6 phải là SC **có thật** trong `.feature` của platform đó | **ERROR** | Đây là **phép so khớp chuỗi**, không có chỗ cho suy luận. Row trỏ SC không tồn tại là sai dứt khoát |
+| **T17** | Tech-doc có block §4.5 (platform client) mà header thiếu `@trace.testid_attr` → lỗi | **ERROR** | Cũng là phép kiểm có/không. Thiếu field là đảm bảo trượt locator (xem `exec-d0-b1`) |
+
+**Tham số:** tech-doc nằm ở `{paths.tech_docs_dir}`, mặc định trùng `specs_dir` trong layout một
+repo. Nếu dự án tách submodule thì khác → thêm cờ `--tech-docs DIR`, **mặc định lấy theo
+`--specs`**, và nếu không tìm thấy thư mục `tech-docs/` nào thì **in một dòng nói rõ là đã bỏ
+qua** — đúng cách T14 đang làm với `--code` (`bin/lint-trace.js:65`):
+
+> *"KHÔNG truyền → T14 bị bỏ qua, và file này IN RA MỘT DÒNG nói rõ là đã bỏ qua. Im lặng rồi
+> báo 'sạch' đúng là cách 910 row kia lọt qua."*
+
+### Khai vào schema
+
+`bin/trace-schema.json` phải khai 3 rule mới để R8 (rule canh "lint-trace tụt lại sau schema")
+không báo lệch. Kiểm lại chỗ khai của T12/T14 rồi làm theo đúng khuôn đó.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `bin/lint-trace.js` | Thêm T15/T16/T17; thêm cờ `--tech-docs` (mặc định theo `--specs`); thêm dòng "đã bỏ qua" khi không tìm thấy tech-doc |
+| `bin/trace-schema.json` | Khai 3 rule mới theo khuôn T12/T14 đã có |
+| `templates/ci/trace-gate.yml` | Nếu file này liệt kê rule theo tên → thêm 3 rule mới (R10 trong `self-check.js` canh đúng chuyện này) |
+| `docs/04-reference/trace-schema.md` | Cập nhật danh sách rule |
+
+## 5. Kiểm thế nào để biết đã xong
+
+Kiểm bằng **ca lỗi cố ý** — quan trọng hơn kiểm ca sạch, vì rule mới dễ viết thành "luôn xanh":
+
+```bash
+# Ca sạch → phải PASS
+node bin/lint-trace.js --specs specs
+
+# Ca T16: sửa 1 row §4.5.6 cho trỏ tới SC không tồn tại (vd UC1 · SC99) → phải ERROR
+# Ca T17: xoá dòng @trace.testid_attr khỏi header 1 tech-doc có §4.5 → phải ERROR
+# Ca T15: xoá 1 row §4.5.6 của element có trong step When → phải WARN (không ERROR)
+# Ca bỏ qua: chạy trên repo không có thư mục tech-docs/ → phải IN DÒNG "đã bỏ qua", exit 0
+```
+
+Rồi:
+
+```bash
+node bin/build.js && node bin/self-check.js && node test/run.js
+```
+
+Nếu có test tự động trong `test/run.js` cho lint-trace (đã có cụm T2/T3/T4/T7 ở đó), thêm 3–4
+test cho T15/T16/T17 theo cùng khuôn.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Bước 1, 2, 3 sửa được hợp đồng và sửa được thói quen — nhưng **không có gì giữ nó không mục
+dần**. Sáu tháng sau: SC bị gộp, row §4.5.6 trỏ vào SC đã xoá; màn hình thêm 3 nút, bảng không
+ai cập nhật; một tech-doc mới tạo tay thiếu header. Từng chuyện nhỏ, không ai báo, và QC lại
+quay về dò DOM vì "hợp đồng không đáng tin".
+
+Đây đúng là cái vòng mà nguyên tắc số 3 của đợt mổ tồn tại để chặn: *"luật gì cũng phải có máy
+canh — thêm luật mới thì thêm rule trong `bin/` cùng lúc, không để sau"*
+([`00-nhat-ky.md` §6](00-nhat-ky.md)).

package/docs/plans/qc-surgery/exec-d0-b5-don-nhan-lech.md

@@ -0,0 +1,196 @@
+---
+buoc: Đợt 0 — Bước 5
+title: Dọn nhãn cột lệch và tên mục "§2b" cũ
+phu_thuoc: d0-b1 → d0-b4
+trang_thai: đã làm
+---
+
+# Đợt 0 · Bước 5 — Dọn phần lệch còn lại
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+> ✅ **Đã làm rồi.** File này là bản **ĐỊNH làm**. Cái **ĐÃ xảy ra** — gồm chỗ lệch
+> so với kế hoạch này và lý do — ghi ở [`buoc/0-05-don-nhan-cot-va-2b.md`](buoc/0-05-don-nhan-cot-va-2b.md).
+
+> ⚠️ **Phạm vi đã thu hẹp sau vòng hỏi–đáp ngày 2026-09-11.** Hai phần vốn thuộc bước này —
+> *"đưa `/map-testids` vào golden path"* (§3.3) và *"chặn cứng ở phía tiêu thụ"* — đã **chuyển
+> hẳn** sang [`exec-d0-b6`](exec-d0-b6-contract-truoc-code.md) §3.2 + §3.4, vì ở đó chúng được
+> giải quyết triệt để hơn (đổi thứ tự lệnh + gate ở `/review-tech-docs`, thay vì chỉ sửa tài
+> liệu). **Làm b6 thì bỏ §3.3 của file này** — đừng sửa `steps/report-footer.md` hai lần theo
+> hai hướng. Phần còn lại của bước này (§3.1 nhãn cột, §3.2 tên mục "§2b") vẫn giữ nguyên.
+> Lý do đầy đủ: [`00-nhat-ky.md` §3.2](00-nhat-ky.md).
+
+## 1. Vì sao
+
+Bốn bước trước sửa phần *hoạt động*. Bước này sửa phần *cách gọi tên* và *vị trí trong quy
+trình* — nghe nhỏ, nhưng cả hai đều đã gây hậu quả thật:
+
+**Nhãn lệch** — cùng một bảng, hai chỗ mô tả cột thứ ba bằng hai cái tên khác nhau. Ai đọc một
+chỗ rồi làm theo chỗ kia sẽ ghi sai định dạng, và không có gì báo (Bước 4 chỉ canh cột "Phục vụ
+SC", không canh cột này).
+
+**Tên mục cũ** — ba file vẫn gọi bảng này là "§2b Test Selectors". Số mục đã đổi thành §4.5.6 từ
+lâu. Agent đọc "§2b" rồi đi tìm §2b trong tech-doc → không có → kết luận tech-doc không có bảng
+test selector → dò DOM. Chính là vòng lỗi mà Bước 3 vừa chặn, nhưng qua một cửa khác.
+
+**Không nằm trong golden path** — `/map-testids` là lệnh **duy nhất** biết đọc source code
+brownfield để rút test-id. Nó không có trong danh sách bước bắt buộc, nên trong thực tế bị bỏ.
+Chính tài liệu của framework đã thừa nhận điều này.
+
+## 2. Tình trạng hiện tại
+
+### 2.1 Nhãn cột thứ ba lệch nhau
+
+| Nơi | Ghi cột 3 là |
+|---|---|
+| `templates/tech-design.template.md:276` | `Component (§4.5.1.x)` |
+| `commands/map-testids.tmpl:64` | `Component (reused/existing/new)` |
+
+Nguyên văn `map-testids.tmpl:64`:
+
+> *"Mỗi row: `Test-ID | Element | Component (reused/existing/new) | Action | Serves SC`."*
+
+Nguyên văn template (`:276`):
+
+```
+| Test-ID | Element | Component (§4.5.1.x) | Action | Phục vụ SC (UC · SC) |
+```
+
+Hai cái này **không phải cùng thứ**: một cái muốn *tên component* (trỏ tới §4.5.1.x — cây
+component), cái kia muốn *phân loại nguồn gốc* (reused/existing/new). Cả hai đều có ích, nhưng
+phải chọn — hoặc tách thành 2 cột.
+
+### 2.2 Tên mục cũ "§2b" còn sót 3 chỗ
+
+| File:dòng | Nội dung |
+|---|---|
+| `skills/spec/SKILL.md:19` | gọi "§2b Test Selectors" |
+| `modules/qc-playwright/stack-profile.yaml:22` | ghi **cả hai**: *"FE tech-design §2b Test Selectors contract (… bảng Test Selectors §4.5.6 …)"* |
+| `specs/domain-knowledge/figma-components/react.md:91` | gọi "§2b" |
+
+### 2.3 `/map-testids` không bắt buộc
+
+Vị trí của nó trong pipeline **mâu thuẫn giữa 3 tài liệu**:
+
+| Nơi | Đặt `/map-testids` ở đâu |
+|---|---|
+| `steps/report-footer.md:63` | Phase **Tech Design** (trước `/generate-code`) |
+| `GAPS-v4.md:724` | trước `/generate-code --phase=ui` |
+| `docs/explain/11-map-testids.md:1,69` | **sau** `/generate-code` + `/review-code` |
+
+Và `docs/explain/11-map-testids.md:60` tự thừa nhận sự mờ này:
+
+> *"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ờ."*
+
+Rồi `:63` nói thẳng hậu quả:
+
+> *"**Không bắt buộc trong golden path** — dễ bị bỏ qua, khiến QC selector giòn."*
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 Chốt 5 cột, một định nghĩa
+
+Giữ đúng 5 cột theo template (đang là bản chuẩn vì `generate-tech-docs` include nó), và **chuyển
+phân loại `reused/existing/new` sang cột Ghi chú** thay vì cột Component:
+
+```
+| Test-ID | Element | Component (§4.5.1.x) | Action | Phục vụ SC (UC · SC) |
+```
+
+Sửa `map-testids.tmpl:64` cho khớp, và nói rõ phân loại nguồn gốc ghi ở đâu (Ghi chú, hoặc
+không ghi vào bảng — nó chỉ là phân loại nội bộ lúc chạy Step 1).
+
+Lý do chọn template làm chuẩn thay vì `map-testids`: `templates/tech-design.template.md` được
+`generate-tech-docs.tmpl:227` include trực tiếp, nên nó là thứ **sinh ra bảng lần đầu**.
+`/map-testids` chỉ cập nhật bảng đã có → phải theo.
+
+### 3.2 Đổi "§2b" → "§4.5.6"
+
+Sửa 3 chỗ ở §2.2. Riêng `modules/qc-playwright/stack-profile.yaml:22` đang ghi cả hai tên —
+bỏ tên cũ, giữ một.
+
+> **Lưu ý thứ tự:** file `modules/qc-playwright/stack-profile.yaml` sẽ được **thay hẳn** ở Đợt 2
+> bước 2 (Python → TypeScript). Nếu Đợt 2 chạy ngay sau Đợt 0 thì sửa ở đây là công cốc — cân
+> nhắc bỏ qua chỗ này và ghi vào việc dọn của `exec-d2-b2`. Hai chỗ còn lại (`skills/spec/`,
+> `specs/domain-knowledge/`) thì sửa bình thường.
+
+### 3.3 Đưa `/map-testids` thành bắt buộc
+
+Chốt vị trí: **sau `/generate-code --phase=ui`, trước `/qc-design-test`**. Lý do:
+
+- Cần code UI tồn tại để nhánh `existing`/`reused` đọc được file component
+  (`map-testids.tmpl:40`, `:48`).
+- Phải xong trước khi QC thiết kế test case, vì `/qc-design-test` đọc §4.5.6 để trích test-id
+  vào bước test (`commands/qc-design-test.tmpl:128`).
+
+Hai việc:
+
+1. Sửa `steps/report-footer.md` (bảng Phase `:63` + bảng Next `:98`) và
+   `docs/explain/11-map-testids.md` cho **cùng nói một vị trí**. Gỡ câu tự thừa nhận "vị trí hơi
+   mờ" ở `:60` sau khi đã chốt.
+2. **Chặn cứng ở phía tiêu thụ** — đây là phần có hiệu lực thật, vì tài liệu thì đọc rồi bỏ
+   qua được: `/qc-design-test` (và `/qc-design-script` ở Đợt 2) khi thấy §4.5.6 **rỗng hoặc
+   không tồn tại** cho platform client thì **DỪNG** với thông báo rõ:
+
+   ```
+   ❌ §4.5.6 Test Selectors rỗng cho platform {platform} của {TICKET-ID}.
+      QC không có hợp đồng locator để bám → script sinh ra sẽ giòn.
+      Chạy /map-testids {UC-ID} trước, rồi chạy lại lệnh này.
+      (Cố ý bỏ qua để prototype: thêm --no-testid-contract, và artifact sẽ được đánh dấu
+       là dựa trên selector dò runtime.)
+   ```
+
+   Cờ `--no-testid-contract` theo đúng tinh thần `--include-draft` của `steps/qc-scope.md`:
+   *"cái thường gặp là cái an toàn, và cái sớm phải nói ra"*.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `commands/map-testids.tmpl` | `:64` — nhãn 5 cột khớp template; nói rõ phân loại `reused/existing/new` ghi ở đâu |
+| `skills/spec/SKILL.md` | `:19` — "§2b" → "§4.5.6" |
+| `specs/domain-knowledge/figma-components/react.md` | `:91` — "§2b" → "§4.5.6" |
+| `modules/qc-playwright/stack-profile.yaml` | `:22` — bỏ tên cũ *(hoặc hoãn sang `exec-d2-b2`, xem §3.2)* |
+| `steps/report-footer.md` | `:63` bảng Phase + `:98` bảng Next — chốt một vị trí cho `/map-testids` |
+| `docs/explain/11-map-testids.md` | `:1`, `:60`, `:63`, `:69` — sửa vị trí pipeline, gỡ câu "vị trí hơi mờ" và "không bắt buộc" |
+| `commands/qc-design-test.tmpl` | Thêm guard §4.5.6 rỗng → DỪNG + cờ `--no-testid-contract` |
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+# 1. Không còn "§2b" nào
+grep -rn "§2b\|section 2b" --include="*.md" --include="*.yaml" . | grep -v "^./GAPS"
+#    → 0 kết quả (trừ file GAPS lịch sử, không sửa)
+
+# 2. Nhãn cột khớp nhau
+grep -n "Test-ID | Element" templates/tech-design.template.md commands/map-testids.tmpl
+#    → 5 cột giống nhau
+
+# 3. Vị trí /map-testids nhất quán
+grep -rn "map-testids" steps/report-footer.md docs/explain/11-map-testids.md
+#    → cùng nói một vị trí
+
+# 4. Build + máy tự kiểm
+node bin/build.js && node bin/self-check.js && node test/run.js
+```
+
+Kiểm bằng tay:
+
+- Trên một UC **chưa** chạy `/map-testids`, chạy `/qc-design-test {UC-ID}` → phải **DỪNG** với
+  thông báo ở §3.3.
+- Thêm `--no-testid-contract` → phải chạy được, và artifact phải có dấu ghi rõ là dựa trên
+  selector dò runtime.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Ba hậu quả, giảm dần theo mức nghiêm trọng:
+
+1. **Không chặn cứng ở phía tiêu thụ (§3.3) là mất phần lớn giá trị của cả Đợt 0.** Sửa hợp
+   đồng, sửa skill, thêm máy canh — nhưng nếu QC vẫn **chạy được** `/qc-design-test` khi §4.5.6
+   rỗng thì trong lúc gấp việc, người ta vẫn bỏ `/map-testids`. Tài liệu nói "nên chạy" thì đọc
+   rồi bỏ qua; lệnh dừng lại thì không.
+2. **"§2b" còn sót** → agent đi tìm mục không tồn tại → kết luận tech-doc không có bảng → dò
+   DOM. Đúng vòng lỗi Bước 3 vừa chặn, đi qua cửa khác.
+3. **Nhãn cột lệch** → hai người ghi bảng theo hai định dạng. Bước 4 chỉ canh cột "Phục vụ SC",
+   nên cột này lệch mà vẫn xanh.