@educa-corp/sdd-framework 0.9.7 → 0.9.8

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

@@ -0,0 +1,111 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/Automation-Standards.md §4 §6 §7 §8 §9 §10 §11 (Approved)
+---
+
+# Soát script — Web Functional *(Playwright Test + TypeScript)*
+
+**Nạp `../_shared/review-rules.md` trước.** File này chỉ có phần riêng của nền web, tầng
+functional.
+
+## Khi nào trigger
+- Soát script cho TC functional (1 màn hoặc đa màn) của một PRD, nền `web`, sau `/qc-design-script`.
+
+## Khi KHÔNG trigger
+- Nền `app` → `../mobile/functional.md` · nền `system` → `../api/endpoint.md`
+- Soát **test case** *(không phải code)* → `/qc-review-testcase`
+- Soát biên bản exploratory → `../exploratory.md`
+
+---
+
+## Phase 1 — Đọc đủ trước khi soát *(R01)*
+
+1. `automation/tests/{TICKET-ID}/<feature>-*.spec.ts` — **mọi** spec của feature
+2. `automation/pages/<feature>.page.ts` + `base.page.ts`
+3. `automation/data/<feature>.data.ts` · `fixtures/*.fixture.ts` nếu spec có dùng
+4. `.Test.md` gốc + `AUTOMATION_ASSESSMENT.md` — để đếm TC `Automatable: Y`
+
+**R07 chặn cửa:** spec thiếu header artifact ID / `@trace.verifies` ⇒ **BLOCKER, dừng soát.**
+
+---
+
+## Phase 2 — Bảy nhóm soát của nền web
+
+### A · Page Object *(§4)*
+
+- Có `extends BasePage`? Không kế thừa là chép lại method dùng chung → **MAJOR**
+- **Không `expect()` trong Page Object** — assertion thuộc spec. Có ⇒ **MAJOR**
+- Method 1 việc, đặt tên **camelCase động từ trước**: `login()` · `fillEmail()` ⇒ sai tên là MINOR
+- Class `PascalCase` + hậu tố `Page`: `LoginPage` · file `kebab-case`: `login.page.ts`
+- Locator khai **trong** Page Object, **không** hard-code trong spec ⇒ trong spec là **BLOCKER**
+
+### B · Locator *(§6.1 · §6.2)*
+
+Thứ tự ưu tiên bắt buộc:
+
+```
+getByRole → getByLabel → getByPlaceholder → getByTestId → getByText → locator('[css]')
+```
+
+- `locator('[css]')` mà **không có comment nêu lý do** ⇒ **MAJOR**
+- Locator bám **class CSS tự sinh** (`.css-1x2y3z`, `.MuiBox-root-42`) ⇒ **MAJOR**
+- XPath ⇒ **MAJOR** *(web có đủ 5 cách tốt hơn)*
+- `.first()` / `.nth(n)` không kèm lý do ⇒ **MINOR** — vị trí đổi là test đổi
+- **test-id lấy từ bảng §4.5.6 của tech-doc**, không dò DOM lúc chạy. Dò DOM ⇒ **MAJOR**
+- Thuộc tính test-id ≠ `data-testid` mà **thiếu** `use: { testIdAttribute: '…' }` trong
+  `playwright.config.ts` ⇒ **BLOCKER** — `getByTestId()` sẽ trượt **100 %**, và nó trượt trông
+  **y hệt một bug sản phẩm**
+
+### C · Assertion *(§7)*
+
+- Dùng **web-first assertion** `await expect(locator).toBeVisible()` — tự retry
+- `expect(await locator.isVisible()).toBe(true)` ⇒ **MAJOR**: chụp giá trị một lần, mất auto-retry
+- Chỉ assert URL mà không assert nội dung ⇒ **MINOR** — điều hướng đúng không có nghĩa hiển thị đúng
+- `expect(true).toBe(true)` hoặc assert không thể sai ⇒ **BLOCKER** *(test xanh giả)*
+- Thiếu assertion âm cho nhánh lỗi mà `.Test.md` có ⇒ **MAJOR**
+
+### D · Wait *(§8)*
+
+- `waitForTimeout(…)` ⇒ **MAJOR** — chờ cứng, hỏng theo tốc độ máy
+- Chờ theo **điều kiện**: `expect(...).toBeVisible()` · `waitForResponse` · `waitForURL`
+- Timeout tự đặt < 3 s hoặc > 30 s mà không nêu lý do ⇒ **MINOR**
+
+### E · Test structure *(§5)*
+
+- Mỗi test **độc lập**: chạy riêng lẻ vẫn pass. Phụ thuộc thứ tự ⇒ **BLOCKER**
+- `test.describe` gom theo màn/nhóm chức năng; tên test mang **TC-ID**
+- Auth dùng `storageState` / fixture, **không** đăng nhập lại trong từng test ⇒ lặp login là **MINOR**
+- Data từ `data/<feature>.data.ts`, **không** hard-code trong spec ⇒ hard-code là **MAJOR**
+- Tạo data thì phải dọn *(teardown)*; trừ khi chỉ mock/intercept ⇒ thiếu dọn là **MAJOR**
+
+### F · Code quality *(§9)*
+
+- TypeScript **strict**: không `any`, không `as any` ⇒ có là **MINOR**
+- Kiểu trả về khai tường minh cho method public
+- Thứ tự import: Playwright → Page Object → data → helper
+- Logic lặp ≥3 lần chưa tách ⇒ **MINOR**
+
+### G · Anti-pattern *(§10)* và flaky *(§11)*
+
+- Test flaky **không mang tag `@flaky`** mà vẫn nằm trong suite chính ⇒ **MAJOR**
+- Tag `@flaky` có, nhưng **không có ghi chú điều tra** ⇒ **MINOR**
+- `test.skip` không nêu lý do ⇒ **MINOR**; `test.only` sót lại ⇒ **BLOCKER** *(CI chạy 1 test rồi báo xanh)*
+
+---
+
+## Phase 3 — Kiểm cơ học *(bắt buộc — `_shared` §5)*
+
+```
+npx tsc --noEmit
+npx playwright test automation/tests/{TICKET-ID}/<feature>-*.spec.ts --list
+```
+
+Số test collect được **phải bằng** số TC `Automatable: Y` của feature này. Lệch ⇒ **BLOCKER**.
+
+---
+
+## Output
+
+Theo `_shared/review-rules.md` §3 — verdict suy từ số đếm, kèm **≥2–3 điểm tốt** *(R05)*.
+Ghi vào `{qc_artifact_dir}test-cases/REVIEW_SCRIPT_<FEATURE>.md`.

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

