@educa-corp/sdd-framework 0.9.6 → 0.9.8

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

@@ -0,0 +1,430 @@
+---
+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)
+
+> Trạm 6/9 của dây chuyền QC automation. 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` · `APPROVED_WITH_SUGGESTIONS` | **đi tiếp** — in một dòng bằng chứng:<br/>`✅ Cổng test case đã soát: {verdict} — {đường dẫn file vừa đọc}` |
+| `REVISION_REQUIRED` · `REJECTED` | **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 (module theo nền — bảng §2b của `steps/qc-scope.md`)
+
+Bạn là **QC Script Designer**. Sinh script test + đối tượng trang/màn/API từ `.Test.md`, theo
+**nền đã phân giải ở §2b** — web · app · system, mỗi nền một hình dạng code khác nhau.
+
+Quy tắc stack (BẮT BUỘC — từ `stack-profile.yaml` của module đã phân giải ở §2b):
+- **Markdown-first:** không bao giờ sinh script khi chưa có `.Test.md` đã review.
+- **Phủ đúng TC `Automatable: Y`** của `AUTOMATION_ASSESSMENT.md` — mỗi TC đúng một test,
+  không hơn không kém. TC `Y` gặp rào cản kỹ thuật lúc viết → `test.fixme('TC-xxx — {lý do}')`
+  + ghi `IMPROVE-xxx`, **không âm thầm bỏ qua**.
+- **Locator từ hợp đồng test-id, 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` — lọc theo cột
+  *"Serves SC"* khớp SC của UC này. Ưu tiên map; fallback 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.
+- **Không hard-code** URL · credential · timeout. **Không chờ cứng.** Data để ở `data/`.
+
+> 🔑 **Cách đọc `@trace.testid_attr` và cấu hình thuộc tính test-id KHÔNG viết ở đây** — nó nằm
+> ở `_shared/{web|mobile|api}-conventions.md` của nền, nạp ở §Skills ngay dưới. Lý do gỡ khỏi lệnh
+> *(Bước S · S4, 2026-09-17)*: bảng đó từng tồn tại **hai bản**, và hai bản đã lệch nhau — bản
+> trong lệnh còn ghi API của stack cũ trong khi bản ở skill đã đúng. **Một bảng, một chỗ.**
+>
+> Nội dung vẫn bắt buộc, chỉ đổi chỗ đọc: thuộc tính test-id ≠ mặc định mà không cấu hình trước
+> thì **mọi locator trượt 100 %**, và nó trượt **trông y hệt một bug sản phẩm** — QC sẽ đi mở
+> phiếu lỗi gửi PO thay vì sửa một dòng config.
+>
+> **Vì sao không suy thuộc tính 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.
+
+## Skills — chọn NỀN rồi TẦNG, nạp MỘT file (`{paths.qc_skills_dir}/qa-script-designer/`)
+
+> 🔴 **DỪNG nếu TC mang lane `job` hoặc `queue`.** Hai hình dạng này có TC *(trạm 3 đã hỗ trợ)*
+> nhưng **chưa có skill sinh script**. Sinh bừa bằng lane `api` là tạo API Object cho một thứ
+> **không có endpoint nào** — script dịch được, chạy được, và kiểm **sai thứ**.
+>
+> ```
+> ⛔ {UC-ID} có {n} TC lane {job|queue} — trạm này chưa hỗ trợ hình dạng đó.
+>    TC vẫn dùng được: chạy tay qua /qc-run-manualtest, hoặc đánh Automatable: N
+>    kèm lý do "chưa có bộ sinh script cho lane {lane}".
+> ```
+>
+> TC lane `api` trong cùng UC thì **vẫn sinh bình thường** — dừng theo TC, không dừng cả UC.
+
+**Nạp trước:** `_shared/{web|mobile|api}-conventions.md` + `_shared/file-naming-and-folders.md`
+theo nền đã phân giải ở `steps/qc-scope.md` §2b. Rồi chọn **MỘT** file lane:
+
+| `active_platform` | File |
+|---|---|
+| `web` · `webview` | `web/functional/{gui-screen,gui-feature,api}.md` · `web/{integration,e2e,non-functional}.md` |
+| `app` · `app-ios` · `app-android` | `mobile/functional/{screen,feature}.md` · `mobile/{integration,e2e,non-functional}.md` |
+| `system` | `api/{endpoint,auth,security}.md` |
+
+> ⚠️ **Ba nền sinh ba hình dạng code khác nhau.** Web dùng Page Object; app dùng **Screen Object**
+> với thứ tự locator của Appium; `system` dùng **API Object** — không màn hình, không locator,
+> không chờ, và **cấm `expect()` bên trong object**. Nạp nhầm lane là sinh ra thứ chạy được nhưng
+> sai kiến trúc, và `/qc-review-script` sẽ chặn nó bằng `R01`.
+
+---
+
+## 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/{TICKET-ID}/<feature>-<scenario>.spec.ts` | spec, 1-1 với `test-cases/` | ✅ **có** — `script-bug` |
+| `pages/<feature>.page.ts` *(web)* · `api/<resource>.api.ts` *(system)* · `screens/<feature>.screen.ts` *(app)* | đối tượng trang/API/màn | ✅ **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 `§layout.{web|api|mobile}` của module đã phân giải ở §2b — KHÔNG viết cứng tên module.)*
+
+**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`:
+
+```typescript
+// @trace.verifies={UC-ID}-SC{N}
+test('TC_<FEATURE>_001 — …', async ({ page }) => { … });
+```
+
+## 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}
+```