@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/core/commands/qc-analyze.md

@@ -10,7 +10,9 @@ ported_from: ai-automation-qc-base
 
 ## Gate
 
-*Checkpoint: **chặn thường** — lệnh ghi 2 file artifact. `--yes` bỏ qua được (gate Bước 3a).*
+*Checkpoint: **chặn CỨNG** — ghi đè DOC_GAP.md đã có → mất cột Trạng thái/Câu trả lời (PO điền TAY, KHÔNG sinh lại được), ĐÁNH SỐ LẠI GAP-ID, phá 🚫 Block trong mọi .Test.md đã sinh. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng chỉ áp khi `DOC_GAP.md` **đã tồn tại** — lần chạy đầu không ghi đè gì, đi thẳng. Xem §Chạy lại.*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -183,14 +185,26 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 rồi mới tiếp tục phần bên dưới.
 
 Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
-`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--force`).
 Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
 cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
 
+---
+
+## Stamp phiên bản nguồn
+
+**BẮT BUỘC — đọc `.agent/steps/qc-stamp.md` và thực thi phần áp cho lệnh này**,
+rồi mới tiếp tục phần bên dưới.
+
+Nó có **hai vế**: §1 **ghi** khối `Nguồn & phiên bản` vào artifact lệnh này sinh ra ·
+§2 **so** stamp của artifact lệnh này ĐỌC với version hiện tại của spec.
+Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp thành một con số không ai
+đọc — và một bộ TC lỗi thời sẽ chạy xanh rồi ghi `pass` **hợp lệ theo mọi phép kiểm**.
+
 > **QC chạy trên BDD chưa chốt có thể phải làm lại.** `qc-scope` mặc định chỉ lấy UC có
 > `@trace.status: approved`; UC còn nháp vẫn vào bảng *Phạm vi phân tích* của `DOC_GAP.md`
 > với dấu `⏸ Chưa xét` — **không im lặng bỏ khỏi bảng**, vì "chưa xét" khác "đã xét, sạch".
-> Cố ý QC sớm thì thêm `--include-draft`, và artifact phải ghi rõ nó dựa trên BDD nháp.
+> Cố ý QC sớm thì thêm `--force`, và artifact phải ghi rõ nó dựa trên BDD nháp.
 
 > **Vì sao trạm này chạy CẢ PRD chứ không từng UC** *(B11)*. Ba lý do, theo thứ tự quan trọng:
 >
@@ -287,6 +301,56 @@ và ghi lại mapping — **làm cho từng UC trong `uc_list`**, và `BR`/`AC`
 (một file phân tích giờ phủ nhiều UC, nên `BR-01` không còn tự phân biệt được là của UC nào) — qc-design-test và qc-run-test cần nó để gắn tag
 `@trace.verifies` cho test và ghi `qc_status` theo từng scenario.
 
+## Guard — BR-tag *(phép so khớp cơ học, chạy SAU khi ghi file, TRƯỚC CHECKPOINT)*
+
+§Trace mapping ở trên đi **một chiều**: từ `BR` bạn tạo ra → `SC` sở hữu nó. Chiều đó đúng và
+cần. Nhưng chiều **ngược lại** — từ tag `@trace.business_rules` đã có trong `.feature` → `BR`
+trong bản phân tích — mới là chiều 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
+```
+
+Nếu bản phân tích chỉ có `BR01`–`BR05` thì `BR07` là **rule mà 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** — đọc **mọi** `.feature` của `uc_list` (đúng `active_platform`), gom toàn bộ giá trị
+   trong tag `@trace.business_rules`.
+2. **Thu B** — gom mọi `BR-xx` trong `REQUIREMENT_ANALYSIS.md` **vừa ghi**.
+3. **So** — `A ∖ B` = rule BDD nhắc mà phân tích không có.
+4. **Xử lý:**
+   - `A ∖ B` rỗng → in `Guard BR-tag: khớp {n}/{n}`
+   - `A ∖ B` ≠ rỗng → **quay lại PRD lấy nội dung thật của từng rule đó, BỔ SUNG NGAY vào
+     `REQUIREMENT_ANALYSIS.md`**, rồi in:
+     `⚠️ Guard BR-tag: bổ sung {k} rule BDD đã nhắc mà phân tích bỏ sót: {danh sách}`
+
+**Guard TỰ SỬA, không chỉ tự báo.** In cảnh báo rồi để người đi lấp là thêm một dòng nữa để bỏ
+qua. Bạn phải mở PRD, tìm rule đó, viết nội dung thật vào bản phân tích — **không** thêm một
+dòng trống mang tên `BR-xx` cho đủ số. 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 đó.
+
+**Chiều `B ∖ A` KHÔNG phải lỗi.** QC sinh `BR09` mà không tag nào nhắc → có thể QC phát hiện một
+rule BDD chưa phủ. Đó là **phát hiện tốt**: ghi thành một gap trong `DOC_GAP.md` (BDD thiếu
+scenario cho rule này), **đừng xoá**.
+
+**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.
+
+> **Vì sao cần guard mà không phả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
+> `.feature`, do một lệnh khác ghi) rồi đối chiếu — không phụ thuộc agent có để ý hay không, và
+> chạy như nhau mỗi lần.
+>
+> **Vì sao bỏ sót ở đây đắt nhất trong cả pipeline.** 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-test` không có gì chạy → báo cáo
+> cuối nói *"coverage 100%"*. Con số đó tính trên mẫu số *"số scenario đã biết"*, không phải
+> *"số rule cần phủ"* — nên nó sai theo hướng nguy hiểm nhất: trông như đã xong.
+
 ## Quét gap — hai nguồn, gộp rồi mới thẩm định
 
 Gap đến từ **hai chỗ**, và chúng bổ sung nhau chứ không thay thế:
