@educa-corp/sdd-framework 0.9.5 → 0.9.7

package/core/commands/review-context.md

@@ -1,11 +1,13 @@
 # /review-context — Review PRD hoặc BDD về Chất lượng & Tính nhất quán
 
-**Chế độ phân tích READ-ONLY — ghi file findings, KHÔNG sửa target.**
+**Hai chế độ.** *Phân tích* — chỉ đọc target, ghi file findings. *`--resume`* — **áp fix THẲNG vào target và bump version**. Nhãn "read-only" cũ chỉ đúng cho chế độ đầu (sửa 2026-09-16).
 **Dùng `--resume` để áp dụng các finding được chấp nhận.**
 
 ## Gate
 
-*Checkpoint: **không chặn** — read-only (ghi findings vào .agent/review/). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+*Checkpoint: **chặn CỨNG** — ghi đè quyết định reviewer: `--full` BỎ QUA findings cũ (mất `status` accepted/modified/rejected của cả một vòng Review Board), và `--resume` áp fix thẳng vào PRD/`.feature` rồi bump version. Cùng hình dạng `/refine-prd`. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng **chỉ áp** khi file findings ĐÃ TỒN TẠI và có ≥1 finding mang `status` `accepted`/`modified`/`rejected` (tức đã qua Review Board), HOẶC khi chạy với `--full`/`--resume`. Lần phân tích đầu không ghi đè gì — bắt CHECKPOINT cứng ở đó là ồn vô cớ. Cùng khuôn `/map-testids`.*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -86,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ờ** |
 
@@ -94,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ì**.

package/core/commands/review-tech-docs.md

@@ -1,11 +1,13 @@
 # /review-tech-docs — Review Technical Design Document
 
-**Chế độ phân tích READ-ONLY — ghi file findings, KHÔNG sửa target.**
+**Hai chế độ.** *Phân tích* — chỉ đọc target, ghi file findings. *`--resume`* — **Phase 2–3 ghi vào thân tech-doc, header (`@trace.bdd_versions` · `@trace.sign_off`), và sổ TSV của MỌI UC mà doc phủ**. Nhãn "read-only" cũ chỉ đúng cho chế độ đầu (sửa 2026-09-16).
 **Dùng `--resume` để áp dụng các finding được chấp nhận.**
 
 ## Gate
 
-*Checkpoint: **không chặn** — read-only (ghi findings vào .agent/review/). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+*Checkpoint: **chặn CỨNG** — ghi đè quyết định reviewer (`--full`), và `--resume` Phase 2–3 ghi vào THÂN tech-doc, HEADER (`@trace.sign_off` là xác nhận của NGƯỜI: be_team/fe_team/app_team/sa), và sổ TSV của mọi UC trong `@trace.ucs`. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng **chỉ áp** khi findings đã có quyết định reviewer, HOẶC khi chạy với `--full`/`--resume`. Lần phân tích đầu đi thẳng.*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -86,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ờ** |
 
@@ -94,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ì**.

package/core/commands/setup-ai-first.md

@@ -82,7 +82,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ờ** |
 
@@ -90,6 +90,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/commands/validate-traces.md

@@ -4,7 +4,7 @@ Check read-only độ phủ giữa spec, code, và test — gồm cả PRD versi
 
 ## Gate
 
-*Checkpoint: **không chặn** — read-only (ghi trace-report.json + TSV status, không đụng spec/code). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+*Checkpoint: **không chặn** — **không phải vì read-only**. Lệnh ghi `trace-report.json`, `.trace-mirror/`, và **append** `trace-history.jsonl`; với `--reconcile-code` còn ghi row TSV và `_seams.tsv`. Nó không chặn vì mọi thao tác ghi VÔ ĐIỀU KIỆN đều hoặc dựng lại được, hoặc là `append` — và hai thao tác nguy hơn đều nằm sau `--reconcile-code`. Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -85,7 +85,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ờ** |
 
@@ -93,6 +93,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ì**.
@@ -219,7 +225,7 @@ Lưu `scope` — mọi step sau dùng nó:
 | Step | Hẹp thế nào |
 |---|---|
 | Step 0 / Step 1 | `all_trace_dirs` giữ nguyên, nhưng chỉ đọc TSV **khớp scope**: `{trace_dir}/{domain}/**` · `{trace_dir}/{domain}/{prd-slug}/**` · `{trace_dir}/**/{UC-ID}-*.tsv` |
-| Step 1.0 (lint) | truyền `--trace` như cũ — **lint luôn chạy toàn bộ**. Sổ hỏng ở domain khác vẫn là sổ hỏng, và lint rẻ (không LLM) |
+| Step 1.0 (lint) | `--trace` như cũ — **rule SỔ (T1–T14) luôn chạy toàn bộ**: sổ hỏng ở domain khác vẫn là sổ hỏng, và lint rẻ (không LLM). **Rule TECH-DOC (T15/T16/T19/T20) thu hẹp theo `--scope-prd`** — xem dưới |
 | Step 2b · 3.9 · 4 · 5* · 7 | chỉ các PRD/UC trong scope |
 | Step 6 · 6b | chỉ ghi lại TSV + mốc của phần trong scope |
 | Step 8 | ghi `scope` **và** `domain` vào biên bản (xem dưới) |
