@educa-corp/sdd-framework 0.9.5 → 0.9.7

package/core/skills/qc/qa-designer/shared/tc-metadata-format.md

@@ -5,7 +5,12 @@ ported_from: ui-automation-testing
 upstream_path: skills/qa-tc-designer/shared/tc-metadata-format.md
 upstream_sha: a31d66a7a8dab19cf821c9102a88282b09e16cb9
 ---
-# TC Metadata Format (Chuẩn chung)
+# TC Metadata Format
+
+> **`Automatable` KHÔNG phải một field của `.Test.md`.** Quyết định *"TC này máy chạy được hay
+> phải chạy tay"* sống ở **đúng một chỗ**: `{qc_artifact_dir}AUTOMATION_ASSESSMENT.md`, do
+> `/qc-automation-assess` ghi. Đừng chép giá trị đó vào đây — hai nơi ghi cùng một quyết định
+> thì một nơi sẽ lệch, và lúc đó không ai biết nơi nào đúng. (Chuẩn chung)
 
 ## ⚠️ Nguyên tắc format file TC (BẮT BUỘC — QC yêu cầu)
 
@@ -57,9 +62,14 @@ Mỗi trường 1 dòng, không bảng, không emoji dư:
 - **Author:** AI
 - **Tags:** <lane>, <loại: smoke|sanity|regression>, <feature-tag>
 - **Trace:** BR-xx (ID gốc trong PRD/BDD ở `{paths.specs_dir}`)