@@ -360,9 +424,18 @@ biệt bằng cột `UC`:
   gap. UC ngoài phạm vi ghi `⏸ Chưa xét`, **không bỏ khỏi bảng**.
 - Mỗi gap phân loại MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, với severity (🔴 Blocker → ⚪ Low) và function/BR/AC bị ảnh hưởng.
 - Không bao giờ bịa câu trả lời; đánh dấu giả định là `ASSUMPTION` để PO/dev confirm.
-- Bất kỳ `🔴 Blocker` nào còn `Open` ⇒ **UC ở cột `UC` của hàng đó** chưa sẵn sàng cho
-  qc-design-test — bàn giao cho qc-plan. *Chặn theo từng UC, KHÔNG chặn cả PRD:* một blocker ở
-  UC3 không có lý do gì dừng việc thiết kế test cho UC1. Ghi rõ UC nào bị chặn ở report.
+- Bất kỳ `🔴 Blocker` nào còn `Open` ⇒ **UC ở cột `UC` của hàng đó** chưa sẵn sàng **để nghiệm
+  thu** — bàn giao cho qc-plan. *Chặn theo từng UC, KHÔNG chặn cả PRD:* một blocker ở UC3 không
+  có lý do gì dừng việc thiết kế test cho UC1. Ghi rõ UC nào bị chặn ở report.
+
+  > **"Chưa sẵn sàng" ≠ "chưa được thiết kế"** *(G66)*. `/qc-design-test` **vẫn chạy được và nên
+  > chạy** trên UC bị chặn — TC chạm gap mang dấu `🚫 Block: [GAP-UC{N}-{nnn}]` trỏ về hàng gap,
+  > vẫn được `Guard SC coverage` đếm là đã phủ, và **chưa chạy** tới khi gap `Answered`.
+  > Cái bị chặn là **chạy test**, không phải **viết test**.
+  >
+  > *Mã gap mang UC (`GAP-UC1-003`) và luật "đánh số độc lập trong từng UC" ở trên **chỉ có nghĩa
+  > vì** test case đang trỏ vào các mã đó. Hiểu "chưa sẵn sàng" thành "đừng thiết kế" là giết cả
+  > cơ chế đó.*
 - **Đẩy các defect spec thực sự lên PO (không chỉ giữ local).** Một blocker là lỗi thật
   trong spec chính thức — `AMBIGUOUS` / `CONTRADICTORY` / `MISSING` trong PRD/BDD — phải tới
   PO qua feedback flow, không chỉ nằm trong `DOC_GAP.md`: tạo `/report-bug {UC-ID} {desc}`
@@ -390,6 +463,61 @@ nó bị loại. Cập nhật `Tổng số gap` + bảng ưu tiên sau khi áp v
 > được. Mà gap ảo không chỉ tốn thời gian PO: nó **làm PO mất tin vào cả danh sách**, và lúc đó
 > những gap thật cũng chết theo. `gap-verify` là bộ lọc duy nhất đứng giữa hai chuyện đó.
 