@@ -0,0 +1,46 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/Automation-Standards.md §5 §7 §8 (Approved)
+---
+
+# Soát script — Web Integration *(GUI ↔ Backend · API · DB)*
+
+**Nạp `../_shared/review-rules.md` trước**, rồi `functional.md` cùng nền — file này chỉ thêm
+phần riêng của tầng tích hợp.
+
+## Khi nào trigger
+- Soát script kiểm **giao tiếp giữa hai thành phần**: UI gọi API, API ghi DB, sự kiện qua queue.
+
+## Khi KHÔNG trigger
+- Chỉ kiểm UI một màn → `functional.md` · chỉ kiểm endpoint → `../api/endpoint.md`
+
+---
+
+## Thêm gì so với functional
+
+### A · Ranh giới thật, không mock
+
+- Tầng này tồn tại để kiểm **đường dây thật**. Mock hết hai đầu ⇒ **BLOCKER** — test không kiểm gì
+- Mock **một** đầu để cô lập lỗi thì được, nhưng phải ghi rõ đầu nào thật
+
+### B · Đối chiếu hai phía
+
+- Assert trên UI **và** đối chiếu dữ liệu phía server *(qua `request` của Playwright)*
+- Chỉ assert UI ⇒ **MAJOR**: màn hình hiển thị đúng **dữ liệu cũ** vẫn là bug, UI assertion không bắt được
+
+### C · Trạng thái và thứ tự
+
+- Data tạo ở bước trước phải được **dọn** kể cả khi test fail giữa chừng *(dùng `finally`/fixture)*
+- Chờ theo **điều kiện của hệ**: `waitForResponse(...)` thay vì chờ cứng ⇒ chờ cứng là **MAJOR**
+- Test phụ thuộc bản ghi có sẵn trên môi trường ⇒ **MAJOR** — môi trường sạch là fail oan
+
+### D · Mã lỗi
+
+- Nhánh lỗi tích hợp *(timeout, 5xx, kết nối đứt)* có được kiểm không? Thiếu hẳn ⇒ **MAJOR**
+
+---
+
+## Kiểm cơ học + Output
+
+Như `functional.md` Phase 3 và §Output.

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

