@educa-corp/sdd-framework 0.9.6 → 0.9.8

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

@@ -6,11 +6,11 @@ ported_from: ai-automation-qc-base
 
 # /qc-design-test — QC Test-Case Design
 
-> Stage 3 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — Python đến sau ở /qc-run-test.
+> Trạm 3/9 của dây chuyền QC automation (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-automation-assess → qc-design-script → qc-review-script → qc-run-script ∥ qc-run-manualtest → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — script tự động đến sau ở /qc-design-script.
 
 ## Gate
 
-*Checkpoint: **chặn CỨNG** — ghi đè `*.Test.md` đã qua cổng HITL `/qc-review` → mất `Status` đã duyệt, `Expected Result` đã sửa theo finding, dấu 🚫 Block vừa gỡ; và ĐÁNH SỐ LẠI `TC_<FEATURE>_NNN` mà `REVIEW_<FEATURE>.md` đang trỏ vào. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+*Checkpoint: **chặn CỨNG** — ghi đè `*.Test.md` đã qua cổng HITL `/qc-review-testcase` → mất `Status` đã duyệt, `Expected Result` đã sửa theo finding, dấu 🚫 Block vừa gỡ; và ĐÁNH SỐ LẠI `TC_<FEATURE>_NNN` mà `REVIEW_<FEATURE>.md` đang trỏ vào. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
 
 *Mức cứng chỉ áp khi file `.Test.md` **đã tồn tại**. Lần thiết kế đầu không ghi đè gì, đi thẳng. Xem §Chạy lại.*
 
@@ -93,7 +93,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -101,6 +101,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.
@@ -228,9 +234,26 @@ Kiểm sự tồn tại của cả ba file dưới `{qc_artifact_dir}`:
          rồi: /qc-plan {TICKET-ID} {active_platform}
 ```
 
-**Đủ cả ba → im lặng, đi tiếp.** Guard này là **điều kiện vào cửa**, không phải phép đo: "đủ file"
-không phải một phát hiện, nên không in dòng nào. *(Khác `Guard BR-tag` và `Guard SC coverage` —
-hai cái đó là phép ĐẾM, con số của chúng có giá trị ngay cả khi sạch, nên chúng luôn in.)*
+**Đủ cả ba → IN MỘT DÒNG BẰNG CHỨNG rồi đi tiếp:**
+
+```
+✅ Đầu vào trạm 3: 3/3 — {qc_artifact_dir}{REQUIREMENT_ANALYSIS,DOC_GAP,TEST_PLAN}.md
+```
+
+> **Vì sao cổng vào cửa PHẢI in, dù "đủ file" không phải một phát hiện** *(sửa 2026-09-17, sau một
+> ca thật)*. Bản trước ghi *"đủ cả ba → im lặng, đi tiếp"* với lý do nghe hợp lý: cổng là điều kiện,
+> không phải phép đo. Cái giá không ai tính: **cổng đạt trong im lặng KHÔNG phân biệt được với cổng
+> chưa bao giờ chạy** — cả hai đều không in gì.
+>
+> **Ca thật:** lệnh chạy trên một PRD mà `{qc_artifact_dir}` **chưa tồn tại**, tự tường thuật
+> *"đủ ba file đầu vào"*, rồi đi tiếp. Không dấu vết nào để đối chiếu, và người dùng chỉ phát hiện
+> vì lệnh sau đó hỏi một câu vô lý.
+>
+> Một dòng in ra làm hai việc mà im lặng không làm được: **bỏ qua thì thấy ngay** *(thiếu dòng)*,
+> và **tường thuật sai thì đối chiếu được** *(đường dẫn in ra, mở là biết)*. Đây không phải nới
+> lỏng luật *"đừng in cái không phải phát hiện"* — mà là phân biệt hai loại: **phép đo** in con số,
+> **cổng vào cửa** in bằng chứng nó đã chạy. Cổng không có bằng chứng thì nó không phải cổng, nó
+> là một lời đề nghị.
 
 > **Vì sao DỪNG chứ không cảnh báo rồi chạy.** Guard duy nhất còn lại của trạm này —
 > `Guard SC coverage` — đối chiếu TC với `.feature`, mà `.feature` ở spec repo thì **luôn có mặt**,
@@ -238,7 +261,7 @@ hai cái đó là phép ĐẾM, con số của chúng có giá trị ngay cả k
 > **không phân biệt được** với một lần chạy đúng.
 >
 > Thiếu `DOC_GAP.md` là ca đắt nhất: TC bị gap chặn **trông y hệt** TC bình thường (không có dấu
-> `🚫 Block` nào), nên `/qc-run-test` chạy nó, thấy đỏ, và `/qc-report` phân loại thành *product-gap*
+> `🚫 Block` nào), nên `/qc-run-script` chạy nó, thấy đỏ, và `/qc-report` phân loại thành *product-gap*
 > rồi in một `/report-bug` sẵn-chạy. Lỗi đi **ra khỏi đội QC** thành bug gửi PO — cho một hành vi
 > mà spec chưa bao giờ định nghĩa. Đây là **báo cáo sai**, cùng loại với việc giữ một `pass` đã hết
 > hiệu lực (`rules/workflow.md` §*"Làm mất hiệu lực ≠ ghi đè"*).
@@ -268,11 +291,65 @@ hai cái đó là phép ĐẾM, con số của chúng có giá trị ngay cả k
 | `--api` | `TC_<FEATURE>_API.Test.md` | 1 Endpoint · 2 Integration API/DB/Kafka |
 | `--all` | **cả hai file** | như trên, hai file riêng biệt |
 | `--atomic-max` | — | bật chế độ tách tối đa (xem dưới) |
+| `--shape=api\|job\|queue` | — | nêu tường minh hình dạng nền `system` — **bắt buộc khi chạy `--yes`** trên UC không suy đượ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. Đây đúng là Bước 2 của
 `{paths.qc_skills_dir}/qa-designer/shared/skill-decision-tree.md`.
 
+### Nền `system` — hỏi hình dạng khi không suy được
+
+> **Chỉ hỏi khi HAI vế cùng đúng.** Hỏi mọi lần nền là `system` là kiểu hỏng **Ồn**: phần lớn UC
+> `system` **là** API thật và BDD nói rõ; hỏi cả những lần đã rõ thì sau vài lần người ta bấm
+> số 1 cho xong, và cổng đó chết trong khi không ai biết.
+
+| Vế | Đo thế nào |
+|---|---|
+| **1** | `active_platform = system` |
+| **2** | **0 dấu hiệu endpoint** — không tìm thấy method/path HTTP trong `.feature` của UC **lẫn** trong tech-doc |
+
+Một trong hai vế sai → **đi tiếp, không hỏi**.
+
+**Cả hai đúng → in bằng chứng rồi mới hỏi.** Hỏi khơi khơi thì người trả lời cũng đang đoán:
+
+```
+{UC-ID} — nền system, không tìm thấy endpoint nào.
+
+  BDD nói   : "{trích nguyên văn dòng When}"
+  Tech-doc  : {đã có, không khai endpoint | chưa có}
+  Tìm thấy  : {n} dòng có method/path HTTP
+
+Hình dạng nào?
+  1  API                — có endpoint; chưa có trong tech-doc thì chờ tech-doc
+  2  Job chạy ngầm      — tự chạy theo lịch/điều kiện, không ai gọi
+  3  Consumer hàng đợi  — nằm chờ, có message tới thì xử lý
+```
+
+**Có `--yes`:** không hỏi — **DỪNG** với lỗi rõ ràng. Cùng luật với phân giải nền
+*(`steps/qc-scope.md` §2)*, và cùng lý do: đoán hình dạng là viết test case kiểm sai thứ, mà
+nó vẫn ra một file trông hợp lệ.
+
+```
+❌ {UC-ID} nền system, không suy được hình dạng (0 dấu hiệu endpoint).
+   Chạy headless thì phải nêu tường minh: /qc-design-test {UC-ID} --shape=job --yes
+```
+
+**Ghi câu trả lời vào `Tags` của MỌI TC sinh ra ở lượt này** — ô `<lane>` đã có sẵn trong khuôn
+metadata:
+
+| Trả lời | `<lane>` | Skill nạp |
+|---|---|---|
+| 1 API | `api` | `functional/api.md` · `integration/api.md` |
+| 2 Job chạy ngầm | `job` | `functional/job.md` |
+| 3 Consumer hàng đợi | `queue` | `integration/queue.md` |
+
+> **Vì sao ghi vào từng TC chứ không một chỗ cho cả PRD.** Một PRD có UC là API và UC là job là
+> chuyện thường. Ghi ở cấp PRD là ép cả PRD thành một kiểu.
+>
+> **Vì sao phải ghi, không chỉ dùng rồi thôi.** Trạm 5 và trạm 6 cũng cần biết hình dạng. Không
+> ghi thì chúng **hỏi lại**, và có thể nhận câu trả lời khác — lúc đó test case và script kiểm
+> hai thứ khác nhau, cả hai đều chạy được, và **không gì bắt được**.
+
 > **Vì sao hai file riêng chứ không một file rồi ghi từng nhóm** *(B12)*. `--api` chạy sau khi
 > file giao diện đã tồn tại là chuyện thường. Nếu chung một file, lần chạy `--api` phải **giữ
 > nguyên** năm nhóm kia — mà viết-lại-cả-file là đúng thứ agent hay làm. Hai file thì hai chế
@@ -316,8 +393,8 @@ vế nói về **cùng một** kết cục — ví dụ *"form hiển thị đ
 ## Role
 
 Bạn là **QC Designer** — stage 3. Sinh/bảo trì các file test-case Markdown
-(`.Test.md`) từ requirement đã phân tích + plan. Output feed vào qc-run-test (Python) và
-qc-review. Bạn **không** viết Python.
+(`.Test.md`) từ requirement đã phân tích + plan. Output feed vào qc-review-testcase rồi
+qc-automation-assess. Bạn **không** viết script tự động.
 
 ## Skills (`{paths.qc_skills_dir}/qa-designer/`)
 
@@ -342,7 +419,8 @@ qc-review. Bạn **không** viết Python.
 | Feature đa-màn | `functional/gui-feature.md` | file giao diện |
 | API endpoint | `functional/api.md` | **file API** |
 | Integration qua UI | `integration/gui.md` | file giao diện |
-| Integration API/DB/Kafka | `integration/{api,db,kafka}.md` | **file API** |
+| Integration API/DB/hàng đợi | `integration/{api,db,queue}.md` | **file API** |
+| Job chạy ngầm *(lane `job`)* | `functional/job.md` | **file API** |
 | End-to-end journey | `e2e/journey.md` | file giao diện |
 | Non-functional | `non-functional.md` | theo câu hỏi phân file |
 | Exploratory | `exploratory/{charter,explore-to-functional}.md` | file giao diện |
@@ -353,11 +431,11 @@ qc-review. Bạn **không** viết Python.
 đều ở `shared/tc-metadata-format.md`. **Đừng lặp lại ở đây.** Dưới đây chỉ là thứ riêng của trạm:*
 
 - Markdown-first; đừng design khi requirement chưa rõ — đẩy ngược về qc-plan/qc-analyze.
-- **Tham chiếu test-id, không phải gợi ý hình ảnh.** Với mỗi step GUI tác động lên một element, trích test-id ổn định từ bảng §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") để qc-run-test dựng locator từ contract. Nếu một element có action không có test-id trong §4.5.6, ghi chú lại (qc-run-test sẽ fallback về locator role/text chậm hơn).
+- **Tham chiếu test-id, không phải gợi ý hình ảnh.** Với mỗi step GUI tác động lên một element, trích test-id ổn định từ bảng §4.5.6 của tech-doc gộp (vd "click `ft001-login-submit-btn`") để qc-design-script dựng locator từ contract. Nếu một element có action không có test-id trong §4.5.6, ghi chú lại (qc-design-script sẽ fallback về locator role/text chậm hơn).
 - **Đọc `@trace.testid_attr` từ header tech-doc gộp** (do `/map-testids` ghi) và ghi lại một
   dòng `Test-ID attribute: {attr}` ở metadata đầu file `.Test.md`. §4.5.6 chỉ cho **giá trị**
-  test-id; `@trace.testid_attr` là **tên thuộc tính** chứa chúng — `/qc-run-test` cần nó để cấu
-  hình locator, `/qc-review` cần nó để biết selector trong script có đúng contract không.
+  test-id; `@trace.testid_attr` là **tên thuộc tính** chứa chúng — `/qc-design-script` cần nó để cấu
+  hình locator, `/qc-review-script` cần nó để biết selector trong script có đúng contract không.
   Không đọc được `@trace.testid_attr` → ghi
   `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`; **đừng bỏ trống, đừng
   tự đoán theo platform** — đoán sai thì mọi locator trượt 100%, vì một lý do không liên quan
@@ -375,7 +453,7 @@ không phải cột bảng** (file TC không có ký tự `|`):
 ```
 
 Lấy từ `@trace.scenario` của `.feature`. Một SC map được nhiều TC. Đây là **join key** cho phép
-qc-run-test ghi `qc_status` theo từng scenario vào sổ trace — **thiếu nó thì test vẫn chạy,
+qc-run-script ghi `qc_status` theo từng scenario vào sổ trace — **thiếu nó thì test vẫn chạy,
 vẫn pass/fail, nhưng kết quả không vào được sổ và không ai biết nó phủ kịch bản nào.**
 
 Cuối file: **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách TC bị block** — cả hai dạng danh sách.
@@ -450,7 +528,7 @@ Hỏi từng SC chưa phủ: *"TC cho SC này verify được mà **không cần
 > — đúng Bước 2 của `shared/skill-decision-tree.md`), không phải một nhận định tự do. Ghi *"SC này
 > phức tạp"*, *"tương tự SC2"* thì **không** rơi vào ô nào của bảng trên.
 >