@@ -280,9 +286,24 @@ Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không
 Chạy checker xác định trên mọi trace dir đã phân giải ở Step 0:
 
 ```bash
-npx @educa-corp/sdd-framework --lint-trace --trace {all_trace_dirs, ngăn cách bởi dấu phẩy} --specs {paths.specs_dir} --code {code_roots, ngăn cách bởi dấu phẩy}
+npx @educa-corp/sdd-framework --lint-trace --trace {all_trace_dirs, ngăn cách bởi dấu phẩy} --specs {paths.specs_dir} --code {code_roots, ngăn cách bởi dấu phẩy} [--scope-prd {domain}/{prd-slug},…]
 ```
 
+**`--scope-prd` — truyền khi và chỉ khi lệnh này chạy CÓ SCOPE** *(`--prd` / `--uc` / `--domain`)*.
+Giá trị: `{domain}/{prd-slug}` của mọi PRD trong scope, ngăn bởi dấu phẩy. Không scope → **đừng truyền**.
+
+> **Vì sao chỉ thu hẹp rule TECH-DOC, không thu hẹp rule SỔ** *(G87)*. Lập luận gốc — *"sổ hỏng ở
+> domain khác vẫn là sổ hỏng"* — **đúng cho T1–T14**: `.tsv` là dữ liệu **không regenerate được**,
+> hỏng ở đâu cũng là hỏng, và Step 3/6 của lệnh này sẽ **ghi ngược vào sổ**.
+>
+> **T15/T16/T19/T20 canh tech-doc, không canh sổ.** Lý do kia không nối sang được, mà `exit 1` thì
+> chung một cửa — nên một lệnh **có scope** bị chặn bởi lỗi ở **PRD ngoài scope**. Đã xảy ra thật:
+> `/validate-traces --prd FEAT-01-1` dừng vì 30 tech-doc của `learning` và `home-ai-native`.
+>
+> **KHÔNG thu hẹp bằng cách trỏ `--specs` hẹp lại.** `lint-trace` cần `{domain}/{prd-slug}` để tìm
+> `bdd/`; trỏ `--specs` thẳng vào feature-package làm nó **bỏ qua im lặng** và báo **sạch** trên một
+> tech-doc chưa từng được kiểm. Cách lách hiển nhiên nhất cho ra **xanh giả**.
+
 **Dựng `code_roots` — bắt buộc truyền, đây là chìa khoá kho của T14:**
 
 | Chế độ | `code_roots` |
@@ -781,7 +802,7 @@ Không tìm thấy seam/stub nào → bỏ qua im lặng.
 Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
 Đồng thời **đồng bộ `uc_status` ← `@trace.status`** của file `.feature` tương ứng (header `.feature` là nguồn-sự-thật về duyệt BDD — người đặt `approved` sau khi review sạch, giống PO đặt PRD Metadata `Status`). Nhờ vậy `approved_ucs` trên dashboard phản ánh đúng thay vì luôn = 0.
 Và **đồng bộ `prd_status` ← `| **Status** |`** của PRD tương ứng (`{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md`) — đối xứng với `uc_status`: PRD Metadata là nguồn-sự-thật về duyệt PRD. Không có bước này thì `prd_status` là **write-once** (chỉ `/generate-bdd` ghi một lần) và sẽ giữ `approved` vĩnh viễn sau khi `/refine-prd` hay `/review-context --fix` reset PRD về `draft`. *(Step 4 đã đọc file PRD này rồi — không phát sinh I/O.)*
