@educa-corp/sdd-framework 0.9.7 → 0.9.8

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.7
+0.9.8

package/core/commands/qc-analyze.md

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-analyze — QC Requirement Analysis
 
-> Stage 1 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-design-script → qc-review-script → qc-run-script → qc-report). Port từ qa-analyst của team QC. Markdown-first: không có script ở đây.
+> Trạm 1/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-analyst của team QC. Markdown-first: không có script ở đây.
 
 ## Gate
 
@@ -284,7 +284,7 @@ ngược về `{id}` của §12 để không đếm hai lần.
 Bạn là **QC Analyst** — stage đầu tiên của QC automation pipeline. Lấy requirement
 chính thức (PRD + BDD `.feature` + design-spec) và phân rã thành một mô tả requirement
 CÓ CẤU TRÚC: function, business rule, data flow, acceptance criteria. Bạn **không**
-viết test case chi tiết hay Python (đó là qc-design-test / qc-design-script).
+viết test case chi tiết hay script tự động (đó là qc-design-test / qc-design-script).
 
 Ranh giới với `/qc-plan`: bạn trả lời *"requirement là gì?"*; qc-plan trả lời *"rủi ro ở đâu,
 hỏi dev gì?"*. Khi có gì mơ hồ/thiếu, ghi nó thành gap và bàn giao cho qc-plan — đừng bao giờ bịa câu trả lời.

package/core/commands/qc-automation-assess.md

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-automation-assess — Quyết định "cái nào máy chạy, cái nào phải tay"
 
-> Chạy **sau** `/qc-review-testcase` (chỉ nhận TC `APPROVED`) và **trước** `/qc-design-script`.
+> **Trạm 5/9** của dây chuyền QC automation — sau `/qc-review-testcase` (chỉ nhận TC `APPROVED`), trước `/qc-design-script`.
 > Ghi `AUTOMATION_ASSESSMENT.md` — bảng quyết định `Automatable: Y/N` kèm lý do chuẩn hoá, và là
 > **nguồn duy nhất** cho ba trạm sau.
 