-> **Vì sao không cứ bù vào file đang mở cho gọn.** File API được `/qc-run-test` đọc bằng lane API.
+> **Vì sao không cứ bù vào file đang mở cho gọn.** File API được `/qc-design-script` đọc bằng lane API.
 > Một TC cần UI nằm ở đó **không chạy nổi** — và nó sẽ đỏ dưới dạng *script-bug* hoặc *product-gap*,
 > không ai truy ngược về một quyết định ghi file ở phase thiết kế.
 
@@ -492,7 +570,7 @@ nó tồn tại, và không ai phát hiện được khi nó chết.
 
 ## Chạy lại — `.Test.md` đã tồn tại *(GIỮ, không sinh lại từ trắng)*
 
-File `.Test.md` đi qua **cổng HITL `/qc-review`**. Bốn thứ trong đó **không sinh lại được**:
+File `.Test.md` đi qua **cổng HITL `/qc-review-testcase`**. Bốn thứ trong đó **không sinh lại được**:
 
 | Mất gì | Vì sao |
 |---|---|
@@ -506,7 +584,7 @@ File `.Test.md` đi qua **cổng HITL `/qc-review`**. Bốn thứ trong đó **k
 | Tình huống | Xử lý |
 |---|---|
 | TC cũ, spec **không đổi** | **Giữ nguyên** — số · `Status` · `Expected Result` đã sửa |