@@ -0,0 +1,49 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/Automation-Standards.md §7 §8 §10 (Approved)
+---
+
+# Soát script — Web Non-Functional *(hiệu năng · bảo mật · a11y · tương thích)*
+
+**Nạp `../_shared/review-rules.md` trước**, rồi `functional.md` cùng nền.
+
+## Khi nào trigger
+- Soát script kiểm thuộc tính **phi chức năng**: thời gian đáp ứng, kiểm soát truy cập, khả năng
+  tiếp cận, chạy đa trình duyệt.
+
+---
+
+## Thêm gì so với functional
+
+### A · Ngưỡng phải là con số, không phải cảm tưởng
+
+- Assert hiệu năng **không có ngưỡng cụ thể** ⇒ **BLOCKER** — không có ngưỡng thì không có kết quả
+- Ngưỡng hard-code trong spec thay vì đọc từ config/data ⇒ **MINOR**
+- Đo bằng `Date.now()` quanh một `await` ⇒ **MINOR**; ưu tiên `page.evaluate(performance…)` hoặc
+  `waitForResponse` + timing của response
+
+### B · Bảo mật
+
+- Payload thử injection **hard-code trong spec** ⇒ **MAJOR** — để ở `data/`
+- Kiểm quyền: phải assert **bị chặn** *(403/redirect/không thấy phần tử)*, không chỉ assert
+  "không lỗi" ⇒ assert yếu ⇒ **MAJOR**
+- Credential thật trong code ⇒ **BLOCKER**
+
+### C · Khả năng tiếp cận
+
+- Dùng thư viện a11y qua Playwright *(vd `@axe-core/playwright`)*, assert trên **số vi phạm theo
+  mức**, không assert "có chạy"
+- Không nêu tiêu chuẩn áp dụng (WCAG mức nào) ⇒ **MINOR**
+
+### D · Tương thích
+
+- Chạy đa trình duyệt bằng **`projects` trong `playwright.config.ts`**, không tự lặp trong spec
+  ⇒ tự lặp ⇒ **MAJOR** *(mất song song, mất report tách theo project)*
+- Chỉ khai một browser rồi gọi là "kiểm tương thích" ⇒ **MAJOR**
+
+---
+
+## Kiểm cơ học + Output
+
+Như `functional.md` Phase 3 và §Output.

package/core/skills/qc/qa-reviewer/shared/read-doc-gap-inputs.md

@@ -16,7 +16,7 @@ upstream_sha: 3caa1562399ef1167ac2dc620add2c6c729e55df
 2. **`Read` toàn bộ DOC_GAP.** Định vị mục **`## Tài liệu đầu vào đã đọc để phân tích`** — bảng liệt kê **đầy đủ** file nguồn (cột "Đường dẫn", tính từ `{paths.specs_dir}/`), kèm vai trò & phiên bản.
 3. **`Read` TỪNG file trong bảng đó** — ghép prefix `{paths.specs_dir}/` vào đường dẫn ở cột. Đọc HẾT, không bỏ sót dòng nào (spec chính + ref bắt buộc + transitive 1-hop). Nếu bảng liệt kê phiên bản, kiểm tra file hiện tại khớp; lệch phiên bản → ghi chú vào REVIEW.
 4. **Đối chiếu chéo:** file nào có mặt ở header DOC_GAP ("Tài liệu nguồn (spec chính)"/"Coverage Attestation") mà thiếu trong bảng → vẫn đọc.
-5. Chỉ sau khi đã nạp xong toàn bộ input + file domain (`business-dictionary.md`, `product-definition/`) mới bắt đầu review — dùng chúng làm chuẩn đối chiếu để phán quyết `APPROVED` / `NEEDS_FIX`.
+5. Chỉ sau khi đã nạp xong toàn bộ input + file domain (`business-dictionary.md`, `product-definition/`) mới bắt đầu review — dùng chúng làm chuẩn đối chiếu để phán quyết `APPROVED` / `REVISION_REQUIRED` / `REJECTED`.
 
 ## Nguyên tắc
 

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

@@ -12,7 +12,7 @@ upstream_sha: bd596393ecc016cbea106835681a4979c0a9ca0e
 >
 > | | Upstream | Ở đây | Vì sao |
 > |---|---|---|---|
