@educa-corp/sdd-framework 0.9.5 → 0.9.7

package/docs/explain/18-qc-review.md

@@ -1,59 +1,85 @@
-[← /qc-design-test](17-qc-design-test.md) · [Explain Home](README.md) · [Next: /qc-run-test →](19-qc-run-test.md)
+[← /qc-design-test](17-qc-design-test.md) · [Explain Home](README.md) · [Next: ba trạm script →](19-qc-run-test.md)
 
-# 18 · `/qc-review` — Trạm 4: Cổng review hai chiều (test case & script)
+# 18 · `/qc-review-testcase` + `/qc-review-script` — Trạm 4: Hai cổng review
 
-> **Một câu.** Gate chất lượng của QC: review **test case** (sau design-test) VÀ **script** (sau run-test) — chạy ở hai thời điểm trong dây chuyền.
+> **Một câu.** Gate chất lượng của QC, **hai lệnh riêng**: `/qc-review-testcase` soát test case sau design-test; `/qc-review-script` soát code test sau khi script được sinh.
+
+> **Trước Đợt 2 đây là MỘT lệnh `/qc-review` làm cả hai vai và tự đoán vai nào bằng cách so ngày sửa file.** Chính trang này từng ghi ở mục *Góc nhìn tối ưu*: *"Chạy 2 lần cùng một lệnh — người dùng phải nhớ gọi đúng thời điểm… **Cân nhắc tách rõ**"*. Đó là việc đã làm.
 
 ---
 
 ## Vấn đề giải quyết
 
-Không chạy test kém. Trạm này chặn: (1) test case chưa đủ tốt trước khi biến thành script; (2) script chưa đúng trước khi coi kết quả là chính thức.
+Không chạy test kém. Hai cổng chặn hai thứ khác nhau:
+
+1. **`/qc-review-testcase`** — test case chưa đủ tốt trước khi biến thành script.
+2. **`/qc-review-script`** — script chưa đúng trước khi coi kết quả chạy là chính thức.
+
+Và **cái mà một-lệnh-hai-vai không làm được:** đặt điều kiện tiên quyết cho trạm sau. `REVIEW_<FEATURE>.md` của lệnh cũ không nói nó là kết quả soát vai nào, nên trạm sau không hỏi được *"cái tôi cần đã APPROVED chưa?"*.
 
 ---
 
 ## Vị trí & tiền đề
 
-- **Vị trí:** Phase QC (trạm 4) — **hai lần**: sau `/qc-design-test` (review case) và sau `/qc-run-test` (review script).
+| Lệnh | Chạy sau | Đọc gì | Ghi gì |
+|---|---|---|---|
+| `/qc-review-testcase` | `/qc-design-test` | `.Test.md` | `REVIEW_<FEATURE>.md` |
+| `/qc-review-script` | trạm sinh script | code test + Page Object | `REVIEW_SCRIPT_<FEATURE>.md` |
+
+**File riêng, không chung.** Hai lượt soát cách nhau vài trạm; chung file thì lượt sau đè bảng chi tiết của lượt trước, và trạm tiêu thụ verdict lại phải đoán — tức mang nguyên vấn đề cũ sang chỗ mới.
 
 ---
 
 ## Input / Output
 
-**Input:** `.Test.md` (case) hoặc script Python (script) + skill `qa-reviewer`.
+**Input:** `.Test.md` *(vai test case)* hoặc code test + Page Object *(vai script)*, cộng skill `qa-reviewer`.
 
-**Output:** verdict APPROVED / NEEDS_FIX + findings review.
+**Output:** file biên bản riêng của mỗi vai, chứa điểm `XX/100` và **một dòng verdict máy đọc được**:
+
+```
+**Verdict:** APPROVED
+**Verdict:** NEEDS_FIX
+```
+
+`APPROVED` khi điểm `≥80` **và** không còn `FAIL` chặn. Đây là **contract**, không phải định dạng cho đẹp — `/qc-automation-assess` loại TC chưa `APPROVED`, `/qc-run-script` dừng khi script chưa `APPROVED`.
 
 ---
 