@@ -232,8 +232,8 @@ Với mỗi UC của PRD, đọc `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.m
 
 | Đọc được | Làm gì |
 |---|---|
-| `APPROVED` | đưa TC của UC đó vào lượt đánh giá |
-| `NEEDS_FIX` · không có file | **LOẠI khỏi lượt** — và **liệt kê ra trong report** kèm trạng thái thật |
+| `APPROVED` · `APPROVED_WITH_SUGGESTIONS` | đưa TC của UC đó vào lượt đánh giá |
+| `REVISION_REQUIRED` · `REJECTED` · không có file | **LOẠI khỏi lượt** — và **liệt kê ra trong report** kèm trạng thái thật |
 
 > **`%Automated/Total` tính trên mẫu số CHỈ GỒM TC đã đánh giá**, và in kèm số TC bị loại. Để
 > không ai đọc *"100%"* mà tưởng đã phủ cả PRD.

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

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-design-script — QC Script Generation (sinh script, KHÔNG chạy)
 
-> Stage 5 của QC automation pipeline native. Chuyển `.Test.md` **đã `APPROVED`** thành script +
+> Trạm 6/9 của dây chuyền QC automation. Chuyển `.Test.md` **đã `APPROVED`** thành script +
 > Page Object. **Không chạy test, không ghi sổ trace** — đó là việc của `/qc-run-script`.
 
 ## Gate
@@ -214,8 +214,8 @@ Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp t
 
 | Đọc được | Làm gì |
 |---|---|
-| `APPROVED` | đi tiếp |
-| `NEEDS_FIX` | **DỪNG** — `❌ Test case chưa đạt. Sửa bằng /qc-design-test {UC-ID}, soát lại bằng /qc-review-testcase {UC-ID}.` |
+| `APPROVED` · `APPROVED_WITH_SUGGESTIONS` | **đi tiếp** — in một dòng bằng chứng:<br/>`✅ Cổng test case đã soát: {verdict} — {đường dẫn file vừa đọc}` |
+| `REVISION_REQUIRED` · `REJECTED` | **DỪNG** — `❌ Test case chưa đạt. Sửa bằng /qc-design-test {UC-ID}, soát lại bằng /qc-review-testcase {UC-ID}.` |
 | Không có file | **DỪNG** — `❌ Chưa soát test case. Chạy /qc-review-testcase {UC-ID} trước.` |
 
 > **Đây là thứ `/qc-run-test` cũ KHÔNG làm được** — nó nhận `REVIEW_<FEATURE>.md` mà không biết
@@ -240,32 +240,62 @@ Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp t
 **chỉ mục ngược duy nhất** TC → file code; `/qc-run-script` đọc đúng cột này để biết chạy file
 nào, thay vì suy đường dẫn từ quy ước đặt tên.
 
-## Role & stack (theo module qc-playwright)
-
-Bạn là **QC Script Designer**. Sinh Python pytest-playwright script + Page Object từ `.Test.md`.
+## Role & stack (module theo nền — bảng §2b của `steps/qc-scope.md`)
+
+Bạn là **QC Script Designer**. Sinh script test + đối tượng trang/màn/API từ `.Test.md`, theo
+**nền đã phân giải ở §2b** — web · app · system, mỗi nền một hình dạng code khác nhau.
+
+Quy tắc stack (BẮT BUỘC — từ `stack-profile.yaml` của module đã phân giải ở §2b):
+- **Markdown-first:** không bao giờ sinh script khi chưa có `.Test.md` đã review.
+- **Phủ đúng TC `Automatable: Y`** của `AUTOMATION_ASSESSMENT.md` — mỗi TC đúng một test,
+  không hơn không kém. TC `Y` gặp rào cản kỹ thuật lúc viết → `test.fixme('TC-xxx — {lý do}')`
+  + ghi `IMPROVE-xxx`, **không âm thầm bỏ qua**.
+- **Locator từ hợp đồng test-id, KHÔNG scan runtime.** Đọc bảng *Test Selectors* §4.5.6 (block
+  platform) của tech-doc gộp tại
+  `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` — lọc theo cột
+  *"Serves SC"* khớp SC của UC này. Ưu tiên map; fallback chỉ cho element có action mà **không** có
+  test-id trong §4.5.6, kèm ghi chú để gap được thêm vào tech-design.
+- **Không hard-code** URL · credential · timeout. **Không chờ cứng.** Data để ở `data/`.
+
+> 🔑 **Cách đọc `@trace.testid_attr` và cấu hình thuộc tính test-id KHÔNG viết ở đây** — nó nằm
+> ở `_shared/{web|mobile|api}-conventions.md` của nền, nạp ở §Skills ngay dưới. Lý do gỡ khỏi lệnh
+> *(Bước S · S4, 2026-09-17)*: bảng đó từng tồn tại **hai bản**, và hai bản đã lệch nhau — bản
+> trong lệnh còn ghi API của stack cũ trong khi bản ở skill đã đúng. **Một bảng, một chỗ.**
+>
+> Nội dung vẫn bắt buộc, chỉ đổi chỗ đọc: thuộc tính test-id ≠ mặc định mà không cấu hình trước
+> thì **mọi locator trượt 100 %**, và nó trượt **trông y hệt một bug sản phẩm** — QC sẽ đi mở
+> phiếu lỗi gửi PO thay vì sửa một dòng config.
+>
+> **Vì sao không suy thuộc tính từ platform cho nhanh:** suy từ platform là **phát biểu lại một
+> sự thật đã ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống.
 
-Quy tắc stack (BẮT BUỘC — từ `modules/qc-playwright/stack-profile.yaml`):
-- Markdown-first: không bao giờ sinh script khi chưa có `.Test.md` đã review.
-- Page Object extends `BasePage` gọn, 3 lớp: locator `_x()`, action `verb_noun()`, assertion `assert_x()` dùng `expect()`.
-- **Locator từ test-id contract (không scan runtime).** Đọc bảng *Test Selectors* §4.5.6 (block platform) của tech-doc gộp tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` — bảng gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này** — và dựng mỗi Page Object locator từ test-id ổn định của nó. **Ưu tiên map; fallback** về role/label/text/CSS chỉ cho element có action mà **không** có test-id trong §4.5.6, kèm ghi chú để gap được thêm vào tech-design.
-- **TÊN THUỘC TÍNH test-id: đọc `@trace.testid_attr`, KHÔNG tự suy từ platform.**
+## Skills — chọn NỀN rồi TẦNG, nạp MỘT file (`{paths.qc_skills_dir}/qa-script-designer/`)
 