-> | Verdict | `APPROVE` / `REJECT` | **`APPROVED` / `NEEDS_FIX`** | Đây là từ vựng chung của framework — `/review-code` dùng đúng cặp này. Đổi theo upstream là làm ba lệnh review nói ba kiểu |
+> | Verdict | `APPROVE` / `REJECT` | **4 mức của `AGT-006`** *(xem §Verdict)* | **Đổi 2026-09-17, Bước S · S3.** Trước đó là `APPROVED`/`NEEDS_FIX` cho khớp `/review-code`. Nay lane QC có `AGT-006` §3.2 định nghĩa **severity thành bốn ô đếm được**, nên bốn verdict chỉ là **tên của bốn ô đó** — không thêm phán quyết nào, và ngưỡng qua cửa đã khai sẵn ở `AGT-005:132`. Lane DEV *(`/review-code` · `/review-context` · `/review-tech-docs`)* **giữ 2 mức** vì chưa có bảng severity tương ứng; ở đó 4 tên sẽ là bốn nhãn phải tự đoán. **Bất đối xứng có lý do, không phải chỗ quên đồng bộ** |
 > | Bảng Tổng quan | mỗi vòng **ghi đè** hàng của tầng đó | mỗi vòng **thêm một hàng** | Ghi đè thì mất điểm vòng trước, và **không ai thấy được điểm có tăng không**. Các bảng chi tiết vẫn ghi đè (chúng là trạng thái hiện tại, tích luỹ chỉ thành nhiễu) |
 
 # Khuôn file Review (dùng chung)
@@ -41,7 +41,7 @@ upstream_sha: bd596393ecc016cbea106835681a4979c0a9ca0e
 - **1 bullet Expected / TC (ATOMIC — đội QC chốt 2026-07-09):** mỗi TC có đúng **1**
   `#### Expected Result` với **ĐÚNG 1 bullet**; Test Steps chỉ `[Action]`/`[Verify]`, **không**
   còn `→ [Expected]` ở bước. Đếm nhanh: số header `### TC_` = số `#### Expected Result` = số
-  bullet Expected. **TC có ≥2 bullet → `NEEDS_FIX` `[MULTI_BULLET_EXPECTED]`**, yêu cầu tách
+  bullet Expected. **TC có ≥2 bullet → `MAJOR` `[MULTI_BULLET_EXPECTED]`**, yêu cầu tách
   thành nhiều TC độc lập (mỗi TC 1 bullet, giữ full steps, đánh số lại tuần tự).
 - **Soi bullet 2-kết-cục ẩn (ATOMIC = 1 KẾT CỤC, không chỉ đếm bullet):** bullet nối bằng `;`
   kiểu "khẳng-định + phủ-định" (grep bullet chứa `;` **và** `không/KHÔNG`, vd
@@ -87,26 +87,45 @@ upstream_sha: bd596393ecc016cbea106835681a4979c0a9ca0e
 - **Oracle tự chứa và đúng nguồn:** chuỗi sao-nguyên-văn (tiêu đề · nhãn · chữ trên nút · thông
   báo lỗi) mà TC assert phải ghi nguyên văn trong Expected Result **và** khớp design-spec/PRD của
   **chính feature này**. Soi kỹ chuỗi **mượn nhầm từ feature anh em** (vd *"tạo tài khoản"* vs
-  *"tạo câu hỏi"*). Chuỗi chưa có nguồn chốt mà bị bịa oracle → `NEEDS_FIX`; đúng ra phải để
+  *"tạo câu hỏi"*). Chuỗi chưa có nguồn chốt mà bị bịa oracle → `MAJOR`; đúng ra phải để
   `Status: PENDING` hoặc gắn `🚫 Block: [GAP-UC{N}-{nnn}]`.
 
 ## Thang điểm
 
 **Điểm chất lượng `XX/100`:** trừ **5đ** mỗi lỗi `FAIL`, trừ **2đ** mỗi `WARN`.
 
+> **Hai bộ nhãn, một phép ánh xạ.** Nhãn cũ `FAIL`/`WARN` dùng để **trừ điểm**; nhãn
+> `BLOCKER`/`MAJOR`/`MINOR`/`SUGGESTION` *(`AGT-006` §3.2)* dùng để **suy verdict**. Ánh xạ:
+> `FAIL` ≡ `BLOCKER` ∪ `MAJOR` · `WARN` ≡ `MINOR` ∪ `SUGGESTION`. Ghi finding thì dùng nhãn
+> **bốn mức** — nó phân biệt được *"không chạy được"* với *"chạy được nhưng khó bảo trì"*,
+> thứ mà `FAIL` gộp làm một.
+
 | Điểm | Nghĩa |
 |---|---|
 | **≥ 80** | đạt |
 | 60–79 | cần cải thiện |
 | < 60 | không đạt |
 