+## Chạy lại — `DOC_GAP.md` đã tồn tại *(THÊM, không THAY)*
+
+Chạy lại trạm này là chuyện bình thường: spec đổi thì phải phân tích lại. Nhưng `DOC_GAP.md` có
+**hai phần khác hẳn nhau**, và chỉ một phần sinh lại được:
+
+| Phần | Ai tạo | Sinh lại được? |
+|---|---|:---:|
+| Mô tả gap · phân loại · severity · UC | lệnh này | ✅ |
+| **Cột `Trạng thái`** (`Open`/`Answered`) · **cột `Câu trả lời`** | **PO điền TAY** | ❌ **không bao giờ** |
+| **Mã `GAP-UC{N}-{nnn}`** | lệnh này, nhưng **`.Test.md` đang trỏ vào** | ❌ đổi là phá |
+
+**Đọc file cũ TRƯỚC khi ghi.** Với mỗi gap:
+
+| Tình huống | Xử lý |
+|---|---|
+| Gap cũ, phân tích lại **vẫn thấy** | **Giữ nguyên** mã · `Trạng thái` · `Câu trả lời`. Chỉ cập nhật phần mô tả nếu spec đổi |
+| Gap cũ, phân tích lại **không thấy nữa** | **KHÔNG xoá hàng.** `Trạng thái` → `Stale`, ghi lý do *"lần phân tích {ngày} không còn thấy"* |
+| Gap **mới** | Cấp mã **tiếp theo** trong UC đó |
+
+**Đánh số: CHỈ CẤP MỚI, không bao giờ tái dùng.** Mốc là **mã cao nhất từng cấp** cho UC đó — kể cả
+khi gap mang mã ấy đã `Answered` hoặc `Stale`. Không dồn số, không lấp chỗ trống.
+
+> **Tái dùng một mã là kịch bản tệ nhất của cả mục này.** `🚫 Block: [GAP-UC1-003]` trong một
+> `.Test.md` cũ vẫn **đúng cú pháp**, vẫn resolve được, và giờ trỏ vào **một câu hỏi hoàn toàn khác**.
+> Không lint nào bắt, không người nào nhìn ra. Liên kết **chết** thì còn thấy được; liên kết **trỏ
+> sai nội dung** thì không.
+
+**Gap `Stale` KHÔNG xoá hàng** — một `.Test.md` có thể đang trỏ vào nó. Xoá là biến `🚫 Block` thành
+liên kết chết, và `/qc-design-test` §Guard vòng đời `🚫 Block` sẽ không phân giải được.
+
+### Lập lại từ trắng — phải nói ra
+
+Có ca hợp lệ: bản phân tích cũ sai hẳn, muốn bỏ. Cờ là **`--force`** (`rules/workflow.md` §Cờ bỏ qua
+điều kiện). Không có cờ → **DỪNG** và nêu rõ cái giá:
+
+```
+❌ DOC_GAP.md đã tồn tại ({n} gap · {k} đã Answered).
+   Mặc định: HOÀ vào bản cũ — giữ mã gap, giữ Trạng thái/Câu trả lời của PO.
+   Muốn bỏ hẳn bản cũ, lập lại từ trắng: thêm --force
+   ⚠️ --force sẽ XOÁ {k} câu trả lời của PO, và làm mọi 🚫 Block trong .Test.md trỏ sai.
+```
+
+Có `--force` → report **bắt buộc** khai:
+```
+⚠️ --force: bỏ qua luật hoà — đã xoá {k} câu trả lời của PO và {n} mã gap cũ.
+   Mọi 🚫 Block trong .Test.md của {TICKET-ID} giờ trỏ sai → chạy lại /qc-design-test cho các UC đó.
+```
+
+> **Vì sao hoà là MẶC ĐỊNH còn lập-lại phải xin.** Cái thường gặp phải là cái an toàn; cái phá huỷ
+> phải nói ra — cùng lập luận `steps/qc-scope.md` dùng cho `approved`-only.
+>
+> **Vì sao gap ảo làm hỏng nhiều hơn một file.** §Thẩm định ở trên đã ghi: *"gap ảo … làm PO **mất
+> tin vào cả danh sách**, và lúc đó những gap thật cũng chết theo"*. Gửi lại PO một câu hỏi **họ đã
+> trả lời rồi** gây đúng thiệt hại đó — và nó còn tệ hơn, vì nó chứng minh hệ thống không nhớ.
+
 ## Output
 
 Ghi **hai file** dưới `{qc_artifact_dir}` (= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/`)
@@ -471,9 +599,15 @@ summary:
 > Review Board có nút *"chấp nhận rồi tự sửa PRD"*. Với gap của `/refine-prd` thì đúng — nó chạy
 > ở **thời điểm PRD**, sửa PRD lúc đó là sửa đúng chỗ đúng lúc.
 >
-> Gap của lệnh này phát hiện **sau khi code đã xong**. Tự sửa PRD ở thời điểm đó là **sửa sau lưng
-> cả dây chuyền**: BDD sinh từ PRD cũ, code sinh từ BDD đó, sổ kết quả kiểm thử neo vào scenario
-> của BDD đó. Đổi PRD mà không đi lại đường ấy thì mọi thứ phía sau nói dối.
+> Gap của lệnh này phát hiện **sau khi BDD đã `approved` và tech-doc đã duyệt** — ở luồng song song,
+> thường là lúc `/generate-code` đang chạy ở nhánh bên kia. Tự sửa PRD ở thời điểm đó là **sửa sau
+> lưng cả dây chuyền**: BDD sinh từ PRD cũ, tech-doc và hợp đồng test-id §4.5.6 chốt theo BDD đó,
+> code đang được sinh từ chúng, và sổ kết quả kiểm thử neo vào scenario của BDD đó. Đổi PRD mà không
+> đi lại đường ấy thì mọi thứ phía sau nói dối.
+>
+> *(Bản trước viết tiền đề là **"sau khi code đã xong"**. Kết luận đúng, tiền đề **hết đúng** từ khi
+> `a3a5f30` mở luồng FE ∥ QC song song — trạm này giờ chạy khi code còn chưa xong. Sửa tiền đề chứ
+> không sửa kết luận: cái chặn không phải là **code**, mà là **BDD + tech-doc đã đóng băng**.)*
 >
 > Đường đúng vẫn là kênh đã có: `/report-bug` cho defect spec thật, `/propose-scenario` cho thiếu
 > độ phủ. File `.yaml` này để **PO đọc và quyết trong một chỗ quen**, không phải để máy tự áp.
@@ -486,6 +620,24 @@ người sửa sau lưng, mỗi lần chạy đều quét lại toàn bộ kèm
 
 ---
 
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mỗi `BR-xx`/`AC-xx` trích được về đúng dòng nào của PRD/BDD — không phải rule tôi tự
+  thêm? Mỗi gap `CONTRADICTORY` nêu được **cả hai** chỗ nói khác nhau, không phải một bên?
+- **Nhảy bước:** đã chạy đủ 4 kỹ năng phân tích + 4 lăng kính + §Đối chiếu tài liệu kỹ thuật —
+  không bỏ lăng kính nào vì "UC này đơn giản"?
+- **Số liệu:** `{N}` gap · `{blockers}` blocker · `{M}` BR/AC in ở report là **đếm thật trên
+  bảng vừa ghi** (`grep -cE "^\| GAP-"`), không phải áng chừng?
+
+> **`gap-verify` và self-review bổ sung nhau, KHÔNG thay nhau.** `gap-verify` kiểm **từng
+> finding** có sống sót qua T1–T6 (sâu, per-finding). Self-review kiểm **cả lượt chạy** có bịa /
+> nhảy bước / đếm sai (rộng, per-run). Chạy một cái rồi bỏ cái kia là bỏ một nửa lưới.
+>
+> Và cả hai **không thay** Guard BR-tag ở trên — guard đó là phép so khớp cơ học, xem §Ranh giới
+> trong file skill.
+
 ## Report
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
@@ -506,6 +658,8 @@ Chéo UC: {X} mâu thuẫn giữa các UC của cùng PRD (đã ghi vào REQUIRE
 Chặn  : {danh sách UC có 🔴 Blocker còn Open} — các UC còn lại vẫn thiết kế test được bình thường
 Chờ chốt: {G} ẩn số §12 tech-doc đang open chạm các UC này (đã ghi vào REQUIREMENT_ANALYSIS, KHÔNG hỏi lại PO)
 SC map: {M} BR/AC map tới {K} scenario
+Guard BR-tag: {khớp {n}/{n} | ⚠️ bổ sung {k} rule BDD đã nhắc mà phân tích bỏ sót: {danh sách}}
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
 Next  : /qc-plan {TICKET-ID} {active_platform}   ← rủi ro / what-if / câu hỏi cho dev
         (giải quyết các gap 🔴 Blocker với PO/Dev trước)
 ```

package/core/commands/qc-design-test.md

@@ -10,7 +10,9 @@ ported_from: ai-automation-qc-base
 
 ## Gate
 
-*Checkpoint: **chặn thường** — lệnh ghi file test-case. `--yes` bỏ qua được (gate Bước 3a).*
+*Checkpoint: **chặn CỨNG** — ghi đè `*.Test.md` đã qua cổng HITL `/qc-review` → mất `Status` đã duyệt, `Expected Result` đã sửa theo finding, dấu 🚫 Block vừa gỡ; và ĐÁNH SỐ LẠI `TC_<FEATURE>_NNN` mà `REVIEW_<FEATURE>.md` đang trỏ vào. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng chỉ áp khi file `.Test.md` **đã tồn tại**. Lần thiết kế đầu không ghi đè gì, đi thẳng. Xem §Chạy lại.*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -181,10 +183,22 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 rồi mới tiếp tục phần bên dưới.
 
 Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
-`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--force`).
 Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
 cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
 
