@educa-corp/sdd-framework 0.9.6 → 0.9.7

package/core/commands/qc-design-script.md

@@ -0,0 +1,400 @@
+---
+version: 1.0
+updated: 2026-09-16
+ported_from: ai-automation-qc-base
+---
+
+# /qc-design-script — QC Script Generation (sinh script, KHÔNG chạy)
+
+> Stage 5 của QC automation pipeline native. Chuyển `.Test.md` **đã `APPROVED`** thành script +
+> Page Object. **Không chạy test, không ghi sổ trace** — đó là việc của `/qc-run-script`.
+
+## Gate
+
+*Checkpoint: **chặn CỨNG** — ghi đè script đã có → XOÁ bản sửa tay `script-bug` của QC, thứ mà chính `/qc-run-script` bảo họ tự sửa. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng chỉ áp khi file script của UC **đã tồn tại**. Lần sinh đầu đi thẳng. Xem §Chạy lại.*
+
+# Gate — Quy trình vào chuẩn cho mọi lệnh
+
+Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
+
+## Bước 0 — Kiểm tra chế độ Sub-Agent
+
+Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
+
+1. Thử parse `$ARGUMENTS` dưới dạng JSON.
+2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
+   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
+   - Đặt target file = `payload.target_file`
+   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
+   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
+   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
+   - Đi thẳng tới phần logic riêng của lệnh.
+3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
+
+## Bước 0-B — Ghi nhận Model *(KHÔNG chặn)*
+
+*Bỏ qua nếu `_agent_mode: true` (sub-agent — orchestrator đã ghi nhận rồi).*
+
+Ghi lại **model mà bạn — agent đang chạy lệnh này — thực sự đang dùng**, rồi mang nó vào
+dòng `Model:` của report cuối (xem `report-footer`). Nếu bạn biết mình **không** phải một
+model Opus, gắn thêm cảnh báo ngay ở dòng đó.
+
+**KHÔNG hỏi người dùng. KHÔNG chờ. KHÔNG dừng.**
+
+> **Vì sao bước này từng là prompt chặn, và vì sao bỏ (GAPS-v3 G41):** bản cũ hiện khối
+> `⚙️ MODEL CHECK` rồi chờ `Y/S/N`. Ba vấn đề cùng chỉ một hướng:
+> **(1)** nó hỏi người dùng thứ mà **agent đã biết chính xác**;
+> **(2)** câu trả lời **không kiểm chứng được** — gõ `Y` xong vẫn đang chạy Haiku thì không
+> gì phát hiện;
+> **(3)** **cả `Y` lẫn `S` đều đi tiếp** — cách duy nhất để nó dừng là tự nguyện gõ `N`.
+> Tức nó **không chặn được ai**, mà tốn một lần chặn ở **mọi** lệnh. Một feature đi hết
+> pipeline dùng 20 lệnh; 30/32 lệnh chạy gate. Hai mươi lần bấm cho một tín hiệu tự-khai
+> không kiểm chứng được — và chính cái giá đó làm mòn CHECKPOINT ở Bước 3, cổng có giá trị thật.
+>
+> Khai báo trong report **mạnh hơn** hỏi: đúng nguồn (agent, không phải người), và nằm
+> **cạnh kết quả** để cân nhắc, thay vì nằm trước khi có kết quả để bấm cho xong.
+
+**Vẫn khuyến nghị Opus:** phân tích spec, review kiến trúc và sinh code đòi hỏi suy luận sâu;
+model nhỏ hơn dễ bỏ sót edge case và vi phạm kiến trúc. Đổi: `/model` → chọn Opus.
+
+## Bước 1 — Xác định Target File
+
+0. **Tách cờ trước khi resolve target.** `$ARGUMENTS` có thể lẫn các `--flag` (vd `--phase=integration`, `--comment`, `--fix`). **Loại bỏ mọi token bắt đầu bằng `--`** ra khỏi phần dùng để tìm target — chỉ giữ phần path/UC-ID/ticket. (Các flag đó do phần logic riêng của lệnh parse ở bước sau, KHÔNG phải tên file.)
+1. Nếu `$ARGUMENTS` (đã tách cờ) được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
+2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
+   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
+   - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
+   - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+
+   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
+3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
+   - Chờ người dùng chọn rồi mới tiếp tục.
+
+## Bước 2 — Chạy Context Loader
+
+Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
+Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
+
+## Bước 3 — CHECKPOINT
+
+*Bỏ qua nếu `_agent_mode: true`.*
+
+### 3a — Lệnh này có phải chặn không?
+
+| Mức | Lệnh nào | `--yes` bỏ qua đượ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ờ** |
+
+`--yes` trong `$ARGUMENTS` → bỏ qua CHECKPOINT mức *chặn thường*. (Bước 1 đã tách mọi token
+`--` 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ì**.
+> Nguồn máy đọc: `bin/trace-schema.json` → `gate.checkpoint_levels`; `self-check` **R11** fail
+> build nếu nhãn trong file lệnh lệch với schema, hoặc nếu một lệnh `hard`/`none` thiếu nhãn.
+> *(Lệnh không có dòng nào = mức **chặn thường**, mặc định.)*
+
+> **Mức *không chặn* là thực thi đúng miễn trừ mà `rules/workflow.md` đã cấp từ trước** —
+> trước G41 file đó viết *"read-only commands may skip CHECKPOINT"* còn gate thì luôn đòi.
+> Hai file cùng được nạp vào mọi lệnh mà nói ngược nhau; agent theo cái nào là tuỳ lúc.
+
+### 3b — In gì
+
+**KHÔNG lặp lại những gì `[CTX LOADED]` vừa in.** Recap của context-loader (Bước 7) đã hiện
+Stack · Platform · Layers · CLAUDE.md · Dict · Entities · Lessons · Service · Status ngay phía
+trên. CHECKPOINT chỉ thêm **một** thông tin mới là `Target`.
+
+**Mọi thứ sạch** — recap báo `Status: FULL`, không cờ nào bật → in đúng hai dòng:
+
+```
+CHECKPOINT — Target: {resolved file path}
+Tiếp tục? (Y/N)
+```
+
+**Có bất thường** → thêm một dòng cho **mỗi** trạng thái, nặng nhất lên đầu:
+
+```
+CHECKPOINT
+🔴 Service  : unresolved — {lý do context-loader đã ghi}
+⚠️ CLAUDE.md: service overlay THIẾU — dùng root (code sinh ra có thể sai stack)
+⚠️ Target   : resolve bằng wildcard — {n} file khớp, chọn {file}
+⚠️ Module   : not configured — code sinh ra sẽ dùng default
+   Status   : PARTIAL — thiếu: {danh sách}
+   Target   : {resolved file path}
+Tiếp tục? (Y/N)
+```
+
+### 3c — Cờ nào bật, cờ nào KHÔNG
+
+Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader đã tính rồi** — không phát minh
+điều kiện mới, chỉ mang thứ đang bị giấu lên chỗ người dùng phải quyết định:
+
+| Bật cờ khi | Nguồn | Mức |
+|---|---|:---:|
+| `active_service = unresolved` | context-loader Bước 2b/2c/Fallback | 🔴 |
+| `Status = MINIMAL` | recap Bước 7 | 🔴 |
+| `Status = PARTIAL` | recap Bước 7 | ⚠️ |
+| CLAUDE.md thiếu, hoặc service overlay thiếu | context-loader Bước 3 | ⚠️ |
+| Target resolve qua wildcard, hoặc nhiều file khớp mà lệnh tự chọn | Bước 1 ở trên | ⚠️ |
+| `module` không cấu hình | recap Bước 7 | ⚠️ |
+
+**KHÔNG bật cờ cho:** `Lessons: chưa có` · `Dict: missing` · `Entities: missing`. Đó là
+*"dự án chưa điền"*, không phải *"có gì đó sai"* — chúng ở lại trong recap.
+
+> **Nguyên tắc một câu:** cờ dành cho thứ **framework không chắc chắn hoặc đã phải đoán**,
+> không dành cho thứ **người dùng chưa làm**. Đẩy hết mọi thứ lên thì CHECKPOINT lại đầy như
+> cũ, và ta quay về đúng chỗ xuất phát: một cổng luôn giống nhau thì bị lướt qua.
+
+### 3d — Chờ trả lời
+
+- "Y" → tiếp tục sang các bước riêng của lệnh.
+- "N" → dừng, hỏi người dùng muốn thay đổi gì.
+- Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
+  🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID (`active_platform` + `qc_artifact_dir` do §Phạm vi QC phân giải). Đọc `.Test.md` đã review từ `{qc_artifact_dir}test-cases/`.*
+
+## Context
+**BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
+rồi mới tiếp tục phần bên dưới.
+
+Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
+`project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+## Phạm vi QC
+
+**BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,
+rồi mới tiếp tục phần bên dưới.
+
+Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--force`).
+Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
+cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
+
+---
+
+## Stamp phiên bản nguồn
+
+**BẮT BUỘC — đọc `.agent/steps/qc-stamp.md` và thực thi phần áp cho lệnh này**,
+rồi mới tiếp tục phần bên dưới.
+
+Nó có **hai vế**: §1 **ghi** khối `Nguồn & phiên bản` vào artifact lệnh này sinh ra ·
+§2 **so** stamp của artifact lệnh này ĐỌC với version hiện tại của spec.
+Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp thành một con số không ai
+đọc — và một bộ TC lỗi thời sẽ chạy xanh rồi ghi `pass` **hợp lệ theo mọi phép kiểm**.
+
+---
+
+## Tiền điều kiện — test case phải `APPROVED`
+
+Đọc `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`, tìm dòng `**Verdict:**`.
+
+| Đọc được | Làm gì |
+|---|---|
+| `APPROVED` | đi tiếp |
+| `NEEDS_FIX` | **DỪNG** — `❌ Test case chưa đạt. Sửa bằng /qc-design-test {UC-ID}, soát lại bằng /qc-review-testcase {UC-ID}.` |
+| Không có file | **DỪNG** — `❌ Chưa soát test case. Chạy /qc-review-testcase {UC-ID} trước.` |
+
+> **Đây là thứ `/qc-run-test` cũ KHÔNG làm được** — nó nhận `REVIEW_<FEATURE>.md` mà không biết
+> biên bản đó soát test case hay soát script, nên không hỏi được câu này. Tách lệnh ở Đợt 2 · b1
+> sinh ra chính để mở đường cho cổng này.
+
+## Đầu vào — `AUTOMATION_ASSESSMENT.md` quyết định sinh cho TC nào
+
+Đọc `{qc_artifact_dir}AUTOMATION_ASSESSMENT.md` (do `/qc-automation-assess` tạo).
+
+| Đọc được | Làm gì |
+|---|---|
+| Bảng có TC `Automatable: Y` | sinh script **chỉ cho chúng** |
+| TC `Automatable: N` | **BỎ QUA** — chúng thuộc `/qc-run-manualtest`. KHÔNG sinh script rồi `skip` |
+| Không có file | **DỪNG** — `❌ Chưa đánh giá khả năng automate. Chạy /qc-automation-assess {TICKET-ID} trước.` |
+
+> **Vì sao phải DỪNG chứ không sinh cho tất cả.** Sinh cho tất cả là quay lại đúng ngầm định
+> mà `/qc-automation-assess` sinh ra để bỏ: TC không automate được bị `skip` rồi **biến mất** —
+> không ai chạy tay, và `/qc-report` chấm cả PRD là FAIL vĩnh viễn.
+
+**Sau khi sinh xong, ĐIỀN cột `Script file`** của từng TC `Y` bằng đường dẫn thật. Đây là
+**chỉ mục ngược duy nhất** TC → file code; `/qc-run-script` đọc đúng cột này để biết chạy file
+nào, thay vì suy đường dẫn từ quy ước đặt tên.
+
+## Role & stack (theo module qc-playwright)
+
+Bạn là **QC Script Designer**. Sinh Python pytest-playwright script + Page Object từ `.Test.md`.
+
+Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
+- Markdown-first: không bao giờ sinh script khi chưa có `.Test.md` đã review.
+- Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
+- **Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này** — và dựng mỗi Page Object locator từ test-id ổn định của nó. **Ưu tiên map; fallback** về role/label/text/CSS chỉ cho element có action mà **không** có test-id trong §4.5.6, kèm ghi chú để gap được thêm vào tech-design.
+- **TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.**
+
+  | Đọc được | Làm gì |
+  |---|---|
+  | web + attr ≠ `data-testid` (vd `data-test` · `data-qa`) | **BẮT BUỘC** cấu hình trước khi dùng `get_by_test_id()`: `playwright.selectors.set_test_id_attribute("{attr}")`. Bỏ bước này thì `get_by_test_id()` vẫn dò `data-testid` mặc định → **trượt 100% locator**. |
+  | web + attr = `data-testid` | `get_by_test_id("...")` như thường |
+  | RN / Flutter / native | Dùng đúng cơ chế mà `{attr}` mô tả (`testID` · `Key`/`Semantics(identifier:)` · `accessibilityIdentifier`) |
+  | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode:** `⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo platform ({attr mặc định}). Nếu FE dùng thuộc tính khác thì MỌI locator sẽ trượt. Chạy /map-testids {UC-ID} để ghi field này.` Rồi mới fallback |
+
+  > **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống. Nó hỏng **im lặng theo kiểu tệ nhất**: test fail "element not found" trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector.
+- pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+- Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
+- Phủ **100%** TC mang `Automatable: Y` — mỗi TC có đúng một test.
+
+## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-runner/`)
+
+`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
+`non-functional.md`, `exploratory/session.md`.
+
+---
+
+## Guard — hợp đồng test-id, chân thứ tư *(phép so GIÁ TRỊ, một chiều)*
+
+`bin/trace-schema.json` canh **ba** chân: §4.5.6 ↔ `.feature` (**T15**) · ↔ header `@trace.testid_attr`
+(**T16**) · ↔ code (**T17/T18**). Chân thứ tư — §4.5.6 ↔ `*.Test.md` — là chân duy nhất mà giá trị id
+bị **chép cứng vào một artifact bền**, và **trạm này chép nó lần thứ hai vào script**.
+
+**Phạm vi.** Không có block §4.5 client trong tech-doc → **im lặng hoàn toàn**, không kiểm gì.
+
+**Phép so — MỘT chiều:** gom id nhắc trong `*.Test.md` của UC · gom id ở §4.5.6 (lọc "Serves SC") ·
+`TC ∖ bảng` = id lạ → ⚠️.
+
+| Kết quả | Làm gì |
+|---|---|
+| Rỗng | **im lặng, đi tiếp** |
+| Có id lạ | `⚠️ Hợp đồng test-id: {k} id trong .Test.md không có ở §4.5.6: {danh sách}`<br/>kèm: `Chạy /map-testids {UC-ID} hoặc /qc-design-test {UC-ID}.` |
+
+**Mức là `warn`, không chặn.** Id sai làm test **ĐỎ**, không làm test **xanh giả**. Nhưng nó đỏ
+**đội lốt thứ khác** — `/qc-report` phân loại *product-gap* rồi in một `/report-bug`, và một lỗi
+**hợp đồng nội bộ** đi ra khỏi đội QC thành phiếu lỗi gửi PO.
+
+## Output — lệnh này ghi những gì, ở đâu
+
+| Đường dẫn | Nội dung | Người sửa tay? |
+|---|---|:---:|
+| `tests/<project>/test_<feature>.py` | pytest script, 1-1 với `test-cases/` | ✅ **có** — `script-bug` |
+| `pages/<feature>_page.py` | Page Object (3 lớp + BasePage) | ✅ **có** — `script-bug` |
+| `{qc_artifact_dir}AUTOMATION_ASSESSMENT.md` — cột `Script file` | đường dẫn script của từng TC | ❌ lệnh ghi |
+
+*(Đường dẫn theo `modules/qc-playwright/stack-profile.yaml` §layout.)*
+
+**KHÔNG ghi sổ trace.** Sinh script không phải là chạy test — ghi `qc_status` ở đây là khẳng định
+một điều chưa xảy ra. Đó là việc của `/qc-run-script` và `/qc-run-manualtest`.
+
+## Trace tag (bắt buộc)
+
+Mỗi test được sinh ra mang scenario nó verify, lấy từ Trace matrix của `.Test.md`:
+
+```python
+# @trace.verifies={UC-ID}-SC{N}
+def test_TC_<FEATURE>_001_...(...): ...
+```
+
+## Tag ưu tiên — `@smoke` / `@regression`
+
+Đọc cột `Priority` của mỗi TC trong `.Test.md`:
+
+| Priority | Tag |
+|---|---|
+| `P0` | `@smoke` **và** `@regression` |
+| `P1`–`P3` | `@regression` |
+
+`/qc-smoke-test` (Đợt 4) chạy đúng tập `@smoke`. Không gắn tag ở đây thì smoke suite rỗng, và
+lệnh đó không có gì để chạy.
+
+## Testability Improvement List
+
+Gặp rào cản kỹ thuật khiến một TC `Automatable: Y` **không** script được (thiếu test-id, không có
+API dựng dữ liệu, màn hình phụ thuộc thiết bị thật) → ghi một mục vào
+`{qc_artifact_dir}TESTABILITY_IMPROVEMENTS.md`:
+
+```
+## IMPROVE-{YYYYMMDD}-{NN} — 🟡 Proposed
+TC        : TC_<FEATURE>_{NNN}
+Rào cản   : {mô tả cụ thể, trỏ được về element/endpoint}
+Đề xuất   : {việc FE/BE cần làm}
+```
+
+**Rồi hạ TC đó về `Automatable: N`** để `/qc-run-manualtest` nhặt lên. Bỏ qua bước này là để TC
+rơi vào khoảng trống giữa hai trạm — đúng lỗ hổng mà lệnh thứ ba sinh ra để bịt.
+
+## Chạy lại — script đã tồn tại *(GIỮ bản sửa tay)*
+
+**Vòng đời của bộ script là CHẠY nhiều, SINH ít.** `/qc-run-script` §Phân loại FAIL khai tường minh
+rằng QC **sửa tay** chính các file trên: *"`script-bug` … **QC tự sửa.** Không mở bug"*. Nên chuỗi
+bình thường là **sinh → chạy → đỏ → QC sửa tay → chạy lại**, và bước cuối **không được** là bước xoá.
+
+| Tình huống | Xử lý |
+|---|---|
+| Script đã có, TC không đổi | **KHÔNG sinh lại.** Báo `đã có, bỏ qua` rồi đi tiếp — đây là ca thường nhất |
+| TC mới xuất hiện trong `.Test.md` | Sinh **chỉ phần thiếu**; giữ nguyên file đã có |
+| Script có **thay đổi chưa commit** | **DỪNG** — xem dưới |
+
+**Nhận diện "đã sửa tay" bằng `git status` / `git diff`** trên các đường dẫn ở §Output.
+
+```
+❌ {n} file script có thay đổi chưa commit — có thể là bản sửa `script-bug` của bạn.
+   Sinh lại sẽ XOÁ chúng.
+   Files: {danh sách}
+   Cách đúng: commit bản sửa trước, rồi chạy lại.
+   Cố ý bỏ hết và sinh từ trắng: thêm --force
+```
+
+**KHÔNG đoán.** Thấy thay đổi chưa commit thì lệnh **không tự phân biệt** *"QC vừa sửa"* với *"lần
+sinh trước chưa commit"* — hai ca nhìn giống hệt nhau trên `git status`. **Dừng oan một lần rẻ hơn
+xoá nhầm một lần.**
+
+> **Vì sao dùng `git`, không dùng marker hay băm nội dung.** Marker (`# @qc.hand-fixed`) **dựa vào
+> kỷ luật** — đúng thứ đã bác ở G64. Băm nội dung **du nhập một lớp cơ chế mới**: `rules/workflow.md`
+> ghi *"0 content hash trong toàn bộ codebase"*, và G63 đã chọn không mở mặt trận đó.
+>
+> **Vì sao ca "không đổi gì" phải HOÀN TOÀN im lặng.** Bản vá nào làm nó hỏi mỗi lần thì người dùng
+> sẽ thêm `--force` vào alias — và lúc đó ta mất sạch lớp bảo vệ này.
+
+Có `--force` → report **bắt buộc** khai:
+```
+⚠️ --force: sinh lại từ trắng — đã xoá {n} file script có thay đổi chưa commit: {danh sách}
+```
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md`.
+
+- **Bịa:** mỗi locator trỏ được về một row §4.5.6 **có thật**, không phải id tự đặt?
+- **Nhảy bước:** mọi TC `Automatable: Y` đều có test, và mọi test đều mang `@trace.verifies`?
+- **Số liệu:** số test sinh ra = đếm thật trên file vừa ghi?
+
+## Report
+
+**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-design-script Hoàn tất — {UC-ID}
+Script  : {n} test · {m} Page Object   ({k} file đã có → bỏ qua)
+Tag     : @smoke {s} · @regression {r}
+Improve : {i} mục IMPROVE-* (TC hạ về Automatable: N)
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý}
+Next    : /qc-review-script {UC-ID}
+```