-| TC cũ, spec **đổi** | Cập nhật **nội dung**; giữ **số** và `Status`, thêm ⚠️ để `/qc-review` soát lại |
+| TC cũ, spec **đổi** | Cập nhật **nội dung**; giữ **số** và `Status`, thêm ⚠️ để `/qc-review-testcase` soát lại |
 | TC **mới** | Cấp số **tiếp theo** — không dồn, không tái dùng |
 | TC không còn ứng với SC nào | **KHÔNG xoá** → `Status: Obsolete`, ghi lý do |
 
@@ -534,7 +612,7 @@ sẵn ở `{paths.qc_skills_dir}/qa-designer/shared/tc-metadata-format.md` §*Qu
 quyết (Answered)*. Bước đóng đó **chưa lệnh nào gọi** — nên dấu chặn chỉ dán vào, không bao giờ gỡ ra.
 
 Một TC mang `🚫 Block` là một TC có **Expected Result dựa trên giả định chưa ai xác nhận**. Nó nằm
-trong thư mục dùng chung, được `Guard SC coverage` đếm là **đã phủ**, và `/qc-run-test` sẽ nhặt lên.
+trong thư mục dùng chung, được `Guard SC coverage` đếm là **đã phủ**, và `/qc-design-script` sẽ nhặt lên.
 
 > **Vì sao stamp phiên bản (§Stamp phiên bản nguồn) KHÔNG phủ ca này.** Gap chuyển `Open → Answered`
 > là một **ô trong `DOC_GAP.md`** — nó **không bump version nào cả**. Mọi drift detector của framework