-**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
+**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-script` + `/qc-run-manualtest` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
 
 ### Step 6b — Ghi mốc `spec_baseline` cho lần audit sau
 
@@ -886,7 +907,7 @@ qc_passing       = rows where qc_status == pass
 qc_failing       = rows where qc_status == fail
 qc_skipped       = rows where qc_status == skip
 qc_not_run       = rows where qc_status in (not_run, —)
-# qc_status is the OFFICIAL QC automation result (set by /qc-run-test),
+# qc_status is the OFFICIAL QC automation result (set by /qc-run-script + /qc-run-manualtest),
 # shown alongside — never merged with — dev_selftest.
 waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
 waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify

package/core/modules/qc-playwright/stack-profile.yaml

@@ -62,5 +62,5 @@ trace_tags:
   source: "# @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
   test_type: "# @trace.test_type=functional|integration|e2e|non-functional"
 
-# qc_status: /qc-run-test writes pass|fail|skip|not_run + qc_run_at into {trace_dir}/{UC-ID}.tsv
+# qc_status: /qc-run-script writes pass|fail|skip|not_run + qc_run_at into {trace_dir}/{UC-ID}.tsv
 # (parallel to dev_selftest), surfaced in Living Docs as the OFFICIAL QC automation result.

package/core/rules/workflow.md

@@ -11,7 +11,7 @@ Ba mức, định nghĩa đầy đủ ở `steps/gate.md` Bước 3a — **đây
 
 | Mức | Lệnh nào | `--yes` bỏ qua? |
 |---|---|:---:|
-| **Không chặn** | read-only (`/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs`) | — |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **không** vì read-only (cả ba đều ghi file), mà vì thao tác ghi nằm sau `(Y/N)` / sau một cờ / là `append` | — |
 | **Chặn thường** | mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | ghi đè file đã có · `--resume` · migrate · prune | ❌ |
 
@@ -21,6 +21,46 @@ Ba mức, định nghĩa đầy đủ ở `steps/gate.md` Bước 3a — **đây
   chỉ hai dòng.
 - `--yes` bỏ qua *chặn thường*, **không** bỏ qua *chặn cứng*, và **không** tắt việc in cờ.
 
+## Cờ bỏ qua điều kiện — MỘT tên duy nhất: `--force`
+
+> Nguồn máy đọc: `bin/trace-schema.json` → `gate.bypass_flags`. Đổi luật thì **sửa schema TRƯỚC**.
+
+Mọi chỗ cho phép *"tôi biết điều kiện này, vẫn muốn chạy"* dùng **`--force`** — không đặt tên riêng
+theo từng lệnh. `--include-draft` đã đổi thành `--force` (2026-09-14); **không giữ alias**.
+
+| Cờ | Nghĩa | Bỏ qua gì |
+|---|---|---|
+| `--yes` | *"tôi không ngồi đây để trả lời"* | CHECKPOINT (câu hỏi Y/N) |
+| `--force` | *"tôi biết điều kiện này, vẫn chạy"* | một **điều kiện nghiệp vụ** mà lệnh tự khai |
+
+**Hai trục khác nhau, KHÔNG BAO GIỜ gộp.** Gộp là để một lần chạy headless âm thầm vượt mọi điều
+kiện — đúng thứ `steps/qc-scope.md` §4 đã từ chối khi tách `--include-draft` khỏi `--yes`. Đổi **tên**
+không đổi lập luận đó.
+
+**Ba điều khoản bắt buộc** — thiếu cái nào thì `--force` thành *"ghi đè tất cả"* và mất hết ý nghĩa:
+
+1. **Phạm vi khai từng lệnh, không bao giờ bao trùm.** Mỗi lệnh tự khai `--force` của nó bỏ qua
+   **đúng** điều kiện nào; mọi điều kiện khác vẫn chặn. *Tiền lệ đúng có sẵn: `/generate-code`
+   §"`--force` có phạm vi HẸP — đây là ranh giới cứng, không phải khuyến nghị… **KHÔNG** phải ghi
+   đè tất cả". Đó là khuôn, không phải ngoại lệ.*
+2. **Phải khai ra đã bỏ qua gì.** Report in một dòng cho **mỗi** điều kiện bị bỏ qua. *Một cờ chung
+   mà im lặng thì người bỏ qua X cũng bỏ qua luôn Y, Z họ chưa từng biết có tồn tại. Tên chung là để
+   **dễ nhớ**, không phải để **dễ mù**.*
+3. **Artifact phải tự khai.** File sinh ra trong lần chạy có `--force` mang một dòng nói nó dựa trên
+   điều kiện bị bỏ qua. *Cờ ở dòng lệnh biến mất sau khi lệnh chạy xong; dấu trong file đi cùng file
+   tới người đọc sau.*
+
+**Không phải mọi điều kiện đều `--force` được.** Điều kiện thuộc lớp **"báo cáo sai"** — bỏ qua nó thì
+lệnh sinh ra một **khẳng định sai** chứ không phải một sản phẩm kém — là **chặn cứng, không cờ nào qua**
+(`gate.bypass_flags.hard_never_forceable`). Phép thử một câu: *"bỏ qua cái này thì tôi nhận về một bản
+kém, hay một bản **dán nhãn sai**?"* — vế sau thì không `--force` được.
+
+> **Vì sao gom về một tên (2026-09-14).** Trước đó mỗi chỗ một tên: `--force` (generate-code),
+> `--include-draft` (qc-scope), và `exec-d0-b5` đang đề xuất `--no-testid-contract` *"theo đúng tinh
+> thần `--include-draft`"* — cái thứ ba chưa kịp sinh ra đã thấy nó sẽ là cái thứ ba. Cái giá thật
+> **không phải** gõ sai cờ, mà là **không biết có đường ra**: người dùng gặp cổng chặn, không nhớ lệnh
+> này dùng từ nào, rồi đi sửa spec cho hợp lệ giả thay vì khai báo tường minh rằng mình đang chạy sớm.
+
 > **Vì sao ba mức thay vì "always show" (G41):** bản cũ viết *"**Always** show a CHECKPOINT"*
 > rồi ngay dòng sau lại cấp một ngoại lệ cho lệnh read-only — mà `gate.md` **không hề thực thi**
 > ngoại lệ đó. Hai file cùng được nạp vào mọi lệnh và nói ngược nhau. Cộng thêm: cổng luôn in
@@ -55,7 +95,7 @@ Ba mức, định nghĩa đầy đủ ở `steps/gate.md` Bước 3a — **đây
 - Field có consumer mà **không có producer** là lỗi chặn build — đó chính là hình dạng
   của G1 (`@trace.sc_version`: 3 consumer, 0 producer, DRIFT chết mà không ai báo).
 - **Làm mất hiệu lực ≠ ghi đè.** Cột trace có chủ sở hữu rõ ràng — `dev_selftest`/`dev_selftest_at`
-  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-test` · `test_count`/`test_classes`
+  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-script` + `/qc-run-manualtest` · `test_count`/`test_classes`
   thuộc `/dev-gen-test` — và **chỉ chủ được ghi giá trị KHẲNG ĐỊNH** (`pass`/`fail`/số lượng).
   Nhưng lệnh nào làm giá trị đó **HẾT ĐÚNG** (spec đổi, code đổi) thì **BẮT BUỘC** hạ nó về giá
   trị "chưa biết" (`not_run` / `—`). Giữ một `pass` đã hết hiệu lực là **báo cáo sai**, không phải

package/core/skills/qc/_shared/self-review-principles.md

@@ -8,7 +8,7 @@ adapted: danh sách lệnh theo pipeline HIỆN TẠI (6 trạm QC) · bổ sung
 # Self-Review — 3 nhóm lỗi AI cần tự kiểm trước khi in Report
 
 Skill **tự chứa**, dùng chung cho các lệnh QC: `qc-analyze` · `qc-plan` · `qc-design-test` ·
-`qc-review` · `qc-run-test` · `qc-report` — và hai nhánh phụ `report-bug` · `propose-scenario`.
+`qc-review-testcase` · `qc-run-script` · `qc-report` — và hai nhánh phụ `report-bug` · `propose-scenario`.
 
 Mỗi file lệnh có mục `## Self-Review` **riêng**, liệt kê tiêu chí **cụ thể cho output của chính
 nó**. File này định nghĩa **3 nhóm lỗi gốc** mà mọi tiêu chí cụ thể đó phải phủ được ít nhất một