package/core/commands/qc-design-test.md

@@ -6,11 +6,11 @@ ported_from: ai-automation-qc-base
 
 # /qc-design-test — QC Test-Case Design
 
-> Stage 3 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — Python đến sau ở /qc-run-test.
+> Stage 3 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-design-script → qc-review-script → qc-run-script → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — Python đến sau ở /qc-design-script.
 
 ## Gate
 
-*Checkpoint: **chặn CỨNG** — ghi đè `*.Test.md` đã qua cổng HITL `/qc-review` → mất `Status` đã duyệt, `Expected Result` đã sửa theo finding, dấu 🚫 Block vừa gỡ; và ĐÁNH SỐ LẠI `TC_<FEATURE>_NNN` mà `REVIEW_<FEATURE>.md` đang trỏ vào. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+*Checkpoint: **chặn CỨNG** — ghi đè `*.Test.md` đã qua cổng HITL `/qc-review-testcase` → mất `Status` đã duyệt, `Expected Result` đã sửa theo finding, dấu 🚫 Block vừa gỡ; và ĐÁNH SỐ LẠI `TC_<FEATURE>_NNN` mà `REVIEW_<FEATURE>.md` đang trỏ vào. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
 
 *Mức cứng chỉ áp khi file `.Test.md` **đã tồn tại**. Lần thiết kế đầu không ghi đè gì, đi thẳng. Xem §Chạy lại.*
 