@@ -590,7 +668,7 @@ Ghi dưới `{qc_artifact_dir}test-cases/`
 PRD**. Tên file mang `<FEATURE>` nên các UC không đâm nhau; `@trace.verifies` là chỗ phân biệt
 TC thuộc UC nào.
 
-**Đuôi bắt buộc là `.Test.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`; ghi ra
+**Đuôi bắt buộc là `.Test.md`.** `/qc-design-script` và `/qc-review-testcase` tìm `*.Test.md`; ghi ra
 `TC_<FEATURE>.md` là ghi ra thứ **không trạm nào tìm thấy**, và **không có gì báo lỗi**.
 
 `🚫 Block` trỏ `../DOC_GAP.md` — lên một cấp, vì file gap ở thư mục cha của `test-cases/`.
@@ -633,5 +711,5 @@ Guard SC coverage: {khớp {K}/{K} | ⚠️ {K}/{total} — đã bù {m} SC: {da
        {nếu có SC cần UI mà đang chạy --api: "⚠️ {n} SC cần UI chưa có TC ở file giao diện —
        KHÔNG bù vào file API. Chạy: /qc-design-test {UC-ID} (không cờ). SC: {danh sách}"}
 Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
-Next : /qc-review {UC-ID}   ← review test case trước khi sinh script
+Next : /qc-review-testcase {UC-ID}   ← review test case trước khi sinh script
 ```

package/core/commands/qc-plan.md

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-plan — QC Test Plan & Risk Analysis
 
-> Stage 2 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-planner của team QC.
+> Trạm 2/9 của dây chuyền QC automation (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-automation-assess → qc-design-script → qc-review-script → qc-run-script ∥ qc-run-manualtest → qc-report). Port từ qa-planner của team QC.
 
 ## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
@@ -88,7 +88,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -96,6 +96,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.
@@ -240,7 +246,7 @@ Bắt buộc:
 
 ### Chạy lại — ghi đè ở đây AN TOÀN, và đây là lý do
 
-*(Ba trạm QC khác — `/qc-analyze` · `/qc-design-test` · `/qc-run-test` — đều ở mức **chặn CỨNG** kèm
+*(Ba trạm QC khác — `/qc-analyze` · `/qc-design-test` · `/qc-design-script` — đều ở mức **chặn CỨNG** kèm
 §Chạy lại. Trạm này **không**, và đó là kết luận có chủ ý, không phải chỗ sót.)*
 
 `TEST_PLAN.md` **không có ô nào người nhập tay**: `questions-for-dev` là danh sách **gửi đi** — câu

package/core/commands/qc-report.md

@@ -1,14 +1,14 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-report — QC Test Report & Evidence
-
-> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ bước report của qa-runner team QC.
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-report — QC Test Report & Evidence
+
+> Trạm 9/9 (cuối) của dây chuyền QC automation (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-automation-assess → qc-design-script → qc-review-script → qc-run-script ∥ qc-run-manualtest → qc-report). Port từ bước report của kho QC gốc (xem `bin/qc-base-map.json`).
+
+## Gate
 # 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ó.
@@ -88,7 +88,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -96,6 +96,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.
@@ -160,74 +166,83 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
 - "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. Sinh report từ lần chạy `/qc-run-test` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
-
-## Context
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Sinh report từ lần chạy `/qc-run-script` gần nhất. **Reporter theo nền** — đọc `§reporting` của module đã phân giải ở `steps/qc-scope.md` §2b: `web`·`system` → **Playwright HTML Report + Trace**; `app` → **Allure Report v2.x**. Không dashboard viết tay.*
+
+> ⚠️ **Hai nền KHÁC NHAU ở chỗ này — đừng "thống nhất" lại.** Luật `No Allure` cũ nay chỉ còn
+> đúng cho web *(`Automation-Standards` §1 + `OQ-01` đóng 2026-06-02: Playwright HTML đủ Phase 1,
+> Allure defer Phase 2)*. Nền mobile thì Allure là **bắt buộc** *(`Mobile-Automation-Standards` §1)*.
+> Đó là quyết định của chuẩn, không phải chỗ sót.
+
+## 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ỗ.
-
----
-
-## Role
-
-Bạn là stage **QC Report** — biến lần chạy gần nhất thành report + evidence chia sẻ được.
-
-## Skill (`{paths.qc_skills_dir}/qa-runner/report/`)
-
-- `report.md` — tự đủ: pytest-html (`--html=reports/<feature>/report.html
-  --self-contained-html`) + Playwright Trace (`test-results/<nodeid>/trace.zip`, xem qua
-  `python3 -m playwright show-trace <file>`), kèm screenshot/evidence đính trên FAIL/SKIP.
-
-## Procedure
-
-1. Định vị artifact của lần chạy gần nhất cho `{UC-ID}` (report pytest-html + trace).
-2. Sinh/làm mới `reports/<feature>/report.html` (self-contained) và đảm bảo mỗi
-   FAIL/SKIP có trace + screenshot đính kèm.
-3. Tóm tắt TOTAL / PASS / FAIL / SKIP; với mỗi FAIL gồm lệnh `show-trace` và
-   phân loại là script-bug hay product-gap.
-4. **Bàn giao product-gap về spec (có nhắc).** Với mỗi FAIL phân loại **product-gap**
-   (defect thật, impl ≠ spec — không phải script-bug), in một
-   `/report-bug {UC-ID} {one-line expected-vs-actual}` sẵn-chạy để QC file nó vào spec repo dùng chung.
-   BUG_FLOW của `/report-bug` rồi định tuyến root cause (Code / BDD / PRD / Design / Env). Không bao giờ
-   fake-pass một product-gap — nó giữ FAIL trong `qc_status` cho tới khi fix + chạy lại. **script-bug
-   KHÔNG được file** (QC fix script và chạy lại). Liệt kê các lệnh; đừng tự tạo report.
-
-## Self-Review *(trước khi in Report)*
-
-Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
-
-- **Bịa:** mọi con số trong báo cáo trích được về **một dòng cụ thể** của sổ trace / output
-  runner / bug report — không nội suy khi thiếu mẫu?
-- **Nhảy bước:** đã tổng hợp trên **toàn bộ** SC trong phạm vi, không chỉ những SC có kết quả
-  đẹp? Đã liệt kê cả SC `not_run` và `flaky`, không im lặng bỏ khỏi bảng?
-- **Số liệu:** mọi `%` là phép chia thật **và nói rõ mẫu số**? Chỗ thiếu dữ liệu ghi **"chưa đủ
-  dữ liệu"** thay vì điền một số cho đủ bảng?
-
-> **Trạm này là nơi số liệu đi ra khỏi đội QC.** Một con số sai ở các trạm trước còn người trong
-> đội nhìn thấy; sai ở đây là đi vào báo cáo cho Lead/PM. Nhóm 3 vì vậy là nhóm nặng nhất ở đây:
-> *"một bảng đầy số sai tệ hơn một bảng có ô trống ghi rõ lý do"*.
-
-## Report
-
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+---
+
+## Role
+
+Bạn là stage **QC Report** — biến lần chạy gần nhất thành report + evidence chia sẻ được.
+
+## Skill (`{paths.qc_skills_dir}/qa-script-runner/`)
+
+- `report.md` — tự đủ, **theo nền**:
+  - `web` · `system` — Playwright HTML Report (`npx playwright show-report`) + Trace
+    (`test-results/<test>/trace.zip`, xem qua `npx playwright show-trace <file>`)
+  - `app` — Allure Report v2.x (`npx allure generate reports/allure-results --clean && npx allure open`)
+
+  kèm screenshot/evidence đính trên FAIL/SKIP.
+
+## Procedure
+
+1. Định vị artifact của lần chạy gần nhất cho `{UC-ID}` (HTML report + trace, theo nền).
+2. Sinh/làm mới `reports/<feature>/report.html` (self-contained) và đảm bảo mỗi
+   FAIL/SKIP có trace + screenshot đính kèm.
+3. Tóm tắt TOTAL / PASS / FAIL / SKIP; với mỗi FAIL gồm lệnh `show-trace` và
+   phân loại là script-bug hay product-gap.
+4. **Bàn giao product-gap về spec (có nhắc).** Với mỗi FAIL phân loại **product-gap**
+   (defect thật, impl ≠ spec — không phải script-bug), in một
+   `/report-bug {UC-ID} {one-line expected-vs-actual}` sẵn-chạy để QC file nó vào spec repo dùng chung.
+   BUG_FLOW của `/report-bug` rồi định tuyến root cause (Code / BDD / PRD / Design / Env). Không bao giờ
+   fake-pass một product-gap — nó giữ FAIL trong `qc_status` cho tới khi fix + chạy lại. **script-bug
+   KHÔNG được file** (QC fix script và chạy lại). Liệt kê các lệnh; đừng tự tạo report.
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mọi con số trong báo cáo trích được về **một dòng cụ thể** của sổ trace / output
+  runner / bug report — không nội suy khi thiếu mẫu?
+- **Nhảy bước:** đã tổng hợp trên **toàn bộ** SC trong phạm vi, không chỉ những SC có kết quả
+  đẹp? Đã liệt kê cả SC `not_run` và `flaky`, không im lặng bỏ khỏi bảng?
+- **Số liệu:** mọi `%` là phép chia thật **và nói rõ mẫu số**? Chỗ thiếu dữ liệu ghi **"chưa đủ
+  dữ liệu"** thay vì điền một số cho đủ bảng?
+
+> **Trạm này là nơi số liệu đi ra khỏi đội QC.** Một con số sai ở các trạm trước còn người trong
+> đội nhìn thấy; sai ở đây là đi vào báo cáo cho Lead/PM. Nhóm 3 vì vậy là nhóm nặng nhất ở đây:
+> *"một bảng đầy số sai tệ hơn một bảng có ô trống ghi rõ lý do"*.
+
+## 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-report Hoàn tất — {UC-ID}
-Report: reports/<feature>/report.html   (TOTAL {N} · PASS {p} · FAIL {f} · SKIP {s})
-Trace : test-results/<nodeid>/trace.zip  (python3 -m playwright show-trace <file>)
-
-Product-gap cần file ({g}):   ← chạy các lệnh này để PO/Dev thấy trên /sync (script-bug bị loại)
-  /report-bug {UC-ID} {gap 1 — expected vs actual}
-  /report-bug {UC-ID} {gap 2 …}
-  (không có → skip)
-
-Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
-Next: /validate-traces {UC-ID}   ← làm mới Living Docs (qc_status), rồi tạo PR
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-report Hoàn tất — {UC-ID}
+Report: reports/<feature>/report.html   (TOTAL {N} · PASS {p} · FAIL {f} · SKIP {s})
+Trace : test-results/<test>/trace.zip    (npx playwright show-trace <file>)   ← web·system
+Report: reports/allure-results            (npx allure open)                    ← app
+
+Product-gap cần file ({g}):   ← chạy các lệnh này để PO/Dev thấy trên /sync (script-bug bị loại)
+  /report-bug {UC-ID} {gap 1 — expected vs actual}
+  /report-bug {UC-ID} {gap 2 …}
+  (không có → skip)
+
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next: /validate-traces {UC-ID}   ← làm mới Living Docs (qc_status), rồi tạo PR
+```