@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/docs/plans/qc-surgery/exec-d3-b1-qc-report-gate-decision.md

@@ -0,0 +1,209 @@
+---
+buoc: Đợt 3 — Bước 1
+title: Nâng cấp /qc-report — coverage kép, 8 ngưỡng, verdict
+phu_thuoc: d2-b2 (CỨNG)
+trang_thai: chưa làm
+---
+
+# Đợt 3 · Bước 1 — Từ "báo cáo" thành "phán quyết"
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+> ⚠️ **Phụ thuộc cứng vào `/qc-run-manualtest`** (d2-b2). Làm trước là biến lệnh giá trị nhất
+> của cả đề xuất thành lệnh không ai dùng được — xem §6.
+
+## 1. Vì sao
+
+Đây là phần giá trị nhất trong toàn bộ đề xuất của chị QC, và nó giải quyết ba câu hỏi mà
+`/qc-report` hiện không trả lời được.
+
+### 1.1 "Coverage bao nhiêu?" — hiện là một số, đáng ra là hai
+
+Hai câu hỏi rất khác nhau bị gộp vào một chữ:
+
+```
+Đã VIẾT test case cho bao nhiêu % scenario?   →  design coverage      = 100%
+Đã CHẠY và có kết quả bao nhiêu % scenario?   →  execution coverage   =  40%
+```
+
+Báo "coverage 100%" khi mới chạy 40% là **báo cáo sai** — và nó sai theo hướng nguy hiểm: người
+đọc kết luận đã kiểm xong.
+
+### 1.2 "Được release chưa?" — hiện không có ai trả lời
+
+`/qc-report` hiện in ra kết quả rồi hết. Người đọc tự quyết định. Nghe có vẻ đúng vai (QC không
+quyết định release), nhưng thực tế nó đẩy một quyết định kỹ thuật thành một quyết định cảm tính:
+*"38/42 pass, 2 fail, 2 skip — thế là được hay không?"*
+
+Cái thiếu không phải quyền quyết định, mà là **ngưỡng khai báo trước**. Có ngưỡng thì QC đưa ra
+tín hiệu kỹ thuật rõ ràng (PASS/FAIL/INCOMPLETE), Lead/PM vẫn giữ quyền quyết định cuối.
+
+### 1.3 "Không có test nào fail" ≠ "tốt"
+
+Đây là lỗ hổng logic nghiêm trọng nhất. Một PRD chạy 0 test sẽ có: 0 fail, 0 bug, không gì đỏ.
+Nếu verdict dựa trên "có fail hay không" thì nó **PASS**.
+
+Framework đã học chính bài này ở phía dev — `bin/trace-schema.json` →
+`positive_assertion_guards` (G55):
+
+> *"AI KHẲNG ĐỊNH MỘT GIÁ TRỊ DƯƠNG THÌ PHẢI KIỂM RẰNG MÌNH ĐƯỢC PHÉP KHẲNG ĐỊNH."*
+
+Bước này là **mệnh đề đối ngẫu ở cấp báo cáo**: không được kết luận PASS chỉ vì không có tin
+xấu.
+
+## 2. Tình trạng hiện tại
+
+`commands/qc-report.tmpl` — 217 dòng, tổng hợp kết quả từ `/qc-run-test`, liệt kê bug, in báo
+cáo. Không có:
+
+- Phân biệt design vs execution coverage.
+- Ngưỡng nào.
+- Verdict nào.
+- Risk matrix nào.
+
+Và số liệu nó tổng hợp lấy từ một lần chạy `/qc-run-test`, nên không phân biệt được *"SC này
+chưa chạy"* với *"SC này chạy rồi và pass"* ở cấp báo cáo — thông tin đó có trong sổ trace nhưng
+không được đưa lên thành chỉ số.
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 Hai số coverage, không gộp
+
+```
+Design coverage    = số SC có ≥1 TC-approved trỏ tới / tổng số SC (đếm từ .feature, trừ ORPHANED)
+Execution coverage = số SC có qc_status ∈ {pass, fail}  / tổng số SC
+```
+
+In **cạnh nhau**, kèm ghi chú rõ **không được gộp**:
+
+```
+Coverage : Design 100% · Execution 90%     ← KHÔNG gộp hai số này
+```
+
+Chú ý: `design coverage` là **cùng phép đếm** với Guard SC coverage ở
+[`exec-d1-b2`](exec-d1-b2-guard-sc-coverage.md). 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). Đó là lý do d1-b2 làm trước.
+
+### 3.2 Cờ `INVERSION`
+
+```
+Design coverage < Execution coverage  →  🔴 INVERSION
+```
+
+Nghĩa: có SC **đã chạy** mà **không có test case approved** đứng sau. Bất thường — hoặc trace
+matrix sai, hoặc có test chạy ngoài quy trình. Phải kiểm lại, không được bỏ qua.
+
+### 3.3 Tám ngưỡng khai báo được
+
+```
+coverage_min          = 85   # % execution coverage tổng, tối thiểu
+p0_pass_rate_min      = 100  # % P0 pass / P0 ĐÃ CHẠY (không tính not_run vào mẫu)
+p1_pass_rate_min      = 95
+overall_pass_rate_min = 90
+skip_rate_max         = 5    # % skip / tổng SC
+critical_risk_max     = 0    # số SC risk CRITICAL còn tồn đọng
+high_risk_max         = 3
+not_run_p0_max        = 0    # số SC P0 not_run — giữ 0: P0 chưa chạy là rủi ro chưa đánh giá được
+```
+
+Override qua `$ARGUMENTS` (`--coverage-min=80`…), hoặc hỏi **một lần** cho `{TICKET-ID}` nếu
+chưa từng đặt trong phiên.
+
+Chú ý cách tính `p0_pass_rate_min`: mẫu số là *P0 **đã chạy***, không phải *tổng P0*. Nếu tính
+trên tổng thì một P0 chưa chạy sẽ làm tỷ lệ tụt và bị hiểu là "có test đỏ" — sai bản chất. Việc
+"P0 chưa chạy" do ngưỡng #8 canh riêng. Hai chuyện khác nhau, hai ngưỡng khác nhau.
+
+### 3.4 Risk matrix — Severity × Impact × Test-type
+
+Với mỗi SC còn `fail` hoặc `not_run`, tính điểm rủi ro tồn đọng, xếp
+`CRITICAL / HIGH / MEDIUM / LOW`. Đầu vào: severity của bug đã file, `Priority` của TC, loại test
+(smoke/functional/integration/e2e). Ngưỡng #6, #7 dùng số này.
+
+### 3.5 Verdict — ba trạng thái, không có trung gian
+
+```
+≥1 ô "⚠️ THIẾU DỮ LIỆU"  →  INCOMPLETE   (chạy lại phần thiếu trước khi ra verdict)
+≥1 ô ❌                   →  FAIL
+mọi ô ✅                  →  PASS
+```
+
+**Thiếu dữ liệu thì ghi "thiếu dữ liệu", không tự ước lượng.** Đây là điều khoản chống chính lỗi
+"số liệu ước lượng" ở [`exec-d1-b4`](exec-d1-b4-self-review-principles.md) nhóm 3.
+
+Và điều khoản trung tâm:
+
+> **KHÔNG BAO GIỜ ra PASS khi execution coverage thấp hoặc 0, dù 0 FAIL thật.**
+> Ngưỡng #1 (`coverage_min`), #5 (`skip_rate_max`), #8 (`not_run_p0_max`) tự chặn ca này:
+> coverage 0% « 85 · skip 100% » 5 · not-run P0 » 0 → verdict tự động rơi về **FAIL**.
+
+### 3.6 Vai trò — QC đưa tín hiệu, Lead/PM quyết định
+
+Verdict là **tín hiệu kỹ thuật**, không phải quyết định release. Report phải nói rõ điều đó, và
+ghi cả bộ ngưỡng đã dùng để người đọc biết verdict được tính trên cơ sở nào:
+
+```
+Ngưỡng dùng: coverage≥85% | P0=100% | P1≥95% | overall≥90% | skip≤5% |
+             critical≤0 | high≤3 | p0-not-run≤0
+```
+
+## 4. Sửa file nào
+
+| File | Việc |
+|---|---|
+| `commands/qc-report.tmpl` | Viết lại: thêm §Coverage (design vs execution) · §Risk Matrix · §Gate Decision (8 ngưỡng + verdict) · giữ phần liệt kê bug và handoff product-gap |
+| `skills/qc/qa-script-runner/report.md` | **Mới** (thay `qa-runner/report/report.md` cho phần automation) — khuôn report theo stack mới: Playwright HTML Report + Trace Viewer (web) · WDIO + Allure (mobile) |
+| `skills/qc/qa-runner/report/report.md` | **Giữ** — phần report cho `/qc-run-manualtest` |
+| `steps/report-footer.md` | Bảng Next sau `/qc-report` |
+| `docs/explain/20-qc-report.md`, `docs/02-concepts/pipeline-steps/08-qc-automation.md` | Cập nhật |
+
+Nguồn: `D:\base\qcframework_proposal\command\qc-report.md` (§Bước 2 Coverage · §Bước 3 Risk
+Matrix · §Bước 4 Gate Decision). Gỡ comment provenance, thay gate cắt tay, và **sửa tham chiếu
+skill treo** `qa-script-runner/report/coverage-evaluator.md` → file này không tồn tại (chỉ có
+`report.md`); hoặc tạo file đó, hoặc sửa tham chiếu. Không sửa thì `self-check.js:1235`
+(R16(d)) fail build.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+node bin/build.js && node bin/self-check.js && node test/run.js
+grep -n "coverage-evaluator" commands/qc-report.tmpl    # → hoặc 0, hoặc file đó phải tồn tại
+```
+
+Kiểm bằng **bốn ca**, và ca 4 là phép thử quyết định của cả đợt mổ:
+
+| Ca | Dựng thế nào | Kỳ vọng |
+|---|---|---|
+| **1 — PASS** | PRD chạy đủ, mọi ngưỡng đạt | `VERDICT: PASS`, in đủ 8 ô ✅ |
+| **2 — FAIL vì fail thật** | 1 test đỏ nhất quán, đã xác nhận `product-gap` | `VERDICT: FAIL`, ngưỡng #2 hoặc #4 ❌ |
+| **3 — FAIL vì chưa chạy** | Không chạy `/qc-run-script` lần nào | `VERDICT: FAIL` (**không** phải PASS dù 0 fail). Ngưỡng #1, #5, #8 phải ❌ |
+| **4 — PRD có test tay** | PRD có ≥1 SC `Automatable: N`, trong đó ≥1 là **P0**. Chạy `/qc-run-script` **và** `/qc-run-manualtest` | `VERDICT: PASS`. Execution coverage phải **đạt** |
+
+**Ca 3** kiểm điều khoản "Untested ≠ Pass". Nếu nó ra PASS thì lỗ hổng logic vẫn còn.
+
+**Ca 4** kiểm việc `/qc-run-manualtest` đã bịt được lỗ hổng. Nếu nó ra FAIL/INCOMPLETE thì
+hoặc `/qc-run-manualtest` chưa ghi trace đúng, hoặc công thức execution coverage chưa tính SC
+manual. **Không được xử lý bằng cách hạ ngưỡng** — đó là bỏ qua vấn đề chứ không sửa.
+
+Thêm ca 5 nếu dựng được: tạo tình huống `INVERSION` (một SC có `qc_status = pass` mà không TC
+approved nào trỏ tới) → phải hiện cờ 🔴.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+**Bỏ cả bước:** `/qc-report` vẫn là bản tổng hợp mỏng. Câu "được release chưa?" vẫn trả lời bằng
+cảm tính, và "coverage 100%" vẫn là con số gộp hai thứ khác nhau.
+
+**Làm bước này TRƯỚC d2-b2 (`/qc-run-manualtest`) — đây là cái phải tránh:**
+
+```
+PRD nào có ≥1 SC phải test tay
+  → SC đó mãi not_run   (không trạm nào ghi)
+  → execution coverage không bao giờ đạt 85
+  → nếu SC đó là P0 thì ngưỡng #8 cũng trượt
+  → VERDICT: FAIL vĩnh viễn, không có cách sửa
+```
+
+Và điều sẽ xảy ra sau đó là điều hợp lý duy nhất còn lại cho đội QC: **hạ `coverage_min` xuống 0
+và `not_run_p0_max` lên vô cùng** để verdict xanh. Lúc đó cả 8 ngưỡng thành trang trí, và ta đã
+làm một lệnh phán quyết mà phán quyết của nó bị vô hiệu hoá ngay từ ngày đầu.
+
+Vì vậy thứ tự d2-b2 → d3-b1 **không phải sở thích**, nó là điều kiện để bước này có nghĩa.

package/docs/plans/qc-surgery/exec-d4-b1-qc-design-testdata.md

@@ -0,0 +1,146 @@
+---
+buoc: Đợt 4 — Bước 1
+title: Thêm /qc-design-testdata — kế hoạch dữ liệu test cho phần automation
+phu_thuoc: d2-b3
+trang_thai: chưa làm
+---
+
+# Đợt 4 · Bước 1 — Dữ liệu test dùng chung là nguồn gốc phổ biến nhất của test chập chờn
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+## 1. Vì sao
+
+Kể một chuyện quen:
+
+Hai test dùng cùng một tài khoản `qa_student_01`. Test A đổi mật khẩu tài khoản đó. Test B đăng
+nhập bằng mật khẩu cũ. Chạy tuần tự thì B đỏ. Chạy song song thì tuỳ thứ tự — đỏ hoặc xanh.
+
+Ai điều tra sẽ thấy test B "chập chờn", gắn nhãn `flaky`, quarantine, rồi tuần sau nó lại nổ. Vì
+nguyên nhân không nằm trong test B — nó nằm ở chỗ **hai test cùng sở hữu một tài khoản mà không
+ai khai điều đó ra**.
+
+Đây là loại lỗi có đặc điểm riêng: nó **không sửa được bằng cách sửa test**. Phải sửa **quyết
+định về dữ liệu** — tài khoản nào dùng riêng, tài khoản nào dùng chung, chạy xong có dọn không.
+Và quyết định đó hiện không được ghi ở đâu.
+
+Bốn câu hỏi cần trả lời trước khi viết script, không phải sau:
+
+| Câu hỏi | Nếu không trả lời |
+|---|---|
+| Dữ liệu này lấy ở đâu? | Hard-code vào test, đổi môi trường là vỡ hết |
+| Có dùng chung với test khác không? | Chuyện ở trên |
+| Chạy xong có phải dọn không? | DB test phình dần, đến lúc test đỏ vì trùng khoá |
+| Có chứa mật khẩu/PII thật không? | Credential lọt vào git |
+
+## 2. Tình trạng hiện tại
+
+Test data hiện là **một field mô tả trong test case**. Kiểm
+`skills/qc/qa-designer/shared/tc-metadata-format.md` — có field `Test Data`, dạng văn xuôi kiểu
+*"tài khoản học sinh đã kích hoạt"*.
+
+Field đó **đủ cho test tay** (người đọc tự hiểu, tự chuẩn bị) nhưng **không đủ cho automation**:
+nó không nói tài khoản nào, ai sở hữu, có dùng chung không, dọn thế nào.
+
+Và `modules/qc-playwright/stack-profile.yaml` có thư mục `test_data/` với ghi chú *"JSON
+datasets"* — tức là chỗ chứa thì có, còn **kế hoạch** thì không.
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 Lệnh mới `/qc-design-testdata`
+
+Chạy **sau** `/qc-automation-assess` (cần biết TC nào `Automatable: Y`) và **trước**
+`/qc-design-script`. Ghi **một** file `TEST_DATA_PLAN.md` cho cả PRD, vào `qc_artifact_dir`.
+
+**Chỉ phục vụ automation.** Test data cho test tay vẫn nằm ở field `Test Data` của `.Test.md`,
+độc lập, không tham chiếu qua lại. Lý do tách: người chạy tay tự xoay được dữ liệu; script thì
+không — nó cần địa chỉ chính xác.
+
+### 3.2 Chín cột của `TEST_DATA_PLAN.md`
+
+| Cột | Ý nghĩa | Vì sao cần |
+|---|---|---|
+| `TD-xxx` | ID, trace được tới TC/SC | Để biết dữ liệu nào phục vụ test nào |
+| **Type** | `Account` / `Boundary Value` / `Negative Value` / `Seed/Reference Data` / `Env Config` | Phân loại để biết cách chuẩn bị |
+| **Dùng bởi** | `{UC-ID}-SC{N}` / `TC_xxx` | **Cột quan trọng nhất** — nhìn là biết dữ liệu bị dùng ở mấy chỗ |
+| **Nguồn** | `Static fixture` / `Factory` (sinh runtime) / `DB seed` / `Env var` (secret) | Script biết lấy ở đâu |
+| **Cách ly** | `Dedicated` / `Pool` / `Stateless` | Đây là cột chặn đúng chuyện ở §1 |
+| **Vòng đời** | `Persistent` / `Ephemeral` | Biết có được sửa hay không |
+| **Cleanup** | Có/không + cách dọn | Chặn DB phình |
+| **Nhạy cảm** | Có chứa PII/credential không → **bắt buộc** qua `Env.*`/`CONFIG` | Chặn credential vào git |
+| **Owner & refresh** | Ai bảo trì, khi nào cần làm mới | Tài khoản test hết hạn thì ai biết |
+
+Hai cột **Dùng bởi** + **Cách ly** là cặp giải quyết vấn đề ở §1: nhìn thấy một tài khoản
+`Dedicated` mà cột "Dùng bởi" có 3 TC là **mâu thuẫn tự lộ ra** — hoặc nó phải là `Pool`, hoặc
+phải tách thành 3 tài khoản.
+
+### 3.3 Nối với nội quy bảo vệ dữ liệu
+
+Cột **Nhạy cảm** không chỉ là ghi chú. Nếu một dòng đánh dấu có chứa credential thì cột
+**Nguồn** **bắt buộc** phải là `Env var`, không được là `Static fixture`. Đây là kiểm được bằng
+máy (một phép so hai cột) — cân nhắc thêm vào `bin/lint-spec.js` (d4-b4) hoặc kiểm ngay trong
+lệnh.
+
+Nối với `rules/data-protection.md` (đã mở rộng ở d1-b5): agent không được in giá trị secret vào
+`TEST_DATA_PLAN.md` — chỉ ghi **tên biến môi trường**, không ghi giá trị.
+
+### 3.4 Escape hatch — không thiết kế trước
+
+Nếu sau này phát hiện một tài khoản/dữ liệu bị dùng lại ở **≥2 PRD khác nhau**, mới cân nhắc
+tách phần đó ra một registry dùng chung (tránh sửa N nơi khi tài khoản đổi). **Không làm trước
+khi thấy dấu hiệu thật** — đúng ý chị QC đã ghi trong đề xuất, và đúng nguyên tắc không dựng hạ
+tầng cho vấn đề chưa có.
+
+## 4. Sửa file nào
+
+| File | Việc |
+|---|---|
+| `commands/qc-design-testdata.tmpl` | **Mới** — `{{include:steps/gate.md}}` + `{{include:steps/qc-scope.md}}` + nhãn `*Checkpoint:*` |
+| `skills/qc/qa-testdata/test-data-plan.md` | **Mới** — khuôn 9 cột, cách chọn giá trị mỗi cột, ví dụ |
+| `commands/qc-design-script.tmpl` | Đọc `TEST_DATA_PLAN.md`; thiếu file → dừng, báo chạy bước này trước |
+| `steps/report-footer.md` | Bảng Phase + Next |
+| `bin/qc-base-map.json` | Entry cho skill mới |
+| `docs/04-reference/commands.md` | Thêm lệnh |
+
+Nguồn: `D:\base\qcframework_proposal\command\qc-design-testdata.md` +
+`skills\qc\qa-testdata\test-data-plan.md`. **Sửa `test-data-plan.md` đang gọi `TC_<FEATURE>.md`**
+→ `.Test.md` (nằm trong 14 file cần dọn).
+
+### Cân nhắc gộp
+
+Chính chị QC đề xuất *"cân nhắc gộp `qc-automation-assess` + `qc-design-testdata` thành 1 lệnh
+nếu đội QC thực tế thấy 2 bước tách biệt là thừa cho case đơn giản"*. Nếu chọn gộp, phần này
+thành một mục trong `/qc-design-script` thay vì một lệnh — **quyết định sau khi chạy thật 2–3
+PRD**, không quyết trước.
+
+## 5. Kiểm thế nào để biết đã xong
+
+```bash
+node bin/build.js && node bin/self-check.js && node test/run.js
+grep -n "TC_<FEATURE>" skills/qc/qa-testdata/test-data-plan.md    # → 0 kết quả
+```
+
+Kiểm bằng tay:
+
+1. `/qc-design-testdata {TICKET-ID}` → `TEST_DATA_PLAN.md` có đủ 9 cột, chỉ phủ TC
+   `Automatable: Y`.
+2. **Ca mâu thuẫn cách ly:** dựng tình huống một tài khoản `Dedicated` mà cột "Dùng bởi" có 2 TC
+   → lệnh phải chỉ ra mâu thuẫn, không im lặng ghi.
+3. **Ca nhạy cảm:** một dòng đánh `Nhạy cảm = có` mà `Nguồn = Static fixture` → phải báo lỗi,
+   đòi đổi sang `Env var`.
+4. **Ca không ghi giá trị secret:** kiểm `TEST_DATA_PLAN.md` không chứa mật khẩu/token thật, chỉ
+   chứa tên biến.
+5. `/qc-design-script` khi **chưa** có `TEST_DATA_PLAN.md` → phải dừng, báo chạy bước này trước.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Không có gì vỡ ngay — đây là lý do bước này ở Đợt 4, không phải Đợt 1. Script vẫn viết được, vẫn
+chạy được, dữ liệu vẫn hard-code hoặc dùng chung ngầm.
+
+Cái vỡ đến muộn và khó truy: **tỷ lệ test chập chờn tăng dần theo số test**. Với 20 test thì hiếm
+khi đụng nhau; với 200 test dùng chung một pool tài khoản thì đụng liên tục. Và mỗi lần đụng,
+`/qc-run-script` sẽ gắn nhãn `flaky` rồi quarantine — tức là **triệu chứng được xử lý, nguyên
+nhân thì không**, và số test bị quarantine chỉ tăng.
+
+Chỉ số **flaky rate trend** ở d4-b3 sẽ cho thấy điều đó bằng số. Nếu đường đó đi lên đều mà
+không rõ vì sao, thì bước này là chỗ đầu tiên nên xem.

package/docs/plans/qc-surgery/exec-d4-b2-qc-smoke-test.md

@@ -0,0 +1,179 @@
+---
+buoc: Đợt 4 — Bước 2
+title: Thêm smoke suite — chạy nhanh tính năng lõi khi có build mới
+phu_thuoc: d2-b2
+trang_thai: chưa làm
+can_chot: TÊN LỆNH (không được nhầm /dev-smoke-test)
+---
+
+# Đợt 4 · Bước 2 — Cổng nhanh trước khi chạy hết regression
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md)
+
+> ⚠️ **Chưa chốt tên lệnh.** Xem §3.1 — phải chốt trước khi viết, vì `/dev-smoke-test` đã tồn
+> tại với nghĩa khác hẳn.
+
+## 1. Vì sao
+
+Hai tình huống mà pipeline hiện không có câu trả lời nhanh:
+
+**a) Có build mới, cần biết ngay tính năng lõi còn sống không.** Cách duy nhất hiện tại: chạy
+`/qc-run-script` cho **từng UC**. Một PRD 5 UC × vài chục test = rất lâu, và phần lớn thời gian
+dành cho test không phải tính năng lõi.
+
+**b) Gấp trước bàn giao, chưa kịp chạy đủ.** Cần một tín hiệu go/no-go trong 5 phút thay vì báo
+cáo đầy đủ trong 2 giờ.
+
+Cả hai cần cùng một thứ: **chạy riêng tập test của tính năng lõi**, phạm vi linh hoạt (1 feature
+/ 1 domain / toàn app), và ra một kết luận đi/không-đi.
+
+Điều kiện để làm được: phải biết test nào là "lõi". Cái đó đã có — `Priority: P0` trong test
+case, và `/qc-design-script` (d2-b2) gắn tag tự động:
+
+```
+P0      →  @smoke + @regression
+P1/P2   →  @regression
+```
+
+Nên bước này là **thu hoạch** của việc gắn tag ở d2-b2, không phải hạ tầng mới.
+
+## 2. Tình trạng hiện tại
+
+**Không có lệnh nào chạy theo tag.** `/qc-run-test` luôn khoá **một UC**, chạy toàn bộ test của
+UC đó.
+
+**Đã có một lệnh tên gần giống, nghĩa khác hẳn** — `commands/dev-smoke-test.tmpl:1-3`:
+
+> *"# /dev-smoke-test — Smoke Test Service hoặc App đang chạy*
+> *Dùng khi service/app **đang chạy sẵn**. Khác `/dev-run-test` (không cần live server)."*
+
+Tức `/dev-smoke-test` là **của dev**, kiểm một service đang chạy có sống không (health check,
+gọi vài endpoint). Không liên quan gì tới tag `@smoke` của bộ test QC.
+
+Hai lệnh cùng chữ "smoke test" với hai nghĩa khác nhau trong cùng một framework là mời gọi gọi
+sai lệnh — đúng loại lỗi mà việc tách `/qc-review` (d2-b1) vừa xử lý.
+
+## 3. Sẽ đổi thành gì
+
+### 3.1 Chốt tên trước — 3 phương án
+
+| Phương án | Ưu | Nhược |
+|---|---|---|
+| `/qc-smoke-run` | Ngắn, giữ chữ "smoke" mà đội QC quen | Vẫn gần `/dev-smoke-test`, đọc nhanh dễ lẫn |
+| `/qc-run-smoke` | Cùng họ với `/qc-run-script`, `/qc-run-manualtest` — nhìn là biết nhóm "chạy test" | Dài hơn một chút |
+| `/qc-gate-check` | Không lẫn với gì; nói đúng mục đích (cổng nhanh go/no-go) | Mất chữ "smoke" mà đội QC đã quen dùng |
+
+**Nghiêng về `/qc-run-smoke`**: nó xếp cùng nhóm với hai lệnh chạy test khác, nên khi gõ `/qc-run`
+là thấy đủ ba lựa chọn — `script` (chạy tự động), `manualtest` (chạy tay), `smoke` (chạy nhanh
+tập lõi). Không tự quyết, **cần chốt với anh + chị QC**.
+
+### 3.2 Phạm vi linh hoạt — khác mọi lệnh QC khác
+
+| `$ARGUMENTS` | Phạm vi |
+|---|---|
+| `{domain}/{prd-slug}` | 1 feature |
+| `{domain}` | cả domain |
+| rỗng hoặc `all` | toàn app |
+
+Đây là điểm **khác biệt có chủ ý**: mọi lệnh QC khác khoá một PRD/UC. Lệnh này không — vì câu hỏi
+nó trả lời là *"build này có sống không"*, không phải *"PRD này đã kiểm xong chưa"*.
+
+Nên nó **không dùng** `steps/qc-scope.md` như 11 lệnh kia (`qc-scope` chốt `TICKET-ID` +
+`active_platform` + `uc_list`). Cần cách phân giải phạm vi riêng — và phải viết rõ vì sao, để
+người sau không "sửa cho đồng bộ".
+
+### 3.3 Chỉ chạy script ĐÃ CÓ
+
+Không tự sinh script mới. Chỉ chạy file đã qua `/qc-design-script` + `/qc-review-script` verdict
+`APPROVED`. Không có script `@smoke` nào trong phạm vi → **báo rõ là chưa có**, đừng báo xanh:
+
+```
+⚠️ Không tìm thấy test @smoke nào trong phạm vi {scope}.
+   Chưa có nghĩa là "sạch" — nghĩa là chưa có gì để kiểm.
+   Chạy /qc-design-script cho các UC có TC Priority P0 trước.
+```
+
+Câu này quan trọng: "0 test chạy, 0 fail" **không phải** go. Cùng logic "Untested ≠ Pass" của
+Đợt 3.
+
+### 3.4 Retry + 3 loại như d1-b3, nhưng rút gọn
+
+Cùng cơ chế phân loại (`script-bug` / `product-gap` / `flaky`), nhưng **1 lần chạy lại** thay vì
+2 — mục đích của lệnh là nhanh.
+
+Đánh đổi phải nói ra: 1 lần chạy lại thì độ chắc chắn thấp hơn. Nên kết quả của lệnh này
+**không** thay `qc_status` chính thức. Xem §3.6.
+
+### 3.5 `product-gap` → báo bug NGAY
+
+Khác `/qc-run-script` (đợi xác nhận hết mọi fail rồi mới file bug): ở đây, `product-gap` được xác
+nhận thì gọi `/report-bug` **ngay lập tức**, không đợi chạy hết phạm vi. Severity đề xuất mặc
+định Critical, nhãn `🔥 Smoke-fail`.
+
+Vì sao: mục đích chính của lệnh là **báo sớm cho dev**. Đợi chạy hết toàn app rồi mới báo là mất
+đúng cái giá trị đó.
+
+### 3.6 Không thay `/qc-run-script`
+
+```
+Output: Smoke Test Summary — go / no-go        ← bản tóm tắt nhẹ, gắn với lần chạy này
+KHÔNG ghi qc_status chính thức vào sổ trace    ← đó là việc của /qc-run-script + /qc-run-manualtest
+```
+
+Lý do: `qc_status` là kết quả QC **chính thức**, và nó phải dựa trên một lần chạy đầy đủ với
+retry ×2. Smoke chỉ là cổng nhanh trước đó.
+
+Nếu ghi `qc_status` từ smoke thì Đợt 3 sẽ tính execution coverage trên dữ liệu chạy rút gọn —
+tức là báo cáo "đã kiểm 85%" trên một tập test P0 mà thôi. Đó là làm sai chính chỉ số vừa xây.
+
+### 3.7 Ai quyết định
+
+🔴 no-go → **báo Lead/PM**, QC không tự quyết định hoãn hay tiếp tục release. QC đưa tín hiệu kỹ
+thuật; quyết định là của Lead/PM — cùng nguyên tắc với verdict của Đợt 3.
+
+## 4. Sửa file nào
+
+| File | Việc |
+|---|---|
+| `commands/{tên-đã-chốt}.tmpl` | **Mới** — `{{include:steps/gate.md}}`; **không** include `qc-scope` (xem §3.2); nhãn `*Checkpoint:*` |
+| `skills/qc/qa-script-runner/smoke.md` | **Mới** — cách chạy theo tag, khuôn Smoke Test Summary |
+| `steps/report-footer.md` | Bảng Next — thêm lệnh này vào nhóm utility, ghi rõ nó **ngoài** luồng tuần tự |
+| `docs/04-reference/commands.md` | Thêm lệnh, **ghi rõ khác gì `/dev-smoke-test`** |
+| `bin/qc-base-map.json` | Entry cho skill mới |
+
+Nguồn: `D:\base\qcframework_proposal\command\qc-smoke-test.md` +
+`skills\qc\qa-script-runner\smoke.md`. Gỡ comment provenance, thay gate cắt tay, đổi tên lệnh
+theo §3.1.
+
+## 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/{tên-đã-chốt}.md
+```
+
+Kiểm bằng tay — **ca 3 và 4 là quan trọng nhất**:
+
+| Ca | Dựng thế nào | Kỳ vọng |
+|---|---|---|
+| 1 | Chạy phạm vi 1 feature có test `@smoke` | Chỉ chạy test `@smoke`, không chạy `@regression` khác |
+| 2 | Chạy phạm vi 1 domain, rồi `all` | Phạm vi mở rộng đúng |
+| **3** | Phạm vi **không có** test `@smoke` nào | Phải báo *"chưa có gì để kiểm"*, **không** báo go |
+| **4** | Sau khi chạy smoke thành công, mở sổ trace | `qc_status` **KHÔNG** bị ghi bởi lệnh này |
+| 5 | Ép 1 test `@smoke` fail nhất quán, xác nhận `product-gap` | `/report-bug` được gọi **ngay**, severity Critical, nhãn `🔥 Smoke-fail` |
+
+Ca 4 là chỗ dễ làm sai nhất: rất tự nhiên để lệnh "ghi luôn kết quả cho tiện", và làm vậy là phá
+chỉ số của Đợt 3.
+
+## 6. Nếu bỏ qua thì hỏng gì
+
+Không có gì vỡ — đây là utility, không nằm trong luồng tuần tự. Đội QC vẫn làm việc được, chỉ là
+mỗi lần có build mới thì phải chạy `/qc-run-script` cho từng UC.
+
+Cái mất là **thu hoạch của việc gắn tag `@smoke` ở d2-b2**: tag được gắn, được lưu trong script,
+và không lệnh nào dùng. Tức là d2-b2 làm một việc không ai tiêu thụ — và sáu tháng sau sẽ có
+người hỏi "cái tag này để làm gì?" rồi gỡ nó đi.
+
+Rủi ro thứ hai nếu làm mà **không chốt tên**: hai lệnh "smoke test" với hai nghĩa. Người gọi sai
+lệnh sẽ nhận một kết quả trông hợp lý nhưng trả lời câu hỏi khác — `/dev-smoke-test` báo "service
+sống" không có nghĩa "tính năng lõi đúng".