-## Các bước xử lý (chi tiết)
+## Các bước xử lý
+
+1. **Role qa-reviewer** — nạp `{qc_skills_dir}/qa-reviewer/`, **đúng bộ của vai mình**.
+2. **Review focus** — test case: đủ phủ SC, expected cụ thể, trace, `🚫 Block` còn hiệu lực. Script: khớp `.Test.md` 1-1, Page Object gọn, `expect()` thật, **selector bám §4.5.6 chứ không dò DOM**, không hard-code.
+3. **Self-Review** — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+4. **Verdict** — `APPROVED` → đi tiếp; `NEEDS_FIX` → sửa rồi review lại.
 
-1. **Role qa-reviewer** — nạp `{qc_skills_dir}/qa-reviewer/`.
-2. **Review focus** — kiểm test case (đủ phủ, đúng SC) hoặc script (đúng logic, selector, không fake-pass).
-3. Verdict: APPROVED → đi tiếp; NEEDS_FIX → sửa rồi review lại.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard.
 
 ---
 
 ## Checkpoint & Gate
 
-- 🛑 **Cổng hai chiều** — chặn `/qc-run-test` (nếu case chưa duyệt) và chặn tạo PR (nếu script chưa duyệt).
+- Cả hai lệnh ở mức **không chặn** — chúng chỉ ghi **biên bản**, và sinh lại = soát lại.
+- Cổng thật nằm ở **verdict chúng phát ra**, được trạm sau đọc.
 
 ---
 
 ## Cơ chế đặc biệt
 