+- **@trace.verifies:** {UC-ID}-SC{N}
 - **🚫 Block:** [GAP-UC{N}-{nnn}](../DOC_GAP.md) — <lý do> *(chỉ khi có)*
 ```
 
+> **`@trace.verifies` là trường BẮT BUỘC, không phải tuỳ chọn** — §Trace dưới đây gọi nó là
+> **join key**: thiếu nó thì kết quả chạy **không vào được sổ trace**. Nó từng vắng mặt ở hai khối
+> mẫu này trong khi §Trace vẫn đòi nó — nên ai copy khối mẫu là bỏ sót đúng trường quan trọng nhất.
+
 ## Quy tắc Trace & Block
 
 - **Trace:** ghi `BR-xx` lấy từ ID trong `{paths.specs_dir}`; không có BR → `⚠️ Chưa có Business Rule`.
@@ -76,6 +86,7 @@ Mỗi trường 1 dòng, không bảng, không emoji dư:
 - **Author:** AI
 - **Tags:** ...
 - **Trace:** BR-xx
+- **@trace.verifies:** {UC-ID}-SC{N}
 - **🚫 Block:** (nếu có)
 
 #### Preconditions
@@ -199,7 +210,7 @@ Mọi thứ trên là chuẩn của đội QC. Bốn thứ dưới đây là **c
 **Câu hỏi phân file:** *"TC này verify được mà **không cần UI** không?"*
 → **có** = file API · **không** = file giao diện. *(Trùng Bước 2 của `skill-decision-tree.md`.)*
 
-⚠️ **Đuôi file là `.Test.md`, không phải `.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`;
+⚠️ **Đuôi file là `.Test.md`, không phải `.md`.** `/qc-design-script` và `/qc-review-testcase` tìm `*.Test.md`;
 ghi ra file thiếu phần `.Test` là ghi ra thứ **không trạm nào tìm thấy**, và không có gì báo lỗi.
 
 Đánh số `TC_<FEATURE>_NNN` **liên tục toàn file**, không đánh lại theo từng nhóm.
@@ -209,7 +220,7 @@ ghi ra file thiếu phần `.Test` là ghi ra thứ **không trạm nào tìm th
 | Trường | Dạng | Vì sao cần |
 |---|---|---|
 | `**Trace:**` | `[BR-xx](../REQUIREMENT_ANALYSIS.md#3-business-rules)` — không có BR → `⚠️ Chưa có Business Rule` | truy về luật nghiệp vụ |
-| `**@trace.verifies:**` | `{UC-ID}-SC{N}` (lấy từ `@trace.scenario` của file `.feature`) | **join key** để `/qc-run-test` ghi `qc_status` theo từng kịch bản vào sổ trace |
+| `**@trace.verifies:**` | `{UC-ID}-SC{N}` (lấy từ `@trace.scenario` của file `.feature`) | **join key** để `/qc-run-script` ghi `qc_status` theo từng kịch bản vào sổ trace |
 
 Một `SC` map được nhiều TC. **Thiếu `@trace.verifies` thì kết quả chạy không vào được sổ** — TC
 vẫn chạy, vẫn pass/fail, nhưng không ai biết nó phủ kịch bản nào.
@@ -226,6 +237,24 @@ sách**, không bảng (§Nguyên tắc format file đầu tài liệu này).
 `DOC_GAP.md` nằm ở **thư mục cha** của `test-cases/`, nên liên kết đi lên một cấp. Mã gap mang
 UC (`GAP-UC1-001`) vì một file gap phủ cả PRD.
 
+## Khối `Nguồn & phiên bản` *(metadata đầu file)*
+
+Ghi ngay dưới dòng `Test-ID attribute`:
+
+```
+Nguồn & phiên bản: BDD {UC-ID} `<vX.Y>` · tech-doc `<rev | —>`
+```
+
+Lấy `<vX.Y>` từ `| **Version** |` ở header `.feature` của **chính UC này**, và `<rev>` từ header
+tech-doc gộp. `/qc-review-testcase` và `/qc-design-script` **so** khối này với version hiện tại để biết bộ TC còn
+khớp spec không (`steps/qc-stamp.md` · `bin/trace-schema.json` → `qc_artifact_stamp`).
+
+**Vì sao cần, khi sổ trace đã có `qc_status`.** `/generate-bdd` hạ `qc_status → not_run` khi spec đổi
+— đó là *"**kết quả chạy** hết hiệu lực"*, và việc phải làm là **chạy lại**. Khối này trả lời câu
+khác: *"**bộ TC** còn khớp không?"*, và việc phải làm là **viết lại**. Thiếu nó thì người ta thấy
+`not_run` rồi chạy lại một bộ TC lỗi thời — ra `pass`, và `pass` đó **hợp lệ theo mọi phép kiểm hiện
+có**.
+
 ## Dòng `Test-ID attribute`
 
 Ghi một dòng ở phần metadata **đầu file**:
@@ -235,8 +264,8 @@ Test-ID attribute: {attr}
 ```
 
 Đọc `@trace.testid_attr` từ header tech-doc gộp (do `/map-testids` ghi). Bảng §4.5.6 chỉ cho
-**giá trị** test-id; đây 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 hợp đồng không.
+**giá trị** test-id; đây 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 hợp đồng không.
 
 Thiếu field trong tech-doc → ghi `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`.
 **Đừng bỏ trống và đừng tự đoán** — đoán sai thì mọi locator trượt 100%, và trượt vì lý do

package/core/skills/qc/qa-planner/test-plan.md

@@ -72,6 +72,13 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature
 | Người lập | qa-planner |
 | Ngày / Phiên bản | … |
 | Nguồn | REQUIREMENT_ANALYSIS · DOC_GAP |
+| **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>` … |
+
+> **Hai hàng cuối: CHÉP LẠI từ khối stamp của `DOC_GAP.md`, KHÔNG tự đi lấy từ spec.**
+> Trạm này không đọc spec trực tiếp — đầu vào của nó là output trạm 1. Tự đi lấy là tạo **hai
+> nguồn cho một số**, rồi chúng lệch nhau và không ai biết bên nào đúng.
+> `/qc-design-test` so hai hàng này với version hiện tại (`steps/qc-stamp.md`).
 
 ## 1. Mục tiêu
 Mục tiêu test của feature (1–3 câu).

package/core/skills/qc/qa-reviewer/script/e2e.md

@@ -92,4 +92,4 @@ Severity: 🔴 fix ngay (missing cleanup, dữ liệu không verify cross-module
 (cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
 Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
 
-**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-design-script`.

package/core/skills/qc/qa-reviewer/script/exploratory.md

@@ -47,7 +47,7 @@ Review session note sau khi test, coaching QC cải thiện kỹ năng.
 (cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
 Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
 
-**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-design-script`.
 Mỗi tiêu chí: ✅/⚠️/❌ + feedback cụ thể
 Top 3 improvement suggestions (coaching tone)
 Đề xuất charter tiếp theo nếu chưa đủ coverage

package/core/skills/qc/qa-reviewer/script/functional.md

@@ -106,4 +106,4 @@ Severity: 🔴 fix ngay (sai logic, POM breach, silent fail) · 🟠 quan trọn
 (cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
 Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
 
-**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-design-script`.

package/core/skills/qc/qa-reviewer/script/integration.md

@@ -96,4 +96,4 @@ Severity: 🔴 fix ngay (mock thay real call, missing DB verify, no cleanup) ·
 (cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
 Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
 
-**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-design-script`.

package/core/skills/qc/qa-reviewer/script/non-functional.md

@@ -131,4 +131,4 @@ Severity: 🔴 fix ngay (assertion không có ngưỡng, gọi production endpoi
 (cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
 Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
 
-**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-design-script`.

package/core/skills/qc/qa-reviewer/shared/review-file-template.md

@@ -31,7 +31,7 @@ upstream_sha: bd596393ecc016cbea106835681a4979c0a9ca0e
   giữa tài-liệu-nền-cũ và PRD đã duyệt là **lệch đồng bộ, KHÔNG chặn** — không phải mâu thuẫn
   chặn. *(Khung "gap thật = QA KHÔNG tự quyết được" — xem `steps/gap-verify.md`.)*
 - **KHÔNG tự sửa** kịch bản hay code. Chỉ nhận xét, chấm điểm, và nêu cụ thể sửa gì. Người sửa là
-  trạm 3 (`/qc-design-test`) hoặc trạm 5 (`/qc-run-test`).
+  trạm 3 (`/qc-design-test`) hoặc trạm 5 (`/qc-run-script`).
 
 ## Kiểm tra cấu trúc TC (bắt buộc mỗi vòng)
 
@@ -126,7 +126,7 @@ soát:
 ```
 
 ⚠️ **Tên file review KHÔNG có đuôi `.Test.md`.** Đuôi đó là của file test case; gắn vào file
-review sẽ làm `/qc-run-test` nhặt nó lên như một file test case rồi cố sinh script từ một bảng
+review sẽ làm `/qc-design-script` nhặt nó lên như một file test case rồi cố sinh script từ một bảng
 điểm.
 
 - **Chưa tồn tại** → `Write` toàn bộ khuôn bên dưới, điền hàng của tầng vừa soát, các tầng khác
@@ -147,7 +147,7 @@ review sẽ làm `/qc-run-test` nhặt nó lên như một file test case rồi
 ```markdown
 # Review Report — <FEATURE>
 
-> Sinh bởi /qc-review. Cập nhật sau mỗi vòng soát. Bảng Tổng quan tích luỹ theo vòng.
+> Sinh bởi /qc-review-testcase hoặc /qc-review-script (mỗi vai một file). Cập nhật sau mỗi vòng soát. Bảng Tổng quan tích luỹ theo vòng.
 
 ## Tổng quan
 

package/core/skills/qc/qa-reviewer/test-case/e2e.md

@@ -12,7 +12,7 @@ Review bộ TC end-to-end và đánh giá chất lượng.
 
 ## Khi nào trigger
 - "review TC E2E cho [Feature]" / "check coverage E2E"
-- Sau khi qa-designer/e2e/journey xong, trước khi /qc-run-test
+- Sau khi qa-designer/e2e/journey xong, trước khi /qc-design-script
 
 ## Khi KHÔNG trigger
 - Review TC functional 1 màn → `test-case/functional`

package/core/skills/qc/qa-reviewer/test-case/functional.md

@@ -12,7 +12,7 @@ Review bộ functional TC và đánh giá chất lượng.
  
 ## Khi nào trigger
 - "review TC cho [Feature]" / "check coverage"
-- Sau khi qa-designer xong, trước khi PO approve hoặc trước khi /qc-run-test
+- Sau khi qa-designer xong, trước khi PO approve hoặc trước khi /qc-design-script
  
 ## Khi KHÔNG trigger
 - Review Python script → dùng qa-reviewer

package/core/skills/qc/qa-reviewer/test-case/integration.md

@@ -12,7 +12,7 @@ Review bộ TC tích hợp (GUI↔Backend, API, DB) và đánh giá chất lư
 
 ## Khi nào trigger
 - "review TC integration cho [Feature]" / "check TC tích hợp"
-- Sau khi qa-designer/integration/* xong, trước khi /qc-run-test
+- Sau khi qa-designer/integration/* xong, trước khi /qc-design-script
 
 ## Khi KHÔNG trigger
 - Review TC functional 1 màn/endpoint → `test-case/functional`

package/core/skills/qc/qa-reviewer/test-case/non-functional.md

@@ -12,7 +12,7 @@ Review bộ TC phi chức năng (performance, security, accessibility, compatibi
 
 ## Khi nào trigger
 - "review TC non-functional cho [Feature]" / "check TC hiệu năng/bảo mật/accessibility"
-- Sau khi qa-designer/non-functional xong, trước khi /qc-run-test
+- Sau khi qa-designer/non-functional xong, trước khi /qc-design-script
 
 ## Khi KHÔNG trigger
 - Review TC chức năng → `test-case/functional`

package/core/skills/qc/qa-runner/e2e.md

@@ -30,7 +30,7 @@ Journey còn phụ thuộc gap → tạo test `@pytest.mark.skip(reason="GAP-UC{
 
 ## Phase 3 — Verify
 `py_compile` + `pytest --collect-only -q` · chạy (môi trường staging + CRM) · cập nhật Status TC.
-**Phân loại FAIL — 3 nhãn, luật ở `/qc-run-test` §Chạy lại trước khi kết luận** (chạy lại ×2 trước, rồi người xác nhận; **không chép lại luật ở đây**). Đặc thù E2E: journey fail vì 1 bước feature chưa wire = `product-gap` (giữ FAIL/skip + bằng chứng), không phải lỗi script; sai selector/state → `script-bug`. Journey dài qua nhiều bước **dễ ra `flaky` hơn test đơn lẻ** — một bước chậm bất thường là đủ; nên đừng vội gọi `product-gap` khi chưa chạy lại.
+**Phân loại FAIL — 3 nhãn, luật ở `/qc-run-script` §Chạy lại trước khi kết luận** (chạy lại ×2 trước, rồi người xác nhận; **không chép lại luật ở đây**). Đặc thù E2E: journey fail vì 1 bước feature chưa wire = `product-gap` (giữ FAIL/skip + bằng chứng), không phải lỗi script; sai selector/state → `script-bug`. Journey dài qua nhiều bước **dễ ra `flaky` hơn test đơn lẻ** — một bước chậm bất thường là đủ; nên đừng vội gọi `product-gap` khi chưa chạy lại.
 
 ## Output
 Script `tests/<project>/e2e/test_<feature>.py` + Page Object/client tái dùng. Bàn giao `qa-reviewer`.
@@ -46,4 +46,4 @@ Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashbo
    - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
    - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
    - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
-3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-test` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-script` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

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

@@ -22,9 +22,9 @@ Skill **tự chứa**: convert `.Test.md` feature span ≥2 màn → Python pyte
 
 ## Phase 1 — Clarify
 Đọc `.Test.md` · liệt kê các màn/PO cần · state truyền giữa màn · fixture dựng tiền điều kiện (data qua nhiều bước).
-**Locator: đọc hợp đồng TRƯỚC, dò DOM là bước cuối.** Thứ tự bắt buộc (luật đầy đủ + lý do ở `/qc-run-test` §Role & stack — **không chép lại ở đây**):
+**Locator: đọc hợp đồng TRƯỚC, dò DOM là bước cuối.** Thứ tự bắt buộc (luật đầy đủ + lý do ở `/qc-design-script` §Role & stack — **không chép lại ở đây**):
 
-1. **Test-id contract** — bảng *Test Selectors* §4.5.6 của tech-doc gộp, lọc theo cột "Phục vụ SC" khớp SC của UC này. TÊN thuộc tính đọc từ `@trace.testid_attr` ở header tech-doc (đừng suy từ platform). Feature đa màn: một UC chạm nhiều màn nhưng **vẫn một bảng §4.5.6** cho cả platform — lọc theo SC, không theo màn.
+1. **Test-id contract** — bảng *Test Selectors* §4.5.6 của tech-doc gộp, lọc theo cột "Serves SC" khớp SC của UC này. TÊN thuộc tính đọc từ `@trace.testid_attr` ở header tech-doc (đừng suy từ platform). Feature đa màn: một UC chạm nhiều màn nhưng **vẫn một bảng §4.5.6** cho cả platform — lọc theo SC, không theo màn.
 2. **Role + accessible name** — cho element có action mà §4.5.6 chưa phủ.
 3. **Dò DOM** — CHỈ khi 1 và 2 đều không định vị được. Dump class/`aria-label`/role, rồi nhìn kết quả:
    - **3a. Element ĐÃ mang test-id trong code** → **DỪNG, đừng tự dùng id nhặt được.** Đây là ca *code đi trước hợp đồng*: chạy `/map-testids {UC-ID}` để đưa id đó vào §4.5.6 (nhánh `existing` — reverse-document), rồi quay lại bậc 1.
@@ -38,7 +38,7 @@ Phủ TC điều hướng forward/back/giữ-reset state. Data từ `test_data/`
 ## Phase 3 — Verify
 `py_compile` + `pytest --collect-only -q` (**số collect = tổng TC**; thiếu → sinh nốt) · chạy · cập nhật Status TC (verify KHÔNG còn Draft) · in mapping.
 **Gom nhóm role/account** tự áp qua `utils/test_ordering.py` (root conftest); fixture auth mới → `register_auth_fixtures([...])`. ⚠️ Run dài bị **WSL suspend** có thể gây flaky login/timeout → re-run TC đó + merge report.
-**Phân loại FAIL — 3 nhãn, luật ở `/qc-run-test` §Chạy lại trước khi kết luận** (chạy lại ×2 trước, rồi người xác nhận; **không chép lại ở đây**). Đặc thù đa màn: sai selector/logic → `script-bug`, sửa & chạy lại; feature chưa wire/defect **đỏ nhất quán** → `product-gap`, giữ FAIL + ghi bằng chứng vào khối "Kết quả thực thi" đầu `.Test.md`, không fake-pass. **State truyền giữa màn là nguồn `flaky` phổ biến** — điều hướng nhanh hơn/chậm hơn một nhịp là đủ đổi kết quả; ghi nghi vấn đó vào phần nguyên nhân.
+**Phân loại FAIL — 3 nhãn, luật ở `/qc-run-script` §Chạy lại trước khi kết luận** (chạy lại ×2 trước, rồi người xác nhận; **không chép lại ở đây**). Đặc thù đa màn: sai selector/logic → `script-bug`, sửa & chạy lại; feature chưa wire/defect **đỏ nhất quán** → `product-gap`, giữ FAIL + ghi bằng chứng vào khối "Kết quả thực thi" đầu `.Test.md`, không fake-pass. **State truyền giữa màn là nguồn `flaky` phổ biến** — điều hướng nhanh hơn/chậm hơn một nhịp là đủ đổi kết quả; ghi nghi vấn đó vào phần nguyên nhân.
 
 ## Output
 Script + nhiều Page Object (mỗi màn) trong `pages/<project>/...`. Bàn giao `qa-reviewer` (script).
@@ -54,4 +54,4 @@ Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashbo
    - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
    - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
    - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
-3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-test` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-script` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

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

@@ -23,9 +23,9 @@ Skill **tự chứa**: convert `.Test.md` (1 màn) → Python pytest + Playwrigh
 
 ## Phase 1 — Clarify
 Đọc `.Test.md` (confirm Reviewed) · platform (web Playwright/mobile) · Page Object đã có chưa → tạo nếu cần · fixture setup data?
-**Locator: đọc hợp đồng TRƯỚC, dò DOM là bước cuối.** Thứ tự bắt buộc (luật đầy đủ + lý do ở `/qc-run-test` §Role & stack — **không chép lại ở đây**):
+**Locator: đọc hợp đồng TRƯỚC, dò DOM là bước cuối.** Thứ tự bắt buộc (luật đầy đủ + lý do ở `/qc-design-script` §Role & stack — **không chép lại ở đây**):
 
-1. **Test-id contract** — bảng *Test Selectors* §4.5.6 của tech-doc gộp, lọc theo cột "Phục vụ SC" khớp SC của UC này. TÊN thuộc tính đọc từ `@trace.testid_attr` ở header tech-doc (đừng suy từ platform).
+1. **Test-id contract** — bảng *Test Selectors* §4.5.6 của tech-doc gộp, lọc theo cột "Serves SC" khớp SC của UC này. TÊN thuộc tính đọc từ `@trace.testid_attr` ở header tech-doc (đừng suy từ platform).
 2. **Role + accessible name** — cho element có action mà §4.5.6 chưa phủ.
 3. **Dò DOM** — CHỈ khi 1 và 2 đều không định vị được. Dump class/`aria-label`/role bằng script tạm, rồi nhìn kết quả:
    - **3a. Element ĐÃ mang test-id trong code** → **DỪNG, đừng tự dùng id nhặt được.** Đây là ca *code đi trước hợp đồng*: chạy `/map-testids {UC-ID}` để đưa id đó vào §4.5.6 (nhánh `existing` — reverse-document), rồi quay lại bậc 1. Dùng thẳng là bỏ qua review, và id đó không bao giờ thành hợp đồng — lần sau lại phải đi khám phá lại.
@@ -41,7 +41,7 @@ Map nhóm GUI→`TestFeatureUI`, Functional→`TestFeatureFunctional`, Negative
 **Gom nhóm role/account**: thứ tự chạy đã tự gom cùng (role, account) liền nhau qua `utils/test_ordering.py` (hook ở root conftest) — fixture auth mới thì `register_auth_fixtures([...])`.
 ⚠️ Run dài có thể bị **WSL suspend** (máy ngủ) làm vài TC lỗi login/timeout = flaky (không phải gap SP) → re-run đúng các TC đó + merge vào report (xem `report/report.md`).
 **Verify KHÔNG còn Draft**: `grep -c "Status: Draft" <file>.Test.md` = 0 trước khi bàn giao.
-**Mỗi FAIL phân loại theo 3 nhãn — luật ở `/qc-run-test` §Chạy lại trước khi kết luận** (chạy lại ×2 trước, rồi người xác nhận; **không chép lại ở đây**). Đặc thù màn đơn: sai selector/expectation → `script-bug`, sửa script & chạy lại; feature không phản hồi sau timeout **và đỏ nhất quán qua các lần chạy lại** → `product-gap`, giữ FAIL + ghi bằng chứng (không fake-pass); timeout **chỉ xảy ra một số lần** → `flaky`, đừng ghi `fail`.
+**Mỗi FAIL phân loại theo 3 nhãn — luật ở `/qc-run-script` §Chạy lại trước khi kết luận** (chạy lại ×2 trước, rồi người xác nhận; **không chép lại ở đây**). Đặc thù màn đơn: sai selector/expectation → `script-bug`, sửa script & chạy lại; feature không phản hồi sau timeout **và đỏ nhất quán qua các lần chạy lại** → `product-gap`, giữ FAIL + ghi bằng chứng (không fake-pass); timeout **chỉ xảy ra một số lần** → `flaky`, đừng ghi `fail`.
 
 ## Output
 Script `tests/<project>/.../test_<screen>.py` + Page Object `pages/<project>/.../<Screen>Page.py` (nếu mới).
@@ -58,4 +58,4 @@ Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashbo
    - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
    - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
    - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
-3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-test` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-script` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

package/core/skills/qc/qa-runner/integration.md

@@ -44,4 +44,4 @@ Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashbo
    - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
    - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
    - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
-3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-test` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-script` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

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

@@ -46,4 +46,4 @@ Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashbo
    - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp) + số đo thực tế.
    - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
    - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
-3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-test` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu + số đo vào Status/khối kết quả của `.Test.md`.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại theo **3 nhãn** (`script-bug` · `product-gap` · `flaky`) — luật đầy đủ + bước chạy lại ×2 ở `/qc-run-script` §Chạy lại trước khi kết luận, **không chép lại ở đây**; ghi mô tả lỗi tiếng Việt dễ hiểu + số đo vào Status/khối kết quả của `.Test.md`.

package/core/steps/context-loader.md

@@ -190,7 +190,7 @@ services:
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 - Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
-- Override `paths.trace_dir` → `{spec_source}/.trace` — **luôn khi `spec_source` được đặt.** Trace TSV được gộp vào spec repo (một nơi authoritative duy nhất, không tách theo service) để PM/PO có một chỗ duy nhất quản lý trạng thái. Cấu trúc bên trong: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv`. Các lệnh phía code (`/generate-code`, `/dev-run-test`, `/qc-run-test`) chạy từ `service_root` nhưng **ghi trace row của chúng vào `{spec_source}/.trace/{domain}/{prd-slug}/`** — giống như chúng đã push `feedback/` vào đó. *(`.trace` theo service chỉ khi không có `spec_source`.)*
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **luôn khi `spec_source` được đặt.** Trace TSV được gộp vào spec repo (một nơi authoritative duy nhất, không tách theo service) để PM/PO có một chỗ duy nhất quản lý trạng thái. Cấu trúc bên trong: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv`. Các lệnh phía code (`/generate-code`, `/dev-run-test`, `/qc-run-script`) chạy từ `service_root` nhưng **ghi trace row của chúng vào `{spec_source}/.trace/{domain}/{prd-slug}/`** — giống như chúng đã push `feedback/` vào đó. *(`.trace` theo service chỉ khi không có `spec_source`.)*
 - Override `paths.refinement_dir` → `{spec_source}/.agent/review` — **luôn khi `spec_source` được đặt.** Findings review (`/refine-prd`, `/review-context`, `/review-tech-docs`) là artifact liên-team *về* tài liệu trong spec repo (PRD/BDD/tech-design) — thuộc cùng khu vực ghi với `.trace/` và `feedback/`. Các lệnh review chạy từ working dir của service (BE repo) nhưng **ghi findings vào `{spec_source}/.agent/review/`**, KHÔNG phải `.agent/review` của service repo. Bên trong flat, phân biệt bằng tên file đã prefix `{prd-slug}`/`{UC-ID}`/`{TICKET-ID}`. *(`.agent/review` theo service chỉ khi không có `spec_source`.)*
 
 > **Vì sao đặt dưới `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, feedback của tester, **trạng thái coverage `.trace/`**, **và findings review `.agent/review/`** đều là **artifact liên team** — chúng nằm trong **spec repo dùng chung** theo bố cục feature-package để mọi umbrella (FE/App/BE) và PM đọc từ một nguồn qua `/sync`. Trong bố cục feature-package, một folder `specs/{domain}/{prd-slug}/` gom tất cả loại artifact của một PRD, giúp spec repo tự đủ và dễ điều hướng theo feature. Service submodule chỉ chứa **code** (+ tooling build/test). `.trace/`, `.agent/review/` và `feedback/` là khu vực **ghi** của dev/QC/reviewer trong spec repo. Ở chế độ single-service (không có `spec_source`), mọi thứ mặc định dưới gốc repo — vẫn là một repo.

package/core/steps/gate.md

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

package/core/steps/qc-scope.md

@@ -99,21 +99,77 @@ Phạm vi QC — {TICKET-ID} / {active_platform}
   → {n} UC trong phạm vi · {m} chưa xét
 ```
 
-**Cờ `--include-draft`:** phân tích cả UC chưa duyệt, nhưng **vẫn in bảng trên** và đánh dấu
-trong artifact là dựa trên BDD nháp.
+**Cờ `--force`:** xử lý cả UC chưa duyệt, nhưng **vẫn in bảng trên**, in dòng khai đã bỏ qua gì,
+và đánh dấu trong artifact là dựa trên BDD nháp. *(Tên cờ chung cho mọi chỗ "biết mà vẫn chạy" —
+`rules/workflow.md` §Cờ bỏ qua điều kiện. Cờ cũ `--include-draft` đã bỏ, không có alias.)*
 
-**Không UC nào `approved` và không có `--include-draft` → DỪNG:**
+### 4a — Cổng cấp PRD: có việc để làm không?
+
+**Không UC nào `approved` và không có `--force` → DỪNG:**
 ```
 ❌ {TICKET-ID} ({active_platform}): 0/{n} UC có BDD approved — không có gì để chạy.
    Cách đúng: người duyệt đặt `# @trace.status: approved` rồi chạy lại.
-   Muốn chạy sớm trên BDD nháp (prototype): thêm --include-draft
+   Muốn chạy sớm trên BDD nháp (prototype): thêm --force
+```
+
+### 4b — Cổng cấp UC: **cái UC vừa được gọi tên** có làm được không?
+
+Bảy lệnh nhận target là **UC-ID** — `/qc-design-test` · `/qc-review-testcase` · `/qc-review-script` · `/qc-design-script` · `/qc-run-script` · `/qc-run-manualtest` · `/qc-report`
+— phải đối chiếu target với **bảng vừa in ở trên**. Hai lệnh cấp PRD (`/qc-analyze` · `/qc-plan`)
+**bỏ qua mục này**: target của chúng là `TICKET-ID`, và cổng 4a đã trả lời đúng câu hỏi của chúng.
+
+| Target | Xử lý |
+|---|---|
+| Có trong `uc_list`, nhóm **Trong phạm vi** | đi tiếp |
+| Có trong `uc_list`, nhóm **⏸ Chưa xét** | **DỪNG** — trừ khi có `--force` |
+| **Không** có trong `uc_list` | **DỪNG** — sai UC-ID hoặc sai nền. **`--force` KHÔNG qua được** |
+
+```
+❌ {UC-ID} có BDD `{status}` — chưa approved, không nằm trong phạm vi QC pass này.
+   Cách đúng: người duyệt đặt `# @trace.status: approved` rồi chạy lại.
+   Cố ý làm sớm trên BDD nháp: thêm --force (artifact sẽ ghi rõ nó dựa trên bản nháp)
 ```
+```
+❌ {UC-ID} không có trong {TICKET-ID} ({active_platform}).
+   UC có mặt: {danh sách uc_list}
+   Kiểm lại UC-ID, hoặc UC này thuộc nền khác — nêu nền tường minh.
+```
+
+> **Vì sao 4a không thay được 4b.** Điều kiện của 4a là **`0/n`** — *"cả PRD không có gì để chạy"*,
+> đúng câu hỏi của một lệnh **cấp PRD**. Lệnh **cấp UC** hỏi câu khác hẳn. Với PRD `UC1 draft` +
+> `UC2 approved`, cổng 4a thấy `1/2` → không phải `0/n` → **mở cửa**, và `/qc-design-test {UC1}`
+> đi thẳng vào một spec chưa ai duyệt.
+>
+> Cái giá không dừng ở "thiết kế trên bản nháp". `Guard SC coverage` của trạm 3 sẽ **khẳng định**
+> `khớp K/K` trên spec chưa duyệt, và `/qc-run-script` sẽ ghi `qc_status = pass` **chính thức** vào sổ
+> trace cho nó. Đó là **báo cáo sai** — `rules/workflow.md` §*"ai KHẲNG ĐỊNH một giá trị dương phải
+> được phép khẳng định"*.
+>
+> **Vì sao gộp luôn ca "UC-ID không có trong `uc_list`".** Cùng **một** phép so (`target ∈ nhóm
+> Trong phạm vi`), và ca đó hiện **không ai bắt**: §1 đối chiếu `TICKET-ID` với tên file PRD thật và
+> DỪNG nếu lệch, nhưng không có bước tương đương cho `UC-ID`. Gõ `/qc-design-test FT-001-UC7` khi PRD
+> chỉ có UC1–UC3 thì không bước nào phát hiện.
+
+### Có `--force` thì artifact phải TỰ KHAI
+
+In dòng khai ở report:
+```
+⚠️ --force: bỏ qua {điều kiện} — {UC-ID} @trace.status: {status}
+```
+Và **mọi** file ghi ra trong lần chạy đó mang một dòng ở metadata:
+```
+⚠️ Dựa trên BDD NHÁP ({UC-ID} @trace.status: {status}) — spec có thể đổi.
+```
+
+> **Vì sao cả hai chỗ.** Cờ nằm ở dòng lệnh thì **biến mất** sau khi lệnh chạy xong. Dòng ở report
+> cho người đang ngồi đó; dòng trong file đi cùng file tới người đọc sau — người sẽ mở `.Test.md`
+> ba tuần nữa và không có cách nào biết nó sinh ra từ bản nháp.
 
-> **Vì sao có `--include-draft` chứ không chặn cứng.** QC sớm trên BDD nháp là một cách dùng
-> **cố ý được cho phép** từ trước (guard cũ là cảnh báo mềm, không phải chặn). Bỏ hẳn nó là
-> lấy đi một năng lực đang có mà không ai khai. Còn để mặc định `approved`-only thì cái
-> thường gặp là cái an toàn, và cái sớm phải nói ra.
+> **Vì sao có `--force` chứ không chặn cứng.** QC sớm trên BDD nháp là một cách dùng **cố ý được
+> cho phép** từ trước (guard cũ là cảnh báo mềm, không phải chặn). Bỏ hẳn nó là lấy đi một năng lực
+> đang có mà không ai khai. Còn để mặc định `approved`-only thì cái thường gặp là cái an toàn, và
+> cái sớm phải nói ra.
 
-> **Vì sao `--yes` không thay được `--include-draft`.** `--yes` nghĩa *"tôi không ngồi đây để
-> trả lời"*; `--include-draft` nghĩa *"tôi biết BDD còn nháp và vẫn muốn chạy"*. Gộp hai cái
-> là để một lần chạy headless âm thầm phân tích spec chưa chốt rồi bàn giao như thể đã chốt.
+> **Vì sao `--yes` không thay được `--force`.** `--yes` nghĩa *"tôi không ngồi đây để trả lời"*;
+> `--force` nghĩa *"tôi biết BDD còn nháp và vẫn muốn chạy"*. Gộp hai cái là để một lần chạy headless
+> âm thầm phân tích spec chưa chốt rồi bàn giao như thể đã chốt.

package/core/steps/qc-stamp.md

@@ -0,0 +1,142 @@
+# QC artifact stamp — ghi mình sinh ra từ bản nào, và đọc cái người trước đã ghi
+
+> Nguồn máy đọc: `bin/trace-schema.json` → `qc_artifact_stamp`. Đổi contract thì **sửa schema TRƯỚC**.
+>
+> **Hai vế, không tách.** Vế ghi (đóng dấu) và vế đọc (so dấu) phải cùng có mặt. Chỉ ghi mà không
+> ai đọc là nhân thêm một con số vô dụng — `DOC_GAP.template.md` đã có sẵn cột `Phiên bản` như thế:
+> được điền mỗi lần chạy, **0 consumer**.
+
+---
+
+## Vì sao tầng artifact QC cần cái này
+
+`/generate-bdd` hạ `qc_status → not_run` khi spec đổi — đúng luật, và nó trả lời câu *"**kết quả chạy**
+còn hiệu lực không?"*.
+
+Câu chưa ai trả lời là *"**tài liệu thiết kế test** còn khớp không?"*. Hai câu dẫn tới hai việc khác nhau:
+
+| Tín hiệu | Nghĩa | Việc phải làm |
+|---|---|---|
+| `qc_status = not_run` | kết quả cũ hết hiệu lực | **chạy lại** `/qc-run-script` |
+| **stamp lệch** | TC/gap/plan mô tả spec cũ | **viết lại** — `/qc-analyze` hoặc `/qc-design-test` |
+
+Thiếu vế sau thì người ta thấy `not_run` và **chạy lại** — đúng phản xạ, sai việc. Một bộ TC lỗi thời
+chạy xanh ra `pass`, và `pass` đó **hợp lệ theo mọi phép kiểm hiện có**.
+
+> **Vì sao phép kiểm nằm ở đây chứ không ở `/validate-traces`.** `qc_dir` là path QC **duy nhất
+> không được remap** khi `setup.spec_source` được đặt — `specs_dir`, `tech_docs_dir`,
+> `domain_knowledge_dir`, `trace_dir` đều remap, `qc_dir` ở lại `docs` của **repo QC**. Nên ở chế độ
+> umbrella (`trace-mirror.md` gọi là *"trường hợp phổ biến"*), sổ trace và artifact QC nằm ở **hai
+> repo khác nhau** và `/validate-traces` không với tới artifact QC.
+>
+> Các trạm QC thì **đã đọc cả hai** — artifact từ `{qc_artifact_dir}`, spec từ `{paths.specs_dir}`.
+> Phép so nằm trong tầm với, không phải vượt repo.
+
+---
+
+## 1 — Khối stamp: ghi gì, ở đâu
+
+Đặt ở **bảng metadata đầu file** (cả bốn artifact đều đã có bảng đó — đây là **thêm hàng**, không
+phải dựng cấu trúc mới):
+
+```
+| 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>` … |
+```
+
+**Lấy từng giá trị ở ĐÂU** — mỗi nguồn một định dạng khác nhau, đừng suy từ cái này sang cái kia:
+
+| Giá trị | Lấy từ | Định dạng |
+|---|---|---|
+| `prd_version` | `\| **Version** \|` — bảng metadata đầu PRD | Markdown |
+| **`bdd_version`** | **`@trace.bdd_version`** — header `.feature` | **Gherkin** — khối comment `# @trace.*`, **KHÔNG có bảng** |
+| `tech_doc_revision` | `@trace.revision` — header tech-doc gộp | khối `@trace` |
+| `design_spec_version` | `\| **Version** \|` — bảng metadata đầu design-spec | Markdown |
+| `testid_attr` | `@trace.testid_attr` — header tech-doc | khối `@trace` |
+
+> **Vì sao bảng này tồn tại** *(G85)*. Bản trước mô tả cả bốn nguồn bằng **một khuôn** —
+> *"`| **Version** |` của header …"* — vì cả bốn "đều là tài liệu có metadata đầu file". Ba đúng,
+> **một không thể đúng**: `.feature` là **Gherkin**, không có bảng Markdown nào. Đo thật: **0/278**
+> file có dạng cũ, **276/278** có `@trace.bdd_version`.
+>
+> *Một khuôn cho N nguồn chỉ đúng khi N nguồn **cùng định dạng**. "Đều có metadata đầu file" không đủ.*
+
+**Nguồn THIẾU → ghi `—` VÀ nói ra.** Đo thật: 2/278 `.feature` không có `@trace.bdd_version`.
+
+```
+⚠️ {UC-ID}: .feature thiếu @trace.bdd_version — stamp ghi '—', không so được ở trạm sau.
+```
+
+**Đừng bỏ trống, đừng đoán.** Bỏ trống im lặng thì *"không lấy được"* trông **y hệt** *"artifact cũ
+chưa có stamp"* — mà §2 bảo **đừng báo lệch** ở ca đó. Điều khoản tương thích ngược sẽ **nuốt luôn**
+lỗi này. *(Cùng khuôn `@trace.testid_attr` của `/qc-design-test` đã dùng.)*
+
+| Artifact | Ai ghi | Stamp gì |
+|---|---|---|
+| `REQUIREMENT_ANALYSIS.md` · `DOC_GAP.md` | `/qc-analyze` | `prd_version` · `bdd_version` **theo từng UC** · `tech_doc_revision` · `design_spec_version` |
+| `TEST_PLAN.md` | `/qc-plan` | **chép lại** stamp của `DOC_GAP.md` |
+| `test-cases/*.Test.md` | `/qc-design-test` | `bdd_version` của UC này · `tech_doc_revision` · `@trace.testid_attr` |
+
+**`bdd_version` phải theo TỪNG UC.** `DOC_GAP.md` và `REQUIREMENT_ANALYSIS.md` phủ **cả PRD**, mà mỗi
+UC là một file `.feature` riêng với version riêng — một số duy nhất cho cả file sẽ **sai cho `n−1` UC**.
+
+**`/qc-plan` CHÉP LẠI, không tự đi lấy.** Nó không đọc spec trực tiếp (đầu vào của nó là output trạm 1).
+Tự đi lấy là tạo **hai nguồn cho một số**, rồi chúng lệch nhau — và lúc đó không ai biết bên nào đúng.
+
+---
+
+## 2 — Phép so: đọc dấu người trước đã ghi
+
+Chạy **ngay sau guard tiền đề** (phần "có file không?"), trước mọi việc khác. Guard tiền đề hỏi
+*"có không?"*; bước này hỏi *"còn khớp không?"*.
+
+Với mỗi artifact mà lệnh này đọc:
+
+1. Đọc khối stamp của nó.
+2. Đọc version **hiện tại** của các nguồn tương ứng (`.feature` của UC · PRD · tech-doc · design-spec).
+3. So từng cặp.
+
+| Kết quả | Xử lý |
+|---|---|
+| Khớp hết | **im lặng, đi tiếp** |
+| **Không có khối stamp** | `⚠️ {file}: chưa có stamp (sinh trước G63) — chạy lại {lệnh} để đóng dấu.` **KHÔNG báo lệch** |
+| Lệch | theo bảng mức dưới đây |
+
+> **Điều khoản tương thích ngược là bắt buộc, không phải lịch sự.** Artifact sinh ra trước khi có
+> contract này thì đương nhiên không có stamp. Báo "lệch" ở đó là **bắt oan mọi dự án đang chạy ngay
+> ngày nâng version** — và việc đầu tiên người ta làm là tìm cách tắt cảnh báo. Cùng điều khoản mà
+> `testid_contract` đã dùng: *"doc không có block §4.5 client thì KHÔNG kiểm gì"*.
+
+### Mức phản ứng — KHÔNG đồng nhất
+
+| Trạm | Lệch thì | Vì sao |
+|---|---|---|
+| `/qc-plan` · `/qc-design-test` · `/qc-review-testcase` | **⚠️ cảnh báo, đi tiếp** | Cùng họ `TECHDOC_DRIFT`/`BDD_DRIFT` — 13/17 cờ audit không chặn. Thiết kế TC trên bản hơi cũ vẫn ra sản phẩm dùng được; chặn ở đây là **ồn** |
+| `/qc-run-script` | **chặn `pass`, KHÔNG chặn chạy** | Lớp **báo cáo sai** |
+
+```
+⚠️ Stamp lệch — {file} dựng trên {nguồn} {ver_cũ}, hiện tại {ver_mới}.
+   UC ảnh hưởng: {danh sách}
+   Nên chạy lại: {lệnh}   (đi tiếp vẫn được, nhưng {hệ quả cụ thể})
+```
+
+**`/qc-run-script` — nhập vào cơ chế đã có, không phát minh cơ chế mới.** Stamp lệch xử lý **y hệt**
+row `DRIFT`/`ORPHANED` của `positive_assertion_guards` + lint **T12** (G55): test vẫn chạy, nhưng
+xanh → ghi `not_run` chứ **không** ghi `pass`, và **không đóng bug nào** ở lần chạy đó.
+
+> **`fail` vẫn ghi `fail` bình thường.** Đây là guard chống **báo cáo sai**, không phải guard **che
+> tin xấu** — nguyên văn lập luận của `positive_assertion_guards`.
+
+---
+
+## 3 — Phép so đi theo từng UC, không theo cả file
+
+Bump `bdd_version` của **UC2** thì `/qc-design-test {UC1}` phải **im lặng hoàn toàn**.
+
+Trạm 3–5 chạy **per-UC**, nhiều lần cho mỗi PRD. Một cảnh báo báo oan ở đây không chỉ sai một lần —
+nó lặp lại mỗi lần chạy, và cảnh báo lặp mà không đúng là cách nhanh nhất để người ta ngừng đọc **mọi**
+cảnh báo của lệnh này.
+
+Nên khi so `DOC_GAP.md` / `REQUIREMENT_ANALYSIS.md` (phủ cả PRD): **chỉ lấy hàng `bdd_version` của UC
+đang chạy** để so. `prd_version` / `tech_doc_revision` / `design_spec_version` là số chung cả PRD nên
+so trực tiếp.