@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/docs/plans/qc-surgery/buoc/1-06-gap-verify-du-bo.md

@@ -0,0 +1,162 @@
+# `gap-verify` đủ bộ — bổ vào bản gốc, KHÔNG fork
+
+| | |
+|---|---|
+| **Đợt** | 1 — Nền tảng |
+| **Bước** | **6/6** của Đợt 1 — đóng Đợt 1 |
+| **File sửa** | `steps/gap-verify.md` |
+| **File test** | Không có test tự động — xem B4 |
+| **Ngày xong** | 2026-09-11 · commit `8cfe9f3` |
+| **Phụ thuộc** | không có |
+| **Ai dùng nó** | `/qc-analyze` (gọi trực tiếp) **và** `steps/review-fanout.md` ← `/refine-prd` · `/review-context` — **3 lệnh** |
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+
+## A1 · Vấn đề
+
+Có một quy trình soát lại dùng chung: mỗi khi hệ thống phát hiện *"tài liệu thiếu chỗ này"*, quy trình đó bắt phát hiện ấy **tự chứng minh** trước khi được ghi nhận — mở lại tài liệu gốc đọc, đối chiếu, loại những cái bịa.
+
+Quy trình đó thiếu **hai phần** so với bản gốc nó được chép ra: một bước chuẩn bị rõ ràng ở đầu, và một bảng soát nhanh ở cuối.
+
+Trưởng phòng QC phát hiện đúng chỗ thiếu. Nhưng cách đề xuất bổ sung là **tạo một bản thứ hai** — và bản gốc đang được **ba** công đoạn khác nhau dùng chung.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+> **Như sửa quy trình trong sổ tay công ty.** Thấy thiếu một bước thì **thêm vào quyển sổ
+> chung**, chứ không photo ra một bản riêng cho phòng mình rồi sửa trên đó. Hai quyển sổ
+> **sẽ** khác nhau — không phải nếu, mà là khi — và lúc đó không ai biết quyển nào đúng.
+
+Bổ vào bản gốc thì hai phòng còn lại **cũng được nâng cấp**, miễn phí.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Quy trình soát lại giờ có một bước chuẩn bị rõ ràng ở đầu (mở đúng tài liệu nguồn ra trước, đếm xem có bao nhiêu việc phải soát) và một bảng tích ở cuối để dán ra dùng khi review.
+
+Và hai công đoạn khác — `/refine-prd`, `/review-context` — **tự động có hai phần đó**, không phải làm gì thêm.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **Fork** — tạo một bản sao riêng của một tài liệu rồi sửa trên bản sao đó.
+- **Finding / gap** — một phát hiện kiểu *"tài liệu chưa nói rõ chỗ này"*.
+
+---
+
+> ### ✅ 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 — fork, đúng như đề xuất
+
+Đề xuất tạo `skills/qc/qa-analyst/gap-verify.md` là bản mở rộng, rồi cho `/qc-analyze` trỏ sang bản mới. Nghe rất hợp lý: bản mở rộng có phần chuyên biệt cho QC (`DOC_GAP.md` · `active_platform` · `GAP-UC{N}-{nnn}`), nên để nó riêng cho sạch.
+
+Sai vì bản gốc được dùng ở **nhiều nơi hơn đề xuất tưởng**:
+
+```
+steps/gap-verify.md
+  ← commands/qc-analyze.tmpl          (gọi trực tiếp)
+  ← steps/review-fanout.md Phase 2.5
+       ← qc-analyze · refine-prd · review-context
+```
+
+Fork sẽ nâng cấp **một** lệnh và **bỏ rơi hai** lệnh kia trên bản cũ. Sáu tháng sau, ai sửa một phép thử ở bản A không biết bản B tồn tại, và `/qc-analyze` với `/refine-prd` áp **hai luật khác nhau cho cùng một việc** — thẩm định phát hiện — **im lặng**, vì `self-check` không so nội dung hai file với nhau.
+
+Đây chính là hình dạng lỗi mà cả kỷ luật `upstream_sha` + `bin/qc-base-map.json` của framework được dựng lên để chống. Fork ở đây là tự tạo lại vấn đề đó từ bên trong.
+
+### Cách sai thứ hai — copy nguyên phần chuyên biệt QC vào bản gốc
+
+Đã quyết không fork thì chép nội dung bản mở rộng vào bản gốc.
+
+Sai vì phần chuyên biệt viết cho QC: `DOC_GAP.md`, `active_platform`, định dạng `GAP-UC{N}-{nnn}`. Chép nguyên vào file dùng chung là bắt `/refine-prd` — vốn làm việc với findings YAML, không có `DOC_GAP.md` nào — đọc một quy trình nói về thứ nó không có.
+
+Bản gốc **đã có sẵn** mục §Tham số (`FINDINGS` · `EVIDENCE_ROOT` · `VERDICT_FIELD`) đúng để làm việc này. Viết theo tham số, không theo tên cụ thể.
+
+### Cách sai thứ ba — bảng soát nhanh chép lại nội dung phía trên
+
+Checklist thì phải đủ chi tiết để dùng một mình chứ.
+
+Sai vì checklist là **bản rút gọn của nội dung phía trên** — tức một dạng **bản sao**, đúng thứ bước này vừa từ chối ở cách sai thứ nhất. Ai sửa một phép thử ở trên mà quên checklist thì hai chỗ lệch.
+
+## B2 · Cách làm đúng
+
+**Bổ hai phần vào bản gốc**, viết theo tham số đã có:
+
+**① GIAI ĐOẠN 0 — Chuẩn bị**, ba việc theo thứ tự. Đây là **bước hành động**, không phải mô tả — §Tham số nói *có những gì*, mục này nói *phải làm gì với chúng trước khi thẩm định finding đầu tiên*:
+
+```
+1. Đọc FINDINGS, lấy danh sách cái đang mở
+2. Dựng DOCUMENT_LIST — MỞ FILE NGUỒN THẬT từ EVIDENCE_ROOT
+3. Chốt VERDICT_FIELD, và ĐẾM tổng số finding phải thẩm định
+```
+
+**Bước 2 là chỗ hay bị nhảy cóc nhất**, và có ghi chú riêng: agent đọc lướt danh sách finding rồi thẩm định **dựa trên trí nhớ** đọc spec từ lúc sinh finding, thay vì **mở lại** file thật. Hai việc khác nhau — verify phải là **một lượt đọc độc lập**, không phải một lượt nhớ lại. Đây là chỗ **thi hành** điều cấm ở §Nguyên tắc tối thượng (cấm dùng field evidence của finding làm bằng chứng cho chính nó).
+
+**Bước 3 có một việc đề xuất không có:** **đếm** tổng số finding và ghi con số đó lại. Nó là **mẫu số** để biết đã đi hết chưa — thay vì bỏ dở giữa đường mà không ai thấy. Checklist ở cuối có một dòng đối chiếu lại con số này.
+
+**② CHECKLIST NHANH**, với hai thứ chặn đúng rủi ro của chính nó:
+
+- Mỗi dòng **trỏ về mục gốc** trong ngoặc: `(T1–T6)` · `(AP1–AP6)` · `(Q1–Q3)` · `(GIAI ĐOẠN 0/2/3)`.
+- Một câu ở đầu bảng:
+
+> ⚠️ **Bảng này là MỤC LỤC, KHÔNG phải định nghĩa.** Định nghĩa đủ nằm ở các mục phía trên.
+> **Lệch nhau thì mục trên thắng.** Sửa một phép thử ở trên thì sửa dòng tương ứng ở đây —
+> đừng sửa ở đây rồi tưởng đã xong.
+
+**Và KHÔNG tạo `skills/qc/qa-analyst/gap-verify.md`.** Khi ốp Đợt 2 (copy skill từ thư mục đề xuất), phải **bỏ file đó khỏi danh sách copy** — dễ sót vì nó nằm lẫn trong `skills/qc/qa-analyst/`.
+
+## B3 · Nếu làm sai thì hỏng theo kiểu nào
+
+**Kiểu hỏng: im lặng** 🔴
+
+| | |
+|---|---|
+| Hỏng ở đâu | Hai bản của một cổng thẩm định 200+ dòng, một cho `/qc-analyze`, một cho `/refine-prd` |
+| Ai phát hiện | **Không ai** — `self-check` canh *file được tham chiếu có tồn tại không*, không canh *hai file có cùng nội dung không* |
+| Sau bao lâu | Lần đầu ai đó sửa một phép thử — có thể vài tháng |
+| Vì sao đắt | Khi đó câu hỏi *"framework thẩm định phát hiện theo luật nào?"* **không còn một câu trả lời**. Và hai lệnh sẽ cho hai kết quả khác nhau trên cùng một tập dữ liệu, mà không ai giải thích được vì sao |
+
+## B4 · Verify bằng gì
+
+| # | Phép thử | Kết quả |
+|---|---|---|
+| 1 | 🔴 Chỉ có **một** bản nguồn: `find . -name "gap-verify.md"` | ✅ `steps/` — hai bản còn lại là `.agent/` và `core/` do build sinh |
+| 2 | Hai phần mới có mặt: `grep -n "^## GIAI ĐOẠN 0\|^## CHECKLIST NHANH" steps/gap-verify.md` | ✅ |
+| 3 | Cả hai nơi tiêu thụ vẫn trỏ đúng | ✅ `qc-analyze.tmpl` + `review-fanout.md` |
+| 4 | `build` · `self-check` · `test` · `lint-trace` | ✅ 212/212 |
+| 5 | Ngân sách không đổi (`steps/` đọc lúc chạy) | ✅ 1208 KB |
+
+**Phép thử tay chưa chạy** — phải kiểm **cả hai** nơi tiêu thụ, vì đây là bước đụng file dùng chung:
+
+| # | Phép thử | Kết quả mong đợi |
+|---|---|---|
+| 6 | `/qc-analyze {TICKET-ID}` trên UC có gap | Chạy qua GIAI ĐOẠN 0 trước; phần T1–T6 không hồi quy |
+| **7** | 🔴 `/refine-prd {TICKET-ID}` | Cũng chạy được, **và nhận được GIAI ĐOẠN 0 mới** |
+
+Phép thử 7 là phép thử quyết định — **nếu fork thì `/refine-prd` sẽ không thay đổi gì**. Nó chứng minh phần lời của quyết định không-fork.
+
+## B5 · Bài học
+
+- **2026-09-11** — Kế hoạch nói *"2 lệnh tiêu thụ"*; thực tế **3** (`/review-context` cũng dùng qua `review-fanout`). Con số đó làm lập luận chống fork **mạnh hơn**, không yếu đi.
+  → **Bài học chuyển giao được:** trước khi quyết định fork hay bổ sung một file dùng chung, **grep hết consumer, gồm cả consumer gián tiếp qua một file trung gian**. Số lượng consumer thường lớn hơn trí nhớ, và nó là dữ kiện chính của quyết định.
+
+- **2026-09-11** — Checklist suýt tái tạo đúng vấn đề mà bước này từ chối: nó **là** một bản sao rút gọn. Chặn bằng hai thứ rẻ (trỏ về mục gốc + câu "mục trên thắng") thay vì bỏ hẳn checklist.
+  → **Bài học chuyển giao được:** khi một thứ **buộc phải** trùng lặp nội dung (mục lục · bảng tóm tắt · checklist), làm rõ **bản nào thắng khi lệch** ngay trong chính nó. Đó là chi phí rẻ nhất để giữ một bản sao hợp pháp không biến thành một nguồn sự thật thứ hai.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | Nguyên tắc **bổ vào bản gốc thay vì fork**, và cách kiểm trước khi quyết: grep hết consumer kể cả gián tiếp. Cách **tổng quát hoá bằng tham số** để một file dùng chung phục vụ nhiều consumer có dữ liệu khác nhau. Và cách xử lý bản-sao-hợp-pháp: trỏ về mục gốc + khai rõ bản nào thắng |
+| ⚠️ **Chỉ đúng ở đây** | Nội dung T1–T6, 5 anti-pattern, 3 câu hỏi lọc — gắn với việc thẩm định gap tài liệu của pipeline này |
+
+## B7 · Link
+
+- Kế hoạch trước khi làm: [`../exec-d1-b6-gap-verify-mo-rong.md`](../exec-d1-b6-gap-verify-mo-rong.md)
+- Bước liên quan: [`1-04`](1-04-self-review-dung-chung.md) (`gap-verify` sâu per-finding · self-review rộng per-run — bổ sung nhau, không thay nhau)

