@educa-corp/sdd-framework 0.9.6 → 0.9.7

package/docs/plans/qc-surgery/01-checklist.md

@@ -1,6 +1,6 @@
 ---
 title: Checklist 20 bước — đợt đại phẫu QC
-updated: 2026-09-11
+updated: 2026-09-16
 ---
 
 # Checklist — đang ở đâu
@@ -19,9 +19,9 @@ updated: 2026-09-11
 
 ```bash
 node bin/build.js            # đúc .tmpl → .md → core/
-node bin/self-check.js       # R1–R16
+node bin/self-check.js       # R1–R18  (R17/R18 thêm ở 0.9.6)
 node test/run.js             # gồm test ngân sách dung lượng core/commands
-node bin/lint-trace.js       # T1–T14 trên sổ trace thật
+node bin/lint-trace.js       # T1–T20 trên sổ trace thật  (T19/T20 thêm ở 0.9.6)
 ```
 
 ---
@@ -73,20 +73,73 @@ node bin/lint-trace.js       # T1–T14 trên sổ trace thật
 
 ---
 
-## Việc dọn bắt buộc — kèm Đợt 2, bỏ là self-check đỏ
+## Việc dọn bắt buộc — đo lại tại HEAD 0.9.6
 
-| | Việc | Lượng |
-|:-:|---|---|
-| [ ] | Sửa file skill còn gọi `TC_<FEATURE>.md` thay `.Test.md` | 14 file |
-| [ ] | Sửa tham chiếu skill treo `qa-script-runner/report/coverage-evaluator.md` | 1 chỗ |
-| [ ] | Bổ nhãn `*Checkpoint: …*` cho lệnh còn thiếu | 6 file |
-| [ ] | Gỡ comment provenance 10+ dòng ở đầu file lệnh → chuyển vào `bin/qc-base-map.json` | 12 file |
-| [ ] | Thay gate cắt tay (5.4 KB) bằng `{{include:steps/gate.md}}` (11.1 KB) | 12 file |
+> **Bốn trong năm dòng đã xong từ trước mà chưa ai tích.** Cột *Ghi* là số của lần lập bảng
+> (2026-09-11); cột *Đo lại* là số đếm thật trên `commands/*.tmpl` + `skills/` ngày 2026-09-15,
+> **đo trước khi sửa file này** — xem cách đếm ở cuối mục. Để nguyên `[ ]` thì người sau đi làm
+> lại bốn việc đã xong.
 
