@educa-corp/sdd-framework 0.9.6 → 0.9.7

package/core/commands/qc-run-manualtest.md

@@ -0,0 +1,401 @@
+---
+version: 1.0
+updated: 2026-09-16
+---
+
+# /qc-run-manualtest — Ghi kết quả test TAY vào sổ trace
+
+> Stage 7b. QC chạy tay các TC mang `Automatable: N`, lệnh **hỏi từng TC** rồi ghi `qc_status`
+> vào sổ trace. Không có lệnh này thì những scenario ấy nằm `not_run` vĩnh viễn — và `/qc-report`
+> sẽ chấm cả PRD là **FAIL**, không cách nào sửa.
+
+## Gate
+
+*Checkpoint: **không chặn** — lệnh chỉ GHI kết quả mà người vận hành vừa tự tay nhập, vào đúng cột sổ trace do nó sở hữu. Không sinh, không đè artifact nào của ai.*
+
+# 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 `AUTOMATION_ASSESSMENT.md` để liệt kê TC `Automatable: N`.*
+
+## 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**.
+
+---
+
+## Vì sao lệnh này tồn tại
+
+`/qc-automation-assess` đóng dấu `Automatable: N` rồi nói *"giữ trong bộ manual"*. Rồi hết —
+**không trạm nào chạy và ghi `qc_status` cho chúng.** Đến `/qc-report`:
+
+```
+SC1 pass · SC2 pass · SC3 pass       ← /qc-run-script ghi
+SC4 not_run  (OTP qua SMS, P0)       ← KHÔNG AI GHI. QC đã test tay, thấy OK, không có chỗ ghi
+SC5 not_run  (sinh trắc học)         ← KHÔNG AI GHI
+
+Execution coverage = 3/5 = 60% < 85        ❌
+SC P0 not_run = 1 > 0                      ❌
+→ VERDICT: FAIL — và FAIL vĩnh viễn
+```
+
+Bước đánh giá **cho phép** đóng dấu `N`; Đợt 3 **trừng phạt** chính dấu đó. Không bịt chỗ này thì
+đội QC sẽ làm điều hợp lý duy nhất còn lại: hạ `coverage_min` về 0 để verdict xanh — **và cả Đợt 3
+thành trang trí.**
+
+## Cách nhập — HỎI TỪNG TC, không đọc file checklist
+
+**Chốt với chị QC ngày 2026-09-16.** Phương án *"QC điền một file `MANUAL_RUN.md`, lệnh đọc file
+đó"* nghe tiện hơn và từng được khuyến nghị. Lý do bác bỏ, nguyên văn:
+
+> *"Chị sợ đọc checklist mà lệch thông tin lại ghi kết quả sai."*
+
+Một file điền tay là **nguồn thứ hai có thể trôi**: TC bị đánh số lại sau một lần `/qc-design-test`,
+TC mới thêm, dòng cũ còn sót. Khi nó lệch thì lệnh ghi `qc_status` cho **đúng SC sai** — sổ trace
+báo `pass` cho một scenario chưa ai chạy. Đó là kiểu hỏng **nói dối**; cái giá của hỏi-từng-TC chỉ
+là **ồn**. Cùng họ với `positive_assertion_guards`: **không bao giờ** ghi `pass` khi dữ liệu nền
+không chắc.
+
+### Ghi NGAY sau mỗi câu trả lời — không gom cuối phiên
+
+Test tay chạy nhiều buổi, nhiều người. Nên:
+
+1. Liệt kê TC `Automatable: N` — **đọc từ `{qc_artifact_dir}AUTOMATION_ASSESSMENT.md`**, không
+   tự đoán TC nào là manual — rồi lọc tiếp những TC mà row sổ trace còn `not_run`.
+   Không có file bảng → **DỪNG**: `❌ Chưa đánh giá khả năng automate. Chạy /qc-automation-assess {TICKET-ID} trước.`
+2. Hỏi **từng cái**, và **ghi vào sổ trace ngay** sau mỗi câu trả lời.
+3. Chạy lại lệnh ⇒ chỉ hỏi những SC **còn** `not_run` — tức **tự resume**.
+
+Mất phiên giữa chừng không mất gì đã nhập. Và **không có artifact trung gian nào để trôi** — sổ
+trace là nguồn duy nhất, đúng điều chị QC lo.
+
+### Khuôn câu hỏi
+
+```
+TC_<FEATURE>_{NNN}  ({UC-ID}-SC{N})  Priority {P}
+  {tóm tắt 1 dòng của TC}
+  Kết quả? (pass / fail / skip / bỏ qua lần này)
+```
+
+`pass` hoặc `fail` → hỏi tiếp **bằng chứng** *(bắt buộc, xem dưới)*.
+
+## Bằng chứng — `pass` không được phép là "vì tôi nói vậy"
+
+`/qc-run-script` chỉ ghi `pass` khi có output của runner. Test tay phải có mức tương đương:
+
+| Ghi | Bắt buộc kèm |
+|---|---|
+| `pass` | **ai chạy** · **ngày** · một trong: ảnh chụp màn hình · số phiếu/giao dịch thật · ghi chú mô tả quan sát được *(≥ 1 câu cụ thể, không phải "ok")* |
+| `fail` | ai chạy · ngày · **hiện tượng quan sát được** so với `Expected Result` |
+| `skip` | lý do — thiếu thiết bị, thiếu tài khoản, môi trường chưa sẵn |
+
+Bằng chứng ghi vào cột `qc_blocked_by`? **Không.** Ghi vào `{qc_artifact_dir}MANUAL_EVIDENCE.md`,
+**append một dòng mỗi lần ghi** — file này chỉ thêm, không sửa, nên nó không trôi được:
+
+```
+| {today} | {UC-ID}-SC{N} | {pass|fail|skip} | {người chạy} | {bằng chứng} |
+```
+
+## Write Trace State — qc_status
+
+Cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv`, khớp row theo `sc_id`.
+
+| Cột | Giá trị |
+|---|---|
+| `qc_status` | `pass` · `fail` · `skip` theo câu trả lời — **sau khi** qua §Guard dưới đây |
+| `qc_run_at` · `last_updated` | hôm nay `YYYY-MM-DD` |
+| `qc_owner` | `dev` nếu `fail` *(defect thật — test tay không có nhánh `script-bug`)* · `po` nếu `skip` vì một `DOC_GAP` 🔴 Blocker đang open · `—` nếu `pass` |
+| `qc_blocked_by` | `GAP-{id}` khi bị chặn bởi spec gap · `BUG-{id}` sau khi `/report-bug` file · `—` ngược lại |
+
+**Không có nhãn `flaky` ở đây.** `flaky` là kết luận rút ra từ việc chạy lại tự động nhiều lần;
+một lượt chạy tay không sinh ra được dữ liệu đó. Kết quả không lặp lại được thì ghi `skip` kèm lý do.
+
+**Không bao giờ** đụng `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu), và không đụng
+row của SC mà lượt này không hỏi tới.
+
+### Guard — ĐỌC `status` trước khi ghi `pass` *(bắt buộc)*
+
+*Contract: `bin/trace-schema.json` → `positive_assertion_guards`. Cùng luật với `/qc-run-script`, và lý do giống hệt.*
+
+`pass` mang nghĩa **"scenario này đã được nghiệm thu theo spec HIỆN TẠI"** — không phải *"tôi vừa bấm thử và thấy chạy"*.
+
+| `status` của row | Ghi gì | `qc_run_at` |
+|---|---|---|
+| `OK` · `GAP` · `UNTRACKED` | như bảng trên | hôm nay |
+| **`DRIFT`** | QC trả lời `pass` → **`not_run`** *(KHÔNG `pass`)* · `fail` → `fail` như thường · `skip` → `skip` | `—` nếu ghi `not_run` |
+| **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` | `—` |
+
+**Chỉ `pass` bị chặn.** `fail` là tin xấu thật, `skip` là giá trị trung tính — chặn chúng là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.
+
+Khi hạ về `not_run` vì `DRIFT`/`ORPHANED`, **KHÔNG** clear `qc_owner`/`qc_blocked_by`. In ngay cho người vừa trả lời:
+```
+⚠️  {sc_id} — bạn báo PASS nhưng row đang {DRIFT | ORPHANED}, nên KHÔNG ghi pass.
+    Spec đã đổi sau lần sinh test gần nhất; kết quả chạy tay đang nghiệm thu một hành vi cũ.
+    Làm: /generate-code {UC-ID} → /qc-design-test lại → chạy lại lệnh này.
+```
+
+> **Vì sao guard này quan trọng hơn ở đây so với `/qc-run-script`.** Ở trạm tự động, người ta còn
+> có trace/video để đối chiếu sau. Ở test tay, **lời khẳng định của người chạy là bằng chứng duy
+> nhất** — nên lớp chặn cơ học là thứ duy nhất đứng giữa một cái gật đầu thiện chí và một dòng
+> `pass` sai trong sổ.
+
+## Refresh Panel Mirror
+# Làm mới panel mirror của Living Docs *(local)*
+
+> **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`. Không regenerate được. | **PHẢI commit** |
+> | `./.trace-mirror/` ở gốc workspace hiện tại | **MIRROR** — bản sao tiện cho panel VS Code. Sinh lại được bất cứ lúc nào. | **Luôn gitignore** |
+>
+> Trước v0.4.3 cả hai đều tên `.trace`, nên một luật gitignore theo tên có thể **xoá sạch sổ gốc**
+> khi dev mở thẳng spec repo làm workspace (lúc đó hai path bằng nhau). Hai tên khác nhau làm
+> luật git đọc được bằng mắt và **không còn ca nhập nhằng nào**: `.trace-mirror/` không bao giờ
+> commit, `.trace/` không bao giờ gitignore.
+
+## Khi nào CÓ mirror
+
+Mirror chỉ tồn tại khi **`{paths.trace_dir}` nằm NGOÀI workspace hiện tại** — panel đọc từ workspace đang mở nên cần một bản sao ở đây.
+
+| Tình huống | `{paths.trace_dir}` | Có mirror? |
+|---|---|---|
+| Single-service | `./.trace` — **trong** workspace | ❌ Không. Panel đọc thẳng `.trace/trace-report.json`. Bỏ qua cả file này. |
+| Dev mở thẳng **spec repo** | `./.trace` — **trong** workspace | ❌ Không. Như trên. |
+| Umbrella + `spec_source`, dev đứng ở umbrella hoặc service submodule | `{spec_source}/.trace` — **ngoài** workspace | ✅ Có |
+| Umbrella legacy (không `spec_source`) | `.trace` theo từng service | ✅ Có |
+
+Quy tắc một dòng: **phân giải `panel_mirror = ./.trace-mirror` ở gốc workspace hiện tại; nếu `{paths.trace_dir}` đã nằm trong workspace này thì bỏ qua toàn bộ bước mirror.**
+
+---
+
+Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
+
+**Khi `setup.spec_source` được đặt (trace gộp — trường hợp phổ biến):**
+`{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
+Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
+commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
+
+1. Phân giải `panel_mirror = ./.trace-mirror` tại **gốc workspace hiện tại**.
+2. Nếu `{paths.trace_dir}` **không** nằm trong workspace hiện tại, copy mỗi
+   `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang ở
+   **cột `service` (cột 23)** của chính từng row, do `/generate-bdd` ghi từ `@trace.service`.
+3. **KHÔNG copy `trace-history.jsonl`.** Nó là dữ liệu tích luỹ, không phải thứ sinh lại được —
+   nhân bản nó ra một thư mục gitignore là tạo hai lịch sử lệch nhau rồi mất bản thật.
+
+**Legacy (không có `spec_source` — trace theo service):**
+Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`
+(namespace theo `active_service`).
+
+Cách này giữ panel Living Docs của workspace đang mở luôn mới **giữa các lần sync** — nó chỉ là
+một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (canonical, trong
+`{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
+được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
+bên trong từng sub-agent.
+
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md`.
+
+- **Bịa:** mỗi `pass` có một dòng bằng chứng **thật** trong `MANUAL_EVIDENCE.md`, không phải mô tả chung chung?
+- **Nhảy bước:** đã hỏi **hết** TC `Automatable: N` còn `not_run`, hay dừng giữa chừng mà không báo?
+- **Số liệu:** số row vừa ghi = đếm thật trên sổ trace?
+
+## 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-run-manualtest Hoàn tất — {UC-ID} ({active_platform})
+Đã hỏi : {n}/{m} TC Automatable: N còn not_run
+Ghi    : pass {p} · fail {f} · skip {s}   ({d} row hạ not_run vì DRIFT/ORPHANED)
+Còn nợ : {r} TC chưa trả lời — chạy lại lệnh này để tiếp tục (tự resume)
+Evidence: {qc_artifact_dir}MANUAL_EVIDENCE.md (+{n} dòng)
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý}
+Next   : /qc-report {UC-ID}
+```