@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/docs/plans/qc-surgery/buoc/0-06-hop-dong-truoc-code.md

@@ -0,0 +1,226 @@
+# Chốt hợp đồng TRƯỚC code — mở luồng FE ∥ QC song song
+
+| | |
+|---|---|
+| **Đợt** | 0 — Hợp đồng test-id |
+| **Bước** | **6/6** của Đợt 0 — bước lớn nhất, **2 commit** |
+| **File sửa** | **A** `commands/{generate-tech-docs,map-testids,generate-code,review-tech-docs}.tmpl` · `steps/report-footer.md` · `docs/explain/11-map-testids.md`<br>**B** `bin/lint-trace.js` · `bin/trace-schema.json` · `commands/map-testids.tmpl` |
+| **File test** | `test/run.js` — 6 test mới (phần B) |
+| **Ngày xong** | 2026-09-11 · commit `a3a5f30` (A) + `8073507` (B) |
+| **Phụ thuộc** | [`0-01`](0-01-testid-attr-co-cho-o.md) · [`0-02`](0-02-mot-nguon-cho-testid-attr.md) · [`0-04`](0-04-may-canh-hop-dong.md) |
+| **Ai dùng nó** | Cả **nhánh dev** (`generate-tech-docs` · `generate-code` · `review-tech-docs`) lẫn nhánh QC — bước duy nhất của Đợt 0 đụng cả hai |
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+
+## A1 · Vấn đề
+
+Đội làm giao diện và đội kiểm thử **phải xếp hàng**: đội kiểm thử ngồi chờ tới khi màn hình làm xong mới bắt đầu viết được kịch bản kiểm tra, vì trước đó họ không biết phải gọi tên từng nút bằng gì.
+
+Nhưng tên các nút thì **hoàn toàn có thể đặt từ bản thiết kế**, trước khi ai gõ dòng code đầu tiên. Việc xếp hàng không phải vì thiếu thông tin — mà vì **thứ tự làm việc đang sai**.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+> **Như đánh số phòng trên bản vẽ trước khi xây.** Có bản vẽ rồi thì thợ xây đi gắn biển số,
+> và **cùng lúc đó** bên nội thất đã đặt được đồ theo số phòng — không ai phải chờ ai.
+> Cả hai đọc **cùng một bản vẽ đã chốt**.
+
+Chứ không phải: xây xong rồi mới đi đo từng phòng để đánh số, rồi bên nội thất mới bắt đầu.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Sau khi duyệt bản thiết kế kỹ thuật, **hai nhánh chạy song song**: bên làm giao diện và bên viết kịch bản kiểm thử, không bên nào chờ bên nào.
+
+Và nếu bản thiết kế có phần giao diện mà **chưa điền bảng tên nút**, người duyệt sẽ **không cho qua** — thay vì cho qua rồi mỗi bên tự nghĩ một kiểu.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **Bản thiết kế kỹ thuật (tech-doc)** — bản vẽ thi công, chứa cả bảng tên nút.
+- **Song song** — hai việc chạy cùng lúc, không phải một việc chờ việc kia xong.
+
+---
+
+> ### ✅ 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 "test-id", "contract", "pipeline" — cả ba đẩy xuống phần B.)*
+
+---
+
+# 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 — siết "một người ghi" mà GIỮ NGUYÊN thứ tự
+
+Đây là cách tôi **đã đề xuất và đã phải rút lại**, nên nó không phải giả định.
+
+Vấn đề nhìn thấy được là *hai lệnh cùng ghi bảng §4.5.6, luật chống giẫm chân chỉ là một câu văn xuôi*. Cách chữa hiển nhiên: `generate-tech-docs` chỉ tạo **khung rỗng**, `/map-testids` là người duy nhất ghi row.
+
+Sai vì `/map-testids` đang chạy **sau** `/generate-code`. Chuỗi sẽ thành:
+
+```
+/generate-tech-docs  →  §4.5.6 RỖNG
+/generate-code       →  đọc §4.5.6 thấy rỗng → TỰ SINH id theo quy ước
+/map-testids         →  đi nhặt lại id mà generate-code vừa bịa
+```
+
+Hợp đồng thành thứ **do code quyết định** — đúng cái vừa bị bác ở câu hỏi *"có thể trích xuất locator từ source code không?"*. Phân vai đúng, thứ tự sai, và kết quả tệ hơn lúc đầu.
+
+**Hai nửa phải đi cùng nhau.** Đây là nội dung chính của B2.
+
+### Cách sai thứ hai — chặn cứng `/generate-code` khi bảng rỗng
+
+Đã chốt hợp đồng đi trước thì code không có hợp đồng phải dừng. Dứt khoát, dễ hiểu.
+
+Sai vì nó **chặn người đang làm việc** — gồm cả những dự án chưa liên quan gì tới đợt mổ này. Người dùng chọn hướng khác: **cảnh báo mạnh rồi để dev quyết**. Và lựa chọn đó chỉ an toàn **vì** phần B có `T18` bắt những id tạm sinh ra ở đó (xem B2).
+
+### Cách sai thứ ba — làm 2 cờ audit trong `/validate-traces` như kế hoạch
+
+Kế hoạch đề hai **cờ audit**. Nghe hợp lý vì framework đã có 17 cờ như vậy.
+
+Sai ở ba điểm: cờ audit do **LLM tự khai** (không xác định, không test được); thêm cờ phải đụng `validate-traces` với counter ở **hai** tầng (rule `R7` canh) **và** `templates/ci/trace-gate.yml` (rule `R10` canh) — cả một vùng rủi ro; và cờ audit **có thể vô tình lọt vào `gate.blocking`** rồi chặn PR cả team.
+
+Trong khi `bin/lint-trace.js` **đã có sẵn** hạ tầng quét code (`CODE_DIRS`/`CODE_EXT`/`walk`) mà rule `T14` đang dùng.
+
+## B2 · Cách làm đúng
+
+### Phần A — thứ tự và phân vai
+
+**Framework đã khai đúng vị trí từ trước.** `steps/report-footer.md:63-64`:
+
+```
+| Tech Design | /generate-tech-docs · /map-testids · /review-tech-docs |
+| Code        | /generate-code · /review-code                          |
+```
+
+`/map-testids` nằm ở phase **Tech Design**, trước phase **Code**. `GAPS-v4.md:724` cũng vậy. Chỉ `docs/explain/11-map-testids.md` nói ngược — và chính nó tự thừa nhận *"vị trí pipeline hơi mờ"*. Nên bước này **không phát minh kiến trúc mới**, nó chốt một mâu thuẫn có sẵn theo hướng đúng.
+
+Và nguyên liệu đã sẵn: `map-testids.tmpl:33` lấy element từ *"step `When` trong `.feature` + các màn Design Spec"* — cả hai đều có **trước** code.
+
+**Thứ tự mới:**
+
+```
+/generate-design-spec ─┐
+                       ├→ /generate-tech-docs   (§4.5 + §4.5.6 KHUNG RỖNG)
+/generate-bdd ─────────┘         ↓
+                        /map-testids            (CHỐT hợp đồng — KHÔNG đụng code)
+                                 ↓
+                        /review-tech-docs       (duyệt CẢ hợp đồng)
+                                 ↓ APPROVED
+              ┌──────────────────┴──────────────────┐
+        /generate-code                        /qc-design-test
+              ↓                                     ↓
+        /review-code                          /qc-review-script
+              └──────────────────┬──────────────────┘
+                        /qc-run-script   ← chỗ ĐẦU TIÊN cần code chạy thật
+```
+
+Hai nhánh không đụng nhau vì đọc **cùng một hợp đồng đã đóng băng**, không đọc output của nhau.
+
+**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` | Khung rỗng + header placeholder. **Không ghi row** |
+| `/map-testids` | **Người duy nhất ghi row.** Hai chế độ: mặc định (design-spec + BDD, không đụng code) · `--from-code` (brownfield, chạy một lần mỗi UC cũ) |
+| `/generate-code` · `/qc-design-test` | Chỉ **đọc** |
+| `bin/lint-trace.js` | **Canh** |
+
+Chế độ `--from-code` **không phải viết mới** — là nhánh `existing`/`reused` đã có (`:34-40`), chỉ tách thành cờ tường minh thay vì để lệnh tự đoán theo sự tồn tại của code.
+
+**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.** `/review-tech-docs` **T6** không cho `APPROVED` nếu có §4.5 client mà §4.5.6 rỗng. Ba lý do tốt hơn một cơ chế nhắc: không cần actor mới, không thời điểm mới (`report-footer.md:100` vốn đã chặn) · đúng bản chất — tech-doc có phần UI mà không khai test selector thì **chưa viết xong**, như có §4 API mà không khai endpoint · chuỗi Next tự dẫn.
+
+**`/generate-code` khi bảng rỗng — cảnh báo mạnh rồi để người quyết.** In rõ ba hệ quả (QC không bám được · `/map-testids` sau này có thể phải **sửa code** · `T18` sẽ báo), gợi ý cách đúng, rồi hỏi `Y/N`. Chọn `Y` thì report **bắt buộc** ghi `⚠️ {n} test-id TẠM (chưa vào §4.5.6)`. `--yes` coi như `Y` nhưng dòng cảnh báo vẫn bắt buộc.
+
+### Phần B — máy canh và làm mất hiệu lực
+
+**Hai rule trong `lint-trace --code`, không phải cờ audit:**
+
+```
+T17  id đã khai ở §4.5.6 mà KHÔNG có trong code    ⚠️ warn
+T18  id trong code mà KHÔNG có trong §4.5.6 nào    ⚠️ warn
+```
+
+**Cả hai WARN, không ERROR** — id đoán từ thiết kế **không sống sót 100%**: lúc implement, dev có thể gộp hai element thành một component hoặc tách một thành hai. Đây là **nợ cần thấy**, không phải cái sai chặn người.
+
+`T18` là **lưới bắt phía sau** cho quyết định ở phần A: chính vì có nó mà `/generate-code` được phép hỏi rồi đi tiếp thay vì chặn cứng.
+
+**Bốn điều khoản chống báo oan**, mỗi cái có một test canh: chưa có hợp đồng nào → không kiểm · thiếu `--code` → in `BỎ QUA` tường minh · **code chưa có id nào của thuộc tính đó** (UI chưa viết / `--code` trỏ sai gốc) → im lặng, không phán "FE chưa gắn" cho cả bảng · `@trace.testid_attr` thiếu hoặc còn placeholder → không so, vì **không biết tìm thuộc tính nào thì mọi so sánh là đoán**.
+
+**`T18` so với HỢP NHẤT mọi bảng**, không so từng doc: monorepo có nhiều PRD, id của PRD khác nằm trong code là bình thường — so per-doc sẽ báo oan gần hết.
+
+**`/map-testids` thành invalidator của `qc_status`.** Đổi một id nghĩa là mọi script QC bám id cũ **hết đúng**. `rules/workflow.md:57-64` đã có luật:
+
+> *"lệnh nào làm giá trị đó **HẾT ĐÚNG** thì **BẮT BUỘC** hạ nó về giá trị 'chưa biết'. Giữ một `pass` đã hết hiệu lực là **báo cáo sai**."*
+
+Và đã có tiền lệ thi hành: `qc_status.written_by` gồm `generate-bdd` · `generate-code` với vai invalidator. Thêm `map-testids` vào đúng khuôn đó. Chuỗi chạy được nhờ cột **"Phục vụ SC"** làm chỉ mục ngược:
+
+```
+đổi id → đọc cột "Phục vụ SC" → hạ qc_status các SC đó về not_run, qc_run_at → —
+         KHÔNG đụng qc_owner/qc_blocked_by — rules/workflow.md:65-67 miễn trừ tường minh
+         (chúng là con trỏ tới bug; đổi test-id không làm con bug biến mất)
+```
+
+## B3 · Nếu làm sai thì hỏng theo kiểu nào
+
+Bước này đóng **hai** kiểu hỏng khác nhau:
+
+| Kiểu | Ở đâu |
+|---|---|
+| **Bỏ chạy** 🟠 | QC xếp hàng chờ code. Đúng nhưng chậm — và việc tách `/qc-design-script` khỏi `/qc-run-script` ở Đợt 2 sẽ **không thu được lợi ích song song** nếu thứ tự vẫn sai |
+| **Im lặng** 🔴 | Hợp đồng do **code** quyết định: QC đọc §4.5.6 thấy rỗng nên đi dò DOM, còn FE đã gắn một bộ id không ai biết. Tới lúc "đối chiếu lúc integration" thì cả hai bên đã làm xong theo hai hướng khác nhau |
+
+| | |
+|---|---|
+| Ai phát hiện | Kiểu Im lặng: không ai, cho tới khi `/qc-run-script` đỏ hàng loạt ở cuối |
+| Sau bao lâu | Cuối chu kỳ — chỗ đắt nhất để phát hiện |
+| Nguy hiểm nhất | Làm phần A **mà bỏ phần B**: contract chốt từ thiết kế, không ai đối chiếu với thực tế → id đoán sai nằm im trong tech-doc, và không gì báo |
+
+## B4 · Verify bằng gì
+
+**6 test tự động** cho phần B:
+
+| # | Phép thử | Kết quả |
+|---|---|---|
+| 1 | Bảng khớp code | ✅ không T17/T18 |
+| 2 | Bảng có id mà code không có | ✅ **T17**, exit 0 (warn, không chặn) |
+| 3 | Code có id mà bảng không có | ✅ **T18** |
+| 4 | 🔴 Code chưa có id nào (UI chưa viết) | ✅ **im lặng** — không phán "FE chưa gắn" cho cả bảng |
+| 5 | 🔴 Thiếu `--code` | ✅ in *"T17/T18 BỎ QUA"*, không im lặng báo sạch |
+| 6 | 🔴 Header còn placeholder | ✅ **không so code** — không biết attr thì mọi so sánh là đoán |
+
+**Chín phép thử tay chưa chạy** — cần PRD thật. Ca **3** và **5** là phép thử quyết định:
+
+| # | Phép thử | Kết quả mong đợi |
+|---|---|---|
+| 7 | `/generate-tech-docs` | §4.5.6 có **khung** nhưng **0 row** |
+| 8 | `/review-tech-docs` ngay sau | **NEEDS_FIX** |
+| **9** | `/map-testids {UC}` khi **chưa có code FE** | Điền row từ design-spec+BDD; **không đụng file code nào** |
+| 10 | `/generate-code --phase=ui` | Element mang đúng id trong bảng, không bịa |
+| **11** | `/qc-design-test` chạy **song song**, trước khi `/generate-code` xong | Chạy được, bám id từ §4.5.6 |
+| 12 | `/generate-code` khi bảng rỗng | Cảnh báo + hỏi; chọn `Y` thì report ghi rõ id là **TẠM** |
+| 13 | Sửa tay một id, chạy `/map-testids` | `qc_status` các SC ở cột "Phục vụ SC" → `not_run`; `qc_owner`/`qc_blocked_by` **giữ nguyên** |
+| 14 | Repo cũ chưa từng chạy `/map-testids` | **0 cờ test-id** |
+
+## B5 · Bài học
+
+- **2026-09-11** — Bản đề xuất "siết một người ghi" của tôi **có lỗ**, và lỗ đó chỉ lộ ra khi người dùng nói *"từ UI đã có thể đặt ra test-id rồi, tôi hướng tới việc chốt locator trước bước sinh code để FE và QC chạy song song"*. Tôi đã phản đối hướng đó vì sợ `/generate-code` tự bịa id — mà lỗ ấy **chỉ tồn tại nếu `/map-testids` chạy sau code**. Câu hỏi của người dùng sửa luôn lỗ trong đề xuất của tôi.
+  → **Bài học chuyển giao được:** khi một cách chữa "đúng về phân vai" mà vẫn thấy sai ở đâu đó, hãy kiểm **thứ tự thực thi** trước khi kết luận cách chữa đó hỏng. Phân vai và thứ tự là hai trục độc lập; sai một trục không có nghĩa trục kia sai.
+
+- **2026-09-11** — Đề xuất "cờ nhắc chạy `/map-testids`" của tôi **đặt sai chỗ**: cờ audit đọc code, mà ở thời điểm cần nhắc thì **chưa có code**. Lỗi lộ ra từ câu hỏi *"nhắc cho ai, khi dev chưa code?"*. Cách đúng hoá ra không phải nhắc ai cả — mà biến nó thành **điều kiện hoàn chỉnh của tài liệu**, kiểm ở đúng lúc đã có người ngồi soát tài liệu đó.
+  → **Bài học chuyển giao được:** trước khi thiết kế một cơ chế nhắc việc, hỏi *"ở thời điểm cần nhắc, dữ liệu để phát hiện đã tồn tại chưa?"*. Nếu chưa, cơ chế đó sai tầng — đi tìm một cổng đã có sẵn ở đúng thời điểm.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | **Chốt hợp đồng ở tầng thiết kế để hai bên tiêu thụ song song** — áp được cho mọi cặp producer/consumer phải khớp nhau (API contract, schema sự kiện, tên cột). Nguyên tắc: hợp đồng phải đi **trước** cả hai bên, không được để một bên vừa dùng vừa định nghĩa. **Nhắc việc = điều kiện hoàn chỉnh của artifact**, kiểm ở cổng review đã có, thay vì dựng cơ chế thông báo mới. Và: cho phép "đi tiếp có cảnh báo" **chỉ khi** có một lưới bắt phía sau |
+| ⚠️ **Chỉ đúng ở đây** | Thứ tự lệnh cụ thể, cấu trúc `§4.5.x`, và việc `qc_status` có cơ chế invalidator sẵn — đều gắn với framework này |
+
+## B7 · Link
+
+- Kế hoạch trước khi làm: [`../exec-d0-b6-contract-truoc-code.md`](../exec-d0-b6-contract-truoc-code.md)
+- Mạch hỏi–đáp dẫn tới bước này: [`../00-nhat-ky.md` §3.2 và §3.3](../00-nhat-ky.md)
+- Bước liên quan: [`0-04`](0-04-may-canh-hop-dong.md) (T15/T16 + R8e tự canh luôn T17/T18) · [`0-05`](0-05-don-nhan-cot-va-2b.md) (phần "golden path" chuyển từ đó sang đây)

package/docs/plans/qc-surgery/buoc/1-01-guard-br-tag.md

@@ -0,0 +1,156 @@
+# Guard BR-tag — đối chiếu tag trong BDD với luật nghiệp vụ sinh ra
+
+| | |
+|---|---|
+| **Đợt** | 1 — Nền tảng |
+| **Bước** | **1/6** của Đợt 1 |
+| **File sửa** | `commands/qc-analyze.tmpl` |
+| **File test** | Không có test tự động — xem B4 |
+| **Ngày xong** | 2026-09-11 · commit `20d177b` |
+| **Phụ thuộc** | không có |
+| **Ai dùng nó** | `/qc-analyze` — trạm đầu tiên của pipeline QC |
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+
+## A1 · Vấn đề
+
+Trạm đầu tiên của kiểm thử đọc tài liệu yêu cầu rồi liệt kê ra **các luật nghiệp vụ** — *"sai mật khẩu 3 lần thì khoá tài khoản"*, kiểu vậy. Mọi việc phía sau dựa trên danh sách đó.
+
+Bỏ sót một luật thì **không có gì báo**. Không có luật → không ai xếp rủi ro cho nó → không ai viết kịch bản kiểm tra → không có gì để chạy → và báo cáo cuối cùng ghi *"đã kiểm 100%"*.
+
+Con số 100% đó tính trên **những thứ đã biết**, không phải trên **những thứ cần kiểm**. Nên nó sai theo hướng nguy hiểm nhất: **trông như đã xong**.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+> **Như đối chiếu hai bản danh sách khách mời.** Cô dâu có một bản, chú rể có một bản. Không ai
+> nhớ hết — nhưng **đặt hai bản cạnh nhau** thì tên nào có ở bản này mà thiếu ở bản kia **hiện ra ngay**.
+
+Ở đây bản thứ hai đã có sẵn: khi viết kịch bản nghiệp vụ, hệ thống đã **ghi kèm** luật nào thuộc kịch bản nào. Chỉ là trước giờ không ai đem hai bản ra đối chiếu.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Cuối báo cáo của trạm này có thêm một dòng: `Guard BR-tag: khớp 12/12`. Nếu có luật bị bỏ sót, nó **tự tìm lại nội dung trong tài liệu gốc, bổ sung vào bản phân tích**, rồi mới báo — kèm danh sách đã bổ sung.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **Luật nghiệp vụ (`BR` — business rule)** — một quy tắc sản phẩm phải tuân theo.
+- **Kịch bản (`SC` — scenario)** — một tình huống cụ thể dùng để kiểm tra.
+- **Tag** — nhãn ghi kèm kịch bản, nói kịch bản này thi hành những luật nào.
+- **Guard** — một phép kiểm do máy làm, chạy như nhau mỗi lầ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 — thêm một câu vào phần tự kiểm
+
+*"Hãy kiểm tra lại xem đã map đủ BR chưa"*. Rẻ, một dòng, và nghe như đã giải quyết.
+
+Sai vì tự kiểm là agent **tự đọc lại bài của mình** — nó bỏ sót **đúng chỗ nó đã bỏ sót lúc viết**. Cùng một agent, cùng một điểm mù, chỉ khác là đọc lần thứ hai. Muốn bắt được cái thiếu thì phải so với **một nguồn khác**, do **một lệnh khác** ghi ra.
+
+Đây là lý do [`1-04`](1-04-self-review-dung-chung.md) phải viết hẳn một mục về ranh giới giữa hai thứ.
+
+### Cách sai thứ hai — guard chỉ in cảnh báo
+
+Phát hiện thiếu thì báo, để người đi xử lý. Đúng vai trò của một cái "guard".
+
+Sai vì nó **thêm một dòng nữa để bỏ qua**. Người chạy lệnh đang ở giữa một việc khác; một dòng cảnh báo giữa report dài sẽ trôi qua. Và lần sau nó lại hiện, rồi lại trôi.
+
+Guard này **tự sửa rồi mới báo**: quay lại tài liệu gốc, tìm nội dung thật của luật đó, bổ sung vào bản phân tích. Cảnh báo là để người **biết đã có chuyện gì xảy ra**, không phải để họ đi làm việc đó.
+
+### Cách sai thứ ba — coi chiều ngược lại cũng là lỗi
+
+Nếu `A ∖ B` (tag có, phân tích thiếu) là lỗi, thì `B ∖ A` (phân tích có, tag không nhắc) cũng phải là lỗi chứ?
+
+Sai. QC sinh ra `BR09` mà không tag nào nhắc tới → rất có thể QC **phát hiện một luật mà BDD chưa phủ**. Đó là **phát hiện tốt**, không phải sai sót. Xử lý đúng: ghi thành một gap trong `DOC_GAP.md` (BDD thiếu scenario cho luật này), **đừng xoá**.
+
+Một guard mà phạt cả hai chiều sẽ dạy agent chỉ liệt kê đúng những gì BDD đã nhắc — tức là **thôi suy nghĩ**.
+
+## B2 · Cách làm đúng
+
+Mục §Trace mapping có sẵn trong lệnh đi **một chiều**: từ `BR` mà QC tạo ra → `SC` sở hữu nó. Chiều đó đúng và cần. Chiều **ngược lại** mới bắt được cái bỏ sót, và nó chưa được kiểm ở đâu.
+
+BDD đã tự nói ra một phần đáp án — mỗi scenario mang tag do `/generate-bdd` ghi khi sinh từ PRD:
+
+```gherkin
+# @trace.scenario: FT-101-UC1-SC3
+# @trace.business_rules: FT-101-UC1-BR02, FT-101-UC1-BR07
+```
+
+Bản phân tích chỉ có `BR01`–`BR05` thì `BR07` là **luật BDD biết mà QC bỏ sót** — và đó là một **phép so khớp chuỗi**, máy làm được.
+
+**Bốn bước, thuần đếm và so:**
+
+```
+1. Thu A — mọi giá trị @trace.business_rules trong .feature của uc_list (đúng nền)
+2. Thu B — mọi BR-xx trong REQUIREMENT_ANALYSIS.md VỪA GHI
+3. So    — A ∖ B
+4. Xử lý — rỗng     → in "Guard BR-tag: khớp {n}/{n}"
+           ≠ rỗng   → quay lại PRD lấy NỘI DUNG THẬT, bổ sung ngay, rồi in danh sách
+```
+
+Bước 4 ghi rõ **không thêm một dòng trống mang tên `BR-xx` cho đủ số** — đó là cách một guard tự-sửa bị làm cho vô nghĩa.
+
+**In dòng `Guard BR-tag:` kể cả khi sạch.** Guard im lặng khi sạch là guard **không ai biết nó tồn tại** — và không ai phát hiện được khi nó chết.
+
+## B3 · Nếu làm sai thì hỏng theo kiểu nào
+
+**Kiểu hỏng: im lặng** 🔴 — và đây là chỗ **đắt nhất trong cả pipeline**, vì lỗi nhân lên theo từng trạm.
+
+```
+thiếu BR → /qc-plan không xếp rủi ro → /qc-design-test không viết test case
+         → /qc-run-test không có gì chạy → /qc-report báo "coverage 100%"
+```
+
+| | |
+|---|---|
+| Hỏng ở đâu | Trạm đầu tiên — nên mọi trạm sau đều thừa hưởng |
+| Ai phát hiện | Không ai trong nội bộ. Người dùng cuối, khi tính năng đó hỏng thật |
+| Sau bao lâu | Sau khi phát hành |
+| Vì sao đắt | Báo cáo cuối **nói dối một cách trung thực**: nó tính đúng trên mẫu số *"số scenario đã biết"*. Không ai sai ở khâu tính; sai ở khâu mẫu số thiếu |
+
+## B4 · Verify bằng gì
+
+| # | Phép thử | Kết quả |
+|---|---|---|
+| 1 | `build` · `self-check` · `test` · `lint-trace` | ✅ 212/212 |
+| 2 | `git diff --stat` — đúng 1 file nguồn | ✅ |
+
+**Phép thử tay chưa chạy** — cần PRD thật. Ca **3** là phép thử quyết định:
+
+| # | Phép thử | Kết quả mong đợi |
+|---|---|---|
+| 3 | UC có `.feature` với tag trỏ ≥3 luật · chạy `/qc-analyze` | Report in `Guard BR-tag: khớp N/N` |
+| **4** | 🔴 Xoá tay một `BR-xx` khỏi `REQUIREMENT_ANALYSIS.md`, chạy lại | In `⚠️ bổ sung 1 rule…` **và** file có lại rule đó **kèm nội dung thật từ PRD** |
+| 5 | Sinh một `BR` mà không tag nào nhắc | **Không** bị coi là lỗi; được ghi thành gap trong `DOC_GAP.md` |
+
+Ca 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**, không chỉ kiểm có dòng.
+
+**Thành thật về giới hạn:** không có test tự động cho bước này. Bốn lệnh kiểm chỉ canh contract của framework — chúng không chạy `/qc-analyze` lên một PRD. Guard này chỉ được chứng minh khi có người chạy ca 4.
+
+## B5 · Bài học
+
+- **2026-09-11** — Không có gì lệch kế hoạch ở bước này; nó chạy đúng như `exec-d1-b1` mô tả. Ghi lại để đối chiếu: **6 trong 12 bước** của hai đợt lệch kế hoạch, và điểm chung của 6 bước đó là **kế hoạch viết trước khi đọc kỹ file đích**. Bước này kế hoạch viết sau khi đã grep xác nhận `/qc-design-test` không có phép kiểm tương đương — nên không lệch.
+  → **Bài học chuyển giao được:** tỷ lệ kế hoạch-lệch-thực-tế là một chỉ số về việc **kế hoạch có được viết trên dữ liệu hay không**, chứ không phải về việc kế hoạch tốt hay dở.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | Nguyên tắc **so với một nguồn khác, do một tác nhân khác ghi** — đó là điều phân biệt một phép kiểm thật với một lượt tự đọc lại. Nguyên tắc **guard tự sửa rồi mới báo**. Nguyên tắc **chiều ngược không phải lỗi** — một phép so hai tập thường chỉ có một chiều là sai sót, chiều kia là phát hiện |
+| ⚠️ **Chỉ đúng ở đây** | Tên tag `@trace.business_rules`, định dạng `BR-xx`, và việc BDD được sinh ra từ PRD nên tag đáng tin — đều gắn với pipeline này |
+
+## B7 · Link
+
+- Kế hoạch trước khi làm: [`../exec-d1-b1-guard-br-tag.md`](../exec-d1-b1-guard-br-tag.md)
+- Bước liên quan: [`1-02`](1-02-guard-sc-coverage.md) (guard anh em — chiều *đếm* thay vì *so khớp*) · [`1-04`](1-04-self-review-dung-chung.md) (ranh giới guard vs tự kiểm)

package/docs/plans/qc-surgery/buoc/1-02-guard-sc-coverage.md

@@ -0,0 +1,153 @@
+# Guard SC coverage — mọi kịch bản phải có ít nhất một test case
+
+| | |
+|---|---|
+| **Đợt** | 1 — Nền tảng |
+| **Bước** | **2/6** của Đợt 1 |
+| **File sửa** | `commands/qc-design-test.tmpl` |
+| **File test** | Không có test tự động — xem B4 |
+| **Ngày xong** | 2026-09-11 · commit `249c233` |
+| **Phụ thuộc** | không có |
+| **Ai dùng nó** | `/qc-design-test`; con số nó tính ra là đầu vào của `/qc-report` ở Đợt 3 |
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+
+## A1 · Vấn đề
+
+Một tính năng có 6 tình huống cần kiểm. Đội kiểm thử viết 11 bài kiểm tra — nghe có vẻ dư dả. Nhưng 11 bài đó dồn vào 4 tình huống, còn **2 tình huống không có bài nào**.
+
+Không ai biết. Và đến cuối, hai tình huống đó nằm im ở trạng thái *"chưa chạy"* — **trông y hệt** hai tình huống đã có bài kiểm nhưng chưa tới lượt chạy.
+
+Hai trạng thái đó dẫn tới hai việc hoàn toàn khác nhau — **viết bài kiểm**, so với **chạy bài kiểm** — mà nhìn vào sổ thì giống nhau.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+> **Như điểm danh.** Không đếm xem có bao nhiêu người trong phòng — mà **gọi tên từng người
+> trong danh sách** và xem ai không có mặt. Hai cách cho ra hai con số rất khác nhau khi có
+> người ngồi trùng chỗ.
+
+Ở đây: không đếm xem viết được bao nhiêu bài kiểm, mà **đi từ danh sách tình huống** và hỏi từng cái *"có bài nào phủ chưa?"*.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Cuối báo cáo có thêm dòng `Guard SC coverage: khớp 6/6`. Nếu thiếu, lệnh **viết bù ngay** rồi mới báo — kèm danh sách tình huống đã bù.
+
+Và con số `{K}/{total}` vốn đã in ở báo cáo từ trước giờ **có một phép tính đứng sau nó**, thay vì là ước lượng.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **Tình huống (`SC` — scenario)** — một trường hợp cụ thể cần kiểm, viết sẵn trong tài liệu kịch bản.
+- **Bài kiểm (`TC` — test case)** — mô tả các bước kiểm một tình huống.
+- **Coverage (độ phủ)** — tỷ lệ tình huống đã được bài kiểm phủ tới.
+
+---
+
+> ### ✅ 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 — cho phép "bỏ trống có lý do"
+
+Đây là cách **kế hoạch của tôi đề xuất**, và nó sai — phát hiện lúc đọc lệnh, trước khi viết.
+
+Lập luận nghe rất hợp lý: có tình huống thật sự chưa viết được test case, vì một khoảng trống trong tài liệu (`gap`) chặn lại. Nên cho phép bỏ qua **nếu** trỏ tới một `GAP-xx` có thật.
+
+Sai vì lệnh **đã có quy ước ngược lại** — `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`."*
+
+Nghĩa là: **gap không phải cái cớ để không viết test case — nó là thứ được GHI VÀO test case.** Tình huống bị chặn vẫn có test case (mang dấu `🚫 Block`), vẫn được tính là đã phủ.
+
+Thêm đường thoát như kế hoạch là **dạy hai luật trái nhau trong cùng một lệnh**, và tệ hơn: nó cho agent một **câu-lý-do-cho-qua**. Guard viết lỏng thì lần sau sẽ có một câu lý do chung chung, và phép đếm mất nghĩa.
+
+Bản triển khai vì vậy **nghiêm hơn mà đơn giản hơn** — chỉ hai trạng thái, không cái nào cho phép bỏ trống.
+
+### Cách sai thứ hai — đợi báo cáo cuối tính là đủ
+
+`/qc-report` ở Đợt 3 sẽ tính **design coverage** bằng **đúng phép đếm này**. Vậy làm hai lần để làm gì?
+
+Sai vì **thời điểm**. Guard đếm **lúc thiết kế** — còn kịp viết bù. Báo cáo đếm **ở cuối** — chỉ còn kịp báo. Phát hiện *"design coverage 68%"* ở phút chót là lúc không còn thời gian viết bù 32%.
+
+## B2 · Cách làm đúng
+
+**Phát hiện lúc đọc lệnh:** report **đã 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ì. Con số tồn tại như một ước lượng. Guard là phép đếm đứng sau nó, cộng với hệ quả.
+
+**Ba bước:**
+
+```
+1. Thu SC — mọi @trace.scenario trong .feature của uc_list (đúng nền).
+            LOẠI SC của UC mà qc-scope đã lọc ra (⏸ chưa xét — BDD chưa approved):
+            chúng ngoài phạm vi lần chạy này, không phải bỏ sót.
+2. Thu V  — mọi @trace.verifies trong các file *.Test.md VỪA GHI.
+3. Đếm    — mỗi SC ∈ tập bước 1 phải có ≥ 1 TC trỏ tới.
+```
+
+**Chỉ còn hai trạng thái, không cái nào cho phép bỏ trống:**
+
+| | Xử lý |
+|---|---|
+| SC **trong** phạm vi | Phải có TC. Bị gap chặn → TC mang dấu `🚫 Block` |
+| SC **ngoài** phạm vi | `qc-scope` đã lọc ở bước 1, 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 trên → **đó là một gap**: mở gap trong `DOC_GAP.md`, viết TC kèm `🚫 Block` trỏ tới nó.
+
+**In dòng `Guard SC coverage:` kể cả khi sạch** — cùng lý do với [`1-01`](1-01-guard-br-tag.md).
+
+## 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ột tình huống không có bài kiểm nào |
+| Ai phát hiện | Không ai — trong sổ trace nó là `qc_status = not_run`, **trông y hệt** một tình huống đã có bài kiểm nhưng chưa chạy |
+| Sau bao lâu | Không bao giờ, trừ khi có người ngồi đối chiếu tay |
+| Vì sao đắt | Hai trạng thái *"chưa viết"* và *"đã viết, chưa chạy"* dẫn tới hai việc khác nhau hoàn toàn, mà **không có chỗ nào trong hệ thống phân biệt được**. Guard này là chỗ duy nhất |
+
+Và nó truyền sang Đợt 3: `/qc-report` sẽ ra verdict `PASS/FAIL` dựa trên coverage — con số đó vô nghĩa nếu mẫu số chưa từng được kiểm.
+
+## B4 · Verify bằng gì
+
+| # | Phép thử | Kết quả |
+|---|---|---|
+| 1 | `build` · `self-check` · `test` · `lint-trace` | ✅ 212/212 |
+| 2 | `git diff --stat` — đúng 1 file nguồn | ✅ |
+
+**Phép thử tay chưa chạy** — ca **4** và **5** là phép thử quyết định:
+
+| # | Phép thử | Kết quả mong đợi |
+|---|---|---|
+| 3 | UC có `.feature` ≥5 scenario, chạy `/qc-design-test` | Report in `Guard SC coverage: khớp K/K` |
+| **4** | Xoá hết TC trỏ tới một SC, chạy lại | In `⚠️ (K-1)/K` **và viết bù TC** |
+| **5** | 🔴 Thử để agent ghi lý do *"tương tự SC2"* | Guard **không** chấp nhận — phải viết TC (kèm `🚫 Block` nếu bị gap chặn) |
+| 6 | UC có BDD chưa `approved` | SC của UC đó **không** tính vào mẫu số |
+
+Ca 5 là chỗ dễ hỏng nhất. Nếu guard nhận một câu lý do chung chung thì nó đã tự vô hiệu hoá — và đó chính là điều bản kế hoạch suýt làm.
+
+## B5 · Bài học
+
+- **2026-09-11** — Kế hoạch thiết kế một đường thoát mâu thuẫn với quy ước `🚫 Block` **đã có trong chính lệnh đó** (`:137`). Lỗi lộ ra khi đọc lệnh để tìm chỗ chèn guard — tức **sau khi viết kế hoạch, trước khi viết code**.
+  → **Bài học chuyển giao được:** trước khi thêm một **ngoại lệ** vào một luật mới, đọc xem luật cũ **đã xử lý ca đó chưa**. Ở đây ca "bị gap chặn" đã có cách xử lý rồi (ghi vào TC), và thêm ngoại lệ là tạo ra cách xử lý thứ hai cho cùng một tình huống — hai cách thì agent sẽ chọn cách dễ hơn.
+
+- **2026-09-11** — Report đã có sẵn con số `{K}/{total}` mà **không có phép tính nào đứng sau**. Đây là một dạng nợ khó thấy: nhìn vào report thì tưởng đã có kiểm.
+  → **Bài học chuyển giao được:** một con số trong báo cáo **không chứng minh** có phép đo. Khi rà một hệ thống, tìm cả **chỗ có số mà không có phép tính**, không chỉ tìm chỗ thiếu số.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | Nguyên tắc **đếm từ danh sách gốc, không đếm sản phẩm** (điểm danh, không đếm đầu người). Nguyên tắc **đừng thêm ngoại lệ khi luật cũ đã xử lý ca đó**. Và: **kiểm sớm ở chỗ còn sửa được**, không đợi báo cáo cuối — cùng một phép đếm, giá trị khác hẳn theo thời điểm |
+| ⚠️ **Chỉ đúng ở đây** | Tag `@trace.scenario`/`@trace.verifies`, quy ước `🚫 Block`, và việc `qc-scope` lọc UC theo trạng thái BDD |
+
+## B7 · Link
+
+- Kế hoạch trước khi làm: [`../exec-d1-b2-guard-sc-coverage.md`](../exec-d1-b2-guard-sc-coverage.md) — đã ghi lại đường thoát bị bỏ, kèm bản gốc
+- Bước liên quan: [`1-01`](1-01-guard-br-tag.md) (guard anh em) · Đợt 3 `/qc-report` (dùng đúng phép đếm này để tính design coverage)