-## Câu còn phải chốt với chị QC
+| | Việc | Ghi | Đo lại 2026-09-15 |
+|:-:|---|---|---|
+| [x] | Sửa file skill còn gọi `TC_<FEATURE>.md` thay `.Test.md` | 14 file | **0 file.** Đúng 2 chỗ còn chuỗi đó, **cả hai** trong `qc-design-test` và là **phản ví dụ có chủ ý** — *"ghi ra thứ không trạm nào tìm thấy"*. Đừng `grep` rồi báo lỗi lại |
+| [x] | Sửa tham chiếu skill treo `qa-script-runner/report/coverage-evaluator.md` | 1 chỗ | **Không phải lỗi — chưa bao giờ hỏng.** Mọi tham chiếu nằm gọn trong `upstream/qc-base/`, và `upstream/qc-base/skills/qa-gate/coverage-evaluator.md` có thật. Không có commit sửa nào để đi tìm |
+| [ ] | Bổ nhãn `*Checkpoint: …*` cho lệnh còn thiếu | 6 file | **18 file** — chỉ 15/33 lệnh có nhãn; số cũ nhỏ hơn thực tế 3 lần *(lần lập bảng đếm trên tập lệnh QC rồi ghi như thể đếm toàn bộ 33 lệnh)*. **Không lệnh nào trong 18 đó được miễn**: cả 5 lệnh mức `none` — `review-code` `validate-traces` `debug` `review-context` `review-tech-docs` — đều ĐÃ có nhãn. 18 là nợ thật |
+| [x] | Gỡ comment provenance 10+ dòng ở đầu file lệnh → `bin/qc-base-map.json` | 12 file | **0 file.** Không tmpl nào còn khối `<!-- -->` ở đầu; provenance rút còn đúng 1 dòng `ported_from:` ở 6 lệnh QC, phần còn lại đã nằm trong `bin/qc-base-map.json` (snapshot `596149f`) |
+| [x] | Thay gate cắt tay (5.4 KB) bằng `{{include:steps/gate.md}}` (11.1 KB) | 12 file | **0 lệnh còn gate cắt tay.** 31/33 tmpl dùng `{{include:steps/gate.md}}`. Hai lệnh còn lại — `sync`, `update-framework` — không phải cắt tay: chúng **không có gate nào cả**, xem cảnh báo dưới |
+
+> ⚠️ **Phát sinh khi đo — KHÔNG thuộc đợt dọn này.** `sync` và `update-framework` đều GHI file
+> (`{service.path}/.agent/project-context.yaml`, `{living_docs_dir}/trace-report.json`, và
+> `--init` copy đè cả `.agent/`) nhưng **không include gate và không có tên trong
+> `gate.checkpoint_levels`** → rơi vào mặc định `normal`, mức lỏng nhất. Đây đúng hình dạng lỗi
+> mà R18 sinh ra để bắt (G67 · G77 · G78 · G79). Xử ở việc **khai nốt registry
+> `artifact_writers`**, không phải ở đây.
+
+<details>
+<summary>Cách đếm — chạy lại được, ra đúng số trên</summary>
+
+```bash
+# 1 — gate: 31 file có include; 2 file thiếu là sync, update-framework
+grep -l "include:steps/gate.md" commands/*.tmpl | wc -l
+
+# 2 — TC_<FEATURE>.md: đúng 2 hit, cả hai trong qc-design-test (phản ví dụ)
+grep -rn 'TC_<FEATURE>.md' skills/ commands/
 
-| | Câu hỏi | Chặn bước nào |
-|:-:|---|---|
-| [ ] | `/qc-run-manualtest` ghi kết quả test tay thế nào — nhập từng TC, hay đọc từ file checklist? | d2-b2 |
-| [ ] | Smoke suite đặt tên gì (không được nhầm `/dev-smoke-test` đã có) | d4-b2 |
-| [ ] | Ngưỡng dung lượng chốt bao nhiêu (đo lại sau d2-b2, ước ~1313 KB) | d2-b2 |
+# 3 — coverage-evaluator: file đích tồn tại ⇒ tham chiếu không treo
+ls upstream/qc-base/skills/qa-gate/coverage-evaluator.md
+
+# 4 — nhãn Checkpoint: 15 có / 18 thiếu trên 33 lệnh
+for f in commands/*.tmpl; do grep -qE '^s**Checkpoint:' "$f" || basename "$f" .tmpl; done | wc -l
+
+# 5 — provenance: 0 dòng <!-- ở đầu tmpl
+head -30 commands/*.tmpl | grep -c '^<!--'
+```
+
+**Vì sao mục này phải mang theo cách đếm:** không máy nào canh file kế hoạch. `self-check` canh
+schema, `lint-trace` canh sổ trace, `test/run.js` canh build — cả ba xanh trong lúc bảng này sai
+bốn dòng. Ghi kết quả đo mà không ghi cách đo thì người sau vẫn phải đo lại từ đầu, tức ô tích
+không tiết kiệm được gì.
+
+</details>
+
+## Câu đã chốt với chị QC  *(2026-09-16)*
+
+| | Câu hỏi | Trả lời | Chặn bước nào |
+|:-:|---|---|---|
+| [x] | `/qc-run-manualtest` ghi kết quả test tay thế nào — nhập từng TC, hay đọc từ file checklist? | **Nhập từng TC.** Nguyên văn: *"ghi kết quả test tay em nhé. Chị sợ đọc checklist mà lệch thông tin lại ghi kết quả sai."* | d2-b2 — **hết chặn** |
+| [x] | Smoke suite đặt tên gì (không được nhầm `/dev-smoke-test` đã có) | **`/qc-smoke-test`** — đúng quy ước hai làn `qc-`/`dev-` | d4-b2 — **hết chặn** |
+| [x] | Ngưỡng dung lượng chốt bao nhiêu | **Không cần hỏi — đo được.** `1309 / 1450 KB` sau d2-b1 (còn 141 KB). Đo lại sau khi viết 3 lệnh của d2-b2 | d2-b2 |
+
+> **Vì sao câu 1 quan trọng hơn vẻ ngoài của nó.** Phương án *"đọc file checklist"* nghe tiện hơn
+> (điền offline, nhiều người điền dần), và đó là phương án được khuyến nghị lúc đầu. Chị QC chỉ ra
+> một rủi ro nặng hơn sự tiện: một file điền tay là **nguồn thứ hai có thể trôi** — TC bị đánh số
+> lại sau một lần `/qc-design-test`, TC mới thêm, dòng cũ còn sót — và khi nó lệch thì lệnh ghi
+> `qc_status` cho **đúng SC sai**. Kiểu hỏng đó là **Nói dối** (sổ trace báo `pass` cho scenario
+> chưa ai chạy); cái giá của phương án hỏi-từng-TC chỉ là **Ồn**. Đổi một rủi ro nói dối lấy một
+> rủi ro phiền là đúng chiều, và cùng họ với `positive_assertion_guards` — luật đã có sẵn để
+> **không bao giờ** ghi `pass` khi dữ liệu nền không chắc.
+>
+> **Điều chỉnh giữ nguyên tính an toàn đó:** lệnh **ghi ngay vào sổ trace sau mỗi câu trả lời**,
+> không gom cuối phiên; chạy lại thì chỉ hỏi những SC còn `not_run` — tức **tự resume**. Như vậy
+> sổ trace là nguồn duy nhất (không artifact trung gian nào để trôi) mà vẫn làm được nhiều buổi,
+> nhiều người. Mỗi lần ghi kèm người chạy + ngày, khớp luật *"`pass` phải có bằng chứng"*.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"