+---
+
+## Stamp phiên bản nguồn
+
+**BẮT BUỘC — đọc `.agent/steps/qc-stamp.md` và thực thi phần áp cho lệnh này**,
+rồi mới tiếp tục phần bên dưới.
+
+Nó có **hai vế**: §1 **ghi** khối `Nguồn & phiên bản` vào artifact lệnh này sinh ra ·
+§2 **so** stamp của artifact lệnh này ĐỌC với version hiện tại của spec.
+Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp thành một con số không ai
+đọc — và một bộ TC lỗi thời sẽ chạy xanh rồi ghi `pass` **hợp lệ theo mọi phép kiểm**.
+
 > **Trạm này vẫn gọi theo TỪNG UC** *(B11)* — thiết kế và chạy test **thật sự** làm tăng dần
 > theo UC, nên giữ khả năng làm UC1 khi UC3 chưa xong là đúng. Chỉ **chỗ đọc/ghi** đổi: mọi
 > artifact nằm chung ở `{qc_artifact_dir}` cấp PRD, không còn một thư mục mỗi UC.
@@ -194,6 +208,58 @@ cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắ
 
 ---
 
+## Guard — tiền đề *(chạy NGAY SAU §Phạm vi QC, TRƯỚC mọi việc khác của lệnh)*
+
+Trạm này là **trạm 3**. Nó **tiêu thụ** output của trạm 1 và trạm 2 — không tự sinh lại được.
+Kiểm sự tồn tại của cả ba file dưới `{qc_artifact_dir}`:
+
+| File | Do lệnh nào sinh | Trạm này dùng để |
+|---|---|---|
+| `REQUIREMENT_ANALYSIS.md` | `/qc-analyze` | neo `BR-xx`/`AC-xx` cho trường `Trace:` của mỗi TC |
+| `DOC_GAP.md` | `/qc-analyze` | gắn `🚫 Block` cho TC bị gap chặn |
+| `TEST_PLAN.md` | `/qc-plan` | độ sâu theo rủi ro (P0/P1) · layer trong scope · entry criteria |
+
+**Thiếu bất kỳ file nào → DỪNG.** Không hỏi Y/N, không cảnh báo rồi đi tiếp:
+
+```
+❌ {TICKET-ID} ({active_platform}): thiếu đầu vào của trạm 3.
+   Không có: {danh sách file thiếu}
+   Chạy trước: /qc-analyze {TICKET-ID} {active_platform}
+         rồi: /qc-plan {TICKET-ID} {active_platform}
+```
+
+**Đủ cả ba → im lặng, đi tiếp.** Guard này là **điều kiện vào cửa**, không phải phép đo: "đủ file"
+không phải một phát hiện, nên không in dòng nào. *(Khác `Guard BR-tag` và `Guard SC coverage` —
+hai cái đó là phép ĐẾM, con số của chúng có giá trị ngay cả khi sạch, nên chúng luôn in.)*
+
+> **Vì sao DỪNG chứ không cảnh báo rồi chạy.** Guard duy nhất còn lại của trạm này —
+> `Guard SC coverage` — đối chiếu TC với `.feature`, mà `.feature` ở spec repo thì **luôn có mặt**,
+> không mất theo khi trạm 1–2 chưa chạy. Nên nó vẫn in `khớp K/K` và lần chạy thiếu đầu vào
+> **không phân biệt được** với một lần chạy đúng.
+>
+> Thiếu `DOC_GAP.md` là ca đắt nhất: TC bị gap chặn **trông y hệt** TC bình thường (không có dấu
+> `🚫 Block` nào), nên `/qc-run-test` chạy nó, thấy đỏ, và `/qc-report` phân loại thành *product-gap*
+> rồi in một `/report-bug` sẵn-chạy. Lỗi đi **ra khỏi đội QC** thành bug gửi PO — cho một hành vi
+> mà spec chưa bao giờ định nghĩa. Đây là **báo cáo sai**, cùng loại với việc giữ một `pass` đã hết
+> hiệu lực (`rules/workflow.md` §*"Làm mất hiệu lực ≠ ghi đè"*).
+>
+> **Vì sao DỪNG chứ không hỏi Y/N.** Một cổng chỉ chặn được khi có người ngồi đó thì ở chế độ
+> headless nó không phải cổng, nó là **treo** — cùng bài học với `steps/qc-scope.md` §2.
+>
+> **Vì sao `--yes` KHÔNG bỏ qua được.** `--yes` nghĩa *"tôi không ngồi đây để trả lời"*, không phải
+> *"tôi chấp nhận thiết kế test không có phân tích gap"*. Gộp hai nghĩa là để một lần chạy headless
+> âm thầm sinh ra một bộ test case thiếu mọi dấu chặn.
+>
+> **Vì sao cả ba file đều bắt buộc, không miễn trừ `TEST_PLAN.md`.** Không có luồng hợp lệ nào có
+> file 1–2 mà thiếu file 3: `Next` của `/qc-analyze` chính là `/qc-plan`. Miễn trừ nó là mở một
+> đường tắt không ai xin.
+>
+> **Chỉ kiểm SỰ TỒN TẠI, không kiểm nội dung hay độ tươi.** Ba file này có còn khớp spec hiện tại
+> không là một câu hỏi khác, và nó cần một cơ chế khác (đóng dấu version nguồn). Trộn hai việc vào
+> một guard thì guard này không bao giờ landing được.
+
+---
+
 ## Cờ — chọn tầng nào, tách mịn đến đâu
 
 | Cờ | Ghi file | Nhóm |