@@ -36,7 +36,7 @@ Bảng phân định hiện tại — đừng dùng self-review cho những vi
 | BR mà BDD nhắc nhưng phân tích bỏ sót | **Guard BR-tag** (so với tag `@trace.business_rules`) | `/qc-analyze` |
 | Scenario chưa có test case nào phủ | **Guard SC coverage** (đếm TC trỏ tới từng SC) | `/qc-design-test` |
 | Bảng §4.5.6 trỏ SC không tồn tại · header thiếu `@trace.testid_attr` · bảng lệch code | **T15–T18** | `bin/lint-trace.js` |
-| Ghi `pass` trên row `DRIFT`/`ORPHANED` | **T12** + `positive_assertion_guards` | `bin/lint-trace.js` + `/qc-run-test` |
+| Ghi `pass` trên row `DRIFT`/`ORPHANED` | **T12** + `positive_assertion_guards` | `bin/lint-trace.js` + `/qc-run-script` |
 | Sổ trace sai cấu trúc / enum / trùng `sc_id` | **T1–T8** | `bin/lint-trace.js` |
 
 Còn lại — **không có nguồn đối chiếu cơ học** — mới là việc của self-review: rủi ro bịa ra,

package/core/skills/qc/qa-analyst/DOC_GAP.template.md

@@ -11,7 +11,7 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 > Giữ một bản kém hơn làm mặc định là để người không biết có cờ nhận bản kém.
 >
 > **Một chỗ CỐ Ý khác upstream:** mức nặng nhất dùng từ **`Blocker`**, không phải `Critical`.
-> Lý do: `/qc-run-test` đọc `🔴 Blocker` để đặt *"scenario đang chờ PO"* vào sổ kết quả trace.
+> Lý do: `/qc-run-script` đọc `🔴 Blocker` để đặt *"scenario đang chờ PO"* vào sổ kết quả trace.
 > Đổi từ là đứt liên kết đó. Ba mức còn lại giữ nguyên upstream.
 >
 > **Phạm vi: MỘT file cho cả (PRD × nền)** *(B11)*, không phải một file mỗi UC. Đây là quay về
@@ -27,9 +27,17 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 | Nền (platform) | `<web \| app \| system>` |
 | Tài liệu nguồn | `<đường dẫn PRD>` · `<đường dẫn BDD nếu có>` · `<các file inputs/ liên quan>` |
 | Ngày phân tích | `<YYYY-MM-DD>` |