@@ -93,7 +93,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ờ** |
 
@@ -101,6 +101,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ì**.
@@ -238,7 +244,7 @@ hai cái đó là phép ĐẾM, con số của chúng có giá trị ngay cả k
 > **không phân biệt được** với một lần chạy đúng.
 >
 > Thiếu `DOC_GAP.md` là ca đắt nhất: TC bị gap chặn **trông y hệt** TC bình thường (không có dấu
-> `🚫 Block` nào), nên `/qc-run-test` chạy nó, thấy đỏ, và `/qc-report` phân loại thành *product-gap*
+> `🚫 Block` nào), nên `/qc-run-script` chạy nó, thấy đỏ, và `/qc-report` phân loại thành *product-gap*
 > rồi in một `/report-bug` sẵn-chạy. Lỗi đi **ra khỏi đội QC** thành bug gửi PO — cho một hành vi
 > mà spec chưa bao giờ định nghĩa. Đây là **báo cáo sai**, cùng loại với việc giữ một `pass` đã hết
 > hiệu lực (`rules/workflow.md` §*"Làm mất hiệu lực ≠ ghi đè"*).
@@ -316,7 +322,7 @@ vế nói về **cùng một** kết cục — ví dụ *"form hiển thị đ
 ## Role
 
 Bạn là **QC Designer** — stage 3. Sinh/bảo trì các file test-case Markdown