package/docs/plans/qc-surgery/buoc/README.md

@@ -0,0 +1,85 @@
+---
+title: Nhật ký từng bước — đợt đại phẫu phần QC
+updated: 2026-09-11
+format: theo D:\base\sdd-re-engine\docs\build-journal\_TEMPLATE-BUOC.md
+---
+
+# Nhật ký từng bước
+
+> **Đây là ghi chép về việc ĐÃ LÀM.** Kế hoạch nằm ở [`../02-lo-trinh.md`](../02-lo-trinh.md),
+> và bản thiết kế trước khi làm của từng bước nằm ở `../exec-d{N}-b{M}-*.md`. Bảy trong mười hai
+> bước **lệch kế hoạch** — file ở đây ghi cái đã xảy ra, file `exec-*` ghi cái đã định làm.
+> Đọc cả hai thì thấy vì sao đổi.
+
+Mỗi file có **hai phần cho hai người đọc khác nhau**:
+
+- **Phần A** — cho người không làm kỹ thuật (PO · QC · quản lý · dev mới). Đọc xong phần A là
+  **dừng được**.
+- **Phần B** — cho người sẽ sửa code. Phần B **không** phải bản chi tiết hoá của phần A; đó là
+  một bài viết khác.
+
+---
+
+## Đợt 0 — Hợp đồng test-id
+
+Bệnh nền: hợp đồng test-id giữa FE và QC **có** nhưng hỏng 4 chỗ, nên QC không dựa được và phải
+tự dò selector từ DOM. Script vì vậy giòn — dev đổi tên một class là test vỡ, và **không ai báo**.
+
+| # | Bước | Kiểu hỏng đã đóng |
+|---|---|---|
+| 1 | [Cho `@trace.testid_attr` một chỗ để ở](0-01-testid-attr-co-cho-o.md) | Im lặng 🔴 |
+| 2 | [Một nguồn duy nhất cho tên thuộc tính](0-02-mot-nguon-cho-testid-attr.md) | Im lặng 🔴 |
+| 3 | [Skill thôi dạy dò DOM trước](0-03-skill-thoi-day-do-dom.md) | Im lặng 🔴 |
+| 4 | [Máy canh bảng hợp đồng (T15/T16 + R8e)](0-04-may-canh-hop-dong.md) | Im lặng 🔴 |
+| 5 | [Dọn nhãn cột và tên mục đã chết](0-05-don-nhan-cot-va-2b.md) | Im lặng 🔴 |
+| 6 | [Chốt hợp đồng TRƯỚC code — mở luồng song song](0-06-hop-dong-truoc-code.md) | Im lặng 🔴 + Bỏ chạy 🟠 |
+
+## Đợt 1 — Nền tảng
+
+Bệnh nền: sáu trạm QC **không có phép kiểm cơ học nào**. Bỏ sót business rule · scenario chưa có
+test case · fail phân loại sai — cả ba đều xảy ra **im lặng**.
+
+| # | Bước | Kiểu hỏng đã đóng |
+|---|---|---|
+| 1 | [Guard BR-tag — đối chiếu tag BDD với BR sinh ra](1-01-guard-br-tag.md) | Im lặng 🔴 |
+| 2 | [Guard SC coverage — mọi scenario phải có test case](1-02-guard-sc-coverage.md) | Im lặng 🔴 |
+| 3 | [Fail 3 nhãn + chạy lại ×2 trước khi kết luận](1-03-fail-3-nhan.md) | Nói dối 🔴 |
+| 4 | [Bộ nguyên tắc tự kiểm + ranh giới với Guard](1-04-self-review-dung-chung.md) | Nói dối 🔴 |
+| 5 | [Spec là dữ liệu, không phải mệnh lệnh](1-05-spec-la-du-lieu.md) | Nói dối 🔴 |
+| 6 | [`gap-verify` đủ bộ — bổ vào bản gốc, không fork](1-06-gap-verify-du-bo.md) | Im lặng 🔴 |
+
+---
+
+## Một việc không phải "bước"
+
+**Nâng ngưỡng dung lượng lệnh 1200 → 1450 KB** (commit `bb53742`).
+
+Có một phép thử canh tổng dung lượng các file lệnh. Nó tồn tại để bắt **một** chuyện: có ai lén
+nhét một đoạn dùng chung to vào mọi lệnh (trước đây từng là ~2069 KB, đã gỡ xuống). Nó **không**
+canh "framework có thêm nội dung mới hay không" — đó là tăng trưởng chính đáng.
+
+Mốc: **1177 KB** trước đợt mổ → **1208 KB** sau Đợt 1. Bước `1-03` chạm **đúng 1200** — nếu chưa
+nâng trước thì nó đã đỏ ở giữa một bước nội dung, và người ta sẽ nâng trong lúc gấp, tức **nâng
+mà không ai đọc lý do**. Nên nâng trước một lần, và ghi lý do vào **chính file test** thay vì
+commit message — người đọc rule sáu tháng sau sẽ mở file test, không mở git log.
+
+1450 vẫn cách rất xa 2069, nên rule vẫn bắt được đúng lớp lỗi nó sinh ra để bắt.
+
+---
+
+## Bốn lệnh kiểm phải xanh sau mỗi bước
+
+```bash
+node bin/build.js       # đúc .tmpl → .md → core/
+node bin/self-check.js  # R1–R16 — canh framework tự mâu thuẫn
+node test/run.js        # 212 test, gồm ngưỡng dung lượng
+node bin/lint-trace.js  # T1–T18 trên dữ liệu thật
+```
+
+## Còn nợ gì — đọc trước khi tin 12 bước này đã xong
+
+| | Việc | Vì sao chưa làm |
+|---|---|---|
+| 🔴 | **Chưa ai chạy thử trên PRD thật** | Bốn lệnh trên chỉ canh **contract của framework**, không chạy `/qc-analyze` hay `/map-testids` lên một spec thật. Phép thử thật cần một dự án dùng thuộc tính **không** mặc định (`data-test`/`data-qa`) và một màn hình brownfield |
+| 🟠 | Ba câu chèn (prompt injection) chưa kiểm tay | Phải làm trên **sandbox** — không commit một PRD có câu chèn vào git |
+| 🟠 | **Phép thử người đọc chưa làm với người thật** | Mọi file ở đây ghi `tự soát`. Cần một người không làm kỹ thuật đọc Phần A rồi kể lại — xem mục "Phép thử người đọc" trong từng file |