+| **Nguồn & phiên bản** | PRD `<vX.Y>` · tech-doc `<rev \| —>` · design-spec `<vX.Y \| —>` |
+| **BDD theo UC** | `<UC-ID>` `<vX.Y>` · `<UC-ID>` `<vX.Y>` … |
 | Tổng số gap | `<N>` (Blocker: x · High: y · Medium: z · Low: w) |
 | Trạng thái chung | 🔴 Blocked / 🟠 Cần làm rõ / 🟢 Đủ rõ để thiết kế TC |
 
+> **Hai hàng `Nguồn & phiên bản` + `BDD theo UC` là hợp đồng máy đọc, không phải ghi chú.**
+> `/qc-plan` và `/qc-design-test` **so** chúng với version hiện tại của spec để biết file này còn
+> khớp không (`steps/qc-stamp.md` · `bin/trace-schema.json` → `qc_artifact_stamp`).
+> `BDD theo UC` phải ghi **từng UC một**: file này phủ cả PRD, mỗi UC là một `.feature` riêng với
+> version riêng — một số duy nhất cho cả file sẽ **sai cho `n−1` UC**.
+
 ---
 
 ## Phạm vi phân tích
@@ -43,7 +51,7 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 | `<UC-ID>` | … | `approved` | ✅ | `<n>` |
 | `<UC-ID>` | … | `draft` | `⏸ Chưa xét` | — |
 
-**Trong phạm vi: `<n>`/`<N>` UC.** Chưa xét: `<danh sách UC-ID>` — chạy lại sau khi BDD được duyệt, hoặc `--include-draft` để xét luôn bản nháp.
+**Trong phạm vi: `<n>`/`<N>` UC.** Chưa xét: `<danh sách UC-ID>` — chạy lại sau khi BDD được duyệt, hoặc `--force` để xét luôn bản nháp.
 
 ---
 

package/core/skills/qc/qa-analyst/spec-issue-reporter.md

@@ -18,7 +18,7 @@ có cấu trúc, đủ thông tin để người nhận trả lời được nga
 > mỗi UC là các hàng phân biệt bằng cột `UC`. Không còn một-file-mỗi-UC.
 >
 > **Một chỗ cố ý khác upstream:** mức nặng nhất dùng `🔴 Blocker`, không phải `Critical` —
-> `/qc-run-test` đọc đúng từ đó để đặt *"scenario đang chờ PO"* vào sổ trace.
+> `/qc-run-script` đọc đúng từ đó để đặt *"scenario đang chờ PO"* vào sổ trace.
 
 ## Đầu vào
 

package/core/skills/qc/qa-automation-assess/matrix.md