-(`.Test.md`) từ requirement đã phân tích + plan. Output feed vào qc-run-test (Python) và
+(`.Test.md`) từ requirement đã phân tích + plan. Output feed vào qc-design-script (Python) và
 qc-review. Bạn **không** viết Python.
 
 ## Skills (`{paths.qc_skills_dir}/qa-designer/`)
@@ -353,11 +359,11 @@ qc-review. Bạn **không** viết Python.
 đều ở `shared/tc-metadata-format.md`. **Đừng lặp lại ở đây.** Dưới đây chỉ là thứ riêng của trạm:*
 
 - Markdown-first; đừng design khi requirement chưa rõ — đẩy ngược về qc-plan/qc-analyze.
-- **Tham chiếu test-id, không phải gợi ý hình ảnh.** Với mỗi step GUI tác động lên một element, trích test-id ổn định từ bảng §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") để qc-run-test dựng locator từ contract. Nếu một element có action không có test-id trong §4.5.6, ghi chú lại (qc-run-test sẽ fallback về locator role/text chậm hơn).
+- **Tham chiếu test-id, không phải gợi ý hình ảnh.** Với mỗi step GUI tác động lên một element, trích test-id ổn định từ bảng §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") để qc-design-script dựng locator từ contract. Nếu một element có action không có test-id trong §4.5.6, ghi chú lại (qc-design-script sẽ fallback về locator role/text chậm hơn).
 - **Đọc `@trace.testid_attr` từ header tech-doc gộp** (do `/map-testids` ghi) và ghi lại một
   dòng `Test-ID attribute: {attr}` ở metadata đầu file `.Test.md`. §4.5.6 chỉ cho **giá trị**