-  | Đọc được | Làm gì |
-  |---|---|
-  | web + attr ≠ `data-testid` (vd `data-test` · `data-qa`) | **BẮT BUỘC** cấu hình trước khi dùng `get_by_test_id()`: `playwright.selectors.set_test_id_attribute("{attr}")`. Bỏ bước này thì `get_by_test_id()` vẫn dò `data-testid` mặc định → **trượt 100% locator**. |
-  | web + attr = `data-testid` | `get_by_test_id("...")` như thường |
-  | RN / Flutter / native | Dùng đúng cơ chế mà `{attr}` mô tả (`testID` · `Key`/`Semantics(identifier:)` · `accessibilityIdentifier`) |
-  | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode:** `⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo platform ({attr mặc định}). Nếu FE dùng thuộc tính khác thì MỌI locator sẽ trượt. Chạy /map-testids {UC-ID} để ghi field này.` Rồi mới fallback |
+> 🔴 **DỪNG nếu TC mang lane `job` hoặc `queue`.** Hai hình dạng này có TC *(trạm 3 đã hỗ trợ)*
+> nhưng **chưa có skill sinh script**. Sinh bừa bằng lane `api` là tạo API Object cho một thứ
+> **không có endpoint nào** — script dịch được, chạy được, và kiểm **sai thứ**.
+>
+> ```
+> ⛔ {UC-ID} có {n} TC lane {job|queue} — trạm này chưa hỗ trợ hình dạng đó.
+>    TC vẫn dùng được: chạy tay qua /qc-run-manualtest, hoặc đánh Automatable: N
+>    kèm lý do "chưa có bộ sinh script cho lane {lane}".
+> ```
+>
+> TC lane `api` trong cùng UC thì **vẫn sinh bình thường** — dừng theo TC, không dừng cả UC.
 
-  > **Vì sao không suy từ platform cho nhanh:** suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác** — đúng lớp lỗi mà `bin/trace-schema.json` sinh ra để chống. Nó hỏng **im lặng theo kiểu tệ nhất**: test fail "element not found" trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector.
-- pytest-playwright fixture; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
-- Không hard-code URL/cred/timeout (dùng `Env.*` / `CONFIG[...]`); không `time.sleep()`; không Allure.
-- Phủ **100%** TC mang `Automatable: Y` — mỗi TC có đúng một test.
+**Nạp trước:** `_shared/{web|mobile|api}-conventions.md` + `_shared/file-naming-and-folders.md`
+theo nền đã phân giải ở `steps/qc-scope.md` §2b. Rồi chọn **MỘT** file lane:
 
-## Skills — chọn layer, nạp MỘT file (`{paths.qc_skills_dir}/qa-runner/`)
+| `active_platform` | File |
+|---|---|
+| `web` · `webview` | `web/functional/{gui-screen,gui-feature,api}.md` · `web/{integration,e2e,non-functional}.md` |
+| `app` · `app-ios` · `app-android` | `mobile/functional/{screen,feature}.md` · `mobile/{integration,e2e,non-functional}.md` |
+| `system` | `api/{endpoint,auth,security}.md` |
 