@@ -0,0 +1,120 @@
+---
+name: automation-feasibility-matrix
+description: Đánh giá từng test case đã APPROVED là Automatable Y/N, kèm lý do chuẩn hoá và %Automated/Total. Dùng bởi /qc-automation-assess.
+---
+
+# Automation Feasibility Matrix
+
+Skill **tự chứa** cho `/qc-automation-assess`: đánh giá từng TC trong `TC_<FEATURE>.Test.md` đã
+qua cổng `/qc-review-testcase` là `Automatable: Y/N`, kèm lý do chuẩn hoá và `%Automated/Total`.
+
+## Khi nào trigger
+
+Sau `/qc-review-testcase` — TC đã `APPROVED` và chưa từng qua automation-assess, **hoặc** TC bị
+gắn cờ `🔄 Re-assess` vì scenario nó verify đang `DRIFT` (BDD/spec đã đổi).
+
+## Tiêu chí đánh giá — trả lời TUẦN TỰ, dừng ở câu đầu tiên là "Có"
+
+Câu nào trả lời "Có" thì **đó là lý do `N`**, và không cần xét tiếp:
+
+1. **Có bước nào đòi input từ con người / bên thứ ba mà script không tự lấy được?**
+   (OTP SMS thật · captcha · chữ ký tay · sinh trắc học trên thiết bị thật)
+   → `N`, nhãn **`Cần OTP/captcha thủ công`**
+2. **Có phụ thuộc hệ thống / thiết bị ngoài tầm kiểm soát của script?**
+   (app khác trên máy thật · máy POS vật lý · email/SMS thật không có test inbox)
+   → `N`, nhãn **`Phụ thuộc hệ thống ngoài`**
+3. **UI/flow có đang thay đổi liên tục?** (redesign · A/B test). Script viết hôm nay nhiều khả
+   năng vỡ trong < 2 tuần vì một thay đổi UI **đã biết trước**
+   → `N`, nhãn **`UI không ổn định`** — ghi rõ mốc dự kiến ổn định để re-assess
+4. **Element cần thao tác có test-id ổn định không, và dev có cam kết thêm nếu thiếu không?**
+   Không có **VÀ** không có cam kết → `N`, nhãn **`Thiếu test-id contract``**
+   > Khác với ca *"sẽ có nhưng chưa"* — ca đó vẫn `Y`, ghi chú chờ `IMPROVE-xxx`.
+5. **ROI có dương không?** Áp công thức dưới; âm rõ ràng → `N`, nhãn **`Effort > ROI`**
+6. Không rơi vào 1–5 → **`Y`**
+
+## Công thức ROI *(ước lượng nhanh, không cần chính xác tuyệt đối)*
+
+```
+ROI ≈ (tần suất chạy lại × chi phí test tay mỗi lần)
+      − (chi phí viết script + chi phí bảo trì dự kiến)
+```
+
+| Tín hiệu ROI **thấp** | Tín hiệu ROI **cao** |
+|---|---|
+| TC chỉ chạy **một lần** (migration một-lần, config set một lần) — viết script tốn hơn chạy tay 1 lần | TC có **nhiều biến thể dữ liệu** (boundary/negative): test tay tốn tuyến tính theo số biến thể, script chạy lại gần như miễn phí |
+
+**Thứ tự ưu tiên khi có nhiều TC `Y` mà chưa đủ thời gian làm hết:** `P0` trước, rồi `P1`/`P2`.
+TC `P0` gần như luôn ROI dương và là ứng viên trực tiếp cho smoke suite (`/qc-smoke-test` chạy
+mỗi build).
+
+> ⚠️ **`P0` mà rơi vào `N` là tín hiệu đáng chú ý hơn bình thường.** Tính năng lõi không có
+> smoke test tự động là rủi ro cao cho cả mục tiêu *"phát hiện lỗi sớm mỗi build"*. Ghi rõ lý do
+> **và** cân nhắc đề xuất `IMPROVE-xxx` để gỡ rào cản, thay vì chấp nhận `N` vĩnh viễn.
+
+## Tín hiệu ổn định — dùng cho tiêu chí 3
+
+| Ổn định | KHÔNG ổn định |
+|---|---|
+| Màn hình đã ship ≥ 1 release, không đổi lớn gần đây | Đang trong sprint thiết kế lại UI |
+| Có test-id contract §4.5.6 đã chốt | Element identify bằng text/class tạm thời |
+| Flow nghiệp vụ ổn định | Business rule đang thử nghiệm (feature flag % rollout) |
+
+## Guard — Re-assessment tự động theo `DRIFT`
+
+TC có scenario `@trace.verifies={UC-ID}-SC{N}` mà row đó trong sổ trace đang `status: DRIFT`
+→ **re-assess lại từ đầu 6 tiêu chí**, KHÔNG tái dùng phán quyết cũ.
+
+Vì sao không tái dùng: spec đổi có thể đổi **cả sáu** câu hỏi — ví dụ một BR mới thêm bước OTP
+biến một TC đang `Y` thành `N`.
+
+| Đổi | Xử lý cột `Script file` |
+|---|---|
+| `Y → N` | **GIỮ** path cũ + ghi chú `⚠️ Script đã lỗi thời — cân nhắc gỡ ở lần /qc-design-script kế tiếp`. **KHÔNG tự xoá file** — để người quyết định |
+| `N → Y` | giữ `—`, chờ `/qc-design-script` điền |
+
+## Output format
+
+```markdown
+# Automation Assessment — {TICKET-ID} ({active_platform})
+
+| TC ID | UC | Automatable | Lý do (nếu N) | Trace SC | Script file | Ghi chú |
+|---|---|:---:|---|---|---|---|
+| TC_LOGIN_001 | UC1 | Y | — | UC1-SC1 | — *(chưa qua qc-design-script)* | |
+| TC_LOGIN_004 | UC1 | N | Cần OTP/captcha thủ công | UC1-SC4 | — *(không automate)* | Giữ trong bộ manual |
+| TC_LOGIN_002 | UC1 | Y | — | UC1-SC2 | — *(chưa qua qc-design-script)* | 🔄 Re-assess (DRIFT, spec đổi {ngày}) — đã re-check: vẫn Y |
+
+**%Automated/Total: {automatable}/{đã đánh giá} = {pct}%**
+**Loại khỏi lượt:** {k} TC của UC chưa APPROVED — {danh sách UC + trạng thái thật}
+```
+
+### Cột `Script file` — ai ghi, khi nào
+
+```
+/qc-automation-assess  →  luôn khởi tạo "—"  (script chưa tồn tại ở bước này)
+/qc-design-script      →  ĐIỀN path thật sau khi sinh
+/qc-run-script         →  ĐỌC cột này để biết chạy file nào — KHÔNG tự suy path
+```
+
+Đây là **chỉ mục ngược duy nhất** từ TC → file code thật; chiều xuôi (code → SC) đã có sẵn qua
+tag `@trace.verifies`. Không có cột này thì `/qc-run-script` phải suy đường dẫn từ quy ước đặt
+tên — suy sai thì chạy sai bộ test, hoặc **chạy 0 test mà vẫn báo xanh**.
+
+> **Đường dẫn theo stack HIỆN TẠI** — module `qc-playwright` (Python + pytest-playwright):
+> `tests/<project>/test_<feature>.py` + `pages/<feature>_page.py`, theo
+> `modules/qc-playwright/stack-profile.yaml` §layout.
+>
+> *(Đề xuất gốc của đội QC viết theo TypeScript + Playwright Test / WebdriverIO. Việc đổi stack
+> là một bước RIÊNG, cố ý tách khỏi đợt tách lệnh — xem quyết định F3, Đợt 2 · b2. Khi stack
+> đổi, chỉ đoạn này và `stack-profile.yaml` cần sửa; cơ chế cột `Script file` không đổi.)*
+
+## Nhãn lý do mới phát sinh
+
+Không khớp nhãn nào trong 5 nhãn chuẩn → **tạo nhãn mới mô tả đúng lý do** *(đừng ép vào nhãn
+có sẵn)*, rồi liệt kê nó trong report để bổ sung vào danh sách lần sau.
+
+> **Vì sao chuẩn hoá nhãn.** Để **đếm được**. *"3 TC không automate vì **thiếu test-id**"* là
+> một tín hiệu hành động được — đi đàm phán với dev. *"3 TC vì lý do kỹ thuật"* thì không.
+>
+> Riêng nhãn `Thiếu test-id contract` nối thẳng với Đợt 0 (hợp đồng test-id §4.5.6): nếu Đợt 0
+> làm đúng thì nhãn này phải **giảm dần theo thời gian** — tức nó đồng thời là **phép đo cho
+> chính Đợt 0**.

package/core/skills/qc/qa-designer/e2e/journey.md

@@ -43,4 +43,4 @@ Mỗi journey → 1 TC bám Format; Expected = chuỗi verify point; chuẩn b
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 6 E2E**. Mỗi journey một TC; tiền điều kiện · kết quả/định tuyến kỳ vọng · BR · phụ thuộc gap · priority ghi dạng trường danh sách.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/exploratory/explore-to-functional.md

@@ -43,4 +43,4 @@ Chuyển draft → TC chính thức bám **format file `TC_<FEATURE>.Test.md`**:
 
 Ghi TC đã chuyển thành functional vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 3 Functional**.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/functional/api.md

@@ -111,4 +111,4 @@ Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 1 En
 
 File này chỉ sinh khi có cờ `--api` hoặc `--all`. Mẫu TC: `../api/endpoint.md` · chuỗi auth: `../api/auth-chain.md` · tra mã: `../api/http-status-codes.md` · header: `../api/common-headers.md`.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/functional/gui-feature.md

@@ -46,4 +46,4 @@ Liệt kê các màn/route + thứ tự điều hướng · state/dữ liệu tr
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 3 Functional** (luồng đa màn trong cùng một feature).
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/functional/gui-screen.md

@@ -51,4 +51,4 @@ chức năng (input/action/display/nav) · constraint (required/min-max/format/e
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 1 GUI** · **Nhóm 2 Validation** · **Nhóm 3 Functional**.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/integration/api.md

@@ -46,4 +46,4 @@ Nhóm TC: happy (dữ liệu đúng đầu→cuối) → contract negative (inpu
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 2 Integration API/DB/Kafka**. Ưu tiên P0 cho định tuyến & tiền-dữ liệu. Chuỗi gọi phụ thuộc nhau: `../api/crud-sequence.md`.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/integration/db.md

@@ -42,4 +42,4 @@ Nhóm TC: ghi đúng giá trị (happy) → default/null đúng → update khôn
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 2 Integration API/DB/Kafka**. Ghi rõ query kiểm tra DB + yêu cầu cleanup; không hardcode ID, chuẩn bị/dọn data qua fixture (3 mức teardown: `../shared/precision-rules.md` §8).
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/integration/gui.md

@@ -44,4 +44,4 @@ Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 4 Integration (qua UI)**. Đây là tầng verify dòng dữ liệu API → giao diện, nên **vẫn thuộc file giao diện**: bỏ UI đi thì TC mất nghĩa.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/integration/kafka.md

@@ -44,4 +44,4 @@ Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 2 Integration API/DB/Kafka**. Mỗi TC ghi topic, key, payload cần verify + hành vi consumer.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/non-functional.md

@@ -44,4 +44,4 @@ Trace BR; gap chặn → 🚫 Block.
 
 Ghi vào file theo cùng câu hỏi phân file *"verify được mà không cần UI?"*: a11y · responsive · touch-target → `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` **Nhóm 5 NFR**; tải/hiệu năng/bảo mật ở tầng API → `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md`. Mỗi TC ghi tiêu chí đo + ngưỡng + công cụ, đơn vị theo `../shared/precision-rules.md` §3.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/shared/duplicate-check-procedure.md

@@ -25,20 +25,31 @@ Hai TC là **trùng** khi **cả 3** điều kiện sau đều giống nhau:
 
 ## Quy trình kiểm tra (3 bước)
 
-### Bước 1 — Grep title keywords trong file TC hiện tại
+### Bước 1 — Grep title keywords trong CẢ THƯ MỤC `test-cases/`
 
-Trước khi viết TC mới, tìm kiếm title keywords trong toàn bộ file:
+Trước khi viết TC mới, tìm title keywords trong **mọi** file `.Test.md` — **không chỉ file đang mở**:
 
 ```bash