-  test-id; `@trace.testid_attr` là **tên thuộc tính** chứa chúng — `/qc-run-test` cần nó để cấu
-  hình locator, `/qc-review` cần nó để biết selector trong script có đúng contract không.
+  test-id; `@trace.testid_attr` là **tên thuộc tính** chứa chúng — `/qc-design-script` cần nó để cấu
+  hình locator, `/qc-review-script` cần nó để biết selector trong script có đúng contract không.
   Không đọc được `@trace.testid_attr` → ghi
   `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`; **đừng bỏ trống, đừng
   tự đoán theo platform** — đoán sai thì mọi locator trượt 100%, vì một lý do không liên quan
@@ -375,7 +381,7 @@ không phải cột bảng** (file TC không có ký tự `|`):
 ```
 
 Lấy từ `@trace.scenario` của `.feature`. Một SC map được nhiều TC. Đây là **join key** cho phép
-qc-run-test ghi `qc_status` theo từng scenario vào sổ trace — **thiếu nó thì test vẫn chạy,
+qc-run-script ghi `qc_status` theo từng scenario vào sổ trace — **thiếu nó thì test vẫn chạy,
 vẫn pass/fail, nhưng kết quả không vào được sổ và không ai biết nó phủ kịch bản nào.**
 
 Cuối file: **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách TC bị block** — cả hai dạng danh sách.
@@ -450,7 +456,7 @@ Hỏi từng SC chưa phủ: *"TC cho SC này verify được mà **không cần
 > — đúng Bước 2 của `shared/skill-decision-tree.md`), không phải một nhận định tự do. Ghi *"SC này
 > phức tạp"*, *"tương tự SC2"* thì **không** rơi vào ô nào của bảng trên.
 >
-> **Vì sao không cứ bù vào file đang mở cho gọn.** File API được `/qc-run-test` đọc bằng lane API.
+> **Vì sao không cứ bù vào file đang mở cho gọn.** File API được `/qc-design-script` đọc bằng lane API.
 > Một TC cần UI nằm ở đó **không chạy nổi** — và nó sẽ đỏ dưới dạng *script-bug* hoặc *product-gap*,
 > không ai truy ngược về một quyết định ghi file ở phase thiết kế.
 
@@ -492,7 +498,7 @@ nó tồn tại, và không ai phát hiện được khi nó chết.
 
 ## Chạy lại — `.Test.md` đã tồn tại *(GIỮ, không sinh lại từ trắng)*
 
-File `.Test.md` đi qua **cổng HITL `/qc-review`**. Bốn thứ trong đó **không sinh lại được**:
+File `.Test.md` đi qua **cổng HITL `/qc-review-testcase`**. Bốn thứ trong đó **không sinh lại được**:
 
 | Mất gì | Vì sao |
 |---|---|
@@ -506,7 +512,7 @@ File `.Test.md` đi qua **cổng HITL `/qc-review`**. Bốn thứ trong đó **k
 | Tình huống | Xử lý |
 |---|---|
 | TC cũ, spec **không đổi** | **Giữ nguyên** — số · `Status` · `Expected Result` đã sửa |
-| TC cũ, spec **đổi** | Cập nhật **nội dung**; giữ **số** và `Status`, thêm ⚠️ để `/qc-review` soát lại |
+| TC cũ, spec **đổi** | Cập nhật **nội dung**; giữ **số** và `Status`, thêm ⚠️ để `/qc-review-testcase` soát lại |
 | TC **mới** | Cấp số **tiếp theo** — không dồn, không tái dùng |
 | TC không còn ứng với SC nào | **KHÔNG xoá** → `Status: Obsolete`, ghi lý do |
 
@@ -534,7 +540,7 @@ sẵn ở `{paths.qc_skills_dir}/qa-designer/shared/tc-metadata-format.md` §*Qu
 quyết (Answered)*. Bước đóng đó **chưa lệnh nào gọi** — nên dấu chặn chỉ dán vào, không bao giờ gỡ ra.
 
 Một TC mang `🚫 Block` là một TC có **Expected Result dựa trên giả định chưa ai xác nhận**. Nó nằm
-trong thư mục dùng chung, được `Guard SC coverage` đếm là **đã phủ**, và `/qc-run-test` sẽ nhặt lên.
+trong thư mục dùng chung, được `Guard SC coverage` đếm là **đã phủ**, và `/qc-design-script` sẽ nhặt lên.
 
 > **Vì sao stamp phiên bản (§Stamp phiên bản nguồn) KHÔNG phủ ca này.** Gap chuyển `Open → Answered`
 > là một **ô trong `DOC_GAP.md`** — nó **không bump version nào cả**. Mọi drift detector của framework
@@ -590,7 +596,7 @@ Ghi dưới `{qc_artifact_dir}test-cases/`
 PRD**. Tên file mang `<FEATURE>` nên các UC không đâm nhau; `@trace.verifies` là chỗ phân biệt
 TC thuộc UC nào.
 
-**Đuôi bắt buộc là `.Test.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`; ghi ra
+**Đuôi bắt buộc là `.Test.md`.** `/qc-design-script` và `/qc-review-testcase` tìm `*.Test.md`; ghi ra
 `TC_<FEATURE>.md` là ghi ra thứ **không trạm nào tìm thấy**, và **không có gì báo lỗi**.
 
 `🚫 Block` trỏ `../DOC_GAP.md` — lên một cấp, vì file gap ở thư mục cha của `test-cases/`.
@@ -633,5 +639,5 @@ Guard SC coverage: {khớp {K}/{K} | ⚠️ {K}/{total} — đã bù {m} SC: {da
        {nếu có SC cần UI mà đang chạy --api: "⚠️ {n} SC cần UI chưa có TC ở file giao diện —
        KHÔNG bù vào file API. Chạy: /qc-design-test {UC-ID} (không cờ). SC: {danh sách}"}
 Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
-Next : /qc-review {UC-ID}   ← review test case trước khi sinh script
+Next : /qc-review-testcase {UC-ID}   ← review test case trước khi sinh script
 ```