@@ -314,6 +380,209 @@ vẫn pass/fail, nhưng kết quả không vào được sổ và không ai bi
 
 Cuối file: **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách TC bị block** — cả hai dạng danh sách.
 
+## Guard — SC coverage *(phép ĐẾM cơ học, chạy SAU khi ghi file, TRƯỚC CHECKPOINT)*
+
+Dòng `Trace:` ở report cuối đã đòi con số `{K}/{total}` từ trước. Guard này là **phép tính sinh
+ra con số đó**, và là **hệ quả khi `K < total`** — trước đây có số mà không có phép tính nào
+đứng sau, nên nó là ước lượng, và `K < total` không dẫn tới việc gì.
+
+### Ba bước
+
+1. **Thu SC** — mọi `@trace.scenario` trong `.feature` của **UC đang chạy** (`{UC-ID}`, đúng
+   `active_platform`) — **KHÔNG phải `uc_list`.**
+
+   `uc_list` là mọi UC approved của **cả PRD**; trạm này chạy **per-UC** (§Phạm vi QC), nên lấy
+   `uc_list` làm mẫu số là ép viết TC cho UC **không ai yêu cầu** — bằng dữ liệu đã lọc bỏ phần
+   của chúng ở Gate (*"lọc theo cột `UC` để lấy phần của UC này"*), tức là **viết mù**.
+
+   *Trạm 1 `/qc-analyze` dùng `uc_list` là **đúng** — nó cấp PRD, và mâu thuẫn chéo UC chỉ lộ ra
+   khi đọc cùng lúc. **Đừng copy mẫu số giữa hai trạm khác tầng.** Phép kiểm một câu: mẫu số của
+   một guard phải khớp **phạm vi mà lệnh đó được gọi**.*
+
+   **Không cần lọc `⏸ chưa xét` ở đây nữa:** `qc-scope` §4b đã chặn UC target chưa approved từ
+   trước khi tới bước này. Chạy được tới đây nghĩa là target hoặc đã `approved`, hoặc người dùng
+   đã nêu `--force` tường minh (và artifact đang mang dấu *"dựa trên BDD nháp"*).
+2. **Thu V** — mọi `@trace.verifies` trong **MỌI** `*.Test.md` dưới `{qc_artifact_dir}test-cases/`
+   — **không chỉ file vừa ghi** — rồi lọc lấy giá trị bắt đầu bằng `{UC-ID}-SC`.
+
+   *Thư mục `test-cases/` dùng chung cho **cả PRD** nên phải lọc theo UC. Và lệnh này có **ba chế
+   độ ghi** (§Cờ), hai trong ba chỉ ghi **một nửa**: `--api` chạy sau khi file giao diện đã tồn tại
+   là **chuyện thường** (§B12 ngay dưới bảng Cờ). Chỉ đếm file "vừa ghi" thì lần chạy `--api` thấy
+   độ phủ ≈ 0, rồi luật "viết bù TC ngay" **nhân bản toàn bộ TC giao diện vào file API** — phá đúng
+   ranh giới hai-file mà §B12 dựng lên.*
+
+   **Tiền tố lọc phải gồm cả `-SC`.** `{UC-ID}-SC` chứ **không** phải `{UC-ID}`:
+   `FT-001-UC1-SC` không khớp `FT-001-UC11-SC3`, còn `FT-001-UC1` thì có. Một PRD tới UC thứ 11
+   là đủ để phép lọc sai **trong im lặng**.
+
+   *Quét cả thư mục chứ không đoán theo tên file: tên file mang `<FEATURE>`, **không** mang UC —
+   `@trace.verifies` là chỗ duy nhất nói TC thuộc UC nào (§Output).*
+3. **Đếm** — mỗi SC ∈ tập ở bước 1 phải có **≥ 1** TC trỏ tới.
+
+### Xử lý
+
+| Kết quả | Làm gì |
+|---|---|
+| Mọi SC đều có ≥1 TC | in `Guard SC coverage: khớp {K}/{K}` |
+| Có SC chưa phủ | **viết bù TC ngay** — vào file đúng theo §Câu hỏi phân file, xem luật định tuyến dưới đây — rồi in `⚠️ Guard SC coverage: {K}/{total} — đã bù {m} SC: {danh sách}` |
+
+**TC bù đi vào file nào — theo §Câu hỏi phân file, KHÔNG mặc định vào file của chế độ đang chạy.**
+
+Hỏi từng SC chưa phủ: *"TC cho SC này verify được mà **không cần UI** không?"*
+
+| Trả lời | Chế độ đang chạy | Làm gì |
+|---|---|---|
+| **Có** (không cần UI) | `--api` hoặc `--all` | bù vào **file API** — xong |
+| **Không** (cần UI) | *(không cờ)* hoặc `--all` | bù vào **file giao diện** — xong |
+| **Không** (cần UI) | **`--api`** | **KHÔNG bù vào file API.** SC vẫn tính là **chưa phủ**; in thêm dòng chỉ đường (dưới) |
+
+```
+⚠️ {n} SC cần UI, chưa có TC ở file giao diện — KHÔNG bù vào file API (§Câu hỏi phân file).
+   Chạy: /qc-design-test {UC-ID}    ← không cờ, để bù đúng chỗ
+   SC: {danh sách}
+```
+
+> **Đây KHÔNG phải "bỏ trống có lý do".** Phân biệt bằng một câu: đường thoát làm SC **được tính là
+> đã phủ**; luật này để SC **vẫn nằm trong số chưa phủ** — `{K}/{total}` không đổi, dòng ⚠️ vẫn in,
+> guard vẫn chưa sạch. Nó chỉ đổi **chỗ ghi TC**, không đổi **phép đếm**.
+>
+> Và nó **không** cho agent một câu-lý-do-cho-qua: điều kiện là một phép so cơ học (*"cần UI không?"*
+> — đúng Bước 2 của `shared/skill-decision-tree.md`), không phải một nhận định tự do. Ghi *"SC này
+> phức tạp"*, *"tương tự SC2"* thì **không** rơi vào ô nào của bảng trên.
+>
+> **Vì sao không cứ bù vào file đang mở cho gọn.** File API được `/qc-run-test` đọc bằng lane API.
+> Một TC cần UI nằm ở đó **không chạy nổi** — và nó sẽ đỏ dưới dạng *script-bug* hoặc *product-gap*,
+> không ai truy ngược về một quyết định ghi file ở phase thiết kế.
+
+**Không có đường "bỏ trống có lý do".** Đây là chỗ dễ làm sai nhất, và quy ước ở §Conventions
+đã trả lời: *"Một TC bị block bởi gap **vẫn viết đủ** + `🚫 Block: [GAP-UC{N}-{nnn}](../DOC_GAP.md)`"*.
+Nghĩa là **gap không phải cái cớ để không viết TC** — nó là thứ được **ghi vào TC**. SC bị chặn
+vẫn có TC, vẫn được đếm là đã phủ.
+
+Nên chỉ còn đúng hai trạng thái, và cả hai đều không cho phép bỏ trống:
+
+- SC **của UC đang chạy** → phải có TC (bị gap chặn thì TC mang dấu `🚫 Block`). Đây là **toàn bộ**
+  mẫu số — bước 1 không lấy SC của UC nào khác.
+- SC **của UC khác** → không thuộc lần chạy này, không tính vào mẫu số. *(Muốn phủ chúng thì chạy
+  `/qc-design-test` cho UC đó — đừng viết TC của chúng ở đây.)*
+
+Nếu bạn thấy một SC "không thể viết TC" mà không thuộc hai loại trên, thì **đó là một gap** —
+mở gap trong `DOC_GAP.md`, viết TC kèm `🚫 Block` trỏ tới nó. Đừng viết một câu lý do rồi đi
+tiếp: guard viết lỏng thì lần sau sẽ có một câu lý do cho qua, và phép đếm mất nghĩa.
+
+*(Ca "SC cần UI mà đang chạy `--api`" **không** phải trạng thái thứ ba: SC đó vẫn ở nhóm thứ nhất,
+vẫn tính vào mẫu số, vẫn chưa phủ. Chỉ **chỗ ghi TC** bị hoãn — xem luật định tuyến ở §Xử lý.)*
+
+**In dòng `Guard SC coverage:` 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.
+
+> **Vì sao đếm ở đây mà không đợi báo cáo cuối.** `/qc-report` **sẽ** tính **design coverage** bằng
+> **đúng phép đếm này** — **Đợt 3, CHƯA TRIỂN KHAI** (`docs/plans/qc-surgery/01-checklist.md`, phụ
+> thuộc cứng vào `d2-b2`). Khác nhau ở 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 cuối là lúc không còn
+> thời gian viết bù 32%.
+>
+> **Tới khi Đợt 3 có, guard này là lớp đếm DUY NHẤT — đừng dựa vào một lớp thứ hai chưa tồn tại.**
+> *(Bản trước viết "sẽ tính" ở thì hiện tại, không nêu trạng thái. Một lời hứa không có trạng thái sẽ
+> được đọc như một sự thật — và tệ nhất là khi nó được dùng để biện minh cho việc không đếm ở chỗ khác.)*
+>
+> **Vì sao "chưa có TC" khác "có TC nhưng chưa chạy".** Hai trạng thái này dẫn tới hai việc khác
+> nhau hoàn toàn — viết test, so với chạy test. Nhưng nhìn vào sổ trace thì giống nhau: cả hai
+> đều là `qc_status = not_run`. Guard này là chỗ duy nhất phân biệt được.
+
+## Chạy lại — `.Test.md` đã tồn tại *(GIỮ, không sinh lại từ trắng)*
+
+File `.Test.md` đi qua **cổng HITL `/qc-review`**. Bốn thứ trong đó **không sinh lại được**:
+
+| Mất gì | Vì sao |
+|---|---|
+| `Status` đổi sau review | **kết luận của người**, không suy từ spec |
+| `Expected Result` sửa theo finding | finding nằm ở `REVIEW_<FEATURE>.md` — **lệnh này không đọc file đó** |
+| Dấu `🚫 Block` vừa gỡ | phụ thuộc ô `Câu trả lời` của `DOC_GAP.md` (xem §Guard vòng đời 🚫 Block) |
+| Đánh số `TC_<FEATURE>_NNN` | **`REVIEW_<FEATURE>.md` đang trỏ vào các số đó**, và nó nằm cùng thư mục |
+
+**Đọc file cũ TRƯỚC khi ghi.** Với mỗi TC:
+
+| Tình huống | Xử lý |
+|---|---|
+| TC cũ, spec **không đổi** | **Giữ nguyên** — số · `Status` · `Expected Result` đã sửa |
+| TC cũ, spec **đổi** | Cập nhật **nội dung**; giữ **số** và `Status`, thêm ⚠️ để `/qc-review` soát lại |
+| TC **mới** | Cấp số **tiếp theo** — không dồn, không tái dùng |
+| TC không còn ứng với SC nào | **KHÔNG xoá** → `Status: Obsolete`, ghi lý do |
+
+> **`Obsolete` chứ không xoá** — cùng luật `Stale` của `/qc-analyze` §Chạy lại: `REVIEW_<FEATURE>.md`
+> đang trỏ vào số đó, xoá hàng là biến biên bản soát thành liên kết chết.
+>
+> **§duplicate-check KHÔNG phải lưới cho ca này.** Nó chống **viết trùng** (*"grep trước khi viết"*),
+> không chống **ghi đè**. Hai chuyện khác nhau, và tên nghe giống nhau đủ để tưởng đã có người lo.
+
+### Lập lại từ trắng — phải nói ra
+
+```
+❌ {n} file .Test.md đã tồn tại ({k} TC có Status khác Draft — đã qua review).
+   Mặc định: GIỮ số + Status + Expected đã sửa, chỉ cập nhật nội dung theo spec mới.
+   Muốn bỏ hẳn và thiết kế lại từ trắng: thêm --force
+   ⚠️ --force sẽ XOÁ {k} kết quả review và làm REVIEW_<FEATURE>.md trỏ sai số TC.
+```
+
+---
+
+## Guard — vòng đời `🚫 Block` *(phép so cơ học, chạy SAU khi ghi file, TRƯỚC CHECKPOINT)*
+
+`🚫 Block` có bước **mở** (§Conventions: TC chạm gap thì mang dấu) và một quy trình **đóng** viết
+sẵn ở `{paths.qc_skills_dir}/qa-designer/shared/tc-metadata-format.md` §*Quy trình khi gap được giải
+quyết (Answered)*. Bước đóng đó **chưa lệnh nào gọi** — nên dấu chặn chỉ dán vào, không bao giờ gỡ ra.
+
+Một TC mang `🚫 Block` là một TC có **Expected Result dựa trên giả định chưa ai xác nhận**. Nó nằm
+trong thư mục dùng chung, được `Guard SC coverage` đếm là **đã phủ**, và `/qc-run-test` sẽ nhặt lên.
+
+> **Vì sao stamp phiên bản (§Stamp phiên bản nguồn) KHÔNG phủ ca này.** Gap chuyển `Open → Answered`
+> là một **ô trong `DOC_GAP.md`** — nó **không bump version nào cả**. Mọi drift detector của framework
+> so **nhãn version**; thay đổi trạng thái nằm *bên trong* một tài liệu đi vòng qua tất cả.
+
+### Bốn bước, thuần so chuỗi
+
+1. **Thu B** — mọi `GAP-ID` xuất hiện trong dòng `🚫 Block:` của các `*.Test.md` của UC này.
+2. **Thu A** — mọi `GAP-ID` có `Trạng thái = Answered` trong `DOC_GAP.md` (lọc theo cột `UC`).
+3. **So** — `A ∩ B` = gap đã trả lời mà TC vẫn mang dấu chặn.
+4. **Xử lý:**
+
+| Kết quả | Làm gì |
+|---|---|
+| `A ∩ B` rỗng | in `Guard 🚫 Block: {n} dấu đang mở, 0 cần gỡ` |
+| Có phần tử, **ô `Câu trả lời` ĐÃ điền** | **GỠ NGAY** theo 4 bước của skill: bỏ dấu `🚫 Block` · cập nhật `Expected Result` theo câu trả lời thật · nếu answer đổi scope thì tách/thêm TC. Rồi in:<br/>`🔓 Guard 🚫 Block: gỡ {k} dấu (gap đã Answered): {danh sách GAP-ID}` |
+| Có phần tử, **ô `Câu trả lời` TRỐNG** | **KHÔNG gỡ.** In:<br/>`⚠️ Guard 🚫 Block: {GAP-ID} = Answered nhưng ô "Câu trả lời" trống — không gỡ được, hỏi lại PO.` |
+
+**Guard TỰ SỬA, không chỉ tự báo** — cùng luật `Guard BR-tag` của `/qc-analyze` đã chốt: *"In cảnh
+báo rồi để người đi lấp là thêm một dòng nữa để bỏ qua."*
+
+**Nhưng ô `Câu trả lời` trống thì DỪNG, không đoán.** Gỡ dấu chặn mà không có câu trả lời thật là
+**biến một giả định thành sự thật trong im lặng** — và `Expected Result` sai sẽ fail lúc chạy, rồi
+`/qc-report` phân loại *product-gap* và in một `/report-bug`. Lúc đó một lỗ hổng **tài liệu** đã đi ra
+ngoài đội QC thành **phiếu lỗi sản phẩm** gửi PO.
+
+**In dòng `Guard 🚫 Block:` kể cả khi sạch** — cùng lý do với hai guard kia.
+
+---
+
+## UC đang Blocked — nói ra, KHÔNG chặn
+
+`TEST_PLAN.md` §5 ghi `Ready`/`Blocked` cho mỗi UC (guard tiền đề đã ép file này phải có). Đọc trạng
+thái của UC đang chạy. **`Blocked` là mức ƯU TIÊN, không phải lệnh cấm** — vẫn thiết kế bình thường,
+chỉ in thêm một dòng ở report:
+
+```
+⚠️ {UC-ID} đang Blocked bởi {n} gap 🔴 — TC chạm chúng mang dấu 🚫 Block, chưa chạy được.
+   Gỡ chặn: trả lời {danh sách GAP-ID} với PO → chạy lại lệnh này để tự gỡ dấu.
+```
+
+> **Vì sao không chặn** *(G66)*. `/qc-analyze` nói *"chưa sẵn sàng"* nghĩa là **chưa sẵn sàng để
+> nghiệm thu**, không phải *"chưa được thiết kế"* — và §Conventions của chính lệnh này đã trả lời:
+> *"TC bị block bởi gap **vẫn viết đủ**"*. Chặn ở đây là giết cơ chế `🚫 Block`, thứ được dựng kỹ tới
+> mức có mã gap mang UC, liên kết ngược `../DOC_GAP.md`, và một dòng riêng trong report.
+>
+> Cái bị chặn là **chạy test**, không phải **viết test**.
+
 ## Output
 
 Ghi dưới `{qc_artifact_dir}test-cases/`