-**Verdict suy ra được, không chấm cảm tính:**
+**Verdict suy ra được, không chấm cảm tính — và suy từ SỐ ĐẾM LỖI, không từ điểm:**
 
 ```
-điểm ≥ 80  VÀ  không còn lỗi FAIL chặn   →  APPROVED
-ngược lại                                 →  NEEDS_FIX
+≥1 BLOCKER                                  →  REJECTED
+0 BLOCKER, ≥1 MAJOR                         →  REVISION_REQUIRED
+0 BLOCKER, 0 MAJOR, ≥1 MINOR/SUGGESTION     →  APPROVED_WITH_SUGGESTIONS
+0 BLOCKER, 0 MAJOR, 0 MINOR/SUGGESTION      →  APPROVED
+
+đi tiếp được:  APPROVED · APPROVED_WITH_SUGGESTIONS      (ngưỡng ≥ APPROVED_WITH_SUGGESTIONS)
+phải sửa lại:  REVISION_REQUIRED · REJECTED
 ```
 
+> **Điểm `XX/100` vẫn giữ, nhưng nó KHÔNG quyết verdict.** Điểm là con số để **so hai vòng soát
+> với nhau**; verdict là kết luận **đi tiếp hay không**. Khi hai thứ mâu thuẫn — điểm 75 mà
+> 0 BLOCKER + 0 MAJOR — thì **số đếm thắng** *(`AGT-006` R06: verdict phải phản ánh đúng finding
+> counts, không được override)*, và chỗ phải sửa là **trọng số trừ điểm**, không phải verdict.
+>
+> **Vì sao không để điểm quyết:** một lỗi BLOCKER duy nhất vẫn có thể ra 85 điểm nếu mọi mục khác
+> tốt — và 85 điểm mà script không dịch được là một con số nói dối.
+
 > **Vì sao là số, không phải chữ cái.** Framework trước đây ghi `Score: A / B / C / D` mà **không
 > có luật chấm** — nên hai người soát ra hai kết quả, và vòng 2 không so được với vòng 1. Một con
 > số có luật trừ điểm làm được cả ba: **so được các vòng** · **verdict suy ra được** · **hai
@@ -177,7 +196,7 @@ review sẽ làm `/qc-design-script` nhặt nó lên như một file test case r
 | Tầng | Kịch bản còn thiếu |
 |---|---|
 
-## Điều kiện để APPROVED (khi đang NEEDS_FIX)
+## Điều kiện để lên `APPROVED` (khi đang `REVISION_REQUIRED` / `REJECTED`)
 
 | Tầng | Điều kiện cần sửa |
 |---|---|

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

@@ -123,7 +123,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID / journey)
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Danh sách journey thiếu TC; TC cần sửa Expected; TC vi phạm isolation.
 Điền thêm bảng **Coverage journey/path (E2E)** ở cuối file review.

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

@@ -84,7 +84,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (charter ID)
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Mỗi charter: ✅ PASS | 🔧 REWORK | ✂️ SPLIT | 🔗 MERGE + feedback cụ thể.
 Charter bổ sung nếu còn gap.

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

@@ -117,7 +117,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Đề xuất TC cần thêm/sửa/xoá, sắp theo priority. Liệt kê TC thiếu Trace BR (⚠️) cần bổ sung.
 

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

@@ -113,7 +113,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID / điểm tích hợp)
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Điểm tích hợp thiếu TC; TC Expected mờ nhạt; TC DB thiếu cleanup.
 Điền thêm bảng **Coverage handshake (Integration)** ở cuối file review.

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

@@ -124,7 +124,7 @@ hàng của tầng mình, KHÔNG ghi đè tầng khác).
 Mỗi tiêu chí: ✅ PASS | ⚠️ WARN | ❌ FAIL + evidence cụ thể (TC ID)
 
 **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
-**Verdict:** `điểm ≥ 80` VÀ không còn `FAIL` chặn → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+**Verdict:** suy từ **số đếm lỗi** theo `shared/review-file-template.md` §Verdict — `≥1 BLOCKER` → `REJECTED` · `≥1 MAJOR` → `REVISION_REQUIRED` · chỉ MINOR/SUGGESTION → `APPROVED_WITH_SUGGESTIONS` · sạch → `APPROVED`. Điểm `XX/100` vẫn ghi, nhưng **không quyết verdict**.
 
 Danh sách TC Expected mờ nhạt (thiếu ngưỡng); loại non-functional thiếu coverage.
 Ghi rõ TC nào cần môi trường đặc biệt. Điền thêm bảng **Chi tiết NFR** ở cuối file review.

package/core/skills/qc/qa-script-designer/_shared/api-conventions.md