package/core/commands/qc-plan.md

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-plan — QC Test Plan & Risk Analysis
 
-> Stage 2 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-planner của team QC.
+> Stage 2 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-design-script → qc-review-script → qc-run-script → qc-report). Port từ qa-planner của team QC.
 
 ## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
@@ -88,7 +88,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ờ** |
 
@@ -96,6 +96,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ì**.
@@ -240,7 +246,7 @@ Bắt buộc:
 
 ### Chạy lại — ghi đè ở đây AN TOÀN, và đây là lý do
 
-*(Ba trạm QC khác — `/qc-analyze` · `/qc-design-test` · `/qc-run-test` — đều ở mức **chặn CỨNG** kèm
+*(Ba trạm QC khác — `/qc-analyze` · `/qc-design-test` · `/qc-design-script` — đều ở mức **chặn CỨNG** kèm
 §Chạy lại. Trạm này **không**, và đó là kết luận có chủ ý, không phải chỗ sót.)*
 
 `TEST_PLAN.md` **không có ô nào người nhập tay**: `questions-for-dev` là danh sách **gửi đi** — câu

package/core/commands/qc-report.md

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-report — QC Test Report & Evidence
 
-> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ bước report của qa-runner team QC.
+> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-design-script → qc-review-script → qc-run-script → qc-report). Port từ bước report của qa-runner team QC.
 
 ## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
@@ -88,7 +88,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ờ** |
 
@@ -96,6 +96,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ì**.
@@ -162,7 +168,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
 
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Sinh report từ lần chạy `/qc-run-test` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Sinh report từ lần chạy `/qc-run-script` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,