-`functional/{gui-screen,gui-feature,api}.md`, `integration.md`, `e2e.md`,
-`non-functional.md`, `exploratory/session.md`.
+> ⚠️ **Ba nền sinh ba hình dạng code khác nhau.** Web dùng Page Object; app dùng **Screen Object**
+> với thứ tự locator của Appium; `system` dùng **API Object** — không màn hình, không locator,
+> không chờ, và **cấm `expect()` bên trong object**. Nạp nhầm lane là sinh ra thứ chạy được nhưng
+> sai kiến trúc, và `/qc-review-script` sẽ chặn nó bằng `R01`.
 
 ---
 
@@ -293,11 +323,11 @@ bị **chép cứng vào một artifact bền**, và **trạm này chép nó l
 
 | Đường dẫn | Nội dung | Người sửa tay? |
 |---|---|:---:|
-| `tests/<project>/test_<feature>.py` | pytest script, 1-1 với `test-cases/` | ✅ **có** — `script-bug` |
-| `pages/<feature>_page.py` | Page Object (3 lớp + BasePage) | ✅ **có** — `script-bug` |
+| `tests/{TICKET-ID}/<feature>-<scenario>.spec.ts` | spec, 1-1 với `test-cases/` | ✅ **có** — `script-bug` |
+| `pages/<feature>.page.ts` *(web)* · `api/<resource>.api.ts` *(system)* · `screens/<feature>.screen.ts` *(app)* | đối tượng trang/API/màn | ✅ **có** — `script-bug` |
 | `{qc_artifact_dir}AUTOMATION_ASSESSMENT.md` — cột `Script file` | đường dẫn script của từng TC | ❌ lệnh ghi |
 
-*(Đường dẫn theo `modules/qc-playwright/stack-profile.yaml` §layout.)*
+*(Đường dẫn theo `§layout.{web|api|mobile}` của module đã phân giải ở §2b — KHÔNG viết cứng tên module.)*
 
 **KHÔNG ghi sổ trace.** Sinh script không phải là chạy test — ghi `qc_status` ở đây là khẳng định
 một điều chưa xảy ra. Đó là việc của `/qc-run-script` và `/qc-run-manualtest`.
@@ -306,9 +336,9 @@ một điều chưa xảy ra. Đó là việc của `/qc-run-script` và `/qc-ru
 
 Mỗi test được sinh ra mang scenario nó verify, lấy từ Trace matrix của `.Test.md`:
 
-```python
-# @trace.verifies={UC-ID}-SC{N}
-def test_TC_<FEATURE>_001_...(...): ...
+```typescript
+// @trace.verifies={UC-ID}-SC{N}
+test('TC_<FEATURE>_001 — …', async ({ page }) => { … });
 ```
 
 ## Tag ưu tiên — `@smoke` / `@regression`

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

@@ -6,7 +6,7 @@ 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-testcase → qc-design-script → qc-review-script → qc-run-script → qc-report). Port từ qa-designer của team QC. Sinh test case Markdown (`.Test.md`) — Python đến sau ở /qc-design-script.
+> 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
 