@@ -326,6 +595,21 @@ TC thuộc UC nào.
 
 `🚫 Block` trỏ `../DOC_GAP.md` — lên một cấp, vì file gap ở thư mục cha của `test-cases/`.
 
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mỗi TC kiểm một hành vi **spec có nêu** — không phải hành vi tôi cho là hợp lý? Mỗi
+  `Expected` là **giá trị cụ thể** (*"hiển thị text 'Tên lớp: Toán 6A'"*), không phải *"hiển thị
+  đúng"* / *"hoạt động bình thường"*?
+- **Nhảy bước:** đã áp luật ATOMIC cho **mọi** TC (không chỉ vài TC đầu), và đã chạy
+  §duplicate-check trước khi thêm TC mới?
+- **Số liệu:** `{n}` TC mỗi file = `grep -cE "^#{2,4} *TC_"` thật? Các con số phân nhóm (GUI /
+  Validation / Functional / …) cộng lại đúng bằng tổng TC?
+
+> Guard SC coverage ở trên là **phép đếm cơ học**, không phải self-review — nó đối chiếu với
+> `.feature`, một nguồn khác. Đừng coi self-review đã bao nó. Xem §Ranh giới trong file skill.
+
 ## Report
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
@@ -340,6 +624,14 @@ Nhóm : GUI {a} · Validation {b} · Functional {c} · Integration {d} · NFR {e
        {nếu file API: "Endpoint {g} · Integration API/DB/Kafka {h}"}
 Trùng: {k} TC bỏ vì trùng ({j} trùng chéo UC — trỏ trace về UC nguồn thay vì viết lại)
 Block: {blocked} TC bị chặn bởi gap — theo UC: {UC1: n · UC2: n}
+       {nếu UC đang Blocked: "⚠️ {UC-ID} đang Blocked bởi {n} gap 🔴 — trả lời {GAP-ID} với PO
+       rồi chạy lại lệnh này để tự gỡ dấu."}
+Guard 🚫 Block: {{n} dấu đang mở, 0 cần gỡ | 🔓 gỡ {k} dấu (gap đã Answered): {danh sách}
+       | ⚠️ {GAP-ID} = Answered nhưng ô "Câu trả lời" trống — không gỡ được, hỏi lại PO}
 Trace: {N} TC map tới {K}/{total} scenario của {UC-ID}
+Guard SC coverage: {khớp {K}/{K} | ⚠️ {K}/{total} — đã bù {m} SC: {danh sách SC}}
+       {nếu có SC cần UI mà đang chạy --api: "⚠️ {n} SC cần UI chưa có TC ở file giao diện —
+       KHÔNG bù vào file API. Chạy: /qc-design-test {UC-ID} (không cờ). SC: {danh sách}"}
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
 Next : /qc-review {UC-ID}   ← review test case trước khi sinh script
 ```