@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/docs/plans/qc-surgery/buoc/0-03-skill-thoi-day-do-dom.md

@@ -0,0 +1,167 @@
+# Skill thôi dạy dò DOM trước khi đọc hợp đồng
+
+| | |
+|---|---|
+| **Đợt** | 0 — Hợp đồng test-id |
+| **Bước** | **3/6** của Đợt 0 |
+| **File sửa** | `skills/qc/qa-runner/functional/gui-screen.md` · `.../gui-feature.md` |
+| **File test** | Không có test tự động — xem B4 |
+| **Ngày xong** | 2026-09-11 · commit `292291f` |
+| **Phụ thuộc** | không có — chạy song song `0-01`/`0-02` được |
+| **Ai dùng nó** | `/qc-run-test` nạp hai skill này khi sinh script cho màn hình GUI |
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+
+## A1 · Vấn đề
+
+Công ty phát cho nhân viên mới hai tập tài liệu. Tập mỏng ghi: *"tìm hàng theo mã vạch trên kệ"*. Tập dày — tập họ thật sự mở ra lúc đi làm — ghi: *"cứ xuống kho nhìn hình dáng thùng mà đoán"*.
+
+Nhân viên làm theo tập dày, vì đó là tập cầm trên tay lúc làm việc.
+
+Rồi kho đổi cách xếp thùng, mọi người tìm nhầm hết. Và cả công ty kết luận: *"mã vạch ở đây không dùng được"* — trong khi mã vạch vẫn dán đầy đủ, chỉ là **không ai được bảo hãy dùng nó**.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+> **Đảo thứ tự trong sách hướng dẫn, không xé trang.** Việc "nhìn hình dáng mà đoán" vẫn cần
+> — kho cũ chưa dán mã vạch thì phải đoán. Nhưng nó chuyển từ **việc đầu tiên** xuống **việc
+> cuối cùng**, và mỗi lần phải làm vậy thì **ghi lại một dòng**: kệ nào chưa có mã.
+
+Nhờ dòng ghi đó, số lần phải đoán **giảm dần** theo thời gian — thay vì giữ nguyên mãi.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Kịch bản kiểm thử sinh ra sẽ bám vào **nhãn đã thoả thuận** thay vì tên lớp hiển thị. Và mỗi khi gặp một nút chưa có nhãn, nó **ghi lại một mục** đề nghị đội lập trình bổ sung — thay vì lặng lẽ dùng tên lớp rồi để đó.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **DOM** — cấu trúc bên trong của một trang web; "dò DOM" là mở trang ra xem thật để tìm cách gọi tên từng nút.
+- **Skill** — tập tài liệu chuyên môn mà trợ lý AI mở ra đọc khi bắt tay vào một việc cụ thể. Khác với **lệnh**, là bản chỉ dẫn tổng quát nó đọc trước.
+- **Hợp đồng test-id** — bảng ghi sẵn nhãn của từng nút, để hai bên không phải đoán.
+
+---
+
+> ### ✅ Phép thử người đọc
+>
+> **Đã thử với:** tự soát · **ngày:** 2026-09-11 · **phải giải thích thêm chỗ nào:** chưa thử với người thật.
+> *(A1 cố ý không nhắc "DOM" hay "selector" — hai từ đó đẩy xuống A4.)*
+
+---
+
+# PHẦN B — Chi tiết kỹ thuật
+
+## B1 · Cách hiển nhiên là gì, và vì sao nó sai
+
+### Cách sai thứ nhất — chỉ sửa lệnh, không sửa skill
+
+Đây là cách gần như ai cũng làm, vì lệnh **nghe có vẻ quan trọng hơn** skill. Và lệnh đã nói đúng rồi — `commands/qc-run-test.tmpl:43`:
+
+> *"**Locator từ test-id contract (không scan runtime).** … **Ưu tiên map; fallback** về role/label/text/CSS chỉ cho element có action mà **không** có test-id trong §4.5.6."*
+
+Sai vì **thứ tự đọc**. Agent đọc lệnh trước, 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. Câu trong skill, `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`…)"*
+
+Và nó nằm ở **Phase 1 — Clarify**, tức **việc đầu tiên**, không phải fallback.
+
+Đây là nguyên nhân gốc khiến đội QC tin rằng phải tự dò selector — và là lý do trưởng phòng QC hỏi *"có thể dùng prompt trích xuất locator từ source code không?"*. Họ không sai; **framework đang bảo họ làm vậy**.
+
+### Cách sai thứ hai — xoá hẳn câu "probe DOM" đi
+
+Đã biết nó sai thì xoá. Nghe dứt khoát.
+
+Sai vì hai lẽ. **Một:** dự án brownfield chưa có contract **vẫn cần dò** — xoá là lấy đi một năng lực đang dùng, mà không ai khai. **Hai:** kiến thức trong câu đó là kinh nghiệm thật và đắt: *BEM `feature__el`* · *element interactive có thể `role="tab/menuitem"` + class `--active`* · *carousel dot thường `role="tab"`, không phải `aria-selected`*. Xoá câu là xoá cả những thứ đó.
+
+### Cách sai thứ ba — chép nguyên luật từ lệnh sang skill
+
+"Skill tự chứa" là nguyên tắc có thật của bộ skill này, nên chép sang nghe hợp lý.
+
+Sai vì tạo **ba bản** của một luật (lệnh + 2 skill). Chúng sẽ lệch — không phải nếu, mà là khi — và lệch **im lặng**, vì không rule nào so nội dung các file với nhau.
+
+## B2 · Cách làm đúng
+
+Đảo thành thang **3 bậc**, giữ nguyên kiến thức cũ nhưng đẩy xuống bậc cuối:
+
+```
+1. Test-id contract — bảng §4.5.6, lọc theo cột "Phục vụ SC" khớp SC của UC này.
+                      TÊN thuộc tính đọc từ @trace.testid_attr (đừng suy từ nền).
+2. Role + accessible name — cho element có action mà §4.5.6 chưa phủ.
+3. Dò DOM — CHỈ khi 1 và 2 đều trượt. Dump class/aria-label/role, rồi nhìn kết quả:
+     3a. Element ĐÃ mang test-id trong code
+         → DỪNG, đừng tự dùng id nhặt được. Chạy /map-testids để đưa vào §4.5.6
+           rồi quay lại bậc 1.
+     3b. Element KHÔNG có test-id nào
+         → mới dùng class/role (BEM · role=tab/menuitem · carousel dot…)
+           VÀ ghi một GAP: element nào, màn nào, thiếu test-id.
+```
+
+**Tách 3a/3b là phần quan trọng nhất, và nó đến từ một câu hỏi lúc review.** Bản nháp đầu viết bậc 3 thành một khối, nên nó **nuốt luôn** ca *"code đã có test-id mà bảng chưa có"*:
+
+```
+§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 thì ổn — script vẫn bám test-id ổn định. Nhưng mất ba thứ: id **không bao giờ vào §4.5.6** (lần sau lại phải khám phá lại) · **không ai review** id đó (dev chưa hề hứa giữ nó) · và 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").
+
+Ba ca dễ bị gộp nhầm, và chúng đi ba đường:
+
+| | Code có test-id? | §4.5.6 có? | Đường đúng |
+|---|:---:|:---:|---|
+| **A** | ✅ | ❌ | `/map-testids` — nhánh `existing`, reverse-document rồi quay lại bậc 1 |
+| **B** | ❌ | ❌ | **bậc 3b** — dùng class/role + ghi gap |
+| **C** | ✅ | ✅ nhưng lệch | Ca đối chiếu, người quyết bên nào đúng ([`0-06`](0-06-hop-dong-truoc-code.md)) |
+
+**Câu chịu lực, không phải trang trí:** *"mỗi lần xuống bậc 3b là một GAP phải ghi"*. Không có nó thì thang 3 bậc chỉ là "vẫn được dò, chỉ là xếp thứ ba" — và thói quen không đổi. Có nó thì số lần dò **giảm dần** theo thời gian, vì mỗi lần dò đẻ ra một việc cho dev.
+
+Và mỗi skill **trỏ** tới luật ở lệnh, kèm câu **"không chép lại ở đây"** viết thẳng vào file — để người sau không "bổ sung cho đầy đủ".
+
+## B3 · Nếu làm sai thì hỏng theo kiểu nào
+
+**Kiểu hỏng: im lặng** 🔴
+
+| | |
+|---|---|
+| Hỏng ở đâu | Mọi selector trong script QC — chúng bám tên class thay vì nhãn đã thoả thuận |
+| Ai phát hiện | Không ai, **cho tới lần dev đổi tên một class** |
+| Sau bao lâu | Vài tuần tới vài tháng — đúng lúc không ai nhớ hai việc đó liên quan gì tới nhau |
+| Vì sao đắt | Class **không phải thứ dev cam kết giữ**. Test vỡ vì một thay đổi hoàn toàn hợp lệ, và QC đi sửa script thay vì đi đòi một hợp đồng |
+
+Thêm một tầng: nếu chỉ sửa lệnh mà quên skill, thì `0-01` + `0-02` + `0-04` **đều mất giá trị** — hợp đồng đầy đủ, máy canh chạy, và QC vẫn dò DOM.
+
+## B4 · Verify bằng gì
+
+| # | Phép thử | Kết quả |
+|---|---|---|
+| 1 | Kiến thức cũ còn nguyên, chỉ đổi vị trí: `grep -n "dò DOM" skills/qc/qa-runner/functional/gui-*.md` | ✅ có ở bậc 3, không ở đầu |
+| 2 | Skill giờ trỏ tới hợp đồng: `grep -c "4.5.6\|testid_attr" …/gui-screen.md` | ✅ 3 |
+| 3 | 🔴 Không ai chép lại luật: `grep -rc "không scan runtime" skills/qc/` | ✅ **0** |
+| 4 | `build` · `self-check` · `test` · `lint-trace` | ✅ 212/212 |
+
+**Phép thử tay chưa chạy** — trên một UC **đã có** §4.5.6 đầy đủ:
+
+| # | Phép thử | Kết quả mong đợi |
+|---|---|---|
+| 5 | `/qc-run-test {UC-ID}`, đọc script sinh ra | Locator là `get_by_test_id(...)` với giá trị **trùng bảng §4.5.6** |
+| 6 | Quan sát quá trình | **Không** thấy agent chạy script dump DOM trong khi §4.5.6 có sẵn id |
+| 7 | Dựng ca A (code có id, bảng chưa có) | Agent **DỪNG** và đề nghị `/map-testids`, không tự dùng id nhặt được |
+
+Phép thử 3 là phép thử canh chính nguyên tắc: nếu một ngày nó ra khác 0, có nghĩa ai đó vừa chép luật vào skill và ba bản đã bắt đầu tồn tại.
+
+## B5 · Bài học
+
+- **2026-09-11** — Bản nháp đầu của bậc 3 viết thành một khối, và nó **nuốt ca A mà không ai biết**. Lỗi lộ ra không phải do đọc lại code, mà do một câu hỏi lúc review: *"cái này phục vụ cho việc có code, lấy test-id nhưng trong bảng chưa có, đúng không?"* — câu hỏi đó buộc phải phân biệt ba ca A/B/C, và lúc phân biệt thì thấy bậc 3 đang gộp hai ca vào một.
+  → **Bài học chuyển giao được:** khi viết một thang ưu tiên có bậc "làm tạm", hãy hỏi **bậc tạm đó đang gộp mấy tình huống khác nhau**. Bậc cuối của một thang ưu tiên là chỗ mọi ca chưa nghĩ tới rơi vào — và chúng thường cần xử lý khác nhau.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | Nguyên tắc **skill thắng lệnh**: tài liệu mà agent đọc gần lúc làm nhất sẽ quyết định hành vi, nên sửa tầng trên mà quên tầng dưới là không sửa gì. Cách "không cấm cách tạm, nhưng bắt nó để lại dấu vết" để một thói quen tự giảm dần. Và việc tách bậc cuối thành các nhánh theo tình huống |
+| ⚠️ **Chỉ đúng ở đây** | Nội dung kỹ thuật ở bậc 3b (BEM · `role="tab"` · carousel dot không dùng `aria-selected`) gắn với stack web cụ thể. Hai skill này còn viết cho Python/pytest — Đợt 2 sẽ đổi sang TypeScript, nên câu chỉ dẫn đã viết trung tính sẵn (bỏ chữ "Playwright") |
+
+## B7 · Link
+
+- Kế hoạch trước khi làm: [`../exec-d0-b3-sua-skill-probe-dom.md`](../exec-d0-b3-sua-skill-probe-dom.md) — §3b có bảng ba ca A/B/C đầy đủ
+- Bước liên quan: [`0-01`](0-01-testid-attr-co-cho-o.md) · [`0-02`](0-02-mot-nguon-cho-testid-attr.md) (sửa hợp đồng) · [`1-03`](1-03-fail-3-nhan.md) (lặp lại đúng lớp lỗi này ở chỗ khác: 8 chỗ skill dạy nhị phân)

package/docs/plans/qc-surgery/buoc/0-04-may-canh-hop-dong.md

@@ -0,0 +1,173 @@
+# Máy canh bảng hợp đồng — T15/T16, và R8e canh chính hai rule đó
+
+| | |
+|---|---|
+| **Đợt** | 0 — Hợp đồng test-id |
+| **Bước** | **4/6** của Đợt 0 |
+| **File sửa** | `bin/lint-trace.js` · `bin/trace-schema.json` · `bin/self-check.js` · `docs/04-reference/trace-schema.md` |
+| **File test** | `test/run.js` — 7 test mới |
+| **Ngày xong** | 2026-09-11 · commit `5b4403c` |
+| **Phụ thuộc** | [`0-01`](0-01-testid-attr-co-cho-o.md) · [`0-02`](0-02-mot-nguon-cho-testid-attr.md) |
+| **Ai dùng nó** | `bin/lint-trace.js` chạy ở CI và gọi tay; `bin/self-check.js` chạy mỗi lần build |
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+
+## A1 · Vấn đề
+
+Ba bước trước sửa xong quyển sổ địa chỉ và dạy mọi người dùng nó. Nhưng **không ai kiểm quyển sổ đó**.
+
+Sáu tháng sau: vài căn nhà bị đập đi, sổ vẫn ghi địa chỉ cũ. Vài căn xây mới, không ai thêm vào sổ. Một quyển sổ mới chép tay thì quên hẳn trang đầu.
+
+Từng chuyện một đều nhỏ, **không ai báo**, và đến lúc đội giao hàng thấy sổ sai quá nhiều thì họ quay về cách cũ — tự đi tìm.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+> **Như máy soát vé ở cửa.** Không cần ai nhớ phải kiểm — cứ đi qua cửa là máy tự đối chiếu.
+> Vé không có trong hệ thống thì kêu ngay, chứ không đợi tới lúc vào chỗ ngồi mới phát hiện.
+
+Và có một máy thứ hai **canh chính cái máy soát vé đó** — để nếu một ngày ai tháo nó ra, hệ thống báo lỗi thay vì im lặng cho tất cả đi qua.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Chạy lệnh kiểm tra dữ liệu sẽ thấy thêm dòng báo nếu bảng địa chỉ trỏ vào một kịch bản không tồn tại, hoặc tài liệu có phần giao diện mà quên ghi loại nhãn. Và nếu dự án **chưa dùng** cơ chế này thì **hoàn toàn im lặng** — không ai bị làm phiền.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **Lệnh kiểm tra dữ liệu (`lint-trace`)** — chương trình đọc các file dữ liệu thật của dự án rồi báo chỗ sai. Khác với **`self-check`**, chỉ kiểm bản thân framework có tự mâu thuẫn không.
+- **Rule** — một phép kiểm cụ thể, có mã riêng (`T15`, `T16`…) để nói tới nó cho gọn.
+
+---
+
+> ### ✅ Phép thử người đọc
+>
+> **Đã thử với:** tự soát · **ngày:** 2026-09-11 · **phải giải thích thêm chỗ nào:** chưa thử với người thật.
+
+---
+
+# PHẦN B — Chi tiết kỹ thuật
+
+## B1 · Cách hiển nhiên là gì, và vì sao nó sai
+
+### Cách sai thứ nhất — viết đủ ba rule như kế hoạch
+
+Kế hoạch (`exec-d0-b4`) đề ba rule, trong đó có: *"element có action xuất hiện trong step `When` của `.feature` mà không có row §4.5.6 → WARN"*. Nghe rất hợp lý: đó chính là ca **"bảng thiếu row"**, ca quan trọng nhất.
+
+Sai vì 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. Câu `Khi người dùng bấm "Đăng nhập"` và câu `Khi hệ thống gửi email xác nhận` — cái đầu có element, cái sau không, và phân biệt hai cái đó bằng regex là bất khả.
+
+Kết cục sẽ là một trong hai: bỏ sót gần hết (rule vô dụng), hoặc báo loạn. Và **báo loạn thì đắt hơn vô dụng**: người ta thêm `--warn-only` vào CI, rồi mất luôn hai rule kia.
+
+Ca đó đã có hai lớp phủ tốt hơn: [`0-03`](0-03-skill-thoi-day-do-dom.md) bắt ghi gap mỗi lần phải dò DOM, và [`0-06`](0-06-hop-dong-truoc-code.md) thêm `T18` so bảng với **code thật**. Phần còn lại — element không có nhãn ở đâu cả — **không kiểm được bằng máy** ở tầng này (phải parse JSX/Vue/Flutter), và câu trả lời đúng cho nó là một cổng review, không phải một rule lint.
+
+### Cách sai thứ hai — thêm rule vào `lint-trace.js` rồi thôi
+
+Rule chạy, test xanh, xong việc.
+
+Sai vì **không ai canh rule đó có còn tồn tại không**. Sáu tháng sau ai đó refactor `lint-trace.js`, xoá nhầm một nhánh — không gì báo. Đây đúng hình dạng lỗi mà cả đợt mổ này đang dọn: *luật đúng, viết rõ, và không ai canh.*
+
+### Cách sai thứ ba — quên dòng mẫu trong template
+
+Template §4.5.6 có một dòng ví dụ, và **mọi tech-doc mới sinh ra đều mang nó**:
+
+```
+| `{uc}-{screen}-{element}-{type}` | {Nút submit} | {Component} | {submit} | {UC1 · SC1, UC1 · SC3} |
+```
+
+Không bỏ qua dòng này thì **mọi tech-doc vừa tạo đã đỏ ngay** vì "SC1 của UC1 không tồn tại". Một rule báo oan ở lần chạy đầu tiên sẽ bị tắt trong tuần đầu.
+
+## B2 · Cách làm đúng
+
+**Hai rule, cả hai là phép so khớp xác định:**
+
+```
+T15  mọi SC ở cột "Phục vụ SC" phải có thật trong .feature của nền đó     🔴 error
+T16  có §4.5 client mà header thiếu HẲN @trace.testid_attr                🔴 error
+     …có nhưng còn placeholder {…} (chưa chạy /map-testids)               ⚠️ warn
+```
+
+**T16 hai mức, không phải một** — chi tiết này quyết định rule sống hay chết. Sau bước `0-01`, 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.
+
+**Điều khoản quan trọng nhất — phạm vi neo vào sự tồn tại của hợp đồng:**
+
+| Tình trạng §4.5.6 | Có kiểm? | Vì sao |
+|---|:---:|---|
+| Không có bảng / bảng rỗng | **Không** | Chưa khai hợp đồng nào → không có lời khẳng định nào để sai |
+| Có row, khớp | Không báo | Đúng |
+| Có row, sai | **Có** | Đã hứa rồi mà không giữ |
+
+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"*. Thiếu điều khoản này thì mọi dự án đang chạy đỏ ngay ngày nâng version.
+
+**Ba quyết định nhỏ, mỗi cái có lý do:**
+
+1. **Pass riêng, chạy TRƯỚC khối thoát sớm.** `bin/lint-trace.js:881` thoát ngay khi không tìm thấy thư mục `.trace/`. Hai rule mới **không cần sổ trace** — chúng so tech-doc với `.feature`. Neo vào sổ là làm chúng câm ở repo chỉ có spec. Và câu thông báo đổi từ *"chưa có gì để kiểm"* thành *"bỏ qua T1–T14"*, vì sau thay đổi này câu cũ thành sai.
+
+2. **Không thêm cờ `--tech-docs`.** Kế hoạch đề xuất thêm. Không cần: `templates/project-context.yaml:100` khai `tech_docs_dir: "specs"` — trùng `specs_dir`. Cờ `--specs` sẵn có là đủ.
+
+3. **Biến thể định dạng → im lặng, không đoán.** 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**. Báo oan là cách nhanh nhất để một rule mới mất niềm tin.
+
+**Và nửa "máy canh chính nó":**
+
+Framework có sẵn khuôn — `bin/trace-schema.json:1754` khai `"lint_rule": "T12"`, và `bin/self-check.js:1089` kiểm rằng `lint-trace.js` **thực sự phát ra** rule đó, bằng regex `\b(?:err|warn)\('(T\d+)'`. Làm theo đúng khuôn: thêm khối `testid_contract` khai hai rule kèm `why`, và thêm **R8e** vào `self-check.js` canh chúng.
+
+Không có R8e thì khối schema chỉ là chữ.
+
+## B3 · Nếu làm sai thì hỏng theo kiểu nào
+
+Bước này có **hai** kiểu hỏng ngược nhau, và phải chặn cả hai:
+
+| Kiểu | Xảy ra khi | Hậu quả |
+|---|---|---|
+| **Ồn** 🟠 | Rule báo oan (dòng mẫu · tech-doc mới · biến thể định dạng) | CI đỏ vì chuyện bình thường → người ta thêm `--warn-only` → **mất cả hai rule** |
+| **Im lặng** 🔴 | Rule viết sai, không bao giờ khớp gì | Tưởng được canh mà không — tệ hơn không có rule, vì nó cho cảm giác an toàn |
+
+| | |
+|---|---|
+| Ai phát hiện | Kiểu **Ồn**: ngay, và phản ứng là tắt nó đi. Kiểu **Im lặng**: không ai |
+| Vì sao viết test cả hai chiều | Ca "phải đỏ" chặn kiểu Im lặng. Ca "phải im" chặn kiểu Ồn. Chỉ test một chiều là chỉ chặn một nửa |
+
+## B4 · Verify bằng gì
+
+**7 test tự động** trong `test/run.js`, và **ba ca quan trọng nhất là ca phải IM LẶNG**:
+
+| # | Phép thử | Kết quả |
+|---|---|---|
+| 1 | Hợp đồng khớp `.feature` | ✅ exit 0 |
+| 2 | Row trỏ `UC1 · SC99` (SC không tồn tại) | ✅ **T15**, exit 1 |
+| 3 | 🔴 Dòng mẫu còn placeholder | ✅ **im lặng** — doc mới tinh không được đỏ |
+| 4 | Header thiếu hẳn `@trace.testid_attr` | ✅ **T16** error |
+| 5 | Header còn placeholder | ✅ **T16 warn**, exit 0 — không chặn |
+| 6 | 🔴 Tech-doc backend-only (không có §4.5) | ✅ **im lặng hoàn toàn** |
+| 7 | 🔴 Repo chưa có tech-doc | ✅ in *"bỏ qua T15/T16"*, **không** im lặng báo sạch |
+
+**Và đã chứng minh cơ chế canh bắt được bản sai** — phá có chủ đích:
+
+```bash
+sed -i "s/err('T15'/err('TXX'/" bin/lint-trace.js
+node bin/self-check.js
+#  ❌ [R8] schema khai `testid_contract` rule `T15` mà bin/lint-trace.js KHÔNG phát ra
+#  exit: 1
+```
+
+R8e đỏ đúng. Nếu nó vẫn xanh thì ta chỉ vừa viết thêm chữ vào schema.
+
+## B5 · Bài học
+
+- **2026-09-11** — Kế hoạch viết **trước** khi đọc kỹ `bin/lint-trace.js`, nên sai ba chỗ: đề 3 rule (một cái không kiểm được bằng máy), đề thêm cờ không cần, và bỏ sót chuyện lệnh thoát sớm khi không có sổ trace. Cả ba chỉ lộ ra khi mở file ra đọc.
+  → **Bài học chuyển giao được:** với bước đầu tiên viết code thật (khác với sửa văn bản chỉ dẫn), **đọc file đích trước khi viết kế hoạch**, không phải sau. Ba chỗ sai ở đây đều là chỗ chỉ thấy được khi nhìn code.
+
+- **2026-09-11** — Bản nháp T15 gom cả dòng phân cách markdown `|---|---|` thành một id tên `---`, vì regex cho phép id bắt đầu bằng dấu gạch. **Lỗi này do test "ca sạch" bắt**, không phải do đọc lại code.
+  → **Bài học chuyển giao được:** test chiều *"phải đỏ"* chỉ chứng minh rule **có khả năng** bắt. Test chiều *"phải im lặng"* mới chứng minh nó **không bắt nhầm** — và với một rule mới, bắt nhầm là kiểu hỏng dễ xảy ra hơn.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | Nguyên tắc **phạm vi neo vào sự tồn tại của hợp đồng** — một rule mới chỉ kiểm nơi đã có lời khẳng định, để dự án cũ không đỏ hàng loạt. Cách khai rule trong schema rồi để một rule khác canh nó có thực sự tồn tại. Thiết kế test **hai chiều**, và ca "phá có chủ đích" để chứng minh cơ chế canh hoạt động. Nguyên tắc "không parse được → im lặng, không đoán" |
+| ⚠️ **Chỉ đúng ở đây** | Cấu trúc bảng §4.5.6, cách đọc cột theo vị trí, và chi tiết `tech_docs_dir` trùng `specs_dir` — đều gắn với bố cục tài liệu của framework này |
+
+## B7 · Link
+
+- Kế hoạch trước khi làm: [`../exec-d0-b4-may-canh-4-5-6.md`](../exec-d0-b4-may-canh-4-5-6.md) — §3 ghi lại cả ba chỗ đã sửa so với bản gốc
+- Tài liệu rule: `docs/04-reference/trace-schema.md` §Hợp đồng test-id
+- Bước liên quan: [`0-06`](0-06-hop-dong-truoc-code.md) (thêm `T17`/`T18` so bảng với **code**) · [`1-04`](1-04-self-review-dung-chung.md) (ranh giới: nơi nào có guard thì đừng thay bằng tự kiểm)

package/docs/plans/qc-surgery/buoc/0-05-don-nhan-cot-va-2b.md

@@ -0,0 +1,133 @@
+# Dọn nhãn cột và tên mục đã chết
+
+| | |
+|---|---|
+| **Đợt** | 0 — Hợp đồng test-id |
+| **Bước** | **5/6** của Đợt 0 |
+| **File sửa** | `commands/{map-testids,qc-design-test,qc-run-test}.tmpl` · `modules/qc-playwright/stack-profile.yaml` · `skills/spec/SKILL.tmpl` · `specs/domain-knowledge/figma-components/{react,flutter}.md` |
+| **File test** | Không có test tự động — xem B4 |
+| **Ngày xong** | 2026-09-11 · commit `931ffe2` |
+| **Phụ thuộc** | [`0-01`](0-01-testid-attr-co-cho-o.md) → [`0-04`](0-04-may-canh-hop-dong.md) |
+| **Ai dùng nó** | Mọi lệnh đọc/ghi bảng §4.5.6 |
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+
+## A1 · Vấn đề
+
+Trong công ty, cùng một cái cột trong cùng một bảng biểu đang được gọi bằng **hai cái tên**: bản hướng dẫn A gọi là *"Phục vụ"*, bản hướng dẫn B gọi là *"Serves"*. Người đọc bản B mở bảng ra, tìm cột *"Serves"*, không thấy, và kết luận **bảng này không có thông tin đó**.
+
+Tệ hơn: bốn chỗ trong tài liệu vẫn chỉ người ta tới **mục §2b** — một mục đã bị đánh số lại từ lâu và **không còn tồn tại**. Ai đi theo chỉ dẫn đó sẽ tìm mãi không ra, rồi tự xoay xở cách khác.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+> **Như đổi biển chỉ đường sau khi đổi tên phố.** Đổi tên phố mà quên gỡ biển cũ thì người
+> lạ vẫn đi theo biển cũ, tới nơi không thấy gì, rồi hỏi đường — và kết luận là bản đồ sai.
+
+Dọn hết biển cũ, và thống nhất **một** cách gọi tên cho mỗi thứ.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Không thấy gì mới — đây là dọn dẹp. Cái quan sát được: tìm chữ `§2b` hay `Serves SC` trong toàn bộ mã nguồn giờ ra **không kết quả nào**.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **§4.5.6 / §2b** — số hiệu mục trong tài liệu thiết kế kỹ thuật. Mục này từng mang số `2b`, sau đó được đánh lại thành `4.5.6`.
+
+---
+
+> ### ✅ Phép thử người đọc
+>
+> **Đã thử với:** tự soát · **ngày:** 2026-09-11 · **phải giải thích thêm chỗ nào:** chưa thử với người thật.
+
+---
+
+# PHẦN B — Chi tiết kỹ thuật
+
+## B1 · Cách hiển nhiên là gì, và vì sao nó sai
+
+### Cách sai thứ nhất — `sed` một phát trên toàn repo
+
+Lỗi đổi tên thì đổi tên. Một dòng lệnh, xong.
+
+Sai vì repo có **ba tầng file cho cùng một nội dung**: nguồn (`commands/*.tmpl`), bản đúc (`commands/*.md`, `core/`), và bản mirror dogfood (`.agent/`). `sed` trên tất cả thì sửa được cả ba — nhưng **lần `npm run build` sau sẽ đúc lại từ nguồn và ghi đè**. Nếu lỡ tay sửa bản đúc mà quên nguồn, thay đổi biến mất mà không ai biết vì sao.
+
+Phải sửa **file nguồn**, rồi build. Đây là lý do phép thử #1 ở B4 kiểm cả bản đúc — để chắc thay đổi đã đi qua đúng đường.
+
+### Cách sai thứ hai — bỏ qua `stack-profile.yaml` vì Đợt 2 sẽ thay nó
+
+File `modules/qc-playwright/stack-profile.yaml` sẽ bị **thay hẳn** ở Đợt 2 (Python → TypeScript). Sửa bây giờ là công cốc — kế hoạch cũng gợi ý cân nhắc bỏ qua.
+
+Sai vì ba lẽ: một dòng, chi phí gần bằng không; nó **sai ngay hôm nay** và Đợt 2 còn xa; và nếu Đợt 2 trượt lịch thì câu sai nằm lại vô thời hạn. Bỏ qua chỉ tiết kiệm được một lần `sed`.
+
+### Cách sai thứ ba — nghĩ cột 3 chỉ là "khác cách gọi"
+
+Hai chỗ mô tả cột thứ ba của bảng:
+
+```
+template:            | … | Component (§4.5.1.x)             | … |
+map-testids.tmpl:68: | … | Component (reused/existing/new)  | … |
+```
+
+Nhìn qua tưởng cùng một cột gọi hai kiểu. **Không phải** — chúng đòi hai thứ **khác nội dung**: một bên hỏi *component nào trong cây*, bên kia hỏi *id này từ đâu ra*.
+
+## B2 · Cách làm đúng
+
+**a) Nhãn cột 5 — chốt theo template**, vì `generate-tech-docs` include template để **sinh ra** bảng, nên template là bản gốc. Đổi 5 chỗ nguồn từ `"Serves SC"` sang `"Phục vụ SC"` — khớp **nguyên văn** thứ agent thật sự nhìn thấy trong bảng.
+
+**b) Cột 3 — bỏ phân loại `reused/existing/new` khỏi bảng.** Lý do không phải thẩm mỹ: phân loại đó **thay đổi theo thời gian** — một element `new` thành `existing` **ngay khi dev viết code**. Nhét dữ liệu biến thiên vào bảng hợp đồng là làm bảng sai dần mà không ai đi cập nhật lại. Phân loại vẫn giữ nguyên vai trò **nội bộ lúc chạy** ở Step 1–4 của `/map-testids` (nó rẽ nhánh theo đó).
+
+Cột 3 nhận `§4.5.1.x`, **hoặc tên component** khi §4.5.1 chưa vẽ — cần nhánh sau vì ca brownfield: `/map-testids` có thể tạo tech-doc tối thiểu chỉ có §4.5.6.
+
+**c) Ghi thẳng vào lệnh một điều trước đây không ai biết:**
+
+> *"Thứ tự cột là load-bearing: `lint-trace` **T15** đọc cột 'Phục vụ SC' theo **vị trí** (ô nội dung cuối cùng). Viết sai thứ tự là T15 đọc nhầm ô."*
+
+Sau bước `0-04` đây là hệ quả **thật**, không phải lý thuyết — và nó là lý do bước dọn dẹp này có sức nặng hơn lúc lập kế hoạch.
+
+**d) "§2b" → "§4.5.6"** ở 4 chỗ nguồn. Kế hoạch chỉ liệt kê 3; `flutter.md` bị bỏ sót hẳn, và `SKILL.md` thực ra phải sửa ở `SKILL.tmpl` vì `.md` là bản đúc.
+
+## B3 · Nếu làm sai thì hỏng theo kiểu nào
+
+**Kiểu hỏng: im lặng** 🔴
+
+| | |
+|---|---|
+| Hỏng ở đâu | Agent đọc "§2b" đi tìm một mục không tồn tại trong tech-doc |
+| Ai phát hiện | Không ai — agent **không báo lỗi**, nó kết luận *"tech-doc không có bảng test selector"* rồi đi dò DOM |
+| Sau bao lâu | Không bao giờ, nếu không ai đọc lại script sinh ra |
+| Vì sao đắt | Đây **đúng vòng lỗi mà [`0-03`](0-03-skill-thoi-day-do-dom.md) vừa chặn**, chỉ đi qua một cửa khác. Sửa skill xong mà để biển chỉ đường sai thì kết quả y hệt |
+
+Riêng nhãn cột lệch có thêm một tầng sau bước `0-04`: người viết bảng theo văn bản chỉ dẫn, mà hai văn bản đang mô tả hai bảng khác nhau → viết sai **thứ tự cột** → `T15` đọc nhầm ô.
+
+## B4 · Verify bằng gì
+
+| # | Phép thử | Kết quả |
+|---|---|---|
+| 1 | `grep -rn "§2b"` toàn repo, **kể cả bản đúc** (trừ `GAPS` lịch sử) | ✅ 0 |
+| 2 | `grep -rn "Serves SC" commands/ modules/ skills/ specs/` | ✅ 0 |
+| 3 | `grep -n "Mỗi row:" commands/map-testids.tmpl` | ✅ 5 cột khớp template, không còn `(reused/existing/new)` |
+| 4 | `build` · `self-check` · `test` · `lint-trace` | ✅ 212/212 |
+
+Phép thử 1 cố ý kiểm **cả bản đúc** — nếu bản đúc còn "§2b" trong khi nguồn đã sạch thì nghĩa là chưa build, hoặc đã sửa nhầm tầng.
+
+## B5 · Bài học
+
+- **2026-09-11** — Phát hiện ngoài dự kiến: `modules/qc-playwright/stack-profile.yaml:22` có **4 dấu `"`** trong một YAML scalar được bọc `"..."` — tức **sai cú pháp YAML**. Chưa vỡ vì **không có parser nào đọc file này** (`grep yaml bin/*.js` → 0; chỉ agent đọc). Dòng 49 cùng file thì escape đúng (`\"`), và các module khác sạch — nên đây là ca lẻ. Đã sửa luôn khi đụng vào (dùng nháy đơn bên trong).
+  → **Bài học chuyển giao được:** file cấu hình **không ai parse bằng máy** là chỗ lỗi cú pháp sống lâu nhất. Chúng chỉ nổ vào ngày có người thêm một parser — và khi đó lỗi trông như lỗi của parser mới.
+
+- **2026-09-11** — Kế hoạch liệt kê 3 chỗ có "§2b", thực tế **4** (thiếu `flutter.md`), và một chỗ ghi nhầm tầng (`SKILL.md` thay vì `SKILL.tmpl`).
+  → **Bài học chuyển giao được:** danh sách "các chỗ cần sửa" viết trong kế hoạch luôn phải **chạy lại grep lúc triển khai**, không dùng lại danh sách cũ. Kế hoạch viết ở một thời điểm; repo đổi sau đó.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | Nguyên tắc: khi cùng một thứ được gọi bằng hai tên, chọn **bản gốc là nơi sinh ra nó**, không phải nơi dùng nó. Nguyên tắc: **đừng nhét dữ liệu biến thiên vào bảng hợp đồng** — hợp đồng là thứ không ai đi cập nhật lại. Và: sửa file **nguồn** rồi build, đừng sửa bản đúc |
+| ⚠️ **Chỉ đúng ở đây** | Tên cột, số hiệu mục, và ba tầng file (nguồn/đúc/mirror) đều là đặc thù của framework này |
+
+## B7 · Link
+
+- Kế hoạch trước khi làm: [`../exec-d0-b5-don-nhan-lech.md`](../exec-d0-b5-don-nhan-lech.md) — phần "đưa `/map-testids` vào golden path" đã **chuyển sang** [`0-06`](0-06-hop-dong-truoc-code.md)
+- Bước liên quan: [`0-03`](0-03-skill-thoi-day-do-dom.md) (cùng vòng lỗi, cửa khác) · [`0-04`](0-04-may-canh-hop-dong.md) (làm thứ tự cột thành load-bearing)