@educa-corp/sdd-framework 0.9.6 → 0.9.7

package/core/steps/gate.md

@@ -77,7 +77,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -85,6 +85,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.

package/core/steps/qc-scope.md

@@ -114,7 +114,7 @@ và đánh dấu trong artifact là dựa trên BDD nháp. *(Tên cờ chung cho
 
 ### 4b — Cổng cấp UC: **cái UC vừa được gọi tên** có làm được không?
 
-Bốn lệnh nhận target là **UC-ID** — `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report`
+Bảy lệnh nhận target là **UC-ID** — `/qc-design-test` · `/qc-review-testcase` · `/qc-review-script` · `/qc-design-script` · `/qc-run-script` · `/qc-run-manualtest` · `/qc-report`
 — phải đối chiếu target với **bảng vừa in ở trên**. Hai lệnh cấp PRD (`/qc-analyze` · `/qc-plan`)
 **bỏ qua mục này**: target của chúng là `TICKET-ID`, và cổng 4a đã trả lời đúng câu hỏi của chúng.
 
@@ -141,7 +141,7 @@ Bốn lệnh nhận target là **UC-ID** — `/qc-design-test` · `/qc-review`
 > đi thẳng vào một spec chưa ai duyệt.
 >
 > Cái giá không dừng ở "thiết kế trên bản nháp". `Guard SC coverage` của trạm 3 sẽ **khẳng định**
-> `khớp K/K` trên spec chưa duyệt, và `/qc-run-test` sẽ ghi `qc_status = pass` **chính thức** vào sổ
+> `khớp K/K` trên spec chưa duyệt, và `/qc-run-script` sẽ ghi `qc_status = pass` **chính thức** vào sổ
 > trace cho nó. Đó là **báo cáo sai** — `rules/workflow.md` §*"ai KHẲNG ĐỊNH một giá trị dương phải
 > được phép khẳng định"*.
 >

package/core/steps/qc-stamp.md

@@ -17,7 +17,7 @@ Câu chưa ai trả lời là *"**tài liệu thiết kế test** còn khớp kh
 
 | Tín hiệu | Nghĩa | Việc phải làm |
 |---|---|---|
-| `qc_status = not_run` | kết quả cũ hết hiệu lực | **chạy lại** `/qc-run-test` |
+| `qc_status = not_run` | kết quả cũ hết hiệu lực | **chạy lại** `/qc-run-script` |
 | **stamp lệch** | TC/gap/plan mô tả spec cũ | **viết lại** — `/qc-analyze` hoặc `/qc-design-test` |
 
 Thiếu vế sau thì người ta thấy `not_run` và **chạy lại** — đúng phản xạ, sai việc. Một bộ TC lỗi thời
@@ -111,8 +111,8 @@ Với mỗi artifact mà lệnh này đọc:
 
 | Trạm | Lệch thì | Vì sao |
 |---|---|---|
-| `/qc-plan` · `/qc-design-test` · `/qc-review` | **⚠️ cảnh báo, đi tiếp** | Cùng họ `TECHDOC_DRIFT`/`BDD_DRIFT` — 13/17 cờ audit không chặn. Thiết kế TC trên bản hơi cũ vẫn ra sản phẩm dùng được; chặn ở đây là **ồn** |
-| `/qc-run-test` | **chặn `pass`, KHÔNG chặn chạy** | Lớp **báo cáo sai** |
+| `/qc-plan` · `/qc-design-test` · `/qc-review-testcase` | **⚠️ cảnh báo, đi tiếp** | Cùng họ `TECHDOC_DRIFT`/`BDD_DRIFT` — 13/17 cờ audit không chặn. Thiết kế TC trên bản hơi cũ vẫn ra sản phẩm dùng được; chặn ở đây là **ồn** |
+| `/qc-run-script` | **chặn `pass`, KHÔNG chặn chạy** | Lớp **báo cáo sai** |
 
 ```
 ⚠️ Stamp lệch — {file} dựng trên {nguồn} {ver_cũ}, hiện tại {ver_mới}.
@@ -120,7 +120,7 @@ Với mỗi artifact mà lệnh này đọc:
    Nên chạy lại: {lệnh}   (đi tiếp vẫn được, nhưng {hệ quả cụ thể})
 ```
 
-**`/qc-run-test` — nhập vào cơ chế đã có, không phát minh cơ chế mới.** Stamp lệch xử lý **y hệt**
+**`/qc-run-script` — nhập vào cơ chế đã có, không phát minh cơ chế mới.** Stamp lệch xử lý **y hệt**
 row `DRIFT`/`ORPHANED` của `positive_assertion_guards` + lint **T12** (G55): test vẫn chạy, nhưng
 xanh → ghi `not_run` chứ **không** ghi `pass`, và **không đóng bug nào** ở lần chạy đó.
 

package/core/steps/report-footer.md

@@ -54,9 +54,9 @@ Discovery → PRD → [Design Spec] → BDD → Tech Design ─┬─ Code → D
 ```
 
 **Sơ đồ rẽ đôi, không phải một dòng thẳng.** `/map-testids` chốt hợp đồng test-id §4.5.6 ở Tech
-Design, nên **Code** và **QC Design** (`/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review`)
+Design, nên **Code** và **QC Design** (`/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review-testcase`)
 đọc cùng một bản đã đóng băng và **chạy song song, không chờ nhau**. Hai nhánh gặp lại ở **QC Run**
-(`/qc-run-test` → `/qc-report`) — trạm duy nhất cần code chạy được.
+(`/qc-run-script` → `/qc-report`) — trạm duy nhất cần code chạy được.
 
 Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
 
@@ -69,8 +69,8 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
 | Code | `/generate-code` · `/review-code` |
 | Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC Design | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` |
-| QC Run | `/qc-run-test` · `/qc-report` |
+| QC Design | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review-testcase` · `/qc-automation-assess` |
+| QC Run | `/qc-design-script` · `/qc-review-script` · `/qc-run-script` · `/qc-run-manualtest` · `/qc-report` |
 | Trace Audit | `/validate-traces` |
 
 Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
@@ -97,10 +97,11 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
 | /qc-analyze             | `/qc-plan {TICKET-ID} {platform}` — **cấp PRD**, không phải `{UC-ID}` (xử lý các gap blocker 🔴 trước) |
 | /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
+| /qc-design-test         | `/qc-review-testcase {UC-ID}`                 |
+| /qc-automation-assess   | `/qc-design-script {TICKET-ID}` (Automatable: Y) · `/qc-run-manualtest {UC-ID}` (N) |
+| /qc-review-testcase     | `/qc-automation-assess {TICKET-ID}` nếu APPROVED; sửa TC bằng `/qc-design-test` nếu NEEDS_FIX |
+| /qc-run-script          | `/qc-run-manualtest {UC-ID}` (TC Automatable: N) rồi `/qc-report {UC-ID}` |
+| /qc-review-script       | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED; sửa script nếu NEEDS_FIX |
 | /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
 | /generate-tech-docs     | `/map-testids {UC-ID}` — chốt hợp đồng test-id §4.5.6 **trước** khi review |
 | /map-testids            | `/review-tech-docs {tech-design-file}` (review CẢ hợp đồng vừa ghi) |
@@ -112,7 +113,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
 | /dev-smoke-test             | Tạo PR và link tới ticket                  |
 | /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
-| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
+| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-script {UC-ID}` để verify + đóng bug |
 | /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
 | /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
 | /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |

package/docs/02-concepts/pipeline-steps/07-dev-selftest.md

@@ -25,7 +25,7 @@ Trước khi đẩy sang QC chính thức, Dev cần một vòng **kiểm nhanh
 
 > **`dev_selftest` ≠ `qc_status`.** Hai trục **độc lập**: dev smoke (nhanh, tự kiểm) vs QC chính thức (Playwright, evidence). Không lấn quyền nhau.
 >
-> ⚠️ **Nhưng "độc lập" chỉ đúng với `status` về KẾT QUẢ CHẠY, không đúng về QUYỀN KHẲNG ĐỊNH** *(GAPS-v4 G55)*. `pass` mang nghĩa *"scenario này đã được nghiệm thu theo spec **hiện tại**"* — nên trên row `DRIFT`/`ORPHANED`, `/dev-run-test` và `/qc-run-test` **không được** ghi `pass`; chúng hạ về `not_run`. `fail`/`skip` thì ghi bình thường. `lint-trace` **T12** bắt trạng thái `DRIFT + pass` ở sổ thật, bất kể ai ghi ra.
+> ⚠️ **Nhưng "độc lập" chỉ đúng với `status` về KẾT QUẢ CHẠY, không đúng về QUYỀN KHẲNG ĐỊNH** *(GAPS-v4 G55)*. `pass` mang nghĩa *"scenario này đã được nghiệm thu theo spec **hiện tại**"* — nên trên row `DRIFT`/`ORPHANED`, `/dev-run-test` và `/qc-design-script` → `/qc-run-script` **không được** ghi `pass`; chúng hạ về `not_run`. `fail`/`skip` thì ghi bình thường. `lint-trace` **T12** bắt trạng thái `DRIFT + pass` ở sổ thật, bất kể ai ghi ra.
 
 ---
 

package/docs/02-concepts/pipeline-steps/08-qc-automation.md

@@ -3,13 +3,13 @@
 # Bước 8 · QC Automation — Dây chuyền kiểm thử 6 trạm (QC Pipeline)
 
 > **Tóm tắt.** Dây chuyền QC tự động 6 trạm: phân rã yêu cầu → lập kế hoạch → thiết kế test case → review → chạy Playwright → report. Ghi `qc_status` **chính thức** + evidence.
-> **Commands:** `/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review` → `/qc-run-test` → `/qc-report`
+> **Commands:** `/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review-testcase` → `/qc-design-script` → `/qc-run-script` → `/qc-review-script` → `/qc-report`
 
 | | |
 |---|---|
 | **Giai đoạn** | QC Automation |
 | **Owner** | 👤 QA / Tester |
-| **Đầu vào** | **Trạm 1–4:** spec (PRD/BDD `approved`) + **hợp đồng test-id §4.5.6** (đóng băng ở bước 5) — **chưa cần code**.<br/>**Trạm 5 `/qc-run-test` thêm:** code đã chạy được — **trạm duy nhất** cần |
+| **Đầu vào** | **Trạm 1–4:** spec (PRD/BDD `approved`) + **hợp đồng test-id §4.5.6** (đóng băng ở bước 5) — **chưa cần code**.<br/>**Trạm 5 `/qc-design-script` → `/qc-run-script` thêm:** code đã chạy được — **trạm duy nhất** cần |
 | **Đầu ra** | Test case, script Playwright, `qc_status`, evidence, product-gap |
 | **HITL** | 🟠 Vừa — cổng review case & script trước khi chạy |
 
@@ -21,7 +21,7 @@
 
 - Phân rã yêu cầu thành test case bám scenario, phát hiện **gap tài liệu**.
 - Chạy test thật, ghi **`qc_status` chính thức** + **evidence**.
-  ⚠️ Nhưng `/qc-run-test` **đọc cột `status` trước khi ghi `pass`** *(GAPS-v4 G55)*: row `DRIFT`/`ORPHANED` + test xanh → hạ về `not_run`, và **không** đóng bug nào ở lần chạy đó. `fail`/`skip` ghi bình thường.
+  ⚠️ Nhưng `/qc-design-script` → `/qc-run-script` **đọc cột `status` trước khi ghi `pass`** *(GAPS-v4 G55)*: row `DRIFT`/`ORPHANED` + test xanh → hạ về `not_run`, và **không** đóng bug nào ở lần chạy đó. `fail`/`skip` ghi bình thường.
 - Phân loại FAIL thành **ba** nhãn — `script-bug` · `product-gap` · `flaky` — **sau khi đã chạy lại tối đa 2 lần**. Một test đỏ **một lần** chưa nói được nó đỏ vì cái gì.
 - Đẩy **product-gap** ngược về PO/Dev.
 
@@ -32,7 +32,7 @@
 - **UC-ID** + platform (QC pass khoá 1 platform).
 - Spec: PRD / `.feature` (từ spec repo, qua `spec_source`).
 - **Hợp đồng test-id**: `@trace.testid_attr` (header tech-doc, **tên** thuộc tính) + §4.5.6 Test Selectors (**giá trị** test-id, cột *Serves SC* là chỉ mục ngược). Đã chốt ở [bước 5](05-tech-docs.md) **trước khi có code**.
-- Code đã sinh & chạy được — **chỉ `/qc-run-test` cần**. Bốn trạm đầu (`/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review`) chạy **song song với FE** vì chỉ cần spec + hợp đồng test-id. Đó là chỗ hai nhánh của [bước 5](05-tech-docs.md) gặp lại.
+- Code đã sinh & chạy được — **chỉ `/qc-design-script` → `/qc-run-script` cần**. Bốn trạm đầu (`/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review-testcase`) chạy **song song với FE** vì chỉ cần spec + hợp đồng test-id. Đó là chỗ hai nhánh của [bước 5](05-tech-docs.md) gặp lại.
 - `qc_dir` (working docs của QC) + module `qc-playwright`.
 
 ## Output (Đầu ra)
@@ -75,8 +75,9 @@ Dây chuyền **6 trạm**, output trạm trước là input trạm sau:
 | 1 | `/qc-analyze` | Phân rã yêu cầu + phát hiện **gap tài liệu** (`DOC_GAP.md`) | **Guard BR-tag** |
 | 2 | `/qc-plan` | Đánh giá **rủi ro** + câu hỏi cho dev (`TEST_PLAN.md`) | — |
 | 3 | `/qc-design-test` | Thiết kế **test case** dạng Markdown (`*.Test.md`) | **Guard SC coverage** |
-| 4 | `/qc-review` | 🛑 **Cổng review** hai chiều: test case & script trước khi chạy | — |
-| 5 | `/qc-run-test` | Sinh & chạy **pytest-playwright**, ghi **`qc_status`** chính thức | **chạy lại ×2 + 3 nhãn FAIL** |
+| 4 | `/qc-review-testcase` | 🛑 **Cổng review test case** — verdict `APPROVED`/`NEEDS_FIX` là điều kiện tiên quyết của trạm sau | — |
+| 6 | `/qc-review-script` | 🛑 **Cổng review script** — biên bản riêng `REVIEW_SCRIPT_<FEATURE>.md` | — |
+| 5 | `/qc-design-script` → `/qc-run-script` | Sinh & chạy **pytest-playwright**, ghi **`qc_status`** chính thức | **chạy lại ×2 + 3 nhãn FAIL** |
 | 6 | `/qc-report` | Report + **evidence**, đẩy **product-gap** về PO/Dev | — |
 
 ### Hai Guard cơ học — chống bỏ sót **im lặng**
@@ -127,7 +128,7 @@ Cả sáu trạm nạp chung `skills/qc/_shared/self-review-principles.md` và c
 
 ## HITL / Gate
 
-- 🛑 `/qc-review` — **cổng review** case & script: không chạy test kém.
+- 🛑 `/qc-review-testcase` · `/qc-review-script` — **hai cổng review riêng**: không chạy test kém, và trạm sau đọc được verdict của ĐÚNG vai nó cần.
 - 🛑 **Xác nhận phân loại FAIL** — mỗi FAIL phải được người chốt nhãn trước khi ghi `qc_status`. Đây là cổng chặn hiếm hoi được **thêm vào** (framework vốn đang giảm số cổng), vì **cả hai hướng sai đều không đảo ngược rẻ**.
 - **Không fake-pass**: FAIL là product-gap → giữ nguyên FAIL + evidence, đẩy về PO/Dev.
 
@@ -137,7 +138,7 @@ Cả sáu trạm nạp chung `skills/qc/_shared/self-review-principles.md` và c
 
 - ❌ Lẫn `qc_status` với `dev_selftest` — hai trục độc lập.
 - ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
-- ❌ Chạy `/qc-run-test` khi chưa qua cổng `/qc-review`.
+- ❌ Chạy `/qc-design-script` → `/qc-run-script` khi chưa qua cổng `/qc-review-testcase`.
 - ❌ **Kết luận từ một lần chạy đỏ** — chưa loại nhiễu thì chưa phân biệt được `flaky` với lỗi thật.
 - ❌ **Tự dò selector từ DOM** thay vì đọc §4.5.6 — script giòn, dev đổi một class là vỡ mà không ai báo.
 - ❌ Dùng self-review làm lý do **bỏ qua** một Guard.

package/docs/02-concepts/pipeline-steps/10-feedback-loop.md

@@ -98,9 +98,9 @@ Framework là pipeline **một chiều** — nhưng vẫn cần đường **ph
 |---|---|---|
 | `🟢 Open` | `/report-bug` | tester/QC file bug |
 | `🟡 Fixed` | `/fix-bug` Phase 5.5 | fix đã commit + push |
-| `🟢 Closed` | **`/qc-run-test`** | QC chạy lại và `qc_status` của SC liên kết flip `pass` |
+| `🟢 Closed` | **`/qc-design-script` → `/qc-run-script`** | QC chạy lại và `qc_status` của SC liên kết flip `pass` |
 
-> **Dev không tự đóng bug của mình** — QC sở hữu verification. `/qc-run-test` đọc `qc_blocked_by` **trước** khi clear nó (cột đó chính là con trỏ tới bug; clear xong là mất đường về).
+> **Dev không tự đóng bug của mình** — QC sở hữu verification. `/qc-run-script` đọc `qc_blocked_by` **trước** khi clear nó (cột đó chính là con trỏ tới bug; clear xong là mất đường về).
 >
 > Ngoại lệ có chủ đích: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + cảnh báo kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**, không phải bug hết — tự đóng ở đây sẽ chôn một defect thật.
 
@@ -149,7 +149,7 @@ QC phát hiện: link reset vẫn dùng được sau khi đổi mật khẩu
                      → trace: test_count +2, dev_selftest → not_run
                      → BUG-217 State: 🟡 Fixed
   /dev-run-test AUTH-UC2 → dev_selftest → pass
-  /qc-run-test  AUTH-UC2 → qc_status SC1 → pass
+  /qc-run-script  AUTH-UC2 → qc_status SC1 → pass
                      → BUG-217 State: 🟢 Closed (verified)
   /learn "luôn invalidate one-time token sau khi dùng"
                      → project-lessons.md (nạp lại lần sau)

package/docs/02-concepts/traceability.md

@@ -42,7 +42,7 @@ Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag expl
 | `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
 | `implemented_by` | `/generate-code` | File code hiện thực SC |
 | `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
-| `qc_status` | `/qc-run-test`, `/report-bug`, **`/map-testids`** | Trạng thái QC **chính thức** (Playwright). `/map-testids` **chỉ hạ về `not_run`**, không bao giờ ghi giá trị khẳng định — xem ô "Làm mất hiệu lực" dưới |
+| `qc_status` | `/qc-design-script` → `/qc-run-script`, `/report-bug`, **`/map-testids`** | Trạng thái QC **chính thức** (Playwright). `/map-testids` **chỉ hạ về `not_run`**, không bao giờ ghi giá trị khẳng định — xem ô "Làm mất hiệu lực" dưới |
 | `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
 | `service` *(cột 23)* | `/generate-bdd` | Đội/submodule sở hữu SC — nguồn của `by_service` trên dashboard |
 | `design_spec_version` *(cột 24)* | `/generate-bdd` | Version design-spec lúc sinh BDD *(FE/App; `—` cho backend)* |

package/docs/03-guides/developer.md

@@ -88,7 +88,7 @@ public TokenDto login(...) { }
 - ❌ Để AI tự review code nó vừa sinh.
 - ❌ Tạo PR khi `/validate-traces` còn cờ 🔴 (`SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`) — build xanh không chứng minh luồng ghép chạy đúng.
 - ❌ Coi FE `fe_phase = ui` là xong vì status đã `OK` — test đang chạy trên **mock**.
-- ❌ Tự đóng bug mình vừa fix — `/fix-bug` chỉ đặt `🟡 Fixed`; `🟢 Closed` là của `/qc-run-test`.
+- ❌ Tự đóng bug mình vừa fix — `/fix-bug` chỉ đặt `🟡 Fixed`; `🟢 Closed` là của `/qc-design-script` → `/qc-run-script`.
 
 ---
 

package/docs/03-guides/tester-qa.md

@@ -12,7 +12,7 @@
 flowchart LR
     M["§4.5.6 đã chốt<br/>(/map-testids, bước 5)"] --> A
     A["/qc-analyze<br/>Guard BR-tag"] --> P["/qc-plan"] --> D["/qc-design-test<br/>Guard SC coverage"]
-    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>chạy lại ×2 · 3 nhãn<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
+    D --> R["/qc-review-testcase<br/>🛑 cổng"] --> RUN["/qc-run-script<br/>chạy lại ×2 · 3 nhãn<br/>ghi qc_status"] --> RS["/qc-review-script<br/>🛑 cổng"] --> REP["/qc-report<br/>product-gap"]
     REP --> FB["/report-bug · /propose-scenario"]
     FB --> SYNC["/sync"]
 ```
@@ -28,8 +28,9 @@ flowchart LR
 | [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu**. **Guard BR-tag** đối chiếu rule BDD đã gắn tag ↔ rule bạn phân tích ra; thiếu thì tự bổ sung từ PRD và in danh sách |
 | `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
 | `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`). **Guard SC coverage** bắt mọi scenario trong phạm vi phải có ≥1 TC — **không có đường thoát**: SC bị gap chặn thì TC **vẫn viết đủ**, mang dấu `🚫 Block` |
-| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
-| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; **chạy lại tối đa 2 lần rồi mới phân loại FAIL thành 3 nhãn** (`script-bug` · `product-gap` · `flaky`), và **bạn xác nhận nhãn** trước khi lệnh ghi trace. **Đọc cột `status` trước khi ghi `pass`** — row `DRIFT`/`ORPHANED` + test xanh → `not_run`, và **không đóng bug nào** ở lần chạy đó *(đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai)* |
+| `/qc-review-testcase` | 🛑 **Cổng review test case** — trước khi chạy |
+| `/qc-review-script` | 🛑 **Cổng review script** — sau khi sinh script |
+| `/qc-design-script` → `/qc-run-script` | Chạy pytest-playwright, ghi **`qc_status`**; **chạy lại tối đa 2 lần rồi mới phân loại FAIL thành 3 nhãn** (`script-bug` · `product-gap` · `flaky`), và **bạn xác nhận nhãn** trước khi lệnh ghi trace. **Đọc cột `status` trước khi ghi `pass`** — row `DRIFT`/`ORPHANED` + test xanh → `not_run`, và **không đóng bug nào** ở lần chạy đó *(đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai)* |
 | `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
 | [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
 
@@ -44,9 +45,9 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
    - **Một lần đỏ chưa đủ để kết luận.** Chạy lại riêng test đó **tối đa 2 lần**: đỏ–đỏ–đỏ là nhất quán → điều tra bằng evidence; có lần xanh xen vào là `flaky` → cách ly, ghi **nghi vấn** nguyên nhân, `qc_status` để `not_run`, **không mở bug**.
    - Đây **không** phải `retries` trong config runner. `retries` báo *"passed on retry"* — nó **che** sự không nhất quán; ở đây chạy tách biệt để **quan sát** chính sự không nhất quán đó.
    - Không chắc giữa `script-bug` và `product-gap` → **mời Dev cùng xem trace**, đừng đoán cho xong.
-3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
+3. **Không chạy test kém** — phải qua cổng `/qc-review-testcase` trước `/qc-design-script` → `/qc-run-script`.
 4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
-5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-run-test` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
+5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-design-script` → `/qc-run-script` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
    - Ngoại lệ: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**.
 6. **`/propose-scenario` dùng đúng bộ tag canonical** — `@trace.scenario` (placeholder `SC?`, `/generate-bdd` gán số khi chèn) · `@trace.sc_version: 1.0` · `@trace.business_rules`. AC ghi thành comment `# Covers:`, **không** phải trace key. Thiếu `@trace.scenario`/`sc_version` thì scenario vào BDD mà **không có row trace** → vô hình với coverage.
 7. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
@@ -77,7 +78,7 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
 ## Anti-pattern
 
 - ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
-- ❌ Chạy `/qc-run-test` khi chưa qua `/qc-review`.
+- ❌ Chạy `/qc-design-script` → `/qc-run-script` khi chưa qua `/qc-review-testcase`.
 - ❌ Lẫn `qc_status` với `dev_selftest`.
 - ❌ Bug không gắn spec → khó truy vết, khó regression.
 - ❌ Kết luận `product-gap` từ **một** lần chạy đỏ → đốt thời gian dev cho một test hên xui.
@@ -88,6 +89,6 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
 
 ## Lệnh của bạn (Your commands)
 
-`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
+`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review-testcase` · `/qc-design-script` → `/qc-run-script` · `/qc-review-script` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
 
 → [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)

package/docs/04-reference/commands.md

@@ -92,8 +92,10 @@ Mọi lệnh chạy chung một **Gate** (model check → target → context-loa
 | `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md` + **Guard BR-tag** | QA |
 | `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
 | `/qc-design-test` | Plan + `.feature` + §4.5.6 | `test-cases/*.Test.md` + **Guard SC coverage** | QA |
-| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
-| `/qc-run-test` | `.Test.md` reviewed + §4.5.6 | Script Playwright + `qc_status`. **Chạy lại ×2 → 3 nhãn FAIL** (`script-bug`·`product-gap`·`flaky`), 🛑 người xác nhận nhãn | QA |
+| `/qc-review-testcase` | Test case | 🛑 Cổng review test case | QA |
+| `/qc-automation-assess` | Test case đã duyệt | Quyết định Automatable Y/N + %Automated | QA |
+| `/qc-review-script` | Script + Page Object | 🛑 Cổng review script | QA |
+| `/qc-design-script` → `/qc-run-script` | `.Test.md` reviewed + §4.5.6 | Script Playwright + `qc_status`. **Chạy lại ×2 → 3 nhãn FAIL** (`script-bug`·`product-gap`·`flaky`), 🛑 người xác nhận nhãn | QA |
 | `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
 
 > **Cả sáu trạm chạy một lượt Self-Review trước khi in report**, theo `skills/qc/_shared/self-review-principles.md` (một file dùng chung, không sáu bản sao).

package/docs/04-reference/trace-schema.md

@@ -99,7 +99,7 @@ public ScoreDto calculate(...) { }
 ### Hợp đồng test-id — được máy canh (`testid_contract`)
 
 Bảng **§4.5.6 Test Selectors** trong tech-doc là hợp đồng FE↔QC: **3 lệnh đọc**
-(`generate-code`, `qc-run-test`, `qc-design-test`), **2 lệnh ghi** (`generate-tech-docs`,
+(`generate-code`, `qc-design-script`, `qc-design-test`), **2 lệnh ghi** (`generate-tech-docs`,
 `map-testids`). Hai rule của `lint-trace` canh nó:
 
 | Rule | Kiểm gì | Mức |
@@ -162,10 +162,10 @@ Shared code dò qua **import chain** từ boundary → tránh tag explosion.
 | 7 | `test_classes` | tên test class / describe | dev-gen-test · fix-bug |
 | 8 | `dev_selftest` | `pass`/`fail`/`not_run` — **dev tự chạy** | **chủ:** dev-run-test · *hạ hiệu lực:* generate-bdd · generate-code · fix-bug |
 | 9 | `dev_selftest_at` | ngày | như trên |
-| 10 | `qc_status` | `pass`/`fail`/`skip`/`not_run` — **QC chính thức** | **chủ:** qc-run-test · *hạ hiệu lực:* generate-bdd · generate-code |
+| 10 | `qc_status` | `pass`/`fail`/`skip`/`not_run` — **QC chính thức** | **chủ:** qc-run-script + qc-run-manualtest · *hạ hiệu lực:* generate-bdd · generate-code |
 | 11 | `qc_run_at` | ngày | như trên |
-| 12 | `qc_owner` | SC đang chờ ai: `dev` / `po` | qc-run-test · report-bug |
-| 13 | `qc_blocked_by` | `BUG-{id}` / `GAP-{id}` | qc-run-test · report-bug |
+| 12 | `qc_owner` | SC đang chờ ai: `dev` / `po` | qc-run-script · qc-run-manualtest · report-bug |
+| 13 | `qc_blocked_by` | `BUG-{id}` / `GAP-{id}` | qc-run-script · qc-run-manualtest · report-bug |
 | 14 | `prd_version` | version PRD lúc sinh BDD | generate-bdd |
 | 15 | `bdd_version` | version `.feature` | generate-bdd · review-context |
 | 16 | `tech_doc_revision` | `@trace.revision` của tech-doc | generate-code · review-tech-docs |

package/docs/explain/17-qc-design-test.md

@@ -1,14 +1,14 @@
-[← /qc-plan](16-qc-plan.md) · [Explain Home](README.md) · [Next: /qc-review →](18-qc-review.md)
+[← /qc-plan](16-qc-plan.md) · [Explain Home](README.md) · [Next: hai cổng review →](18-qc-review.md)
 
 # 17 · `/qc-design-test` — Trạm 3: Thiết kế test case (Markdown)
 
-> **Một câu.** Thiết kế **test case dạng Markdown** (`.Test.md`) từ plan — chưa sinh Python; script đến sau ở `/qc-run-test`.
+> **Một câu.** Thiết kế **test case dạng Markdown** (`.Test.md`) từ plan — chưa sinh Python; script đến sau ở `/qc-design-script` → `/qc-run-script`.
 
 ---
 
 ## Vấn đề giải quyết
 
-Tách "thiết kế test case" (con người đọc/review được) khỏi "code test" (máy chạy). `.Test.md` là bản thiết kế mà `/qc-review` duyệt và `/qc-run-test` biến thành script.
+Tách "thiết kế test case" (con người đọc/review được) khỏi "code test" (máy chạy). `.Test.md` là bản thiết kế mà `/qc-review` duyệt và `/qc-design-script` → `/qc-run-script` biến thành script.
 
 ---
 
@@ -55,7 +55,7 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 
 ## Checkpoint & Gate
 
-- Không gate chặn người ở đây; gate là `/qc-review` kế tiếp.
+- Không gate chặn người ở đây; gate là `/qc-review-testcase` kế tiếp.
 - Nhưng Guard SC coverage **có hệ quả bắt buộc**: thiếu thì lệnh **viết bù** rồi mới báo, không phải chỉ cảnh báo.
 
 ---
@@ -81,4 +81,4 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 
 ## Kết nối
 
-**Trước:** [`/qc-plan`](16-qc-plan.md) · **Sau:** [`/qc-review`](18-qc-review.md) (review test case).
+**Trước:** [`/qc-plan`](16-qc-plan.md) · **Sau:** [`/qc-review-testcase`](18-qc-review.md) (review test case).

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

@@ -1,63 +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:** 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
+```
 
-**Output:** verdict APPROVED / NEEDS_FIX + findings review.
+`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/`.
-2. **Review focus** — kiểm test case (đủ phủ, đúng SC) hoặc script (đúng logic, **selector bám §4.5.6 chứ không dò DOM**, không fake-pass).
-3. **Self-Review** *(mới)* — 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.
-> **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.
+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.
 
+> **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.
-- **Review script thì soát cả nguồn selector** — script lấy locator từ §4.5.6 Test Selectors, hay tự dò DOM? Dò DOM là script giòn: dev đổi một class là vỡ, và **không ai báo**.
+- **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.
 
 ---
@@ -67,7 +70,7 @@
 
 ## 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.
@@ -89,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 |
 
@@ -111,4 +114,4 @@ Bug report đã đổi phải **commit + push** vào spec repo — file local l
 
 ## 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`.
 
 ---
 
@@ -61,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

@@ -117,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