@@ -0,0 +1,94 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §4 §5 §6 §10 §11 · AGT-010 §2 §3 (Approved)
+---
+
+# Quy ước viết script API — TypeScript + Playwright (API mode)
+
+**Nạp file này trước mọi file lane `api/`.** Nó là bản song song của `web-conventions.md` cho
+nền `system`; hai file **không** kế thừa nhau vì đối tượng khác hẳn.
+
+> ⚠️ **API Object ≠ Page Object.** Không màn hình, không locator, không chờ. Mang thói quen web
+> sang đây là viết ra thứ chạy được nhưng sai kiến trúc — và `/qc-review-script` lane `api` sẽ
+> chặn nó bằng `R01`.
+
+## 1 · API Object *(§4 · AGT-010 §2.2 · R01)*
+
+```typescript
+// api/booking.api.ts
+export class BookingAPI extends BaseAPI {
+  async create(payload: BookingPayload): Promise<APIResponse> {
+    return this.ctx.post('/bookings', { data: payload });
+  }
+}
+```
+
+| Luật | Vi phạm là |
+|---|---|
+| **Mọi HTTP request đi qua API Object** — không `request.post()` thô trong spec | `BLOCKER` |
+| `extends BaseAPI`; class `<Resource>API`; file `<resource>.api.ts` | `MINOR` |
+| **1 method = 1 endpoint action** | `MAJOR` |
+| Trả `Promise<APIResponse>` — **không parse response bên trong** | `MAJOR` |
+| **Không `expect()` trong API Object** — assertion thuộc spec | `MAJOR` |
+| Mỗi resource một API Object, không "God API Object" | `MAJOR` |
+
+**Vì sao cấm `expect()` bên trong:** API Object là *nơi biết gọi đâu*, spec là *nơi biết thế nào
+là đúng*. Trộn hai vai thì một thay đổi hợp đồng phải sửa ở hai chỗ, và cái sót lại nói dối.
+
+## 2 · Cấu trúc spec — AAA *(§5)*
+
+```typescript
+test('TC-API-001 — tạo booking hợp lệ trả 201', async ({ bookingAPI }) => {
+  const payload = validBooking;                    // Arrange
+  const res = await bookingAPI.create(payload);    // Act
+  expect(res.status()).toBe(201);                  // Assert
+  expect(await res.json()).toMatchObject({ id: expect.any(String) });
+});
+```
+
+- Header block mang **TC-ID** + `@trace.verifies` — thiếu là `BLOCKER` *(`R07`)*
+- Ba khối tách rõ; trộn assert vào giữa chuỗi gọi ⇒ `MINOR`
+- Data-driven bằng `for...of` / `test.each`, không chép test năm lần ⇒ `MINOR`
+
+## 3 · Assertion *(§6)*
+
+| Bắt buộc | Mức nếu thiếu |
+|---|---|
+| Assert **mã trạng thái** | `BLOCKER` |
+| Assert **cấu trúc + giá trị** của body, không chỉ status | `MAJOR` |
+| Kiểm schema cho response có cấu trúc *(`helpers/schema.helper.ts`)* | `MINOR` |
+| Assert header khi hợp đồng nêu | `MINOR` |
+
+`expect(res.ok()).toBeTruthy()` làm assertion **duy nhất** ⇒ `MAJOR` — nó đúng cho mọi 2xx/3xx,
+nên nó không phân biệt được thành công với chuyển hướng.
+
+## 4 · Async *(AGT-010 R02)*
+
+- **`waitForTimeout` tuyệt đối không dùng** ⇒ `BLOCKER`. API đồng bộ về bản chất: `await` thẳng.
+- Thiếu `await` trước lời gọi ⇒ `BLOCKER` — test kết thúc trước khi có response và **xanh giả**.
+
+## 5 · Dữ liệu *(AGT-010 R03)*
+
+- Credential · payload · giá trị mong đợi để ở `data/<resource>.data.ts` ⇒ hard-code là `MAJOR`
+- Token qua `fixtures/api.fixture.ts`, phân biệt **theo vai** ⇒ một token cho mọi test là `MAJOR`
+- Bản ghi tạo ra phải xoá ở `afterEach`/`afterAll`, kể cả khi test fail ⇒ thiếu là `MAJOR`
+
+## 6 · Đặt tên và đường dẫn
+
+```
+api-automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts
+api-automation/api/<resource>.api.ts        ← PHẲNG, dùng lại xuyên PRD
+api-automation/data/<resource>.data.ts
+api-automation/fixtures/api.fixture.ts
+api-automation/helpers/{schema,auth}.helper.ts
+```
+
+Dãy ID của lane này **độc lập** với web/mobile *(§7.3)*: `TS-API` · `SCN-API` · `TC-API` ·
+`AUT-API` · `TDS-API`.
+
+## 7 · Chất lượng *(§10 · §11)*
+
+- TypeScript strict, không `any` ⇒ `MINOR`
+- `test.only` sót lại ⇒ `BLOCKER` *(CI chạy một test rồi báo xanh)*
+- Test flaky phải mang tag `@flaky` và bị tách khỏi suite chính ⇒ không tag là `MAJOR`

