@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/docs/plans/qc-surgery/exec-d0-b6-contract-truoc-code.md

@@ -0,0 +1,350 @@
+---
+buoc: Đợt 0 — Bước 6
+title: Chốt contract test-id TRƯỚC code — mở luồng FE ∥ QC song song
+phu_thuoc: d0-b1, d0-b2, d0-b4
+trang_thai: đã làm
+canh_bao: đụng cả nhánh dev, không chỉ nhánh QC
+---
+
+# Đợt 0 · Bước 6 — Hợp đồng đi trước, hai bên tiêu thụ song song
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md) ·
+Mạch hỏi–đáp dẫn tới bước này: [`00-nhat-ky.md` §3](00-nhat-ky.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-06-hop-dong-truoc-code.md`](buoc/0-06-hop-dong-truoc-code.md).
+
+> Bước lớn nhất của Đợt 0, và là bước duy nhất **đụng cả nhánh dev** (`/generate-tech-docs`,
+> `/generate-code`, `/review-tech-docs`, `/validate-traces`), không chỉ nhánh QC.
+
+## 1. Vì sao
+
+### 1.1 FE và QC đang phải xếp hàng, mà lẽ ra không cần
+
+Hôm nay QC phải **chờ code xong** mới dựng được locator, vì hợp đồng test-id chỉ trở nên đáng
+tin sau khi `/map-testids` đối chiếu với code thật. Nhưng nguyên liệu để **đặt tên** test-id thì
+có từ trước code — `commands/map-testids.tmpl:33` nói rõ nguồn của nó:
+
+> *"Từ các step `When` trong `.feature` FE của UC **+ các màn Design Spec**, liệt kê mọi element
+> **có action** mà scenario chạm tới (button, input, link, select, toggle, form-submit)."*
+
+Cả hai nguồn đều nằm ở phase Tech Design, trước code. Nên việc xếp hàng là **do vị trí lệnh**,
+không do thiếu thông tin.
+
+### 1.2 Framework đã khai đúng vị trí — chỉ một tài liệu nói ngược
+
+| Nơi | Đặt `/map-testids` ở đâu |
+|---|---|
+| `steps/report-footer.md:63-64` | Phase **Tech Design** (`/generate-tech-docs · /map-testids · /review-tech-docs`), **trước** phase Code |
+| `GAPS-v4.md:724` | trước `/generate-code --phase=ui` |
+| `docs/explain/11-map-testids.md:1,17,69` | **sau** `/generate-code` + `/review-code` ← lệch |
+
+Và chính file lệch đó tự thừa nhận (`:60`):
+
+> *"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ờ."*
+
+Bước này **không phát minh kiến trúc mới** — nó chốt mâu thuẫn có sẵn theo hướng đúng, và làm
+cho hướng đó thực sự hoạt động.
+
+### 1.3 Ba việc đang bị gộp trong một lệnh
+
+| | Việc | Cần code chưa? |
+|---|---|---|
+| 1 | Chốt contract từ design-spec + BDD | **Không** |
+| 2 | FE gắn attribute theo contract (`/generate-code`) | — |
+| 3 | Đối chiếu contract với code thật, patch chỗ thiếu | **Có** |
+
+`/map-testids` hiện làm **1 + 3** trộn lẫn, và chính việc 3 kéo cả lệnh xuống sau code. Tách 1
+khỏi 3 là đủ.
+
+## 2. Tình trạng hiện tại
+
+**Hai lệnh cùng ghi §4.5.6:**
+
+- `commands/generate-tech-docs.tmpl:79` — *"thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào
+  §4.5.6 dùng chung của nhóm platform đó"*
+- `commands/map-testids.tmpl:58-64` — Step 5 ghi/làm mới bảng
+
+Luật chống giẫm chân là **một câu văn xuôi** (`map-testids.tmpl:62`): *"`/generate-tech-docs` …
+không được ghi đè các id §4.5.6 mà lệnh này đã ghi"* — luật đúng, không ai canh.
+
+**`/generate-code` có nhánh tự sinh id** — `commands/generate-code.tmpl:504`:
+
+> *"Nếu chưa có (vd `--phase=ui` trước khi §4.5 được vẽ), **sinh id theo quy ước**
+> `{uc-lower}-{screen}-{element}-{type}` … chúng sẽ được đối chiếu với §4.5.6 của tech-design
+> lúc integration."*
+
+Nhánh này là chỗ contract **bị code quyết định ngược trở lại**.
+
+**`/review-tech-docs` không kiểm §4.5.6** — đã grep: `grep -n "Selector|testid|4.5.6"
+commands/review-tech-docs.tmpl` → 0 kết quả. Nên một tech-doc có §4.5 mà bảng rỗng vẫn được
+`APPROVED`.
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 Phân vai — một người ghi, bốn người đọc, một người canh
+
+| Lệnh | Với §4.5.6 |
+|---|---|
+| `/generate-tech-docs` | Tạo **khung rỗng** + header `@trace.testid_attr`. **Không ghi row nào** |
+| `/map-testids` | **Người duy nhất ghi row.** Nguồn: design-spec + BDD |
+| `/generate-code` | Chỉ **đọc**. **Bỏ hẳn** nhánh tự sinh id (`:504`) — §4.5.6 rỗng giờ là lỗi quy trình |
+| `/qc-design-test`, `/qc-design-script` | Chỉ **đọc** |
+| `/validate-traces` | **Đối chiếu** contract vs code, bật cờ. Không ghi |
+
+Phân vai này chỉ sạch được **nhờ** thứ tự mới ở §3.2 — nếu `/map-testids` vẫn chạy sau
+`/generate-code` thì khung rỗng sẽ khiến `/generate-code` bịa id.
+
+### 3.2 Thứ tự mới + chuỗi Next rẽ nhánh
+
+```
+/generate-design-spec ─┐
+                       ├→ /generate-tech-docs   (§4.5 + §4.5.6 khung rỗng)
+/generate-bdd ─────────┘         ↓ Next
+                        /map-testids            (CHỐT contract — không đụng code)
+                                 ↓ Next
+                        /review-tech-docs       (duyệt CẢ contract)
+                                 ↓ chỉ khi APPROVED
+              ┌──────────────────┴──────────────────┐
+        /generate-code                        /qc-design-test
+        (FE gắn attr từ contract)             /qc-design-script
+              ↓                                     ↓
+        /review-code                          /qc-review-script
+              └──────────────────┬──────────────────┘
+                                 ↓
+                        /qc-run-script   ← chỗ ĐẦU TIÊN cần code chạy thật
+                                 ↓
+                        /validate-traces ← đối chiếu contract vs code (việc 3)
+```
+
+Hai nhánh không đụng nhau vì chúng đọc **cùng một contract đã đóng băng**, không đọc output của
+nhau.
+
+Đây cũng là chỗ việc tách `/qc-run-test` ở Đợt 2 trả lãi: `/qc-design-script` (viết script) tách
+khỏi `/qc-run-script` (chạy script) → viết script không cần code chạy. **Trước Đợt 2 thì nhánh
+QC chỉ song song được tới `/qc-design-test`**; sau Đợt 2 mới song song trọn vẹn.
+
+### 3.3 Hai chế độ của `/map-testids`
+
+Tên lệnh **giữ nguyên** — "lập bản đồ test-id" vẫn đúng nghĩa cho cả hai vai.
+
+```
+/map-testids {UC-ID}              ← mặc định: chốt contract từ design-spec + BDD.
+                                    KHÔNG đọc code, KHÔNG patch code.
+                                    Actor: người viết tech-doc.
+
+/map-testids {UC-ID} --from-code  ← thu hoạch contract từ code đã có (brownfield).
+                                    Đọc + patch code như hiện nay.
+                                    Actor: Dev.  Chạy MỘT LẦN cho mỗi UC cũ.
+```
+
+Chế độ `--from-code` **không phải viết mới** — nó chính là nhánh `existing`/`reused` đang có
+(`map-testids.tmpl:40`, `:46-52`), chỉ tách ra thành cờ tường minh thay vì để lệnh tự đoán theo
+sự tồn tại của code.
+
+Ở chế độ mặc định, mọi element đều là `new` → Step 3 (patch catalog) và Step 4 (patch usage
+site) **bị bỏ qua**, chỉ chạy Step 1, 2, 5.
+
+### 3.4 Nhắc việc = điều kiện hoàn chỉnh của tài liệu, không phải thông báo
+
+Không dựng cơ chế nhắc. Thay vào đó `/review-tech-docs` **không cho `APPROVED`** khi:
+
+```
+có block §4.5 cho platform client   VÀ   §4.5.6 của block đó rỗng
+   → NEEDS_FIX, báo: "Tech-doc có phần UI nhưng chưa khai Test Selectors.
+                      Chạy /map-testids {UC-ID} rồi review lại."
+```
+
+Ba lý do cách này đúng hơn một cơ chế nhắc:
+
+1. **Không cần actor mới, không thời điểm mới** — `/review-tech-docs` vốn đã chặn:
+   `steps/report-footer.md:100` (*"`/generate-code` nếu APPROVED; sửa doc nếu NEEDS_FIX"*).
+2. **Đúng về bản chất** — tech-doc có phần UI mà không khai test selector thì **chưa viết xong**,
+   giống như có §4 API mà không khai endpoint.
+3. **Chuỗi Next tự dẫn** — xong `/generate-tech-docs` thì report báo chạy `/map-testids` tiếp.
+   Không ai phải nhớ.
+
+### 3.5 Hai cờ audit — đối chiếu contract vs code, KHÔNG chặn PR
+
+| Cờ | Bật khi | Nghĩa |
+|---|---|---|
+| `TESTID_UNIMPLEMENTED` | §4.5.6 có row · code FE của UC đó đã tồn tại · **không tìm thấy id đó trong code** | FE chưa gắn hoặc gắn sai → QC sẽ trượt locator |
+| `TESTID_UNDECLARED` | Code có element mang test-id **không có** trong §4.5.6 | Ai đó gắn ngoài contract → contract không còn đủ |
+
+**Cả hai vào `audit_flags`, KHÔNG vào `gate.blocking`.** Bằng chứng cho thấy an toàn:
+
+```
+audit_flags   = 17 cờ   ← báo cáo
+gate.blocking =  4 cờ   ← chặn PR: orphaned · trace_orphan · seam_unwired · stub_unresolved
+```
+
+13/17 cờ hiện tại **không chặn gì**, kể cả `TECHDOC_DRIFT`, `BDD_DRIFT`. Và `bin/self-check.js`
+rule **R9** báo ERROR nếu *"cờ 🟠 lọt vào `gate.blocking`"* — nên nếu sau này ai lỡ tay đưa cờ
+test-id vào nhóm chặn thì build đỏ, chứ không âm thầm chặn PR cả team.
+
+**Phạm vi kiểm neo vào sự tồn tại của contract:**
+
+| Tình trạng §4.5.6 | Cờ bật? | Vì sao |
+|---|:---:|---|
+| Không có bảng / bảng rỗng | **Không** | Chưa khai contract nào → không có lời khẳng định nào để sai |
+| Có row, code khớp | Không | Đúng |
+| Có row, code thiếu id | Có (🟠) | Đã khai rồi mà code không làm |
+
+Nên dự án đã gen code **trước** đợt điều chỉnh này sẽ **im lặng hoàn toàn** — chúng chưa từng
+chạy `/map-testids` nên §4.5.6 rỗng. Cờ 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"*.
+
+### 3.6 `/map-testids` thành invalidator của `qc_status`
+
+Khi contract đổi một id, mọi script QC bám id cũ **hết hiệu lực**. Framework đã có luật cho đúng
+chuyện này — `rules/workflow.md:57-64`:
+
+> *"lệnh nào làm giá trị đó **HẾT ĐÚNG** (spec đổi, code đổi) thì **BẮT BUỘC** hạ nó về giá trị
+> 'chưa biết' (`not_run` / `—`). Giữ một `pass` đã hết hiệu lực là **báo cáo sai**, không phải
+> tôn trọng quyền sở hữu."*
+
+Và đã có tiền lệ thi hành — `bin/trace-schema.json` cột `qc_status`:
+
+```json
+"$comment": "Chủ (ghi pass/fail/skip): qc-run-test — DUY NHẤT.
+             Invalidator (chỉ hạ về not_run khi spec/code vừa đổi): generate-bdd · generate-code."
+"written_by": ["qc-run-test", "generate-bdd", "generate-code"]
+```
+
+Thêm `map-testids` vào danh sách đó, vai **invalidator**. Chuỗi chạy được nhờ cột "Phục vụ SC"
+làm chỉ mục ngược:
+
+```
+đổi id  ft101-login-submit-btn → ft101-auth-submit-btn
+   ├─ đọc cột "Phục vụ SC" của row đó  →  UC1·SC1, UC1·SC3, UC2·SC2
+   ├─ hạ qc_status 3 SC đó → not_run        (qc_run_at → —)
+   │    KHÔNG hạ qc_owner/qc_blocked_by — rules/workflow.md:65-67 miễn trừ tường minh
+   │    (spec đổi không làm con bug biến mất)
+   └─ in cảnh báo: "3 scenario có script bám id cũ — chạy /qc-design-script {UC-ID} lại"
+```
+
+QC thấy ở đâu: sổ trace và dashboard hiện 3 SC đó `not_run` thay vì `pass` — **đã là** cách QC
+biết "phải chạy lại" với mọi thay đổi spec khác, không phải học cơ chế mới.
+
+Lý lẽ tại sao phải hạ chứ không giữ, `rules/workflow.md:83-84` nói thẳng:
+
+> *"`pass` **không** mang nghĩa 'test đã chạy xanh' — nó mang nghĩa 'scenario này đã được nghiệm
+> thu theo spec **hiện tại**'."*
+
+### 3.7 Khi contract lệch code — ai đúng
+
+`--from-code` phát hiện lệch, agent **đề xuất**, **người xác nhận** (cùng hình dạng với cổng
+phân loại Fail):
+
+| Ca | Ai đúng | Xử lý |
+|---|---|---|
+| Contract đúng, code gắn sai/thiếu | **Contract** (mặc định) | Patch code — Step 4 đã làm sẵn, chế độ EXTEND |
+| Element thật đã đổi (gộp 2 thành 1, tách 1 thành 2, bỏ hẳn) | **Code** | Cập nhật row §4.5.6 → kéo theo §3.6 |
+
+Mặc định contract thắng vì sửa một attribute là thao tác cơ học, an toàn, đảo ngược được; còn
+sửa contract là đổi một tài liệu đã review.
+
+### 3.8 Bốn đánh đổi phải nói ra
+
+1. **Id đoán từ thiết kế không sống sót 100%** — dev có thể gộp/tách element lúc implement. →
+   cờ ở §3.5 là **bắt buộc**, không tuỳ chọn. Contract không có máy đối chiếu sẽ mục trong một
+   sprint.
+2. **QC gen được script nhưng script chưa chạy được** — đúng thiết kế. Phải ghi vào tài liệu để
+   không ai kỳ vọng test xanh trước khi FE xong.
+3. **Dự án không có design-spec** (chưa có Figma node link) → contract chỉ rút từ step `When` của
+   BDD, phủ ít hơn. Cần luật fallback: `/map-testids` phải **ghi rõ** contract là "đầy đủ" hay
+   "một phần (thiếu design-spec)", để `/qc-design-script` biết mà cảnh báo.
+4. **Brownfield** → phải chạy `--from-code` một lần trước khi đi tiếp theo chiều xuôi.
+
+### 3.9 Tên id nhúng UC — chấp nhận có ý thức
+
+Quy ước `{uc-lower}-{screen}-{element}-{type}` cho ra `ft101-login-submit-btn`, trong khi cột
+"Phục vụ SC" cho phép id đó phục vụ `UC1·SC1, UC2·SC2`. Tên nói "của UC1" mà phục vụ nhiều UC.
+
+**Không đổi quy ước** — đổi là đổi mọi id đã gắn trong code, đắt hơn giá trị thu được. Thay vào
+đó ghi một câu vào `templates/tech-design.template.md` §4.5.6: *tiền tố UC là UC **đầu tiên**
+giới thiệu element này; nó không có nghĩa element chỉ thuộc UC đó — xem cột "Phục vụ SC" để
+biết phạm vi thật.*
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `commands/generate-tech-docs.tmpl` | `:79`, `:225` — thôi ghi row §4.5.6, chỉ tạo khung bảng + header |
+| `commands/map-testids.tmpl` | Đảo trọng tâm sang nguồn design-spec + BDD; thêm cờ `--from-code`; Step 3/4 chỉ chạy ở chế độ đó; thêm phần invalidate `qc_status` (§3.6) |
+| `commands/generate-code.tmpl` | `:504` — **bỏ** nhánh tự sinh id; §4.5.6 rỗng → DỪNG, báo chạy `/map-testids` |
+| `commands/review-tech-docs.tmpl` | Thêm kiểm: có §4.5 client mà §4.5.6 rỗng → `NEEDS_FIX` |
+| `commands/validate-traces.tmpl` | 2 cờ mới + counter ở **cả** Step 7 **lẫn** khối `summary` — rule **R7** canh đủ hai tầng |
+| `bin/trace-schema.json` | `audit_flags` +2 · **không** đụng `gate.blocking` · thêm `map-testids` vào `written_by` của `qc_status` + `qc_run_at`, sửa `$comment` theo khuôn `generate-bdd`/`generate-code` |
+| `templates/tech-design.template.md` | Ghi chú §3.9 vào §4.5.6 |
+| `templates/ci/trace-gate.yml` | Rule **R10** canh file này theo kịp danh sách cờ |
+| `steps/report-footer.md` | `:63` phase · `:99-101` chuỗi Next rẽ hai nhánh song song (§3.2) |
+| `docs/explain/11-map-testids.md` | `:1`, `:17`, `:24`, `:60`, `:63`, `:69` — sửa vị trí pipeline, gỡ câu "vị trí hơi mờ" và "không bắt buộc", đổi mô tả Input |
+| `docs/04-reference/commands.md` | `:77` — actor không còn chỉ là Dev; ghi hai chế độ |
+
+⚠️ **Quan hệ với `exec-d0-b5`:** việc "đưa `/map-testids` vào golden path" ở b5 được **thay thế
+hoàn toàn** bởi §3.2 + §3.4 của bước này. Làm b6 thì bỏ phần đó khỏi b5, tránh sửa
+`steps/report-footer.md` hai lần theo hai hướng.
+
+⚠️ **Quan hệ với `exec-d0-b2`:** b2 giữ `active_module` làm fallback kèm cảnh báo mềm. Bước này
+**bỏ hẳn** nhánh tự sinh **id**, nhưng fallback cho **tên thuộc tính** (`active_module`) thì
+giữ — hai thứ khác nhau, đừng bỏ nhầm.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+node bin/build.js && node bin/self-check.js && node test/run.js && node bin/lint-trace.js
+
+# generate-tech-docs không còn ghi row
+grep -n "row vào §4.5.6\|row vào 4.5.6" commands/generate-tech-docs.tmpl   # → 0
+
+# generate-code không còn tự sinh id
+grep -n "sinh id theo quy ước" commands/generate-code.tmpl                  # → 0
+
+# cờ mới KHÔNG nằm trong gate.blocking
+node -e "const s=require('./bin/trace-schema.json');
+console.log(JSON.stringify(s.gate.blocking.map(g=>g.counter)))"
+# → không có testid_* nào
+```
+
+Kiểm bằng tay — **ca 3 và 5 là phép thử quyết định**:
+
+| Ca | Dựng thế nào | Kỳ vọng |
+|---|---|---|
+| 1 | `/generate-tech-docs` trên PRD có platform web | §4.5.6 có **khung bảng** nhưng **0 row**; header có `@trace.testid_attr` |
+| 2 | `/review-tech-docs` ngay sau đó | **NEEDS_FIX** — báo chưa khai Test Selectors |
+| 3 | `/map-testids {UC-ID}` (mặc định), **chưa có code FE** | Điền row từ design-spec + BDD; **không** đụng file code nào; `/review-tech-docs` giờ `APPROVED` |
+| 4 | `/generate-code {UC-ID} --phase=ui` | Element mang đúng id trong §4.5.6, không bịa id mới |
+| **5** | Song song: `/qc-design-test` + `/qc-design-script` **trước khi** `/generate-code` chạy | Chạy được, script bám id từ §4.5.6 *(cần Đợt 2 mới có `/qc-design-script`; trước đó kiểm tới `/qc-design-test`)* |
+| 6 | `/generate-code` khi §4.5.6 rỗng | **DỪNG**, báo chạy `/map-testids` trước |
+| 7 | Sửa tay một id trong §4.5.6, chạy `/map-testids` | `qc_status` của mọi SC ở cột "Phục vụ SC" hạ về `not_run`; `qc_owner`/`qc_blocked_by` **giữ nguyên** |
+| 8 | Xoá id đó khỏi code FE, chạy `/validate-traces` | Cờ `TESTID_UNIMPLEMENTED` bật, **PR không bị chặn** |
+| 9 | Repo cũ chưa từng chạy `/map-testids` → `/validate-traces` | **0 cờ test-id** (§4.5.6 rỗng → không kiểm) |
+| 10 | `/map-testids {UC-ID} --from-code` trên màn brownfield | Thu hoạch id từ code vào §4.5.6; lệch thì **hỏi người**, không tự chọn bên |
+
+Ca 9 là ca bảo vệ dự án đang chạy — nếu nó ra cờ thì cơ chế đang kiểm quá phạm vi.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+**Bỏ cả bước:** QC vẫn phải chờ code xong mới dựng locator. Đợt 2 tách `/qc-design-script` khỏi
+`/qc-run-script` sẽ **không thu được lợi ích song song** — tách ra rồi vẫn xếp hàng.
+
+**Làm §3.1 (phân vai) mà bỏ §3.2 (đổi thứ tự):** đây là cái **tệ nhất**, và là lỗi mà bản nháp
+đầu của bước này mắc phải. Chuỗi sẽ thành:
+
+```
+/generate-tech-docs → §4.5.6 rỗng → /generate-code TỰ BỊA id → /map-testids đi nhặt lại
+```
+
+Hợp đồng thành thứ **do code quyết định** — đúng cái đã bị bác ở câu hỏi "trích xuất locator từ
+source code". Hai nửa này phải đi cùng nhau.
+
+**Làm §3.2 mà bỏ §3.5 (cờ đối chiếu):** contract chốt từ thiết kế, không ai đối chiếu với thực
+tế → id đoán sai sẽ nằm im trong tech-doc, FE gắn một kiểu, QC tìm một kiểu, và không gì báo
+cho tới khi `/qc-run-script` đỏ hàng loạt ở cuối. Đúng kiểu hỏng im lặng mà cả Đợt 0 tồn tại để
+chống.
+
+**Bỏ §3.6 (invalidate `qc_status`):** id đổi mà `qc_status` vẫn `pass` → dashboard báo scenario
+đã nghiệm thu, trong khi script của nó đang định vị một element không còn tồn tại. Đó là **báo
+cáo sai**, đúng nghĩa mà `rules/workflow.md:61` gọi tên.

package/docs/plans/qc-surgery/exec-d1-b1-guard-br-tag.md

@@ -0,0 +1,129 @@
+---
+buoc: Đợt 1 — Bước 1
+title: Guard cơ học BR-tag cho /qc-analyze
+phu_thuoc: không
+trang_thai: đã làm
+---
+
+# Đợt 1 · Bước 1 — Đối chiếu business rule đã tag trong BDD với BR mà QC sinh ra
+
+← [`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/1-01-guard-br-tag.md`](buoc/1-01-guard-br-tag.md).
+
+## 1. Vì sao
+
+`/qc-analyze` đọc PRD + BDD rồi sinh ra danh sách business rule (`BR-01`, `BR-02`…) làm nền cho
+mọi test case về sau. Nếu nó **bỏ sót một rule**, hậu quả đi suốt pipeline: không có BR → không
+có test case → không có test → lỗi thoát ra production. Và không ai biết là đã bỏ sót, vì không
+có gì để so.
+
+Nhưng có một chuyện may mắn: **BDD đã tự nói ra một phần đáp án**. Mỗi scenario trong `.feature`
+mang tag `@trace.business_rules` — do `/generate-bdd` ghi khi sinh scenario từ PRD. Ví dụ:
+
+```gherkin
+# @trace.scenario: FT-101-UC1-SC3
+# @trace.business_rules: BR-02, BR-07
+Scenario: Đăng nhập sai mật khẩu 3 lần liên tiếp
+```
+
+Nghĩa là: BDD đang khẳng định scenario này thi hành `BR-02` và `BR-07`. Nếu bản phân tích của QC
+chỉ có `BR-01` đến `BR-05`, thì `BR-07` là **rule mà BDD biết nhưng QC bỏ sót** — và đó là một
+phép **so khớp chuỗi**, máy làm được, không cần ai đọc lại.
+
+Đây là điểm khác biệt quan trọng so với self-review: self-review là agent **tự đọc lại bài của
+mình**, nên nó bỏ sót đúng chỗ nó đã bỏ sót lúc viết. Guard đọc **một nguồn khác** (tag trong
+BDD) rồi đối chiếu — không phụ thuộc agent có để ý hay không.
+
+## 2. Tình trạng hiện tại
+
+`commands/qc-analyze.tmpl:121-126` **có nói** về việc map, nhưng chỉ là chỉ dẫn, không có phép
+kiểm:
+
+> **## Trace mapping (bắt buộc)**
+>
+> *"File `.feature` chính thức đã định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}` với
+> `@trace.business_rules`. Map mọi `BR-xx` / `AC-xx` bạn tạo ra tới `{UC-ID}-SC{N}` sở hữu nó
+> và ghi lại mapping…"*
+
+Chú ý hướng của câu này: **"map mọi BR bạn tạo ra tới SC"** — tức là đi từ *BR của QC* → *SC*.
+Chiều ngược lại — *tag trong BDD* → *BR của QC* — **không được kiểm**. Mà chính chiều ngược đó
+mới bắt được cái bỏ sót.
+
+Không có gì trong `bin/` kiểm việc này: rule liên quan gần nhất là `T14` của `lint-trace.js`
+(đối chiếu code với sổ trace), không phải BR.
+
+## 3. Sẽ đổi thành gì
+
+Thêm một mục **`## Guard — BR-tag`** vào `commands/qc-analyze.tmpl`, chạy **sau** khi đã ghi
+`REQUIREMENT_ANALYSIS.md` và **trước** khối CHECKPOINT.
+
+Quy trình 4 bước, thuần đếm và so khớp:
+
+```
+1. Thu: đọc mọi file .feature của uc_list (đúng active_platform), thu toàn bộ giá trị
+   trong tag @trace.business_rules → tập A.
+2. Thu: đọc mọi BR-xx trong REQUIREMENT_ANALYSIS.md vừa ghi → tập B.
+3. So: A \ B = rule mà BDD nhắc mà QC không có.
+4. Xử lý:
+   - A \ B rỗng  → in "Guard BR-tag: khớp {n}/{n}"
+   - A \ B ≠ rỗng → BỔ SUNG NGAY vào REQUIREMENT_ANALYSIS.md (đọc lại PRD để lấy nội dung
+                    rule đó), rồi in:
+                    "⚠️ Guard BR-tag: bổ sung {k} rule BDD đã nhắc mà phân tích bỏ sót: {list}"
+```
+
+**Hai điểm thiết kế cần giữ đúng:**
+
+**a) Guard tự sửa, không chỉ tự báo.** Nếu chỉ in cảnh báo rồi để người xử lý thì nó thành một
+dòng nữa để bỏ qua. Agent phải quay lại PRD, tìm rule đó, bổ sung vào bản phân tích — rồi mới
+báo. Người đọc cảnh báo để **biết đã có chuyện gì xảy ra**, không phải để đi làm việc đó.
+
+**b) Chiều ngược lại (B \ A) KHÔNG phải lỗi.** QC sinh `BR-09` mà không tag nào trong BDD nhắc
+tới → có thể QC phát hiện một rule mà BDD chưa phủ. Đó là **phát hiện tốt**, không phải sai.
+Ghi nó thành một gap trong `DOC_GAP.md` (BDD thiếu scenario cho rule này), đừng xoá.
+
+**In tường minh trong report.** Dòng `Guard BR-tag:` phải xuất hiện trong report cuối, kể cả khi
+sạch. Guard im lặng khi sạch là guard không ai biết có tồn tại — và không ai phát hiện được khi
+nó chết.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `commands/qc-analyze.tmpl` | Thêm mục `## Guard — BR-tag` sau §Trace mapping (`:126`); thêm dòng `Guard BR-tag:` vào khối Report cuối |
+
+Nguồn nội dung tham khảo: `D:\base\qcframework_proposal\command\qc-analyze.md` (mục Guard
+tương ứng).
+
+Không đụng `bin/` — guard này chạy trong lệnh, không phải rule của lint. *(Có thể cân nhắc đưa
+nó thành rule máy về sau, nhưng nó cần đọc `REQUIREMENT_ANALYSIS.md` — artifact QC — nên chưa
+thuộc phạm vi `lint-trace.js` hiện tại.)*
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+node bin/build.js && node bin/self-check.js && node test/run.js
+```
+
+Kiểm bằng **ca lỗi cố ý** — đây là phép thử thật:
+
+1. Chọn một UC có `.feature` với tag `@trace.business_rules` trỏ tới ≥3 rule.
+2. Chạy `/qc-analyze {TICKET-ID}` bình thường → report phải in `Guard BR-tag: khớp N/N`.
+3. **Tạo ca lỗi:** sửa tay `REQUIREMENT_ANALYSIS.md`, xoá một `BR-xx` mà BDD có tag.
+4. Chạy lại `/qc-analyze {TICKET-ID}` → phải in `⚠️ Guard BR-tag: bổ sung 1 rule…` và
+   `REQUIREMENT_ANALYSIS.md` phải có lại rule đó **kèm nội dung thật từ PRD**, không phải một
+   dòng trống mang tên `BR-xx`.
+
+Bước 4 là chỗ dễ làm sai nhất: guard có thể "bổ sung" một dòng rỗng cho đủ số. Phải kiểm nội
+dung.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Bỏ sót business rule ở trạm đầu tiên là loại lỗi **đắt nhất** trong cả pipeline, vì nó nhân lên
+theo từng trạm: không có BR → `/qc-plan` không xếp rủi ro cho nó → `/qc-design-test` không viết
+test case → `/qc-run-script` không có gì để chạy → `/qc-report` báo coverage 100%.
+
+Và **coverage 100% ở đây là con số sai theo hướng nguy hiểm nhất**: nó tính trên mẫu số là "số
+scenario đã biết", không phải "số rule cần phủ". Đợt 3 sẽ dựng verdict PASS/FAIL trên chính con
+số đó — nên guard này là điều kiện để con số của Đợt 3 có nghĩa.

package/docs/plans/qc-surgery/exec-d1-b2-guard-sc-coverage.md

@@ -0,0 +1,159 @@
+---
+buoc: Đợt 1 — Bước 2
+title: Guard cơ học SC coverage cho /qc-design-test
+phu_thuoc: không
+trang_thai: đã làm
+---
+
+# Đợt 1 · Bước 2 — Mọi scenario phải có ít nhất một test case trỏ tớ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/1-02-guard-sc-coverage.md`](buoc/1-02-guard-sc-coverage.md).
+
+## 1. Vì sao
+
+`/qc-design-test` nhận danh sách scenario từ `.feature` rồi viết test case. Câu hỏi đơn giản mà
+hiện không ai trả lời được: **scenario nào chưa có test case nào phủ?**
+
+Ví dụ cụ thể. `.feature` của UC1 có 6 scenario:
+
+```
+FT-101-UC1-SC1   Đăng nhập thành công
+FT-101-UC1-SC2   Sai mật khẩu
+FT-101-UC1-SC3   Sai mật khẩu 3 lần → khoá tài khoản
+FT-101-UC1-SC4   Đăng nhập bằng OTP
+FT-101-UC1-SC5   Tài khoản chưa kích hoạt
+FT-101-UC1-SC6   Đăng nhập khi hết session
+```
+
+QC viết `TC_LOGIN.Test.md` với 11 test case. Trong đó SC5 và SC6 **không có test case nào**
+trace tới — có thể vì bị bỏ sót lúc viết, có thể vì đang chờ PO trả lời một gap. Không ai phát
+hiện. Đến `/qc-report` thì SC5, SC6 nằm im ở `not_run`, và không ai biết là **chưa từng được
+thiết kế**, chứ không phải "đã thiết kế nhưng chưa chạy".
+
+Hai trạng thái đó khác nhau hoàn toàn về hành động cần làm — nhưng nhìn vào sổ trace thì giống
+nhau. Guard này là chỗ phân biệt.
+
+Đây cũng là **phép đếm thuần**: liệt kê `{UC-ID}-SC{N}` từ `.feature`, đếm số test case có
+`@trace.verifies` trỏ tới từng cái. Không suy luận, không phụ thuộc agent để ý.
+
+## 2. Tình trạng hiện tại
+
+`commands/qc-design-test.tmpl` **không có phép kiểm nào**. Đã grep xác nhận:
+
+```bash
+grep -n "Kiểm tra phủ\|coverage\|Trace SC\|thiếu TC\|SC{N}" commands/qc-design-test.tmpl
+# → chỉ 1 kết quả:
+#   :146  - **@trace.verifies:** {UC-ID}-SC{N}
+```
+
+Tức là lệnh **định nghĩa định dạng** của tag `@trace.verifies` (test case phải mang tag gì),
+nhưng **không đếm** xem mọi scenario đã được phủ chưa. Định dạng đúng ≠ phủ đủ.
+
+Không có gì trong `bin/` kiểm việc này ở cấp test case: `lint-trace.js` canh sổ `.tsv` và code,
+không mở `.Test.md`.
+
+## 3. Sẽ đổi thành gì
+
+Thêm mục **`## Guard — SC coverage`** vào `commands/qc-design-test.tmpl`, chạy **sau** khi ghi
+xong file `.Test.md` và **trước** khối CHECKPOINT.
+
+```
+1. Thu: liệt kê mọi @trace.scenario trong .feature của UC (đúng active_platform) → tập SC.
+2. Thu: liệt kê mọi giá trị @trace.verifies trong .Test.md vừa ghi → tập V.
+3. Đếm: với mỗi sc ∈ SC, đếm số TC có sc ∈ @trace.verifies.
+4. Xử lý:
+   - Mọi SC đều có ≥1 TC  → in "Guard SC coverage: khớp {k}/{k}"
+   - Có SC chưa phủ       → với TỪNG SC thiếu, phải ghi MỘT TRONG HAI:
+       (a) viết bổ sung test case ngay, HOẶC
+       (b) ghi lý do có căn cứ + tham chiếu gap thật, dạng:
+           "⚠️ {UC-ID}-SC{N} — chưa có TC, block bởi GAP-UC1-003 (đang Open)"
+     Rồi in: "⚠️ Guard SC coverage: {k-m}/{k} — {m} SC chưa phủ (xem danh sách)"
+```
+
+> ⚠️ **SỬA LÚC TRIỂN KHAI (2026-09-11) — phần bảng "lý do hợp lệ" dưới đây đã BỊ BỎ.**
+>
+> Bản gốc thiết kế một đường thoát: *SC chưa có TC thì được bỏ qua nếu trỏ tới một `GAP-xx` có
+> thật*. Đọc kỹ lệnh thì đường đó **mâu thuẫn với quy ước đã có** —
+> `commands/qc-design-test.tmpl:137`:
+>
+> > *"Một TC bị block bởi gap **vẫn viết đủ** + `🚫 Block: [GAP-UC{N}-{nnn}](../DOC_GAP.md) — lý do`."*
+>
+> Tức **gap không phải cái cớ để không viết TC — nó là thứ được GHI VÀO TC.** SC bị gap chặn vẫn
+> có TC (mang dấu `🚫 Block`), vẫn được đếm là đã phủ. Thêm đường thoát như bản gốc là dạy hai
+> luật trái nhau trong cùng một lệnh, và cho agent một câu-lý-do-cho-qua.
+>
+> **Bản đã triển khai nghiêm hơn và đơn giản hơn:** chỉ còn hai trạng thái, không cái nào cho
+> phép bỏ trống — SC **trong** phạm vi thì phải có TC (bị chặn thì TC mang `🚫 Block`); SC
+> **ngoài** phạm vi thì `qc-scope` đã lọc ở bước thu, không tính vào mẫu số. Thấy một SC
+> "không thể viết TC" mà không thuộc hai loại đó → **đó là một gap**: mở gap rồi viết TC kèm
+> `🚫 Block` trỏ tới nó.
+>
+> **Phát hiện kèm theo:** report của lệnh đã có sẵn con số `Trace: {N} TC map tới {K}/{total}
+> scenario` từ trước — nhưng **không có phép tính nào sinh ra nó** và `K < total` không dẫn tới
+> việc gì. Guard biến con số đó từ ước lượng thành kết quả của một phép đếm, và thêm hệ quả.
+
+*(Bản gốc, giữ để đối chiếu:)* **Điểm thiết kế quan trọng: không cho phép "bỏ qua vô cớ".** Có
+hai lý do hợp lệ để một scenario chưa có test case:
+
+| Lý do | Có được chấp nhận? |
+|---|---|
+| Bị chặn bởi một gap `DOC_GAP` đang `Open` — chưa biết hành vi đúng là gì thì không viết được test | ✅ Được, **nhưng phải trỏ tới `GAP-xx` có thật** trong `DOC_GAP.md` |
+| Scenario nằm ngoài phạm vi lần này (UC chưa `approved`, đã lọc bởi `qc-scope`) | ✅ Được, ghi rõ |
+| "Tương tự SC khác nên không cần" | ❌ Không. Nếu thật sự trùng thì `.feature` sai — mở gap, đừng bỏ im lặng |
+| Không lý do | ❌ Không |
+
+Yêu cầu "phải trỏ tới `GAP-xx` có thật" là để guard không bị vô hiệu hoá bằng một câu lý do
+chung chung. `DOC_GAP.md` nằm cùng `qc_artifact_dir` nên kiểm được.
+
+**In tường minh kể cả khi sạch** — cùng lý do như `exec-d1-b1`: guard im lặng là guard không ai
+biết khi nó chết.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `commands/qc-design-test.tmpl` | Thêm mục `## Guard — SC coverage` trước khối CHECKPOINT; thêm dòng `Guard SC coverage:` vào Report cuối |
+
+Nguồn nội dung tham khảo: `D:\base\qcframework_proposal\command\qc-design-test.md` (mục Guard
+tương ứng).
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+node bin/build.js && node bin/self-check.js && node test/run.js
+```
+
+Kiểm bằng ca lỗi cố ý:
+
+1. Chọn UC có `.feature` ≥5 scenario. Chạy `/qc-design-test {UC-ID}` → report in
+   `Guard SC coverage: khớp K/K`.
+2. **Ca thiếu:** sửa tay `.Test.md`, xoá hết test case trỏ tới một SC → chạy lại → phải in
+   `⚠️ Guard SC coverage: (K-1)/K` **và** phải hoặc viết bù test case, hoặc đòi một `GAP-xx`.
+3. **Ca lý do khống:** thử để agent ghi lý do "tương tự SC2" → guard phải **không** chấp nhận,
+   phải đòi gap thật hoặc viết test case.
+
+Ca 3 là chỗ dễ hỏng: guard viết lỏng thì agent sẽ học cách viết một câu lý do cho qua.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Hai hậu quả, cái sau nặng hơn:
+
+**1. Lỗ hổng phủ im lặng.** Scenario không có test case trông giống scenario có test case nhưng
+chưa chạy. Người đọc dashboard không phân biệt được, nên không ai đi lấp.
+
+**2. Con số của Đợt 3 mất nghĩa.** `/qc-report` mới tính:
+
+```
+Design coverage = số SC có ≥1 TC-approved trỏ tới / tổng số SC
+```
+
+Đó **chính là** phép đếm mà guard này làm — chỉ khác là guard làm ở **lúc thiết kế** (còn kịp
+sửa), còn `/qc-report` làm ở **cuối** (chỉ còn kịp báo). Không có guard thì Đợt 3 sẽ báo
+"design coverage 68%" ở phút cuối, khi không còn thời gian viết bù 32%. Và cờ `INVERSION` của
+Đợt 3 (design coverage < execution coverage) cũng dựa vào cùng phép đếm này.
+
+Nói cách khác: guard này là phiên bản "chặn sớm" của một chỉ số mà Đợt 3 sẽ dùng để ra verdict.
+Làm nó trước là để verdict kia có nghĩa.