-# Tìm TC có chứa từ khóa scenario sắp viết
-grep -i "<từ_khóa_scenario>" {qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md
+# Tìm TC có chứa từ khóa scenario sắp viết — QUÉT CẢ THƯ MỤC
+grep -ril "<từ_khóa_scenario>" {qc_artifact_dir}test-cases/*.Test.md
 ```
 
 Ví dụ: Sắp viết TC "Nhập email không hợp lệ":
 ```bash
-grep -i "email\|invalid\|không hợp lệ" {qc_artifact_dir}test-cases/TC_LOGIN.Test.md
+grep -ril "email\|invalid\|không hợp lệ" {qc_artifact_dir}test-cases/*.Test.md
 ```
 
+> **Vì sao quét cả thư mục, không chỉ file đang mở** *(G75)*. Thư mục `test-cases/` dùng chung cho
+> **cả PRD** — mọi UC, và cả hai file giao diện/API của cùng một feature. `/qc-design-test` §Skills
+> dặn riêng: *"**trùng chéo UC** giờ mới thực sự xảy ra vì mọi UC dùng chung một thư mục"*. Quét một
+> file là mù đúng loại trùng lặp hay xảy ra nhất.
+>
+> **Và nó từng mù cùng chỗ với một lỗi khác.** Khi G62 còn sống (`Guard SC coverage` chỉ đếm file
+> *"vừa ghi"*, nên lần chạy `--api` nhân bản TC giao diện sang file API), quy trình này là cơ chế
+> **được dựng lên để bắt** đúng loại trùng đó — và nó **im lặng**, vì phạm vi quét của nó **cũng** là
+> *"file hiện tại"*. Hai cơ chế độc lập chia nhau **cùng một giả định phạm vi** thì **không phải hai
+> lớp bảo vệ — chúng là một lớp, đếm hai lần.**
+
 ### Bước 2 — So sánh preconditions + test data
 
 Nếu grep tìm thấy TC tương tự, so sánh:
@@ -59,6 +70,23 @@ Nếu grep tìm thấy TC tương tự, so sánh:
 | Cùng condition, khác platform (Web/App) | **KHÔNG trùng** — mỗi nền một thư mục (`{qc_dir}/{TICKET-ID}/web/` vs `/app/`) và mỗi nền phải tự đạt full coverage. Trùng logic giữa hai nền là **chủ đích** |
 | Không tìm thấy tương tự | Viết TC mới bình thường |
 
+**Tìm thấy ở FILE KHÁC — ba nhánh, không gộp làm một** *(G75)*:
+
+| Tìm thấy ở | Hành động |
+|---|---|
+| **Cùng file** đang mở | Như bảng trên |
+| **File khác, CÙNG UC** — vd `TC_<FEATURE>_API.Test.md` vs `TC_<FEATURE>.Test.md` | **KHÔNG chép sang.** Kiểm lại §Câu hỏi phân file (*"TC này verify được mà không cần UI không?"*): TC đang nằm **đúng chỗ** thì để yên, đừng nhân bản |
+| **File khác, UC KHÁC** | **KHÔNG viết lại.** Trỏ `@trace.verifies` về SC của UC đang làm và đếm vào ô `Trùng: {j} trùng chéo UC` ở report |
+
+> **Nhánh giữa là lớp thứ hai chặn G62.** G62 (`Guard SC coverage` chỉ đếm file *"vừa ghi"*) đã được
+> sửa ở tầng guard — mẫu số/tử số. Nhánh này chặn cùng ca đó ở tầng skill: nếu vì bất kỳ lý do gì mà
+> một TC giao diện sắp được viết vào file API, bước này bắt được.
+>
+> **Nhánh cuối làm ô `{j}` có phép đo đứng sau.** `/qc-design-test` §Report đã có sẵn ô
+> `Trùng: {k} TC bỏ vì trùng ({j} trùng chéo UC …)`. Khi Bước 1 chỉ quét một file thì `{j}` **luôn
+> bằng 0** — một con số không có phép tính, đúng thứ `buoc/1-02` §B5 cảnh báo: *"một con số trong báo
+> cáo KHÔNG chứng minh có phép đo"*.
+
 ---
 
 ## Trường hợp đặc biệt