package/docs/plans/qc-surgery/exec-d0-b1-testid-attr-header.md

@@ -0,0 +1,147 @@
+---
+buoc: Đợt 0 — Bước 1
+title: Thêm @trace.testid_attr vào header template tech-design
+phu_thuoc: không
+trang_thai: đã làm
+---
+
+# Đợt 0 · Bước 1 — Cho `@trace.testid_attr` một chỗ để ở
+
+← [`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-01-testid-attr-co-cho-o.md`](buoc/0-01-testid-attr-co-cho-o.md).
+
+## 1. Vì sao
+
+Kể bằng một chuyện có thể xảy ra tuần sau:
+
+Dự án FE dùng thuộc tính `data-test` (không phải `data-testid` — nhiều team chọn vậy). QC sinh
+script Playwright, dùng `page.getByTestId('login-submit-btn')`. Playwright mặc định tìm
+`data-testid`, nên nó **không tìm thấy gì cả**. Test đỏ với thông báo:
+
+```
+Error: locator.click: Timeout 30000ms exceeded.
+Call log: waiting for getByTestId('login-submit-btn')
+```
+
+Thông báo này **trông y hệt một bug sản phẩm** — "nút submit không hiển thị". QC mở bug, gán
+cho dev. Dev mở app, bấm thử, nút vẫn ở đó. Mất một ngày của hai người, và cuối cùng phát hiện
+chỉ là sai tên thuộc tính.
+
+Framework **đã lường trước** chuyện này: có một field tên `@trace.testid_attr` để ghi *tên
+thuộc tính* mà dự án dùng, và `/qc-run-test` đọc nó để cấu hình Playwright trước khi chạy. Cơ
+chế đúng.
+
+Nhưng field đó **không có chỗ nào trong template tech-design** — nên trong thực tế không ai
+điền, và mọi lần chạy đều rơi vào nhánh fallback.
+
+## 2. Tình trạng hiện tại
+
+**Field được khai đầy đủ trong schema** — `bin/trace-schema.json:471-485`:
+
+```json
+"name": "@trace.testid_attr",
+"artifact": "tech-design.md",
+"scope": "file",
+"written_by": ["map-testids"],
+"read_by": ["generate-code", "qc-run-test", "qc-design-test"]
+```
+
+**Nhưng template không có nó** — `templates/tech-design.template.md:35-48` liệt kê 12 field, và
+không có `testid_attr`:
+
+```
+---
+@trace.id: {TICKET-ID}
+@trace.domain: {domain}
+@trace.prd: {TICKET-ID}
+@trace.ucs: {TICKET-ID}-UC1, {TICKET-ID}-UC2{, …}
+@trace.service: {service — từ header BDD @trace.service}
+@trace.module: {module liên quan — vd dotnet, angular}
+@trace.platforms: {system | web | app | webview | …}
+@trace.bdd_versions: {MAP theo từng platform …}
+@trace.api_source: {existing | —}
+@trace.revision: 1
+@trace.status: draft
+@trace.generated_at: {YYYY-MM-DD}
+---
+```
+
+Kiểm lại bằng grep: `grep -rn "testid_attr" templates/ steps/ rules/` → **không kết quả**.
+
+**`/map-testids` chỉ ghi field này ở một nhánh** — `commands/map-testids.tmpl:58-64` (Step 5):
+
+- `:61` — *"Nếu tech-doc **tồn tại** → cập nhật **bảng** §4.5.6 của platform này"* → chỉ nói
+  bảng, **không nói header**.
+- `:62` — *"Nếu **chưa** tồn tại (pure brownfield) → ghi một file tối thiểu: header `@trace`
+  (gồm `@trace.testid_attr`) + §4.5.6"* → chỉ nhánh này ghi header.
+
+Đường đi thường của dự án là: `/generate-tech-docs` tạo tech-doc trước, rồi `/map-testids` chạy
+sau. Tức là **luôn** đi vào nhánh `:61` — nhánh không ghi header.
+
+Kết quả: `/qc-run-test` rơi vào nhánh *"Không tìm thấy field"* (`commands/qc-run-test.tmpl:53`),
+in cảnh báo mềm rồi đoán theo platform.
+
+## 3. Sẽ đổi thành gì
+
+**a) Thêm field vào template**, đặt ngay sau `@trace.platforms` (vì nó là thuộc tính của
+platform client):
+
+```
+@trace.platforms: {system | web | app | webview | … — tuỳ thư mục BDD nào tồn tại}
+@trace.testid_attr: {tên thuộc tính chứa test-id của stack client — web data-testid|data-test|data-qa · RN testID · Flutter Key/Semantics(identifier:) · iOS accessibilityIdentifier. Bỏ trống nếu doc chỉ phủ platform `system`.}
+```
+
+**b) Sửa `/map-testids` Step 5** để **cả hai nhánh** đều ghi/làm mới header, không chỉ nhánh
+brownfield. Câu ở `:61` đổi thành đại ý: *cập nhật bảng §4.5.6 của platform này, **và** đảm bảo
+header `@trace` có `@trace.testid_attr` với giá trị vừa phân giải ở Step 0 (`:29`) — thiếu thì
+thêm, lệch thì cảnh báo chứ không im lặng ghi đè.*
+
+Vì sao "lệch thì cảnh báo": nếu tech-doc đang ghi `data-testid` mà `/map-testids` phân giải ra
+`data-test`, thì một trong hai sai — có thể FE vừa đổi convention, có thể module khai sai. Ghi
+đè im lặng là làm mất tín hiệu.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `templates/tech-design.template.md` | Thêm 1 dòng `@trace.testid_attr` vào khối `@trace` (sau `:42`) |
+| `commands/map-testids.tmpl` | Step 5 (`:58-64`): nhánh "tech-doc tồn tại" cũng ghi/làm mới header |
+
+Không đụng `bin/trace-schema.json` — field đã khai đúng, không cần thêm gì.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+# 1. Field đã có trong template
+grep -n "testid_attr" templates/tech-design.template.md      # phải có 1 dòng
+
+# 2. Build + máy tự kiểm còn xanh
+node bin/build.js && node bin/self-check.js && node test/run.js
+```
+
+Kiểm bằng tay trên một PRD web thật:
+
+1. Chạy `/generate-tech-docs {TICKET-ID}` → mở tech-doc, header phải có dòng
+   `@trace.testid_attr:` (dù còn là placeholder).
+2. Chạy `/map-testids {UC-ID}` → header phải có **giá trị thật** (vd `data-testid`), không còn
+   placeholder.
+3. Chạy `/qc-run-test {UC-ID}` → report **không** được in cảnh báo
+   `⚠️ Tech-doc thiếu @trace.testid_attr`.
+
+Bước 3 là phép thử thật: nếu cảnh báo vẫn hiện, field vẫn chưa tới được nơi cần dùng.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Field vẫn tồn tại trên giấy, vẫn được 3 lệnh khai là đọc, và vẫn không ai điền. `/qc-run-test`
+mãi rơi vào nhánh fallback `:53` → đoán tên thuộc tính theo platform. Đúng với dự án dùng
+`data-testid` mặc định; **trượt 100% locator** với dự án dùng `data-test`/`data-qa`.
+
+Và nó hỏng theo kiểu tệ nhất — `commands/qc-run-test.tmpl:55` đã nói thẳng:
+
+> *"hỏng **im lặng theo kiểu tệ nhất**: test fail với 'element not found' — trông y hệt một bug
+> sản phẩm, nên QC sẽ đi mở bug thay vì sửa selector."*
+
+Ngoài ra Bước 4 (máy canh §4.5.6) có một check phụ thuộc field này, nên bỏ b1 thì b4 mất một
+phần ba giá trị.

package/docs/plans/qc-surgery/exec-d0-b2-thong-nhat-nguon-testid-attr.md

@@ -0,0 +1,152 @@
+---
+buoc: Đợt 0 — Bước 2
+title: Chốt một nguồn duy nhất cho @trace.testid_attr
+phu_thuoc: d0-b1
+trang_thai: đã làm
+---
+
+# Đợt 0 · Bước 2 — Hai nửa hợp đồng đang đọc hai file khác nhau
+
+← [`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-02-mot-nguon-cho-testid-attr.md`](buoc/0-02-mot-nguon-cho-testid-attr.md).
+
+> **Đây là lỗi nặng nhất của Đợt 0.** Bước 1 cho field một chỗ để ở; bước này đảm bảo hai bên
+> cùng đọc đúng chỗ đó.
+>
+> ⚠️ **Đừng nhầm hai thứ khi làm chung với [`exec-d0-b6`](exec-d0-b6-contract-truoc-code.md):**
+> bước này nói về **TÊN THUỘC TÍNH** (`@trace.testid_attr`, 1 giá trị ở header) — fallback theo
+> `active_module` **vẫn giữ**, kèm cảnh báo mềm. Còn b6 bỏ hẳn nhánh `/generate-code` tự sinh
+> **GIÁ TRỊ id** khi §4.5.6 rỗng. Một cái là tên thuộc tính, một cái là giá trị id — bỏ nhầm là
+> mất fallback đang cần.
+
+## 1. Vì sao
+
+`@trace.testid_attr` là **hợp đồng giữa hai bên**:
+
+```
+FE (/generate-code)  ──đọc field──→  gắn thuộc tính này lên element
+QC (/qc-run-test)    ──đọc field──→  cấu hình Playwright tìm thuộc tính này
+```
+
+Hợp đồng chỉ có nghĩa khi **cả hai đọc cùng một bản**. Hiện tại FE đọc bản ở file A, QC đọc bản
+ở file B. Nếu hai bản khác nhau — hoặc một bản không tồn tại — thì FE gắn một kiểu, QC tìm một
+kiểu, và không có gì báo.
+
+Chuyện cụ thể: dự án khai `@trace.testid_attr: data-test` trong tech-doc. QC đọc được, cấu hình
+đúng, tìm `data-test`. Còn `/generate-code` không đọc file đó — nó chỉ đọc header `.feature`,
+không thấy gì, nên rơi về mặc định theo module là `data-testid`. FE gắn `data-testid`, QC tìm
+`data-test`. **Không trùng một element nào.**
+
+## 2. Tình trạng hiện tại
+
+**Nửa QC — đọc từ `tech-design.md`** (`commands/qc-run-test.tmpl:45-46`):
+
+> *"**TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.** Đọc
+> `@trace.testid_attr` từ **header tech-doc gộp** (do `/map-testids` ghi — nó đã phân giải một
+> lần cho cả feature). Đây là **nửa QC của contract FE↔QC**: `/generate-code` đọc chính field
+> này để emit thuộc tính lên element."*
+
+**Schema cũng nói `tech-design.md`** (`bin/trace-schema.json:473`):
+
+```json
+"artifact": "tech-design.md",
+"scope": "file",
+"written_by": ["map-testids"]
+```
+
+**Nửa FE — đọc từ `.feature`** (`commands/generate-code.tmpl:505`):
+
+> *"2. **Emit qua attribute platform** — chọn attribute theo **`active_module`** (bảng dưới,
+> mặc định). Chỉ override khi header `.feature` khai tường minh `@trace.testid_attr={attr}`
+> (hiếm; dùng cho stack lai)."*
+
+Ba điểm lệch trong một câu:
+
+| | Nửa QC + schema | Nửa FE |
+|---|---|---|
+| Field nằm ở đâu | `tech-design.md` | header `.feature` |
+| Vai trò của field | **nguồn chính** — "KHÔNG tự suy từ platform" | **override hiếm** cho stack lai |
+| Nguồn mặc định | không có; thiếu field thì cảnh báo rồi mới fallback | `active_module` |
+
+Và điều trớ trêu: `qc-run-test.tmpl:55` có sẵn một đoạn giải thích **vì sao không được suy từ
+platform**:
+
+> *"suy từ platform là **phát biểu lại một sự thật đã được ghi ở nơi khác** — đúng lớp lỗi mà
+> `bin/trace-schema.json` sinh ra để chống."*
+
+Đó chính xác là điều `/generate-code` đang làm ở nửa bên kia.
+
+## 3. Sẽ đổi thành gì
+
+**Chốt một nguồn: header `tech-design.md`.** Ba lý do:
+
+1. Khớp `bin/trace-schema.json:473` (`artifact: tech-design.md`) — không phải sửa schema.
+2. Khớp `/map-testids`, lệnh **duy nhất** được khai là `written_by` của field.
+3. Đúng cấp phạm vi: thuộc tính test-id là **một** giá trị cho cả PRD/platform, không phải mỗi
+   UC một giá trị. `.feature` là cấp UC → đặt field ở đó là mời gọi 5 UC khai 5 giá trị khác
+   nhau cho cùng một FE.
+
+**Sửa `commands/generate-code.tmpl:505`** thành thứ tự ưu tiên rõ ràng:
+
+```
+1. Header tech-doc gộp {TICKET-ID}-tech-design.md → @trace.testid_attr    ← NGUỒN CHÍNH
+2. Không có field  → cảnh báo mềm + fallback theo active_module
+```
+
+Khuôn cảnh báo dùng lại đúng cái đã có ở `qc-run-test.tmpl:53`, để hai bên nói cùng một giọng:
+
+```
+⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo module ({attr mặc định}).
+   Nếu FE dùng thuộc tính khác thì MỌI locator của QC sẽ trượt.
+   Chạy /map-testids {UC-ID} để ghi field này.
+```
+
+**Bỏ hẳn đường đọc từ header `.feature`?** Không — nhưng hạ nó xuống dưới cùng và ghi rõ nó là
+lối cũ (vd một PRD trải hai platform với hai attribute khác nhau, `.feature` của từng platform
+có thể khai riêng). Điều kiện: nếu **cả hai** nơi đều có mà **lệch nhau** → cảnh báo, ưu tiên
+tech-doc, **không im lặng chọn một bên**.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `commands/generate-code.tmpl` | Mục §Test Selectors ý 2 (`:505`) — đổi thứ tự nguồn; thêm khối cảnh báo mềm |
+| `commands/qc-run-test.tmpl` | Không đổi logic. Chỉ sửa câu ở `:46` nếu cần cho khớp câu chữ mới của `generate-code` |
+| `docs/explain/09-generate-code.md` | Cập nhật ma trận phase (`:67` — dòng `Test Selectors (emit test-id)`) nếu nó mô tả nguồn cũ |
+
+Không đụng `bin/trace-schema.json`.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+# 1. generate-code không còn coi .feature là nguồn chính
+grep -n "testid_attr" commands/generate-code.tmpl
+#    → phải thấy "tech-design" đứng trước ".feature"
+
+# 2. Build + máy tự kiểm
+node bin/build.js && node bin/self-check.js && node test/run.js
+```
+
+Kiểm bằng tay — **phép thử quyết định** của bước này. Trên một dự án dùng thuộc tính **không**
+mặc định:
+
+1. Đặt `@trace.testid_attr: data-test` vào header tech-doc.
+2. Chạy `/generate-code {UC-ID} --phase=ui` → mở code FE vừa sinh, element phải mang
+   `data-test="..."`, **không** phải `data-testid="..."`.
+3. Chạy `/qc-run-test {UC-ID}` → script phải cấu hình `testIdAttribute: 'data-test'` và locator
+   phải khớp.
+
+Nếu bước 2 vẫn ra `data-testid`, tức `/generate-code` chưa đọc đúng nguồn.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Hợp đồng FE↔QC vẫn là hai bản độc lập. Dự án nào dùng `data-testid` mặc định thì **may mà
+trùng**, nên lỗi này ẩn — nó chỉ nổ ở dự án dùng `data-test`/`data-qa`, và nổ dưới dạng "test
+đỏ hàng loạt không rõ lý do".
+
+Nặng hơn: Bước 1 (thêm field vào template) sẽ **tạo cảm giác an toàn sai**. Field có mặt, có
+giá trị, ai đọc tech-doc cũng thấy — nhưng `/generate-code` vẫn không dùng nó. Tức là làm b1 mà
+bỏ b2 thì tệ hơn không làm gì: trước đây không ai tưởng field có tác dụng, sau b1 thì mọi người
+tưởng có.