package/core/skills/qc/qa-script-designer/_shared/file-naming-and-folders.md

@@ -0,0 +1,109 @@
+---
+version: 1.0
+updated: 2026-09-09
+new_in: post-review fix — trước đây `<project>` là placeholder không được định nghĩa, và
+  Page Object có 2 quy ước đặt tên mâu thuẫn nhau giữa các file
+---
+
+# Quy ước đặt tên & Folder — Automation Code (nguồn chuẩn duy nhất)
+
+Mọi file khác (`_shared/web-conventions.md`, `_shared/mobile-conventions.md`, `qc-design-script.md`,
+`qc-run-script.md`, mọi layer file trong `qa-script-designer/`, `qa-script-runner/`,
+`qa-reviewer/script/`) **tham chiếu file này** thay vì tự lặp lại quy ước path — sửa path chỉ
+sửa ở một chỗ.
+
+## 0. Vị trí repo (đã chốt)
+
+Automation code nằm trong **repo/module riêng** cho QC — tách biệt spec repo (`spec_source`)
+và repo product code. Root **KHÔNG khai bằng key cấu hình riêng** — nó lấy từ `§layout` của module
+đã phân giải ở `steps/qc-scope.md` §2b: `web`·`webview` → `automation/` · `system` → `api-automation/`
+· `app`·`app-ios`·`app-android` → `mobile-automation/`.
+
+> **Vì sao không có key riêng** *(quyết định `S-PATH`, 2026-09-17)*: `§layout` của module đã nói
+> gốc ở đâu. Thêm một key nữa là **hai nguồn cho một sự thật**; khi chúng lệch, artifact ghi vào
+> thư mục nền này còn script sinh theo layout nền kia — hỏng **im lặng**. Cùng lập luận đã dùng
+> khi bỏ `tech_stack.qc_module`.
+
+```
+automation/
+├── web/                          ← Playwright Test + TypeScript
+│   ├── tests/{TICKET-ID}/{feature-slug}.spec.ts
+│   ├── pages/{TICKET-ID}/{feature-slug}.page.ts
+│   ├── fixtures/                 ← client API/DB/Kafka dùng chung nhiều feature
+│   ├── playwright/.auth/{role}.json   ← storageState per-role (xem web-conventions.md §6.1)
+│   └── playwright.config.ts
+└── mobile/                       ← WebdriverIO + Appium + TypeScript
+    ├── test/specs/{TICKET-ID}/{feature-slug}.spec.ts
+    ├── pageobjects/{TICKET-ID}/{feature-slug}.page.ts
+    ├── fixtures/
+    └── wdio.conf.ts
+```
+
+`{TICKET-ID}` — **dùng lại đúng 2 giá trị đã resolve ở Gate Bước 1** khi target là
+UC-ID (cùng 2 segment đang dùng cho `{paths.specs_dir}/{TICKET-ID}/...`). Automation
+code tổ chức theo **cấu trúc sản phẩm** (domain/feature-package), không theo UC-ID — vì 1 file
+script thường phục vụ nhiều UC-ID cùng lúc (1 màn hình bị nhiều UC verify các khía cạnh khác
+nhau), nên tổ chức theo UC-ID sẽ ép phải chọn 1 UC "sở hữu" file trong khi thực tế không đúng.
+Đây là lý do automation code **KHÔNG** mirror cấu trúc `{paths.qc_dir}/{UC-ID}/...` (khác trục
+tổ chức, không phải thiếu sót).
+
+## 1. Chuyển đổi slug (bắt buộc, một chiều duy nhất)
+
+Nguồn gốc của mọi slug là `<FEATURE>` trong tên file thiết kế manual `TC_<FEATURE>.md`
+(qa-designer, UPPER_SNAKE_CASE, vd `TC_LOGIN.md`, `TC_STUDENT_ENROLLMENT.md`):
+
+| Ngữ cảnh | Transform | Ví dụ (từ `TC_LOGIN.md`) |
+|---|---|---|
+| Tên file script/spec | kebab-case, giữ nguyên | `login.spec.ts` |
+| Tên file Page Object | kebab-case + suffix `.page.ts` | `login.page.ts` |
+| Tên class Page Object | PascalCase + suffix `Page` | `LoginPage` |
+| Tag/tiêu đề test | giữ nguyên `TC_LOGIN_001` (từ TC ID gốc trong `.md`) | `test('TC_LOGIN_001 — ...', ...)` |
+
+**Một chiều duy nhất** — không suy ngược từ code ra `<FEATURE>`, luôn suy từ `TC_<FEATURE>.md`
+đã có sang code. Nếu chưa có TC file (chưa qua phase 3) thì chưa có gì để suy — không tự đặt
+tên trước.
+
+## 2. Nhiều UC cùng chạm 1 màn hình/feature (bắt buộc kiểm tra trước khi tạo file mới)
+
+Feature/màn hình có thể được nhiều UC-ID khác nhau verify các khía cạnh khác nhau (vd UC1
+"login thành công", UC2 "login khoá tài khoản" — cùng chạm màn Login). Trước khi tạo file mới
+ở phase 6 (`qc-design-script`):
+
+1. **Tìm Page Object đã tồn tại chưa** — glob
+   `automation/pages/{TICKET-ID}/*.page.ts` (hoặc mobile tương ứng)
+   theo cùng slug màn hình. Có rồi → tái sử dụng, **không tạo file PO thứ 2** cho cùng 1 màn.
+2. **Tìm file spec đã tồn tại chưa** cùng slug — nếu UC khác đã tạo `login.spec.ts` cho cùng
+   màn hình, **thêm `test.describe()` mới vào file đó** (nhóm theo UC nguồn, vd
+   `test.describe('UC2 — Login lockout', () => {...})`), không tạo file trùng lặp
+   (`login-2.spec.ts`, `login-uc2.spec.ts`…).
+3. Nếu `<FEATURE>` slug của 2 UC khác nhau nhưng cùng route/màn hình (do qa-designer đặt tên
+   khác nhau ở 2 lần chạy) → dùng slug của file **tạo trước** (kiểm tra tồn tại theo route,
+   không chỉ theo tên) để tránh phân mảnh; ghi chú lại trong report của `qc-design-script` nếu
+   phát hiện trường hợp này.
+
+## 3. Ví dụ đầy đủ — UC1 (domain `academic`, prd-slug `student-enrollment`, screen Login)
+
+```
+automation/
+├── tests/academic/student-enrollment/login.spec.ts     # @trace.verifies=UC1-SC1, UC2-SC1...
+├── pages/academic/student-enrollment/login.page.ts      # class LoginPage
+└── playwright/.auth/teacher.json
+```
+
+## 4. Vị trí file "hồ sơ" khác (không phải code) — không đổi so với trước
+
+`AUTOMATION_ASSESSMENT.md`, `TEST_DATA_PLAN.md`, `TESTABILITY_IMPROVEMENTS.md` vẫn ở
+`{paths.qc_dir}/{UC-ID}/{active_platform}/` như các phase 4/5/6 đã định — đây là hồ sơ **theo
+UC-ID** (đúng trục của chúng: đánh giá/dữ liệu/rào cản là quyết định gắn với 1 UC cụ thể tại 1
+thời điểm), khác với code (gắn với màn hình, dùng lại xuyên UC). Hai trục tổ chức khác nhau
+cho hai loại artifact khác nhau — không phải thiếu nhất quán.
+
+> **Trạng thái tích hợp sdd-framework — ĐÃ THI HÀNH** *(Bước S · S1, 2026-09-17)*. Module của stack cũ
+> — `qc-playwright` — đã **gỡ hẳn** *(quyết định `H2`)*, thay bằng hai module:
+> `qc-playwright-ts` *(nền `web` và `system` — hai `layout`, cùng một dãy phiên bản Playwright/TS)*
+> và `qc-wdio-appium` *(nền `app`)*. Không giữ bản deprecated nào: một hồ sơ stack cũ còn
+> sống trong `core/` là một cửa để nó quay lại.
+>
+> Ghi chú gốc của bộ đề xuất từng dự kiến khai tên module qua `tech_stack.qc_module`. **Không
+> làm vậy** — key đó chưa bao giờ tồn tại trong framework, và `active_platform` đã trả lời xong
+> câu "dùng module nào" ngay ở trạm 1.