@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/docs/plans/qc-surgery/exec-d2-b1-tach-qc-review.md

@@ -0,0 +1,166 @@
+---
+buoc: Đợt 2 — Bước 1
+title: Tách /qc-review thành /qc-review-testcase và /qc-review-script
+phu_thuoc: Đợt 1 xong
+trang_thai: chưa làm
+---
+
+# Đợt 2 · Bước 1 — Một lệnh hai vai, không ai biết đang gọi vai nào
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+## 1. Vì sao
+
+`/qc-review` hiện là **một lệnh làm hai việc khác nhau ở hai thời điểm khác nhau**:
+
+```
+sau /qc-design-test   →  soát test case (.Test.md)      — coverage, độ rõ, trace
+sau /qc-run-test      →  soát code test (Python/PO)     — locator, assertion, hard-code
+```
+
+Cách lệnh biết nó đang làm vai nào: **tự đoán**. Nguyên văn `commands/qc-review.tmpl:41-42`:
+
+> *"Phát hiện mode: nếu artifact target là `.Test.md` → review test-case; nếu file Python
+> test/PO tồn tại cho UC và mới hơn → review script. Nếu mơ hồ, hỏi."*
+
+Ba vấn đề với việc đoán:
+
+1. **Điều kiện "mới hơn" là một phép so ngày tháng, không phải ý định.** Sửa một dòng trong file
+   test hôm nay rồi gọi `/qc-review` để soát lại **test case** → lệnh chọn vai script.
+2. **Người chạy không biết mình đã gọi vai nào cho tới khi đọc kết quả.** Bộ tiêu chí hai vai
+   khác nhau hoàn toàn (`skills/qc/qa-reviewer/test-case/*` vs `script/*`).
+3. **Không đặt được điều kiện tiên quyết cho trạm sau.** Đây là hậu quả nặng nhất: `/qc-run-test`
+   không thể hỏi *"test case đã APPROVED chưa?"* vì không phân biệt được `REVIEW_<FEATURE>.md`
+   là kết quả soát test case hay soát script.
+
+Chính file lệnh cũng ghi rõ hai vai không được lẫn — `:57`:
+
+> *"gắn nhãn lỗi cho thứ đáng lẽ không có ở đó. Vai 2 dùng bộ tiêu chí riêng ở `script/*.md`."*
+
+Đã biết là hai vai riêng, dùng tiêu chí riêng, chỉ còn thiếu việc gọi tên riêng.
+
+## 2. Tình trạng hiện tại
+
+**Lệnh tự khai là "gate hai chiều"** — `commands/qc-review.tmpl:9`:
+
+> *"Một gate hai chiều: review test case (sau qc-design-test) VÀ script (sau qc-run-test)."*
+
+**Hai bộ skill đã tách sẵn** — `:60-61`:
+
+```
+- Soát test-case: test-case/{functional,e2e,integration,non-functional,exploratory}.md
+- Soát script:    script/{functional,e2e,integration,non-functional,exploratory}.md
+```
+
+**Tin tốt — bước này rẻ nhất trong cả Đợt 2:**
+
+```bash
+grep -c '"qc-review"' bin/trace-schema.json
+# → 0
+```
+
+`/qc-review` **không ghi cột trace nào**, nên nó không có trong `actors`, không có trong
+`tsv_columns.written_by`, không có trong `positive_assertion_guards`. Tách nó **không đụng
+schema** → không gặp ràng buộc nguyên tử của `bin/self-check.js` (R3/R14/R15) như bước 2.
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 Hai lệnh, mỗi lệnh một vai
+
+| Lệnh mới | Soát gì | Skill dùng | Chạy khi nào |
+|---|---|---|---|
+| `/qc-review-testcase` | `.Test.md` — coverage, độ rõ, trace | `qa-reviewer/test-case/*` | sau `/qc-design-test` |
+| `/qc-review-script` | code test + Page Object | `qa-reviewer/script/{web,mobile}/*` | sau `/qc-design-script` (Đợt 2 bước 2) |
+
+Bỏ hẳn phần tự đoán mode. Không còn `:41-42`.
+
+### 3.2 Verdict thành điều kiện tiên quyết — đây là phần có giá trị thật
+
+Mỗi lệnh ghi verdict rõ ràng vào `REVIEW_<FEATURE>.md`: **`APPROVED`** hoặc **`NEEDS_FIX`**.
+
+Và trạm sau **đọc verdict rồi mới chạy**:
+
+```
+/qc-automation-assess   ← chỉ nhận TC có REVIEW verdict = APPROVED
+                          TC còn Draft hoặc NEEDS_FIX → loại khỏi lượt, liệt kê ra
+/qc-run-script          ← đọc verdict của /qc-review-script;
+                          NEEDS_FIX hoặc chưa có → DỪNG, báo chạy /qc-review-script trước
+```
+
+Đây là điều `/qc-review` hiện **không làm được**, và là lý do chính để tách.
+
+*(Hai trạm tiêu thụ này thuộc bước 2 và 3 của Đợt 2. Ở bước 1 chỉ cần ghi verdict đúng định
+dạng; phần đọc verdict làm ở bước sau.)*
+
+### 3.3 Thay 4 skill soát script dạng phẳng bằng web/mobile
+
+Hiện `skills/qc/qa-reviewer/script/` có 5 file phẳng: `e2e.md`, `functional.md`,
+`integration.md`, `non-functional.md`, `exploratory.md`. Stack mới có 2 nền (web Playwright /
+mobile WebdriverIO) với tiêu chí khác nhau → thay bằng cấu trúc của đề xuất:
+
+```
+qa-reviewer/script/
+├── web/     { e2e, functional, functional/api, integration, non-functional }
+├── mobile/  { e2e, functional, integration, non-functional }
+└── exploratory.md      ← giữ nguyên, không theo nền
+```
+
+**Kiểm trước khi gỡ 4 file cũ:** không có entry `ported` nào trong `bin/qc-base-map.json` cho
+chúng → gỡ **không** trip R16(c) (*"target của entry `ported` phải tồn tại"*). Đã xác nhận bằng
+cách quét bản đồ.
+
+## 4. Sửa file nào
+
+| File | Sửa gì |
+|---|---|
+| `commands/qc-review-testcase.tmpl` | **Mới** — dùng `{{include:steps/gate.md}}`, `{{include:steps/qc-scope.md}}`; khai nhãn `*Checkpoint:*` |
+| `commands/qc-review-script.tmpl` | **Mới** — tương tự |
+| `commands/qc-review.tmpl` + `.md` | **Gỡ** |
+| `skills/qc/qa-reviewer/script/{e2e,functional,integration,non-functional}.md` | **Gỡ**, thay bằng `script/{web,mobile}/*` từ đề xuất |
+| `skills/qc/qa-reviewer/script/exploratory.md` | Giữ |
+| `steps/report-footer.md` | Bảng Phase + bảng Next — thay `/qc-review` bằng 2 lệnh mới |
+| `docs/explain/18-qc-review.md` | Tách thành 2 mục, hoặc đổi tên file |
+| `docs/04-reference/commands.md` | Cập nhật bảng lệnh |
+| `bin/qc-base-map.json` | Entry cho skill `script/{web,mobile}/*` mới |
+
+Nguồn nội dung: `D:\base\qcframework_proposal\command\qc-review-testcase.md` và
+`qc-review-script.md` — **viết lại thành `.tmpl`**, thay gate cắt tay (5.4 KB của họ) bằng
+`{{include:steps/gate.md}}` (11.1 KB thật). Gỡ khối comment provenance 10+ dòng ở đầu file, đưa
+vào `bin/qc-base-map.json`.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+# 1. Không còn dấu vết lệnh cũ
+ls commands/qc-review.*                       # → không tồn tại
+grep -rn "/qc-review\b" commands/ steps/ docs/ rules/ | grep -v "qc-review-testcase\|qc-review-script"
+#    → 0 kết quả (trừ file GAPS lịch sử)
+
+# 2. Hai lệnh mới có nhãn Checkpoint và include gate thật
+grep -n "Checkpoint:" commands/qc-review-testcase.tmpl commands/qc-review-script.tmpl
+grep -n "{{include:steps/gate.md}}" commands/qc-review-testcase.tmpl commands/qc-review-script.tmpl
+
+# 3. Mọi tham chiếu skill trỏ tới file có thật (R16d) + shortcut được sinh
+node bin/build.js && node bin/self-check.js && node test/run.js
+ls core/commands/qc-review-*.md               # → 2 file
+```
+
+Kiểm bằng tay:
+
+1. `/qc-review-testcase {UC-ID}` → soát `.Test.md`, ghi `REVIEW_<FEATURE>.md` với verdict rõ
+   ràng. Phải **không** đi tìm file code test.
+2. `/qc-review-script {UC-ID}` → soát code test. Phải **không** đi soát `.Test.md`.
+3. `/qc-review {UC-ID}` → phải báo lệnh không tồn tại (đã gỡ).
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+**Bước 2 và 3 của Đợt 2 mất phần chặn của chúng.** `/qc-run-script` được thiết kế để **DỪNG** khi
+script chưa `APPROVED`; `/qc-automation-assess` để **loại** TC chưa `APPROVED` khỏi lượt đánh
+giá. Cả hai đọc verdict — mà verdict của `/qc-review` hiện không nói nó thuộc vai nào. Nên nếu
+không tách, hai cơ chế chặn đó không dựng được, và pipeline mới mất đúng hai điểm kiểm soát mà
+nó thêm vào so với pipeline cũ.
+
+Thêm nữa: `/qc-review` hiện đọc `.Test.md` **và** code Python. Đợt 2 bước 2 đổi stack sang
+TypeScript. Lệnh hai vai sẽ phải mang cả hai bộ tiêu chí cho cả hai nền (web + mobile) trong
+một file — tức là bốn bộ tiêu chí trong một lệnh, và phép đoán mode phải đoán thêm một chiều
+nữa. Tách trước là để không phải viết cái đó.

package/docs/plans/qc-surgery/exec-d2-b2-tach-qc-run-test-atomic.md

@@ -0,0 +1,267 @@
+---
+buoc: Đợt 2 — Bước 2
+title: Tách /qc-run-test thành 3 lệnh — MỘT COMMIT DUY NHẤT
+phu_thuoc: d2-b1
+trang_thai: chưa làm
+canh_bao: commit nguyên tử, ~30 file
+---
+
+# Đợt 2 · Bước 2 ⚠️ — Commit lớn nhất của cả đợt mổ
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+> **Đọc §3.1 trước khi bắt tay.** Bước này **không chia nhỏ được** — nếu tách thành nhiều commit
+> thì commit ở giữa sẽ làm `node bin/self-check.js` đỏ. Làm trên branch riêng.
+
+## 1. Vì sao
+
+### 1.1 Một lệnh gánh bốn việc
+
+`/qc-run-test` hiện làm:
+
+```
+1. quyết định test nào automate được   ← ngầm định: TẤT CẢ
+2. viết code test + Page Object
+3. chạy test
+4. phán "fail này là lỗi sản phẩm hay lỗi code test"  → ghi qc_status
+```
+
+Bốn việc, bốn loại quyết định, **không có chỗ nào dừng lại giữa chúng**. Hậu quả cụ thể:
+
+- Không thể review code test **trước khi** chạy — lúc lệnh chạy xong thì code đã chạy rồi.
+- Không thể sửa code test rồi chạy lại **mà không sinh lại từ đầu**.
+- Việc số 1 không tồn tại như một bước, nên TC không automate được (OTP, captcha, thiết bị thật)
+  bị ép sinh script, rồi `pytest.skip` — và biến mất khỏi tầm nhìn.
+
+### 1.2 Lỗ hổng test tay — lý do có lệnh thứ ba
+
+Đề xuất của chị QC tách thành 2 lệnh (`design-script` + `run-script`). Nhưng như vậy còn thiếu
+một chỗ: **ai ghi kết quả cho TC không automate được?**
+
+`/qc-automation-assess` (bước 3) đóng dấu `Automatable: N` và nói *"giữ trong bộ manual"*. Rồi
+hết. Không trạm nào chạy và ghi `qc_status` cho chúng.
+
+Đến Đợt 3, `/qc-report` tính:
+
+```
+Execution coverage = số SC có qc_status ∈ {pass, fail} / tổng số SC
+Ngưỡng: coverage_min = 85    not_run_p0_max = 0
+```
+
+Ví dụ PRD "Đăng nhập" 5 scenario, trong đó SC4 (OTP qua SMS, **P0**) và SC5 (sinh trắc học) phải
+test tay:
+
+```
+SC1  pass        ← /qc-run-script ghi
+SC2  pass        ← /qc-run-script ghi
+SC3  pass        ← /qc-run-script ghi
+SC4  not_run     ← KHÔNG AI GHI. QC đã test tay, thấy OK, nhưng không có chỗ ghi lại
+SC5  not_run     ← KHÔNG AI GHI
+
+→ Execution coverage = 3/5 = 60%  < 85   ❌
+→ SC P0 not_run   = 1            > 0    ❌
+→ VERDICT: FAIL   ...và FAIL vĩnh viễn, không có cách nào sửa
+```
+
+Nghịch lý: bước 3 **cho phép** đóng dấu `N`, Đợt 3 **trừng phạt** chính dấu đó. Hai trạm cùng
+pipeline nói ngược nhau.
+
+Nên thêm lệnh thứ ba: **`/qc-run-manualtest`** (tên do anh chọn).
+
+Bonus: đề xuất định **gỡ** 9 skill `skills/qc/qa-runner/**` — đó đúng là bộ hướng dẫn chạy test
+theo từng loại (màn hình, API, integration, exploratory session). `/qc-run-manualtest` dùng lại
+chúng, nên **giữ**.
+
+## 2. Tình trạng hiện tại
+
+**Lệnh gộp** — `commands/qc-run-test.tmpl:7-9`:
+
+> *"# /qc-run-test — QC Script Generation & Run (ghi qc_status)"*
+> *"Sinh & chạy Python pytest-playwright từ `.Test.md` đã review, rồi ghi `qc_status` **chính
+> thức** vào trace TSV."*
+
+**Nó là chủ duy nhất của 4 cột trace** — `bin/trace-schema.json`:
+
+| Cột | `qc-run-test` là | Dòng |
+|---|---|---|
+| 10 `qc_status` | **chủ ghi** (`"Chủ (ghi pass/fail/skip): qc-run-test — DUY NHẤT"`) | :785, :787 |
+| 11 `qc_run_at` | chủ ghi | :804 |
+| 12 `qc_owner` | chủ ghi | :818 |
+| 13 `qc_blocked_by` | chủ ghi + đọc | :831, :837 |
+
+Và nó xuất hiện **21 chỗ** trong schema:
+
+| Khối | Số chỗ | Dòng |
+|---|:---:|---|
+| `actors` | 1 | :31 |
+| `tags` | 3 | :197, :204, :480 |
+| `tsv_columns` (`written_by`/`read_by`) | 10 | :666, :764, :779, :787, :804, :818, :831, :837, :933, :1004 |
+| `queues` | 1 | :1060 |
+| `positive_assertion_guards` → `owner` | 1 | :1769 |
+| `strict_use_check` → `actors` | 1 | :1821 |
+| Văn xuôi giải thích (`$comment`, `$history_note`, `why`) | 4 | :483, :484, :785, :802 |
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 ⚠️ Vì sao phải là MỘT commit
+
+`bin/self-check.js` phân giải tên lệnh → file nguồn ở ba rule:
+
+```js
+// bin/self-check.js:1050  (R14 — positive_assertion_guards)
+const rel = `commands/${g.owner}.tmpl`;
+if (!fs.existsSync(abs)) err('R14', `khai chủ cột ... là ${g.owner} — ${rel} không tồn tại`);
+
+// bin/self-check.js:1159  (R15 — strict_use_check)
+const rel = schema.actors[actor] || `commands/${actor}.tmpl`;
+if (!fs.existsSync(abs)) err('R15', `khai actor ${actor} — ${rel} không tồn tại`);
+```
+
+Nên:
+
+| Nếu làm | Kết quả |
+|---|---|
+| Đổi tên file trước, sửa schema sau | Commit giữa: schema trỏ `commands/qc-run-test.tmpl` không còn tồn tại → **R14 + R15 đỏ** |
+| Sửa schema trước, đổi tên file sau | Commit giữa: schema trỏ `commands/qc-run-script.tmpl` chưa tồn tại → **R14 + R15 đỏ** |
+
+Không có thứ tự nào an toàn. Nguyên tắc số 1 của đợt mổ (*mỗi commit đều xanh*) buộc gộp thành
+một.
+
+**Thêm một ràng buộc của R14:** file chủ cột phải **nhắc từng status bị chặn**. `bin/self-check.js`
+đọc `positive_assertion_guards.blocked_when_status = ["DRIFT", "ORPHANED"]` rồi kiểm file chủ có
+nhắc **cả hai token** — bằng `mentions()` (khớp ranh giới token, không phải `includes()`). Nên cả
+`/qc-run-script` **và** `/qc-run-manualtest` đều phải có đoạn guard nhắc rõ `DRIFT` và
+`ORPHANED`. Đề xuất đã có đoạn đó cho `run-script`; phải viết thêm cho `run-manualtest`.
+
+### 3.2 Ba lệnh mới
+
+| Lệnh | Việc | Ghi trace? |
+|---|---|---|
+| `/qc-design-script` | Viết code test + Page Object cho TC `Automatable: Y`. Sinh **Testability Improvement List** (`IMPROVE-{date}-{NN}`) khi gặp rào cản kỹ thuật. Đọc `Priority` → gắn tag `@smoke`/`@regression`. Điền cột `Script file` của `AUTOMATION_ASSESSMENT.md` | Không |
+| `/qc-run-script` | Chạy code test đã `APPROVED`. Chạy lại ×2 → phân loại 3 loại → người xác nhận → ghi `qc_status` | **Có** — chủ cột 10–13 |
+| `/qc-run-manualtest` | QC chạy tay TC `Automatable: N`, ghi kết quả vào sổ trace. Dùng lại `skills/qc/qa-runner/**` | **Có** — chủ cột 10–13 |
+
+**Hai chủ cho cùng bốn cột** là điều mới. Cần khai đúng trong `positive_assertion_guards`
+(`owner` hiện là một chuỗi, có thể phải thành mảng — kiểm cấu trúc rồi sửa `self-check.js:1050`
+cho khớp nếu cần).
+
+### 3.3 `/qc-run-manualtest` — điểm còn phải chốt với chị QC
+
+Chưa chốt: **cách nhập kết quả**. Hai phương án:
+
+| | Cách | Ưu | Nhược |
+|---|---|---|---|
+| A | Lệnh hỏi từng TC `Automatable: N`: pass/fail/skip + ghi chú | Không cần file trung gian; nhắc đủ TC | Nhiều lần hỏi nếu bộ manual lớn |
+| B | QC điền một file checklist (`MANUAL_RUN.md`), lệnh đọc file đó rồi ghi trace | Điền offline, dễ nhiều người | Thêm một artifact phải bảo trì |
+
+Không tự chọn — **hỏi chị QC trước khi viết lệnh này** (đã ghi trong `01-checklist.md`).
+
+Bất kể phương án nào, hai luật giữ nguyên:
+- Áp `positive_assertion_guards`: row `DRIFT`/`ORPHANED` → **không bao giờ ghi `pass`**, hạ
+  `not_run`.
+- `qc_status = pass` phải có **bằng chứng** (ai chạy, ngày nào, ảnh/ghi chú). Không cho phép
+  "pass vì tôi nói vậy" — cùng tinh thần với `/qc-run-script` phải có output runner.
+
+## 4. Sửa file nào
+
+### 4.1 File lệnh
+
+| File | Việc |
+|---|---|
+| `commands/qc-design-script.tmpl` | **Mới** |
+| `commands/qc-run-script.tmpl` | **Mới** |
+| `commands/qc-run-manualtest.tmpl` | **Mới** — không có trong đề xuất, tự viết |
+| `commands/qc-run-test.tmpl` + `.md` | **Gỡ** |
+
+Cả 3 file mới: `{{include:steps/gate.md}}` + `{{include:steps/qc-scope.md}}` + nhãn
+`*Checkpoint:*`. Nguồn tham khảo: `D:\base\qcframework_proposal\command\{qc-design-script,
+qc-run-script}.md` — gỡ comment provenance, thay gate cắt tay.
+
+### 4.2 Schema — 21 chỗ (bảng ở §2)
+
+- `actors` (:31): 1 entry → 3 entry.
+- `tsv_columns` cột 10–13: `written_by` đổi `qc-run-test` → `qc-run-script` **+**
+  `qc-run-manualtest`. Cột 1, 8, 9, 21 (`read_by`) → cả 3 lệnh mới, tuỳ lệnh nào thật sự đọc.
+- `positive_assertion_guards` (:1769): `owner` → 2 lệnh ghi trace.
+- `strict_use_check` (:1821), `queues` (:1060), `tags` (:197, :204, :480).
+- 4 chỗ văn xuôi (:483, :484, :785, :802): sửa cho khớp, đừng để giải thích nói tên lệnh đã chết.
+
+### 4.3 Lệnh khác nhắc tên cũ — 12 file
+
+`dev-gen-test` · `dev-run-test` · `fix-bug` · `generate-bdd` · `generate-code` · `qc-analyze` ·
+`qc-design-test` · `qc-plan` · `qc-report` · `report-bug` · `validate-traces` (`.tmpl`).
+
+### 4.4 Step, rule, skill, module
+
+| File | Việc |
+|---|---|
+| `steps/context-loader.md`, `steps/report-footer.md`, `rules/workflow.md` | Đổi tên lệnh; cập nhật bảng Phase + Next |
+| ~13 file `skills/qc/**` | Đổi tên lệnh (`DOC_GAP.template.md`, `spec-issue-reporter.md`, `tc-metadata-format.md`, `qa-reviewer/**`) |
+| `skills/qc/qa-runner/**` (9 file) | **GIỮ** — `/qc-run-manualtest` dùng. Chỉ sửa chỗ nhắc `/qc-run-test` |
+| `modules/qc-playwright/` | Thay bằng `modules/qc-playwright-ts/` (web: TypeScript + Playwright Test) + `modules/qc-wdio-appium/` (mobile: WebdriverIO + Appium `FlutterIntegration`). Giữ `qc-playwright` deprecated 1 version |
+| `bin/qc-base-map.json` | Entry cho skill mới: `qa-script-designer/**`, `qa-script-runner/**`, `qa-testdata/**`, `_shared/**` |
+
+### 4.5 Cấu hình & ngân sách
+
+| File | Việc |
+|---|---|
+| `templates/project-context.yaml` + `path_keys` | Thêm `qc_automation_dir`, `feedback_dir` |
+| `test/run.js` | Test *"tổng lệnh phải ở mức slim"*: `1200` → `1450`. **Comment nêu rõ vì sao**: thêm bộ QC 10+2, không phải vì một step lớn bị inline lại. Đo lại số thật rồi chốt |
+
+### 4.6 Việc dọn bắt buộc — làm kèm, xem [`01-checklist.md`](01-checklist.md)
+
+14 file skill còn gọi `TC_<FEATURE>.md` · 1 ref skill treo · 6 lệnh thiếu nhãn Checkpoint ·
+12 comment provenance · 12 gate cắt tay.
+
+### 4.7 Tài liệu
+
+`docs/explain/19-qc-run-test.md` (tách thành 3) · `docs/04-reference/commands.md` ·
+`docs/02-concepts/pipeline-steps/08-qc-automation.md` · `docs/03-guides/tester-qa.md` ·
+`sdd-guide.html`.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+# 1. Không còn dấu vết tên cũ trong file nguồn
+grep -rn "qc-run-test" commands/ steps/ rules/ skills/ bin/ modules/ templates/ | grep -v "^GAPS"
+#    → 0 kết quả
+
+# 2. Bốn lệnh kiểm
+node bin/build.js && node bin/self-check.js && node test/run.js && node bin/lint-trace.js
+
+# 3. Ba lệnh mới được ship
+ls core/commands/qc-design-script.md core/commands/qc-run-script.md core/commands/qc-run-manualtest.md
+
+# 4. Ngân sách thật là bao nhiêu
+node -e "const fs=require('fs'),p=require('path');let t=0;for(const f of fs.readdirSync('core/commands'))if(f.endsWith('.md'))t+=fs.statSync(p.join('core/commands',f)).size;console.log(Math.round(t/1024)+' KB')"
+```
+
+Kiểm bằng tay trên 1 PRD thật — **phép thử quyết định là dòng cuối**:
+
+```bash
+/qc-design-script {TICKET-ID}      # cột Script file được điền; P0 có tag @smoke
+/qc-review-script {TICKET-ID}      # APPROVED
+/qc-run-script {TICKET-ID}         # ép 1 test flaky → qc_status = not_run, qc_owner = qc
+/qc-run-manualtest {TICKET-ID}     # ghi qc_status cho TC Automatable:N
+```
+
+Rồi mở sổ trace: **mọi** SC phải có `qc_status ≠ not_run` (trừ SC thật sự chưa xử lý). Nếu SC
+manual vẫn `not_run` thì `/qc-run-manualtest` chưa làm đúng việc — và Đợt 3 sẽ FAIL.
+
+Thêm 2 ca âm:
+- `/qc-run-script` khi `/qc-review-script` verdict `NEEDS_FIX` → phải **DỪNG**.
+- Ghi `pass` trên row `DRIFT` → phải bị hạ `not_run` (cả `run-script` lẫn `run-manualtest`).
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+**Bỏ cả bước:** pipeline giữ nguyên 6 trạm, `/qc-run-test` vẫn gánh 4 việc, và Đợt 3 + Đợt 4
+không có nền để dựng (`/qc-report` cần `Automatable` + kết quả theo TC; `/qc-smoke-test` cần tag
+`@smoke` do `design-script` gắn).
+
+**Làm bước này mà bỏ `/qc-run-manualtest`:** tệ hơn cả bỏ cả bước. Ta sẽ có pipeline mới đầy đủ,
+`/qc-report` với 8 ngưỡng và verdict — và verdict đó **luôn FAIL** với mọi PRD có test tay. Đội
+QC sẽ làm điều hợp lý duy nhất còn lại: hạ `coverage_min` xuống 0 và `not_run_p0_max` lên vô
+cùng, để verdict xanh. Lúc đó cả Đợt 3 thành trang trí.
+
+**Chia nhỏ commit:** build đỏ ở commit giữa (§3.1). Nếu ai đó merge commit giữa vào `main` thì
+`npm run build` của mọi người cùng đỏ, và không publish được.

package/docs/plans/qc-surgery/exec-d2-b3-qc-automation-assess.md

@@ -0,0 +1,198 @@
+---
+buoc: Đợt 2 — Bước 3
+title: Thêm /qc-automation-assess + cột Script file
+phu_thuoc: d2-b2
+trang_thai: chưa làm
+---
+
+# Đợt 2 · Bước 3 — Quyết định "cái nào máy chạy, cái nào phải tay" thành một bước có hồ sơ
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+## 1. Vì sao
+
+### 1.1 Framework hiện ngầm định mọi test case đều automate được
+
+`/qc-run-test` nhận `.Test.md` rồi sinh script cho **tất cả**. Nhưng thực tế luôn có TC không nên
+hoặc không thể automate:
+
+| TC | Vì sao không automate |
+|---|---|
+| Đăng nhập bằng OTP gửi SMS | Cần mã do người/bên thứ ba sinh ra |
+| Xác minh captcha | Cùng lý do |
+| In hoá đơn ra máy in thật | Thiết bị vật lý |
+| Màn hình đang redesign hàng tuần | Chi phí bảo trì script > lợi ích |
+| Test chạy 1 lần trước khi tính năng bị bỏ | Effort > ROI |
+
+Hiện chúng vẫn bị sinh script, rồi `pytest.skip("lý do")`. Ba hệ quả:
+
+1. **Quyết định không được ghi lại.** Sáu tháng sau không ai biết vì sao TC đó skip — là do
+   không automate được, hay do quên?
+2. **Không có số liệu.** Câu "automation phủ bao nhiêu %?" không trả lời được, vì mẫu số lẫn cả
+   TC không bao giờ định automate.
+3. **TC không automate được biến mất khỏi tầm nhìn.** Nó nằm trong file test case, có dòng
+   `skip`, và không ai chạy tay nó cả. Đây là nửa còn lại của lỗ hổng mà
+   [`exec-d2-b2`](exec-d2-b2-tach-qc-run-test-atomic.md) bịt bằng `/qc-run-manualtest` — bước
+   này là nửa *"biết TC nào cần chạy tay"*.
+
+### 1.2 Không có đường từ test case → file code
+
+Hiện muốn biết TC nào được test bởi file nào thì phải `grep` tag `@trace.verifies` trong code.
+Ngược lại — *"file `login.spec.ts` phục vụ những TC nào"* — phải đọc cả file.
+
+`/qc-run-script` cần biết **chạy file nào** cho UC này. Không có chỉ mục thì nó phải tự suy
+đường dẫn từ quy ước đặt tên — và suy sai thì chạy sai bộ test, hoặc không chạy gì mà vẫn báo
+xanh.
+
+## 2. Tình trạng hiện tại
+
+**Không có lệnh nào cho việc này.** Trong 33 lệnh hiện tại không có bước đánh giá khả năng
+automate. `/qc-design-test` viết test case rồi chuyển thẳng sang `/qc-review` → `/qc-run-test`.
+
+**`.Test.md` không có field nào ghi quyết định automate.** Kiểm
+`skills/qc/qa-designer/shared/tc-metadata-format.md` — có `Priority`, có `@trace.verifies`, có
+`Test Data`, **không có** `Automatable`.
+
+**Không có chỉ mục ngược TC → file code.** `bin/lint-trace.js` có rule `T14` đi từ code → sổ
+trace (`@trace.implements`), nhưng đó là code sản phẩm, không phải code test.
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 Lệnh mới `/qc-automation-assess`
+
+Chạy **sau** `/qc-review-testcase` (chỉ nhận TC verdict `APPROVED`) và **trước**
+`/qc-design-script`. Ghi `AUTOMATION_ASSESSMENT.md` vào `qc_artifact_dir` (cấp PRD, cùng chỗ
+`TEST_PLAN.md`):
+
+```markdown
+# Automation Assessment — {TICKET-ID} ({active_platform})
+
+| TC ID | UC | Automatable | Lý do (nếu N) | Trace SC | Script file | Ghi chú |
+|---|---|:---:|---|---|---|---|
+| TC_LOGIN_001 | UC1 | Y | — | UC1-SC1 | — *(chưa qua design-script)* | |
+| TC_LOGIN_004 | UC1 | N | Cần OTP/captcha thủ công | UC1-SC4 | — *(không automate)* | Giữ bộ manual |
+
+**%Automated/Total: {automatable}/{total} = {pct}%**
+```
+
+### 3.2 Nhãn lý do — danh sách cố định, mở rộng được
+
+| Nhãn | Khi dùng |
+|---|---|
+| `Cần OTP/captcha thủ công` | Bước bắt buộc nhập mã do người/bên thứ ba sinh |
+| `Phụ thuộc hệ thống ngoài` | App khác, thiết bị vật lý, email thật |
+| `UI không ổn định` | Màn đang redesign/A-B test, bảo trì script > lợi ích |
+| `Effort > ROI` | Tần suất chạy thấp, hoặc chi phí viết/bảo trì vượt giá trị |
+| `Thiếu test-id contract` | Element không có test-id ổn định và dev chưa cam kết thêm |
+
+Không khớp nhãn nào → **tạo nhãn mới** mô tả đúng lý do (không ép vào nhãn có sẵn), rồi ghi nhãn
+mới đó trong report để bổ sung vào danh sách lần sau.
+
+Vì sao chuẩn hoá nhãn: để đếm được. *"3 TC không automate vì thiếu test-id"* là một tín hiệu
+hành động được (đi đàm phán với dev); *"3 TC vì lý do kỹ thuật"* thì không.
+
+Riêng nhãn `Thiếu test-id contract` nối trực tiếp với Đợt 0: nếu Đợt 0 làm đúng thì nhãn này
+phải **giảm dần** theo thời gian.
+
+### 3.3 Cột `Script file` — chỉ mục ngược tường minh
+
+```
+Khởi tạo ở bước này        →  "—"
+/qc-design-script điền     →  qc-automation/web/tests/academic/FT-101-login/login.spec.ts
+/qc-run-script ĐỌC cột này →  biết chạy file nào, KHÔNG tự suy path
+```
+
+Đây là điều kiện để `/qc-run-script` không đoán. Đề xuất đã có ý này; giữ nguyên.
+
+### 3.4 Cờ re-assessment tự động theo `DRIFT`
+
+Trước khi đánh giá TC mới, quét cột `status` trong sổ trace. Với TC đã có dòng trong
+`AUTOMATION_ASSESSMENT.md` từ lần trước mà scenario nó verify đang `DRIFT` (spec/BDD đã đổi):
+
+- Gắn cờ `🔄 Re-assess` — quyết định `Y/N` cũ **không còn đáng tin**.
+- Đánh giá lại **ngay trong lượt này**, không cần lịch định kỳ, không cần ai nhắc.
+- Nếu kết quả đổi `Y → N` (đã có script, giờ không nên automate nữa): **giữ** path cũ trong cột
+  `Script file` + ghi chú `⚠️ Script đã lỗi thời — cân nhắc gỡ ở lần /qc-design-script kế tiếp`.
+  **Không tự xoá file** — để người quyết định.
+- Nếu `N → Y`: cột vẫn `—`, chờ `/qc-design-script`.
+
+### 3.5 TC `Automatable: N` không mất đi
+
+Ba điều phải đúng:
+
+1. **Không xoá khỏi `.Test.md`** — bộ test tay không đổi.
+2. **Là đầu vào của `/qc-run-manualtest`** (d2-b2) — lệnh đó lọc `Automatable: N` từ file này để
+   biết phải chạy tay những gì. Đây là mắt xích khiến execution coverage của Đợt 3 đạt được.
+3. **TC `Priority: P0` mà `Automatable: N` → cảnh báo riêng.** Tính năng lõi không có smoke test
+   tự động là tín hiệu đáng chú ý: cân nhắc `IMPROVE-xxx` để gỡ rào cản thay vì chấp nhận `N`
+   luôn.
+
+### 3.6 Chốt một chỗ còn nhoè về phạm vi
+
+`/qc-automation-assess` chạy theo **TICKET-ID** (cả PRD), còn `/qc-review-testcase` chạy theo
+**UC-ID**. PRD 3 UC mà chỉ UC1 `APPROVED` thì sao? Chốt hành vi:
+
+- Đánh giá TC của UC đã `APPROVED`.
+- TC của UC còn `Draft`/`NEEDS_FIX` → **loại khỏi lượt**, và **liệt kê ra trong report** kèm
+  trạng thái thật.
+- `%Automated/Total` tính trên mẫu số **chỉ gồm TC đã đánh giá**, và in kèm số TC bị loại — để
+  không ai đọc "100%" mà tưởng đã phủ cả PRD.
+
+Nguyên tắc: *"chưa xét" khác "đã xét, sạch"* — cùng tinh thần bảng phạm vi của
+`steps/qc-scope.md`.
+
+## 4. Sửa file nào
+
+| File | Việc |
+|---|---|
+| `commands/qc-automation-assess.tmpl` | **Mới** — `{{include:steps/gate.md}}` + `{{include:steps/qc-scope.md}}` + nhãn `*Checkpoint:*` |
+| `skills/qc/qa-automation-assess/matrix.md` | **Mới** — tiêu chí đánh giá, danh sách nhãn, công thức ROI, khuôn bảng |
+| `commands/qc-design-script.tmpl` | Đọc `AUTOMATION_ASSESSMENT.md`, lọc `Automatable: Y`; điền cột `Script file` sau khi sinh |
+| `commands/qc-run-script.tmpl` | Đọc cột `Script file` để biết chạy file nào |
+| `commands/qc-run-manualtest.tmpl` | Đọc `Automatable: N` để biết chạy tay những gì |
+| `skills/qc/qa-designer/shared/tc-metadata-format.md` | Cân nhắc thêm ghi chú: quyết định `Automatable` **không** nằm trong `.Test.md`, nó ở `AUTOMATION_ASSESSMENT.md` (tránh hai chỗ ghi cùng một quyết định) |
+| `steps/report-footer.md` | Bảng Phase + Next |
+| `bin/qc-base-map.json` | Entry cho `qa-automation-assess/matrix.md` |
+| `docs/04-reference/commands.md`, `docs/02-concepts/pipeline-steps/08-qc-automation.md` | Thêm lệnh mới |
+
+Nguồn: `D:\base\qcframework_proposal\command\qc-automation-assess.md` +
+`skills\qc\qa-automation-assess\matrix.md`. Gỡ comment provenance, thay gate cắt tay, và **sửa
+`matrix.md` đang gọi `TC_<FEATURE>.md`** → `.Test.md` (nằm trong 14 file cần dọn).
+
+⚠️ R16(d): tạo `skills/qc/qa-automation-assess/matrix.md` **trước hoặc cùng lúc** với việc lệnh
+tham chiếu tới nó, không thì `self-check` đỏ.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+node bin/build.js && node bin/self-check.js && node test/run.js
+ls core/commands/qc-automation-assess.md
+grep -n "TC_<FEATURE>" skills/qc/qa-automation-assess/matrix.md      # → 0 kết quả
+```
+
+Kiểm bằng tay trên PRD có **cả hai loại** TC:
+
+1. `/qc-automation-assess {TICKET-ID}` → `AUTOMATION_ASSESSMENT.md` có đủ TC, mỗi TC có `Y/N`,
+   `N` phải kèm nhãn từ danh sách; `%Automated` là **phép chia thật** trên số dòng bảng.
+2. Cột `Script file` phải là `—` ở lượt này (script chưa tồn tại).
+3. `/qc-design-script {TICKET-ID}` → chỉ sinh script cho `Y`; cột `Script file` được điền.
+4. `/qc-run-script {TICKET-ID}` → chạy đúng file trong cột đó, **không** đoán path.
+5. **Ca DRIFT:** đổi một scenario trong `.feature` để row trace thành `DRIFT`, chạy lại lệnh →
+   TC tương ứng phải có cờ `🔄 Re-assess` và được đánh giá lại.
+6. **Ca phạm vi:** PRD 2 UC, để 1 UC `Draft` → report phải liệt kê TC bị loại, và `%Automated`
+   phải in kèm số TC bị loại.
+7. **Ca P0+N:** đặt một TC `P0` thành `Automatable: N` → phải có cảnh báo riêng.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Ba mắt xích đứt cùng lúc:
+
+1. **`/qc-design-script` không biết sinh script cho TC nào** → quay lại ngầm định "tất cả", và
+   TC không automate được lại bị `skip` rồi biến mất.
+2. **`/qc-run-manualtest` không biết chạy tay TC nào** → lệnh vừa thêm ở d2-b2 không có đầu vào
+   → lỗ hổng execution coverage của Đợt 3 **không được bịt**, dù đã có lệnh.
+3. **`/qc-run-script` phải tự suy đường dẫn file test** → suy sai thì chạy sai bộ test hoặc
+   không chạy gì mà vẫn báo xanh. Đây là kiểu hỏng im lặng tệ nhất: báo cáo xanh trên một lần
+   chạy không tồn tại.
+
+Và mất luôn chỉ số `%Automated/Total` — con số đầu tiên mà Lead/PM sẽ hỏi khi thấy pipeline mới.