@@ -234,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**,
@@ -274,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ế
@@ -322,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-design-script (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/`)
 
@@ -348,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 |

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-testcase → qc-design-script → qc-review-script → qc-run-script → 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

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-testcase → qc-design-script → qc-review-script → qc-run-script → 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ó.
@@ -166,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-script` 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
+```

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

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-review-script — QC Review Gate: script
 
-> Soát **code test + Page Object** đã sinh: khớp `.Test.md`, cấu trúc Page Object, assertion,
+> **Trạm 7/9** của dây chuyền QC automation. Soát **code test + Page Object** đã sinh: khớp `.Test.md`, cấu trúc Page Object, assertion,
 > selector, hard-code. Cặp với `/qc-review-testcase` — hai lệnh, hai vai, không còn đoán.
 
 ## Gate
@@ -214,17 +214,25 @@ trạm sinh script. *Reviewer tự sửa rồi tự duyệt là bỏ mất cái
 |---|---|
 | `shared/read-doc-gap-inputs.md` | Nạp **đủ** mọi tài liệu nguồn theo bảng *Tài liệu đầu vào đã đọc* của `DOC_GAP.md` — soát mù thì kết luận "0 lỗi" là vô nghĩa |
 | `shared/review-file-template.md` | Khuôn file kết quả · thang điểm `XX/100` · luật ghi file · nguyên tắc *mặc định hoài nghi* |
+| `script/_shared/review-rules.md` | **Luật soát dùng chung**: R01–R07 · 4 mức severity · 4 verdict suy từ số đếm · phép kiểm cơ học · đường dẫn theo `§layout` |
 
-**Rồi chọn theo tầng, nạp MỘT file:**
-`script/{functional,e2e,integration,non-functional,exploratory}.md`
+**Rồi chọn theo NỀN rồi theo TẦNG, nạp MỘT file** *(nền phân giải ở `steps/qc-scope.md` §2b)*:
+
+| `active_platform` | File |
+|---|---|
+| `web` · `webview` | `script/web/{functional,integration,e2e,non-functional}.md` |
+| `app` · `app-ios` · `app-android` | `script/mobile/{functional,integration,e2e,non-functional}.md` |
+| `system` | `script/api/{endpoint,auth,security}.md` |
+| *(mọi nền)* | `script/exploratory.md` — biên bản phiên khám phá, không phải code |
+
+> ⚠️ **Ba nền soát ba thứ khác nhau, không phải một checklist đổi tên.** Thứ tự locator của web
+> *(`getByRole` → … → css)* **không tồn tại** ở Appium *(`~accessibilityId` → `id` → `xpath`)*, và
+> lane `api` **không có locator lẫn wait** — nó có API Object với luật *"không `expect()` bên
+> trong"*. Nạp nhầm lane là đi tìm những thứ không tồn tại rồi kết luận "không có lỗi".
 
 > ⚠️ **KHÔNG nạp `shared/review-check-groups.md` và §*Kiểm tra cấu trúc TC*.** Hai thứ đó kiểm
 > **cấu trúc file test case** — áp vào một Page Object là bảo reviewer đi tìm `#### Expected Result`
 > trong code, rồi gắn nhãn lỗi cho thứ đáng lẽ không có ở đó.
->
-> *Ghi chú Đợt 2 · b2:* bộ `script/*` hiện **phẳng theo tầng**. Khi bước 2 chốt stack, nó sẽ tái
-> cấu trúc thành `script/{web,mobile}/*` — tiêu chí soát khác nhau theo nền. **Cố ý chưa làm ở
-> bước này**: viết tiêu chí cho một stack chưa chốt là viết hai lần.
 
 ---
 
@@ -233,8 +241,8 @@ trạm sinh script. *Reviewer tự sửa rồi tự duyệt là bỏ mất cái
 - **Khớp `.Test.md` 1-1?** Mỗi TC có đúng một test tương ứng; không test mồ côi, không TC bị bỏ.
 - **Page Object 3 lớp + BasePage gọn?** Logic điều hướng không rò vào file test.
 - **`expect()` chứ không phải bare assert?** Assertion phải nói được nó kỳ vọng gì khi đỏ.
-- **Không hard-code** URL · credential · timeout. Không `sleep` cố định. Không Allure.
-- **Selector theo thứ tự ưu tiên** (`data-testid` → role → …), lấy từ §4.5.6 chứ không dò DOM.
+- **Không hard-code** URL · credential · timeout. Không chờ cứng (`waitForTimeout` · `browser.pause`).
+- **Locator theo thứ tự ưu tiên CỦA NỀN** — web `getByRole → … → css` · app `~accessibilityId → id → xpath` · api không có locator. Lấy từ §4.5.6, không dò DOM.
 - **100% TC đã script** — không còn TC ở trạng thái `Draft`.
 
 Sinh findings (mức độ + vị trí + cách sửa), chấm điểm, ra verdict.
@@ -273,13 +281,14 @@ File **phải** chứa đúng một dòng theo khuôn này, ở §Tổng quan:
 ```
 hoặc
 ```
-**Verdict:** NEEDS_FIX
+**Verdict:** REVISION_REQUIRED   ← hoặc REJECTED khi có BLOCKER
 ```
 
-`APPROVED` khi **điểm `≥80` VÀ không còn `FAIL` chặn**; ngược lại `NEEDS_FIX`.
+Verdict suy từ **số đếm lỗi**, không từ điểm — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Xem `qa-reviewer/shared/review-file-template.md` §Verdict.
 
 > **Đây là contract, không phải định dạng cho đẹp.** `/qc-run-script` (Đợt 2 · b2) **DỪNG** khi
-> verdict là `NEEDS_FIX` hoặc chưa có file này. Đổi chuỗi này là làm trạm đó mù — nên nếu phải
+> verdict là `REVISION_REQUIRED` / `REJECTED`, hoặc chưa có file này. Ngưỡng đi tiếp:
+> **`≥ APPROVED_WITH_SUGGESTIONS`** (`AGT-005:132`). Đổi chuỗi này là làm trạm đó mù — nên nếu phải
 > đổi, đổi ở cả hai nơi trong cùng một commit.
 
 ### Chạy lại — ghi đè ở đây AN TOÀN, và đây là lý do
@@ -312,7 +321,7 @@ Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — *
   field `quote` của finding làm bằng chứng cho nó** — mở lại file đọc lại đoạn đó.
 - **Nhảy bước:** đã đi hết bộ tiêu chí `script/*`, **không** trộn tiêu chí test case vào? Verdict
   `APPROVED` phát ra **sau** khi soát đủ, không phải vì "trông ổn"?
-- **Số liệu:** số finding theo mức (critical/major/minor) = đếm thật trên file vừa ghi?
+- **Số liệu:** số finding theo **bốn mức** (BLOCKER/MAJOR/MINOR/SUGGESTION) = đếm thật trên file vừa ghi, và verdict khớp đúng số đếm đó *(R06)*?
 
 > **Verdict của lệnh này là cổng cho trạm chạy.** Một `APPROVED` phát ra sớm cho chạy một bộ script
 > chưa đạt, và kết quả chạy đó đi thẳng vào `/qc-report` thành số liệu người ta tin.
@@ -325,9 +334,9 @@ Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 ```
 /qc-review-script Hoàn tất — {UC-ID} vòng #{N}
 Điểm  : {XX}/100  ({fail} FAIL × −5đ · {warn} WARN × −2đ){nếu có vòng trước: "   ← vòng #{N-1}: {YY}/100"}
-Verdict: {APPROVED | NEEDS_FIX} — {n} findings ({crit} chặn)
+Verdict: {APPROVED | APPROVED_WITH_SUGGESTIONS | REVISION_REQUIRED | REJECTED} — {n} findings ({blk} BLOCKER · {maj} MAJOR · {min} MINOR · {sug} SUGGESTION)
 File  : {qc_artifact_dir}test-cases/REVIEW_SCRIPT_<FEATURE>.md (thêm 1 hàng vào bảng Tổng quan)
 Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
-Next (APPROVED) : /qc-report {UC-ID}  rồi tạo PR
-     (NEEDS_FIX → sửa script bị gắn cờ, rồi chạy lại lệnh này)
+Next (≥ APPROVED_WITH_SUGGESTIONS) : /qc-report {UC-ID}  rồi tạo PR
+     (REVISION_REQUIRED | REJECTED → sửa script bị gắn cờ, rồi chạy lại lệnh này)
 ```