-- **Một lệnh, hai vai** — review case và review script dùng chung skill, khác focus.
-- **Gate thật của QC** — điểm HITL chính trong dây chuyền tự động.
+- **Chân thứ tư của hợp đồng test-id** — phép so §4.5.6 ↔ `*.Test.md`, mức `warn`, một chiều. Vai này thuộc **`/qc-review-testcase`** *(`bin/trace-schema.json` → `testid_fourth_leg.checked_by`)*, vì phép so chạy trên `.Test.md`. Ở trạm script, locator dựng **lúc chạy** từ bảng tươi nên nó tự cứu.
+- **Đọc stamp phiên bản nguồn** — cũng thuộc vai test case *(`qc_artifact_stamp.checked_by`)*.
+- **Điểm có luật chấm** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`; bảng Tổng quan **thêm một hàng mỗi vòng**, không ghi đè. Đó là cách duy nhất thấy được sửa xong có tốt lên không.
+- **Reviewer KHÔNG tự sửa** — chỉ nhận xét và chấm. *Tự sửa rồi tự duyệt là bỏ mất cái cổng.*
 
 ---
 
 ## 👓 Góc nhìn tối ưu
 
-- **Chạy 2 lần cùng một lệnh** — người dùng phải nhớ gọi đúng thời điểm. Footer "Next" hướng dẫn, nhưng dễ nhầm. Cân nhắc tách rõ hoặc auto-detect giai đoạn.
-- **Verdict thủ công** — phụ thuộc reviewer; không có findings-file có mã như review-context. Đáng xem có nên chuẩn hoá.
+- **Verdict vẫn do LLM phát ra** — có luật chấm rõ, nhưng không có máy nào kiểm lại. Lớp CI cho nó là `T19` *(chân thứ tư)*; phần điểm số thì chưa.
+- **Bộ tiêu chí `script/*` còn phẳng theo tầng.** Khi Đợt 2 bước 2 chốt stack, nó sẽ tách theo nền (`web`/`mobile`) vì tiêu chí khác nhau. Cố ý chưa làm ở bước 1 — viết tiêu chí cho stack chưa chốt là viết hai lần.
 
 ---
 
 ## Kết nối
 
-**Trước:** [`/qc-design-test`](17-qc-design-test.md) (case) / [`/qc-run-test`](19-qc-run-test.md) (script) · **Sau:** case APPROVED → [`/qc-run-test`](19-qc-run-test.md); script APPROVED → [`/qc-report`](20-qc-report.md) / PR.
+**Trước:** [`/qc-design-test`](17-qc-design-test.md) *(vai test case)* · [ba trạm script](19-qc-run-test.md) *(vai script)*
+**Sau:** test case `APPROVED` → [ba trạm script](19-qc-run-test.md) · script `APPROVED` → [`/qc-report`](20-qc-report.md) rồi tạo PR

package/docs/explain/19-qc-run-test.md

@@ -1,6 +1,6 @@
-[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
+[← hai cổng review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
 
-# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
+# 19 · `/qc-design-script` · `/qc-run-script` · `/qc-run-manualtest` — Trạm 5–7: sinh · chạy · chạy tay
 
 > **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
 
@@ -8,13 +8,16 @@
 
 ## Vấn đề giải quyết
 
+> **Trước Đợt 2 · b2 đây là MỘT lệnh `/qc-run-test` gánh BỐN việc**: quyết cái nào automate được · viết mã · chạy · phán một kết quả đỏ là lỗi sản phẩm hay lỗi mã test. Bốn quyết định, không chỗ nào dừng giữa chúng — nên không ai soát được mã trước khi nó chạy, và TC **không** automate được (OTP, sinh trắc học) rơi ra ngoài: không trạm nào ghi `qc_status` cho chúng, rồi `/qc-report` chấm cả PRD là FAIL vĩnh viễn. `/qc-run-manualtest` sinh ra để bịt đúng chỗ đó.
+
+
 Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
 
 ---
 
 ## Vị trí & tiền đề
 
-- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
+- **Vị trí:** Phase QC, **ba trạm** — 5 sinh script · 6 chạy script · 7b chạy tay. `/qc-design-script` chạy sau `/qc-review-testcase` (case APPROVED); `/qc-run-script` chạy sau `/qc-review-script` (script APPROVED).
 - **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
 
 ---
@@ -36,20 +39,41 @@
 1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
 2. **Skills** — nạp một file skill `qa-runner` theo layer.
 3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
-4. **Chạy** — phân loại mỗi FAIL: **script-bug** (fix selector/logic) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
+4. **Chạy.** Test đỏ **một lần** chưa nói được nó đỏ vì cái gì → **chạy lại riêng test đó, tối đa 2 lần**, rồi mới phân loại thành **ba** nhãn:
+
+   ```
+   đỏ → đỏ → đỏ     ⇒ NHẤT QUÁN       → sang bước điều tra: script-bug | product-gap
+   đỏ → xanh        ⇒ KHÔNG NHẤT QUÁN → flaky
+   đỏ → đỏ → xanh   ⇒ KHÔNG NHẤT QUÁN → flaky
+   ```
+
+   | Nhãn | Khi nào | Hệ quả |
+   |---|---|---|
+   | `script-bug` | Sai locator / logic test / timing / dữ liệu test | QC tự sửa. **Không** mở bug |
+   | `product-gap` | Hành vi thật ≠ spec — defect thật | Mở bug qua `/report-bug`. Giữ `fail` + evidence, **không bao giờ fake-pass** |
+   | `flaky` | Không nhất quán ở bước chạy lại — **chưa đủ căn cứ** | Cách ly + ghi **nghi vấn** nguyên nhân. **Không** mở bug từ một lần chạy hên xui |
+
+   **Điều tra bằng bằng chứng, không đoán** — đọc trace/video/log: timeline, DOM snapshot, network, console **tại thời điểm fail**. Không chắc giữa `script-bug` và `product-gap` → **mời Dev cùng xem trace**.
+
+   🛑 **Người xác nhận TRƯỚC khi hành động** — lệnh in đề xuất kèm evidence cụ thể rồi **dừng chờ**. **Không ghi `qc_status`** cho scenario nào còn FAIL chưa được xác nhận nhãn.
 5. **Write Trace State — `qc_status`** (kết quả QC chính thức) + `qc_run_at`, `qc_owner`, `qc_blocked_by`, `last_updated`.
 
    ⚠️ **ĐỌC cột `status` TRƯỚC KHI GHI `pass`** *(GAPS-v4 G55, đối xứng `/dev-run-test`)*: row `DRIFT`/`ORPHANED` + test xanh → **`not_run`**, không bao giờ `pass`. `fail` và `skip` ghi bình thường — chỉ giá trị **khẳng định** cần giấy phép.
 
    Và ở lệnh này hậu quả đi **xa hơn** `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify). Nên khi hạ về `not_run`, lệnh **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy bước đóng bug — đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai.
-6. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
-7. **Refresh Panel Mirror** — Living Docs local.
+   `flaky` → `qc_status = not_run`, `qc_owner = qc`. Không tạo trạng thái mới: `not_run` đúng nghĩa *"chưa có kết luận"*, và `qc_owner = qc` để nó không rơi vào khoảng không ai nhận.
+6. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+7. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
+8. **Refresh Panel Mirror** — Living Docs local.
 
 ---
 
 ## Checkpoint & Gate
 
-- Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
+- Tiền đề: case đã APPROVED ở `/qc-review-testcase`. Script sinh ra → review lại ở `/qc-review-script` trước PR.
+- 🛑 **Xác nhận nhãn FAIL** — cổng chặn được **thêm vào**, trong khi framework vốn đang giảm số cổng chặn (G41). Lý do: **cả hai hướng sai đều không đảo ngược rẻ.** Gắn nhầm `script-bug` cho lỗi sản phẩm thật là **giấu bug** cho tới khi khách gặp; mở bug từ một lần chạy hên xui là **đốt thời gian dev** và làm mòn niềm tin vào QC.
+
+> **Đây KHÔNG phải `retries` trong config test runner.** `retries` tự thử lại rồi báo *"passed on retry"* — nó **che** sự không nhất quán. Ở đây chạy **tách biệt từng lần để quan sát**, vì chính sự không nhất quán mới là thông tin cần.
 
 ---
 
@@ -57,6 +81,7 @@
 
 - **`qc_status` là trục authoritative** — khác `dev_selftest`; có evidence.
 - **Không fake-pass** — product-gap giữ nguyên FAIL, đẩy về PO/Dev.
+- **Chạy lại để QUAN SÁT, không để cho qua** — ba nhãn FAIL tách *chưa đủ căn cứ* (`flaky`) ra khỏi *đã đủ căn cứ* (`script-bug` / `product-gap`). Trước đây hai nhãn gộp cả ba tình huống, nên một test hên xui hoặc bị gán bừa `script-bug` (giấu bug), hoặc thành một bug ma gửi cho dev.
 - **Stack QC tách hẳn dev** — `@trace.verifies` nối script ↔ SC.
 - **`active_platform` khoá sổ trace** — `qc_status` ghi đúng `{UC-ID}-{platform}.tsv`.
 - **Chủ sở hữu bước `🟡 Fixed → 🟢 Closed`.** `/report-bug` mở bug (`🟢 Open`), `/fix-bug` đặt `🟡 Fixed`, và **chỉ QC re-verify mới đóng được** — dev không tự đóng bug của mình.
@@ -67,7 +92,7 @@ Khi `qc_status` flip `pass`, lệnh clear `qc_owner`/`qc_blocked_by` về `—`.
 
 | `State` của bug | SC vừa `pass` → làm gì |
 |---|---|
-| `🟡 Fixed` | → `🟢 Closed` + dòng `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass` |
+| `🟡 Fixed` | → `🟢 Closed` + dòng `Verified: /qc-run-script {today} — {UC-ID}-SC{N} pass` |
 | `🟢 Open` (chưa ai fix) | **KHÔNG đóng.** Giữ `Open` + ghi chú kiểm tra lại test |
 | `GAP-*` thay vì `BUG-*` | không đụng — spec-gap thuộc PO, không phải QC |
 
@@ -80,12 +105,13 @@ Bug report đã đổi phải **commit + push** vào spec repo — file local l
 ## 👓 Góc nhìn tối ưu
 
 - **Trạm nặng nhất của QC** — sinh + chạy + phân loại + ghi trace. Chạy thật phụ thuộc môi trường (browser, data, service lên).
-- **Phân loại script-bug vs product-gap phụ thuộc AI/reviewer** — sai loại → hoặc giấu lỗi sản phẩm hoặc báo nhầm. Đáng có tiêu chí rõ.
-- **Selector phụ thuộc `/map-testids`** — nếu chưa map, script giòn.
-- **Chạy lại tốn tài nguyên** — cân nhắc scoped run như dev-run-test.
+- **Phân loại vẫn phụ thuộc người đọc evidence** — nhưng giờ có **tiêu chí và thứ tự bắt buộc**: chạy lại ×2 → đọc trace/log → đề xuất nhãn → **người xác nhận**. Chỗ mềm còn lại là ranh giới `script-bug` ↔ `product-gap` khi hành vi nằm ở **biên của spec**; đường ra đã ghi rõ là **mời Dev cùng xem trace**, không đoán cho xong.
+- **Selector bám hợp đồng `/map-testids`** — §4.5.6 đã được chốt **trước** `/generate-code`, nên trạm này có bảng selector sẵn. Ca còn lại: §4.5.6 rỗng (dự án cũ chưa từng chạy `/map-testids`) → script quay về dò DOM và **giòn**.
+- **Chạy lại tốn tài nguyên** — ×2 cho mỗi FAIL là chi phí thật. Đánh đổi có chủ đích: rẻ hơn nhiều so với một bug ma gửi cho dev, hoặc một defect thật bị gán `script-bug` rồi chôn.
+- **`flaky` không có cột riêng trong sổ trace** — nó nằm ở `qc_status = not_run` + `qc_owner = qc` + nghi vấn ghi trong report. Cố ý: thêm một giá trị enum mới sẽ kéo theo sửa schema, lint, mọi lệnh đọc cột đó — trong khi `not_run` đã đúng nghĩa *chưa có kết luận*. Cái giá là **không truy được lịch sử flaky bằng máy**, phải đọc report.
 
 ---
 
 ## Kết nối
 
-**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).
+**Trước:** [`/qc-review-testcase`](18-qc-review.md) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review-script`](18-qc-review.md) (script).

package/docs/explain/20-qc-report.md

@@ -1,4 +1,4 @@
-[← /qc-run-test](19-qc-run-test.md) · [Explain Home](README.md) · [Next: /validate-traces →](21-validate-traces.md)
+[← ba trạm script](19-qc-run-test.md) · [Explain Home](README.md) · [Next: /validate-traces →](21-validate-traces.md)
 
 # 20 · `/qc-report` — Trạm 6: Report + evidence + product-gap
 
@@ -14,7 +14,7 @@ Kết quả chạy cần được trình bày có bằng chứng và **định t
 
 ## Vị trí & tiền đề
 
-- **Vị trí:** Phase QC (trạm 6, cuối), sau `/qc-run-test`.
+- **Vị trí:** Phase QC (trạm 6, cuối), sau `/qc-design-script` → `/qc-run-script`.
 
 ---
 
@@ -30,8 +30,11 @@ Kết quả chạy cần được trình bày có bằng chứng và **định t
 
 1. **Role qa-runner/report** — nạp skill report.
 2. **Procedure** — tổng hợp kết quả run (pass/fail per SC), đính evidence.
-3. Tách **product-gap** → định tuyến về PO/Dev (có thể thành `/report-bug`).
-4. **Output** report.
+3. Tách **product-gap** → định tuyến về PO/Dev (có thể thành `/report-bug`). Scenario mang nhãn **`flaky`** **không** thành bug — nó là *chưa có kết luận*, `qc_status` để `not_run`.
+4. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+5. **Output** report.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 
@@ -58,4 +61,4 @@ Kết quả chạy cần được trình bày có bằng chứng và **định t
 
 ## Kết nối
 
-**Trước:** [`/qc-run-test`](19-qc-run-test.md) · **Sau:** [`/validate-traces`](21-validate-traces.md) (làm mới Living Docs); product-gap → [`/report-bug`](25-report-bug.md).
+**Trước:** [ba trạm script](19-qc-run-test.md) · **Sau:** [`/validate-traces`](21-validate-traces.md) (làm mới Living Docs); product-gap → [`/report-bug`](25-report-bug.md).

package/docs/explain/23-fix-bug.md

@@ -35,7 +35,7 @@ Sửa bug ad-hoc dễ tái phát và mất truy vết. Command áp một quy tr
 4. **Phase 4 · Regression Test** — thêm test tái hiện bug để chống tái phát.
 5. **Phase 4.5 · Cập nhật sổ trace** — regression test phải hiện lên coverage (xem dưới).
 6. **Phase 5 · Build & Commit** — build verify; umbrella **push 2 tầng** (Tầng 1: fix branch trong service submodule nơi code sống; Tầng 2: umbrella pointer).
-7. **Phase 5.5 · Đặt `🟡 Fixed`** — nếu fix một `{BUG-ID}` đã file. **Không** đặt `Closed` — bước đó thuộc `/qc-run-test`.
+7. **Phase 5.5 · Đặt `🟡 Fixed`** — nếu fix một `{BUG-ID}` đã file. **Không** đặt `Closed` — bước đó thuộc `/qc-design-script` → `/qc-run-script`.
 8. **Phase 6 · Đề xuất Lesson** — nếu lỗi tái diễn → `capture-lesson` (L1–L5).
 
 ### Phase 4.5 — vì sao `/fix-bug` phải ghi sổ trace
@@ -49,7 +49,7 @@ Sửa bug ad-hoc dễ tái phát và mất truy vết. Command áp một quy tr
 | `dev_selftest` → `not_run` · `dev_selftest_at` → `—` | code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
 | `last_updated` | hôm nay |
 
-**Hai nhóm cột cấm đụng:** `qc_*` (QC sở hữu — `/qc-run-test` flip khi re-verify **và** chính nó đóng bug) · `spec_ver`/`gen_ver` (**fix bug không đổi spec** — đụng vào là tạo `DRIFT` giả).
+**Hai nhóm cột cấm đụng:** `qc_*` (QC sở hữu — `/qc-design-script` → `/qc-run-script` flip khi re-verify **và** chính nó đóng bug) · `spec_ver`/`gen_ver` (**fix bug không đổi spec** — đụng vào là tạo `DRIFT` giả).
 
 Vì `dev_selftest` bị reset, Next của lệnh là **`/dev-run-test`** để lấy lại tín hiệu xanh, rồi mới tạo PR.
 

package/docs/explain/README.md

@@ -98,12 +98,15 @@ Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (f
 - [05 · `/generate-design-spec`](05-generate-design-spec.md)
 - [06 · `/generate-bdd`](06-generate-bdd.md)
 - [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
+- [**11** · `/map-testids`](11-map-testids.md) ← **chốt hợp đồng test-id, TRƯỚC code**
 - [08 · `/review-tech-docs`](08-review-tech-docs.md)
 
+> Danh sách này xếp theo **thứ tự chạy**, không theo số file. `/map-testids` giữ số `11` vì lý do lịch sử — giữ tên file để không gãy link cũ.
+> §4.5.6 chốt ở đây là lý do **Phase Implementation** và **Phase QC Automation** chạy được **song song**.
+
 ### Phase Implementation
 - [09 · `/generate-code`](09-generate-code.md)
 - [10 · `/review-code`](10-review-code.md)
-- [11 · `/map-testids`](11-map-testids.md)
 
 ### Phase Dev Self-Test
 - [12 · `/dev-gen-test`](12-dev-gen-test.md)
@@ -114,8 +117,8 @@ Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (f
 - [15 · `/qc-analyze`](15-qc-analyze.md)
 - [16 · `/qc-plan`](16-qc-plan.md)
 - [17 · `/qc-design-test`](17-qc-design-test.md)
-- [18 · `/qc-review`](18-qc-review.md)
-- [19 · `/qc-run-test`](19-qc-run-test.md)
+- [18 · `/qc-review-testcase` + `/qc-review-script`](18-qc-review.md)
+- [19 · `/qc-design-script` · `/qc-run-script` · `/qc-run-manualtest`](19-qc-run-test.md)
 - [20 · `/qc-report`](20-qc-report.md)
 
 ### Phase Trace & Quality

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.5",
+  "version": "0.9.7",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"