@educa-corp/sdd-framework 0.9.6 → 0.9.8

package/docs/plans/qc-surgery/exec-S-ap-stack-typescript.md

@@ -0,0 +1,420 @@
+---
+buoc: Bước S (chen giữa Đợt 2 và Đợt 3)
+title: Áp stack đã chốt — TypeScript + Playwright / WDIO+Appium
+phu_thuoc: Đợt 2 xong (d2-b1, d2-b2, d2-b3)
+trang_thai: ✅ XONG 2026-09-17 — 6/6 việc · bốn lệnh kiểm XANH · R5 đỏ 27→0
+---
+
+# Bước S — Áp stack đã chốt lên ba trạm còn sinh mã sai
+
+← [`PLAN_v2.md`](PLAN_v2.md) · [`01-checklist.md`](01-checklist.md) · [`00-nhat-ky.md`](00-nhat-ky.md)
+
+| | |
+|---|---|
+| **Lớp** | chen giữa Đợt 2 và Đợt 3 — **CHẶN Đợt 3** |
+| **Bước** | **S/1** (một bước, một commit cho lớp lệnh) |
+| **File code** | `modules/qc-*` · `skills/qc/qa-script-{designer,runner}/` · `skills/qc/qa-reviewer/script/` · 3 `commands/qc-*-script.tmpl` |
+| **File test** | `test/run.js` — thêm **một guard cơ học** (xem B4 · G3) |
+| **Ngày xong** | — |
+| **Phụ thuộc** | Đợt 2 xong ✅ · 4 quyết định ở §1 **chốt 2026-09-17** ✅ |
+| **Ai dùng nó** | `/qc-design-script` · `/qc-run-script` · `/qc-review-script` · gián tiếp `/qc-report` (Đợt 3) |
+
+---
+
+## 0 · Đo lại trước — và PLAN_v2 dính đúng Bẫy 1 của chính nó
+
+> Luật ở [`PLAN_v2.md §5 Bẫy 1`](PLAN_v2.md): *"chạy lại mọi lệnh đếm trong kế hoạch trước khi
+> làm theo nó."* Chạy lại thì **3/6 con số trong §3 của PLAN_v2 sai** — lần thứ **tư** liên tiếp.
+
+| Nơi khai | PLAN_v2 §3 khai | Đo lại 2026-09-16 | Lệch |
+|---|---|---|---|
+| `skills/qc/qa-runner/` | 6 file · 44 KB | **8 file · 26,931 B (26.3 KB)** | +2 file · **−40 % dung lượng** |
+| đích `qa-script-designer/` *(proposal)* | 12 file · 88 KB | **14 file · 57,864 B (56.5 KB)** | +2 file · **−36 %** |
+| đích `qa-script-runner/` *(proposal)* | 4 file · 20 KB | 4 file · **13,445 B (13.1 KB)** | đúng số file · **−35 %** |
+| `modules/qc-playwright/` | 1 file · 66 dòng · thiếu `module.yaml` | ✅ **đúng y hệt** | — |
+| ngân sách | 1368 / 1450 KB | ✅ **1368, còn 82 KB** | — |
+| 4 lệnh kiểm | xanh · 244/244 | ✅ **244/244 PASS** | — |
+
+**Vì sao lệch quan trọng, không phải chuyện làm tròn:** con số 44 KB → 88 KB đọc như *"thay một
+bộ nhỏ bằng một bộ to gấp đôi"*. Số thật là **26 KB → 57 KB** — vẫn gấp đôi, nhưng **tổng khối
+lượng nhỏ hơn ước lượng ~30 KB**, và điều đó đổi câu trả lời cho H1: gánh cả web lẫn mobile trong
+một bước **rẻ hơn** so với bản kế hoạch mô tả.
+
+**Ba phát hiện mới, không có trong PLAN_v2:**
+
+| # | Phát hiện | Hệ quả |
+|:-:|---|---|
+| N1 | `active_platform` **đã có giá trị `system`** — `.agent/steps/qc-scope.md:9`, `bdd/system/` là hạng nhất trong `generate-bdd` | lane API **không phải trục thứ ba mới** — nó là **ô trống của một trục đã có**. Đổi hẳn câu trả lời §1.1 |
+| N2 | Ngân sách 1450 KB **chỉ đếm `core/commands/*.md`** (`test/run.js:697`) — skill **không** tính | thêm 57 KB skill **không** chạm ngân sách. Rủi ro ngân sách chỉ nằm ở **3 file lệnh** (25+27+21 = 73 KB) |
+| N3 | `docs/explain/18-qc-review.md` và `19-qc-run-test.md` **giải thích 2 lệnh đã bị tách bỏ từ Đợt 2** | **nợ độc lập mới** — chưa có trong PLAN_v2 §3 |
+
+---
+
+## 1 · BỐN CÂU — ĐÃ CHỐT 2026-09-17
+
+> Giữ nguyên cả phần bằng chứng và các phương án **không** được chọn. Sáu tháng nữa, câu hỏi
+> *"sao hồi đó không làm cách kia"* chỉ trả lời được nếu cách kia còn nằm đây.
+
+| Mã | Câu | Chốt | Ngày |
+|---|---|---|---|
+| **S-API** | Lane API là nền thứ ba hay layer của web? | **Nền thứ ba ở tầng SKILL, KHÔNG phải module thứ ba** | 09-17 |
+| **H1** | web + mobile cùng lúc hay web trước? | **B — cùng lúc (lệnh+module cả 3 lane), khác độ sâu (mobile port khung)** | 09-17 |
+| **H2** | gỡ hẳn `qc-playwright` hay giữ deprecated? | **Gỡ hẳn** | 09-17 |
+| **H3** | port `smoke.md` luôn? | **Không — để d4-b2** | 09-17 |
+
+### 1.1 · Lane API — nền thứ ba, hay một layer của web?  ✅ **nền thứ ba ở tầng skill**
+
+**Bằng chứng nghiêng về "nền thứ ba":**
+
+| # | Bằng chứng | Nguồn |
+|:-:|---|---|
+| a | Thư mục gốc **riêng**: `api-automation/` — *"tách biệt với `automation/` (web) — tránh xung đột config và dependency"* | `API-Testing-Standards.md` §2.1 |
+| b | `playwright.config.ts` **riêng**, `package.json` có thể riêng | §2.1 |
+| c | **API Object ≠ Page Object**: `BaseAPI`, 1 method = 1 endpoint, **không** `expect()` trong object | §4 · `AGT-010` §2.2 |
+| d | Dãy ID **độc lập**: `TC-API-001` ≠ `TC-001` *cùng một project* | §7.3 |
+| e | `AGT-010` là agent riêng, **Approved** (`AGT-005` mới Draft) | `AGT-010` header |
+| f | **`active_platform` đã có `system`** — `bdd/system/*.feature`, sổ trace `{UC}-system.tsv` | `qc-scope.md:9` **(N1)** |
+
+**Bằng chứng nghiêng về "layer của web":**
+
+| # | Bằng chứng | Nguồn |
+|:-:|---|---|
+| g | **Cùng stack**: Playwright + TypeScript + Playwright Test + `expect` — AD-API-001 nói rõ chọn Playwright API mode *"để giảm số tool, tái dùng infrastructure với Web testing"* | `API-Testing-Standards.md` §1 |
+| h | Bộ đề xuất **đã xếp API dưới web**: `qa-script-designer/web/functional/api.md` · `qa-reviewer/script/web/functional/api.md` | `qcframework_proposal/` |
+| i | Framework đã có `qa-designer/functional/api.md` + `qa-designer/api/*` (6 file) | `skills/qc/qa-designer/` |
+
+> 🔑 **Chỗ hai bên tưởng mâu thuẫn nhưng không.** (i) là tầng **thiết kế test case** — *"test cái
+> gì"*. Lane đang bàn là tầng **sinh mã** — *"code thế nào"*. Hai trục khác nhau, `qa-designer/`
+> **không bị đụng** dù chốt kiểu gì.
+
+**✅ CHỐT (09-17): nền thứ ba ở tầng SKILL, nhưng KHÔNG phải module thứ ba.**
+
+```
+active_platform          module                    skill lane
+─────────────────────────────────────────────────────────────────────────
+web · webview        →   qc-playwright-ts      →   qa-script-designer/web/*
+app · app-ios · …    →   qc-wdio-appium        →   qa-script-designer/mobile/*
+system               →   qc-playwright-ts      →   qa-script-designer/api/*
+                         (layout thứ hai:
+                          api-automation/)
+```
+
+Lý do: (c)(d)(e) làm **nội dung** khác hẳn → phải là file riêng; nhưng (g) làm **stack** y hệt
+→ dựng module thứ ba là chép hai lần cùng một dãy phiên bản `Playwright/TS v5.x`, và **hai bản
+của một sự thật là nơi drift sống** *(đúng lý do `qc-scope.md` ra đời)*. Còn (f) nói lane API
+không phải trục mới — nó lấp ô `system` mà **hôm nay đang hỏng im lặng**: chạy
+`/qc-design-script` trên một PRD `system` thì lệnh vẫn sinh Page Object + Python UI script.
+
+**Phương án KHÔNG chọn — "layer của web"** → bỏ `qa-script-designer/api/`, dồn vào
+`web/functional/api.md` + `_shared/api-conventions.md`; `active_platform=system` map về lane
+`web`. Rẻ hơn ~3 file, nhưng `api-automation/` (a) mất chỗ khai và ô `system` vẫn nhoè.
+
+**Phương án KHÔNG chọn — "module thứ ba đầy đủ"** (`modules/qc-playwright-api/`) → trung thành
+nhất với §2.1, nhưng dãy phiên bản `Playwright/TS v5.x` sống ở **hai** file.
+
+---
+
+### 1.2 · H1 — web + mobile cùng lúc, hay web trước?  ✅ **B**
+
+**Ràng buộc cứng, không phải sở thích** — [`PLAN_v2 §5 Bẫy 5`](PLAN_v2.md): tách được ≠ cái còn
+lại dùng được. Gỡ `qc-playwright` mà chỉ port lane web thì `/qc-design-script` trên PRD `app`
+**vẫn trỏ vào một module không còn tồn tại** — hỏng nặng hơn hôm nay.
+
+| Phương án | Phạm vi | Cái giá |
+|---|---|---|
+| **A · cùng lúc, cùng độ sâu** | 3 lane đầy đủ | to nhất; mobile chưa có dự án thật để thử |
+| **B · cùng lúc, khác độ sâu** ⭐ | **lớp lệnh + module: cả 3 lane**; **nội dung skill: web+api đầy đủ, mobile port khung `_shared/mobile-conventions.md` (12.7 KB) + 5 file lane** | mobile chưa được chạy thử thật — ghi rõ là hẹp *(§8 luật 4)* |
+| **C · web trước + chặn cứng** | chỉ web(+api); `/qc-design-script` **từ chối** khi `active_platform=app`, kèm câu báo rõ | commit nhỏ nhất, **không sai im lặng**; nhưng đội mobile bị khoá cửa và phải mở lại ở một bước sau |
+
+**✅ CHỐT (09-17): B.** Vì §0 đo được mobile chỉ là **12.7 KB `_shared` + 5 file lane ≈ 22 KB** —
+rẻ hơn con số 88 KB mà bản kế hoạch cũ dựng lên. **C** là phương án lùi hợp lệ nếu cần commit
+nhỏ; **A** bị loại vì viết sâu cho một nền chưa có dự án thật là viết hai lần.
+
+> 🔴 **Nghĩa vụ đi kèm B — phải ghi, không được quên.** Lane mobile port **khung**, chưa chạy
+> thử trên dự án thật. Theo [`PLAN_v2 §8 luật 4`](PLAN_v2.md) *("khai một phạm vi hẹp và nói rõ
+> là hẹp")*, `modules/qc-wdio-appium/module.yaml` phải mang một dòng khai đúng điều đó, và
+> `00-nhat-ky.md` phải có một dòng nợ: *"lane mobile chờ dự án thật để xác nhận"*.
+
+---
+
+### 1.3 · H2 — gỡ hẳn `qc-playwright` hay giữ deprecated 1 version?  ✅ **gỡ hẳn**
+
+**Bằng chứng:**
+- Tiền lệ **đã chốt 09-16**: `E3` — *"gỡ `/qc-review` ngay, không giữ cầu"*.
+- `bin/qc-base-map.json`: chỉ **3/82 entry** dính `qa-runner`, cả ba `targets: []`, `state: undecided`
+  → gỡ **không** làm đỏ `R16`.
+- Giữ deprecated nghĩa là `modules/qc-playwright/stack-profile.yaml` (66 dòng Python) **vẫn ở
+  trong `core/`** — và nó là **nguồn duy nhất** mà 3 lệnh trích dẫn. Hai stack-profile QC cùng
+  sống = guard ở B4 không bao giờ xanh được.
+
+**✅ CHỐT (09-17): gỡ hẳn.** Lịch sử đã nằm ở `qc-base-map.json` (snapshot `596149f`) và git.
+
+**Phương án KHÔNG chọn — "giữ 1 version"** → guard S0 phải thêm ngoại lệ đường dẫn, tức **cửa
+để Python quay lại**; và phải chốt thêm *"1 version"* là mốc nào, ai gỡ.
+
+---
+
+### 1.4 · H3 — port `qa-script-runner/smoke.md` luôn?  ✅ **không, để d4-b2**
+
+**Bằng chứng:** `smoke.md` = 5,895 B, thuộc `/qc-smoke-test` — lệnh của **d4-b2**, chưa tồn tại.
+Port bây giờ để lại một file **không lệnh nào nạp**. `bin/self-check.js:274` (R4) đã cảnh báo
+đúng lớp lỗi này cho key context; skill mồ côi thì **chưa có rule nào bắt** → nó sẽ nằm im.
+Mặt khác d4-b2 **đã hết chặn** (chị QC chốt tên 09-16) và trạm 6 đã gắn `@smoke` cho `P0`.
+
+**✅ CHỐT (09-17): KHÔNG port ở Bước S — để d4-b2**, và ghi một dòng nợ trỏ tới nó. Bước S đã là
+bước to nhất của cả đợt; thêm một file cho một lệnh chưa có là mở rộng phạm vi không có người
+dùng ở đầu kia.
+
+**Phương án KHÔNG chọn — "port luôn"** → +1 file · +5.9 KB, và d4-b2 rút ngắn còn viết lệnh.
+
+---
+
+# PHẦN A — Chuyện gì đang xảy ra
+*(cho người không làm kỹ thuật · đọc xong phần này là đủ hiểu)*
+
+## A1 · Vấn đề
+
+Đội QC đã chốt cách viết bài kiểm tra từ ngày 10/9 và xác nhận qua email. Từ hôm đó tới nay, bộ
+khung vẫn phát ra bài viết theo cách cũ — cách đã bị bỏ. Ai nhận cũng phải viết lại từ đầu, nên
+phần đáng lẽ được làm hộ trở thành phần phải dọn. Tệ hơn: không có gì báo sai. Mọi đèn kiểm đều
+xanh, nên nhìn từ ngoài vào thì trạm này vẫn đang chạy tốt.
+
+## A2 · Cách giải quyết, nói bằng một hình ảnh
+
+Như một xưởng in vẫn in bản đồ theo tên đường cũ sau khi thành phố đổi tên. Máy vẫn chạy, giấy
+vẫn đẹp, không ai báo hỏng — chỉ người cầm bản đồ đi mới lạc, và lạc xong thì tưởng mình đọc sai.
+Bước này thay **bản gốc trong máy**, một lần, cho cả ba loại bản đồ: web, điện thoại, dịch vụ.
+
+## A3 · Xong rồi thì thấy gì khác
+
+Chạy lệnh sinh script sẽ ra file đuôi `.spec.ts` thay vì `.py`, nằm trong `automation/` (web)
+hoặc `api-automation/` (dịch vụ), và lệnh **hỏi nền trước khi sinh** thay vì mặc định một nền.
+Thêm một đèn kiểm mới: nếu chữ "Python" quay lại chỗ nào trong bộ QC, đèn đó đỏ.
+
+## A4 · Thuật ngữ dùng ở trên
+
+- **stack** — bộ công cụ + ngôn ngữ mà test được viết bằng. Ở đây: TypeScript + Playwright (web, dịch vụ), WebdriverIO + Appium (điện thoại).
+- **script** — bài kiểm tra ở dạng máy chạy được, khác với bài kiểm tra viết cho người đọc rồi làm tay.
+- **nền / platform** — web · điện thoại · dịch vụ (`system`). Một lần chạy QC khoá đúng **một** nền.
+- **module** — hồ sơ khai stack của một loại dự án, để lệnh đọc mà biết sinh code theo kiểu nào.
+- **skill** — file hướng dẫn mà lệnh nạp lúc chạy; nội dung chi tiết nằm ở đây, không nằm trong lệnh.
+- **Page Object / API Object** — cách gom thao tác lên một màn hình / một endpoint vào một chỗ, để sửa một lần thay vì sửa khắp nơi.
+- **đèn kiểm / guard** — một phép kiểm tự động chạy sau mỗi lần sửa; đỏ thì không được commit.
+
+---
+
+> ### ✅ Phép thử bắt buộc trước khi coi Phần A là xong
+> **Đã thử với:** *(chưa — tự đọc to sau khi anh chốt §1, vì phạm vi đổi thì A3 đổi)* ·
+> **ngày:** — · **phải giải thích thêm chỗ nào:** —
+
+---
+
+# PHẦN B — Chi tiết kỹ thuật
+
+## B1 · Cách hiển nhiên là gì, và vì sao nó sai
+
+### Cách hiển nhiên 1 — tìm-thay chuỗi
+
+Đo được: **363 dòng khớp** `pytest|python|\.py` trong `skills/ commands/ core/ templates/ rules/
+bin/ docs/`, trải trên **47 file nguồn**. Cách hiển nhiên là thay `Python`→`TypeScript`,
+`pytest`→`Playwright Test`, `.py`→`.spec.ts` rồi chạy 4 lệnh kiểm.
+
+**Vì sao sai — cụ thể:** cái phải đổi **không phải từ vựng, là hình dạng**.
+
+| Thứ đổi theo stack | `pytest-playwright` (nay) | `@playwright/test` + TS (chốt) |
+|---|---|---|
+| Nơi test sống | `tests/<project>/test_<feature>.py` | `automation/tests/<feature>/<feature>-happy-path.spec.ts` |
+| Đối tượng | `pages/<feature>_page.py` · `BasePage` | `pages/<feature>.page.ts` — và **API lane dùng `api/<res>.api.ts` · `BaseAPI`, cấm `expect()` bên trong** |
+| Cách gom setup | `conftest.py` + fixture pytest | `fixtures/*.fixture.ts` |
+| Chạy | `python3 -m pytest` | `npx playwright test` |
+| Mobile | *(không có)* | WDIO v9 + Appium v2 + UiAutomator2 · **gesture helper** · **environment validation checklist** |
+
+Tìm-thay cho ra văn bản **đúng từ vựng TypeScript, đúng cấu trúc Python**. Và nó **qua cả 4 lệnh
+kiểm** — `build.js` chỉ đúc template, `self-check.js` R1–R22 không biết stack, `run.js` không có
+rule nào về stack QC, `lint-trace.js` soi sổ trace. Tức nó **vào được `main` với 244/244 xanh**,
+rồi vỡ ở lần chạy thật đầu tiên của chị QC, hai tuần sau, dưới dạng *"framework sinh code không
+chạy được"* — một câu không chỉ về đâu để sửa.
+
+### Cách hiển nhiên 2 — bê nguyên thư mục skill của bộ đề xuất
+
+`qcframework_proposal/skills/qc/qa-script-designer/` có sẵn 14 file đúng hình dạng cần. Cách
+hiển nhiên là copy cả cụm.
+
+**Vì sao sai:** bộ đề xuất **chỉ nói tên stack**; `qc-base-new/` là *Official Project Knowledge*,
+status **Approved**, và **ghim phiên bản cụ thể** (Appium v2.x · WebdriverIO v9.x · TypeScript
+v5.x · UiAutomator2) + §Anti-patterns + §Flaky Policy. Copy đề xuất = chốt một stack **không có
+số hiệu phiên bản** — đúng lớp lỗi mà `AD-API-001`/`AGT-010` sinh ra để chặn.
+
+**Luật chia nguồn** *(đã ghi ở [`PLAN_v2 §4.2`](PLAN_v2.md), nhắc lại vì đây là chỗ dễ trượt)*:
+**bố cục thư mục ← đề xuất · nội dung stack ← `qc-base-new/`.**
+
+## B2 · Cách làm đúng
+
+**Thứ tự bắt buộc — guard trước, vá sau** *(quyết định `G3`, 09-16)*.
+
+**S0 · Dựng đèn trước khi vá.** Thêm vào `test/run.js` một test: không dòng nào trong
+`skills/qc/**` · `commands/qc-*.tmpl` · `modules/qc-*/` khớp `pytest|python3?\b|\.py\b`.
+Chạy ngay → **đỏ với ~47 file**. Đó là bằng chứng đèn bắt được lỗi **đang sống**, không phải
+đèn viết sau khi đã sạch nên vĩnh viễn xanh.
+
+**S1 · Lớp module.** `modules/qc-playwright/` (1 file, 66 dòng, **thiếu `module.yaml`** — trong
+khi `react/` và `flutter/` đều có 2 file) → hai module, mỗi cái **đủ cặp**:
+
+| Module | `module.yaml` | `stack-profile.yaml` |
+|---|---|---|
+| `qc-playwright-ts` | `language: TypeScript` · `test_framework: "Playwright Test"` | `layout.web` = `automation/` · **`layout.api` = `api-automation/`** *(theo §1.1)* · locator priority · anti-patterns |
+| `qc-wdio-appium` | `language: TypeScript` · `test_framework: "WebdriverIO + Appium"` | `layout.mobile` · gesture helper · environment validation checklist |
+
+**S2 · Lớp skill.** `qa-runner/` **(8 file · 26.3 KB — bộ SINH MÃ Python, không phải "hướng dẫn
+chạy test"; xem [`PLAN_v2 §5 Bẫy 3`](PLAN_v2.md))** → gỡ, thay bằng:
+
+```
+qa-script-designer/
+  _shared/  web-conventions.md (16.5 KB) · mobile-conventions.md (12.7 KB) · file-naming-and-folders.md (7.3 KB)
+  web/      functional/{gui-screen,gui-feature,api}.md · integration.md · e2e.md · non-functional.md
+  mobile/   functional/{screen,feature}.md · integration.md · e2e.md · non-functional.md
+  api/      endpoint.md · auth.md · security.md            ← lane thứ ba (S-API ✅)
+qa-script-runner/
+  web/run.md · mobile/run.md · report.md                   ← smoke.md để d4-b2 (H3 ✅)
+```
+
+Nguồn nội dung 3 file `api/`: `API-Testing-Standards.md` §4 *(API Object)* · §5 *(Test Spec, AAA)*
+· §6 *(Assertion)* · §8 *(Test Design)* · §9 *(Security)*, cộng `AGT-010` §3 *(R01–R03)*.
+
+**S3 · `qa-reviewer/script/`** 5 file phẳng (22 KB) → `script/{web,mobile,api}/*` — thực thi
+`E1`, quyết định đã dời sang đây từ 09-16.
+
+**S4 · Lớp lệnh — 3 file, và đây là chỗ duy nhất chạm ngân sách.** `qc-design-script`
+`Role & stack` hiện **nhúng thẳng luật Python vào lệnh** (dòng 69–89 của `.tmpl`). Thay bằng
+**bảng phân giải nền + một con trỏ sang skill**:
+
+```
+active_platform → module → lane skill        (bảng 3 dòng, ~10 dòng văn bản)
+```
+
+**Con số và lý do:** 3 lệnh hiện **25 + 27 + 21 = 73 KB**; ngân sách còn **82 KB** và
+`test/run.js:697` **chỉ đếm `core/commands/*.md`** *(N2)* — nên 57 KB skill **không tính vào
+đây**. Kéo luật stack ra khỏi lệnh giúp 3 file **co lại**, và đó là cách duy nhất thêm lane thứ
+ba mà không ăn vào 82 KB còn lại.
+
+**S5 · Ăn theo.** `skills/qc/qa-automation-assess/matrix.md` (dòng 102–104 trỏ `qc-playwright`
+Python) · `commands/qc-report.tmpl` (5 dòng) · `bin/trace-schema.json` (4 dòng: 1477 · 2419 ·
+2422 · 2496) · `bin/qc-base-map.json` (3 entry `undecided` → `decided`) · 6 file `docs/`.
+
+## B3 · Nếu làm sai thì hỏng theo kiểu nào
+
+**Kiểu hỏng: Im lặng 🔴** *(và nó **đang** hỏng theo kiểu này ngay lúc này)*.
+
+Hỏng ở đâu: lệnh sinh ra file `.py` mà không dự án nào chạy được — hoặc tệ hơn, `.spec.ts` đúng
+từ vựng nhưng sai hình dạng thư mục nên `npx playwright test` không thấy file nào và báo
+**"0 tests"**, tức **xanh**. Ai phát hiện: chị QC, ở lần chạy thật đầu tiên. Sau bao lâu: đo được
+là **6 ngày và vẫn đang đếm** — stack chốt 09-10, hôm nay 09-16, 4 lệnh kiểm chưa đỏ một lần.
+
+## B4 · Verify bằng gì
+
+| # | Phép thử | Kết quả mong đợi |
+|:-:|---|---|
+| 1 | **S0 chạy TRƯỚC khi sửa** | **ĐỎ**, liệt kê ~47 file. Xanh ngay từ đầu = đèn viết sai, làm lại |
+| 2 | `grep -rniE 'pytest\|python' skills/ commands/ modules/` | **0** dòng (trừ `upstream/` và `docs/plans/`) |
+| 3 | `ls modules/qc-playwright-ts modules/qc-wdio-appium` | mỗi thư mục **đúng 2 file** — bằng `react/` và `flutter/` |
+| 4 | `ls modules/qc-playwright` | **không tồn tại** *(H2 ✅ gỡ hẳn)* |
+| 5 | 4 lệnh kiểm | `build` ✅ · `self-check` R1–R22 ✅ · `run.js` **245/245** (thêm S0) ✅ · `lint-trace` T1–T20 ✅ |
+| 6 | Ngân sách | `core/commands` **< 1450 KB**, và 3 lệnh script **≤ 73 KB** (không được phình) |
+| 7 | **Phá có chủ đích:** đặt `active_platform=system` rồi chạy `/qc-design-script` | trỏ đúng lane API + `api-automation/` — **không** ra Page Object. *(Hôm nay: ra Page Object Python.)* |
+| 8 | **Phá có chủ đích:** `active_platform=app` | trỏ `qc-wdio-appium` + lane mobile *(H1 ✅ B — lane có mặt, nội dung ở mức khung)* |
+| 9 | `node bin/self-check.js` sau khi sửa `qc-base-map.json` | **R16 không đỏ** — 3 entry `qa-runner` có `targets: []` nên gỡ file cục bộ không phá map |
+
+## B5 · Bài học
+
+- **2026-09-16** — PLAN_v2 §3 khai `qa-runner` **6 file · 44 KB**; đo lại: **8 file · 26.3 KB**. Đây là lần **thứ tư** một bản kế hoạch của đợt này mang số đã lỗi thời → nguyên nhân thật: số được chép từ bản kế hoạch trước chứ không đo lại. Sửa: §0 của mọi bước từ nay **bắt đầu bằng bảng đo lại**, kể cả khi bản trước vừa viết hôm qua.
+- **2026-09-16** — Tưởng ngân sách 1450 KB chặn việc thêm skill. Đọc `test/run.js:697`: nó **chỉ đếm `core/commands/*.md`**. Nguyên nhân thật: PLAN_v2 ghi *"ngân sách core/commands"* nhưng để nó cạnh các số toàn repo nên đọc thành *"cả bộ"*. Sửa: ghi rõ **phép đếm**, không chỉ tên thư mục.
+
+## B6 · Copy được / không copy được
+
+| | |
+|---|---|
+| ✅ **Copy được sang dự án khác** | Thứ tự **guard-trước-vá-sau** (`G3`); tách **bố cục ← đề xuất / nội dung ← tài liệu Approved**; luật *"một lệnh phải đổi cho mọi nền nó với tới, trong một commit"* (Bẫy 5); đo lại số trước khi làm theo kế hoạch (Bẫy 1) |
+| ⚠️ **Chỉ đúng ở đây** | Tên `web`/`app`/`system` và cách `qc-scope.md` khoá một nền; ngưỡng 1450 KB và phép đếm của nó; ba lane gắn với `TestingOS` của chị QC; tài liệu nguồn tiếng Việt |
+
+## B7 · Link
+
+- [`PLAN_v2.md`](PLAN_v2.md) — §3 *(thứ tự)* · §4 *(nguồn)* · §5 *(bẫy)* · §6 *(4 câu này)* · §7 `E1`·`E3`·`G3`
+- [`exec-d2-b1-tach-qc-review.md`](exec-d2-b1-tach-qc-review.md) — §3.3, phần `E1` dời sang đây
+- [`exec-d2-b2-tach-qc-run-test-atomic.md`](exec-d2-b2-tach-qc-run-test-atomic.md) — §4.4, chỗ khai sai bản chất `qa-runner` (Bẫy 3)
+- [`exec-d3-b1-qc-report-gate-decision.md`](exec-d3-b1-qc-report-gate-decision.md) — bước **bị chặn** bởi bước này
+- `upstream/qc-base-new/` — `Automation-Standards.md` · `Mobile-Automation-Standards.md` · `API-Testing-Standards.md` · `AGT-005` · `AGT-006` · `AGT-010`
+
+---
+
+## 8 · Phạm vi đã khoá — thứ tự triển khai
+
+> 🔄 **Thứ tự đổi 2026-09-17 (`S-ORDER`): S0 → S1 → S5 → S3 → S2 → S4.**
+> Đo được: **16/18 file đỏ không có phụ thuộc nào** — chỉ **S4** bị ép *(cần S2+S3)*. Thứ tự
+> đánh số 2·3·4·5 là thói quen, không phải ràng buộc. Ba lý do đổi:
+> **①** S5 chỉ ~10 dòng và **đã được S1 quyết định hết**, lại **chứa một bug thật**
+> *(`qc-design-test.tmpl:151` còn trỏ `/qc-review` — lệnh đã gỡ ở `E3`)*.
+> **②** S3 trước S2 là `G3` áp ở tầng nội dung: **viết tiêu chí review trước, viết bộ sinh sau**
+> — ngược lại thì tiêu chí bị nắn theo thứ bộ sinh vừa đẻ ra, mất đối chứng độc lập.
+> **③** Đứt session giữa chừng thì mất ít hơn.
+> Phạm vi **không đổi** — vẫn 6 việc, vẫn cùng nội dung.
+
+Sau khi chốt 4 câu, Bước S là **6 việc**.
+
+| # | Việc | Kích thước đo được | Commit |
+|:-:|---|---|:-:|
+| **S0** ✅ | Guard cơ học — **6 entry `forbidden_patterns` có `scope`, chạy qua R5 sẵn có**. **ĐÃ LÀM 09-17**: đỏ **19 file** *(G3)*. Bản trình bày: [`exec-S0`](exec-S0-guard-cam-stack-cu.md) | `test/run.js` **không đổi** — vẫn 244 | 1 |
+| **S1** ✅ | `modules/qc-playwright/` **gỡ** → `qc-playwright-ts` *(layout `web` + `api`)* + `qc-wdio-appium`, mỗi cái đủ `module.yaml` + `stack-profile.yaml` | 1 file → 4 file | 2 |
+| **S2** ✅ | `qa-runner/` (8 file · 26.3 KB) **gỡ** → `qa-script-designer/` *(web+api đầy đủ, mobile khung)* + `qa-script-runner/` *(3 file)* | 26 KB → ~57 KB skill · **không chạm ngân sách** *(N2)* | 2 |
+| **S3** ✅ | `qa-reviewer/script/` 5 file phẳng → **XOÁ, viết mới** `script/{web,mobile,api}/*` — thực thi `E1` | 22 KB, **viết lại** *(xem §8.1)* | 2 |
+| **S4** ✅ | 2 lệnh: gỡ bảng `testid_attr` trùng bản + 6 dòng cuối → **bảng phân giải nền + con trỏ skill** | 73 KB → **phải ≤ 73 KB** | 2 |
+| **S5** ✅ | Ăn theo: `matrix.md` · `qc-report.tmpl` · `trace-schema.json` *(4 dòng)* · `qc-base-map.json` *(3 entry)* · 6 `docs/` | ~15 chỗ | 2 |
+
+### 8.1 · Vì sao S3 là **viết lại**, không phải sửa — và vì sao chỉ S3
+
+Câu hỏi *"sao không bỏ hết code Python của QC rồi xây lại từ đầu"* (09-17) được đo và trả lời
+bằng số:
+
+| Đo | Kết quả |
+|---|---|
+| Tỉ lệ nhiễm của `skills/qc/` | **112 / 5320 dòng = 2,1 %** |
+| Phần **thật sự là Python** | `modules/qc-playwright/` + `qa-runner/` = **9 file** → **đã xoá hẳn** ở S1/S2 |
+| 9 file nhiễm nhẹ nhất *(qa-designer · qa-planner · qa-reviewer/test-case · shared)* | cộng lại **18 dòng**, trong các file dài 120–272 dòng mà 98 % nội dung **không phụ thuộc ngôn ngữ** |
+| `qa-reviewer/script/non-functional.md` · `functional.md` | **11,2 %** và **9,2 %** ← ngưỡng khác hẳn |
+
+**S3 đổi vì mật độ, không vì nguyên tắc.** Tái bố cục một file sai stack 10 % *dưới cái tên
+"sửa"* dẫn thẳng vào bẫy B1: người viết giữ khung cũ và chỉ đổi chữ. Nên: **xoá 5 file, viết mới**
+từ `Automation-Standards` §10 · `Mobile-Automation-Standards` · `API-Testing-Standards` §10 ·
+`AGT-006` *(có sẵn scoring rules)*. Giữ lại đúng một thứ: **cấu trúc mục của
+`review-check-groups.md`**, để hai bên còn khớp.
+
+**Vì sao KHÔNG xây lại cả `skills/qc/`** — nguồn không phủ đủ, và đã đo:
+
+- `qc-base-new/` **7 file** tự khai trong header là **L4 Execution** + **L5 Governance**. Không
+  có file nào cho phân tích yêu cầu · doc-gap · test plan · thiết kế TC · review TC — **4 trạm
+  đầu**, và cả 4 đang **✅ đủ** theo §2.
+- `qcframework_proposal/` cắt **2026-09-10**, mà nó **đã chứa** công của đợt này (`testid_attr`
+  7 file · `self-review-principles` 8 file · `script-bug`/`product-gap` · §4.5.6) → **bản phái
+  sinh của chính framework**, không phải nguồn độc lập. Xây lại từ nó là mất 6 ngày sửa: 24 GAP
+  lane QC *(`dfe5bd5`)* · R17/R18/T19 · T20/R8f *(`02642bd`)* · G84 · G86+G87 · 0.9.6 · 0.9.7.
+
+Đổi **18 dòng sửa tay** lấy **42 file sạch + 6 ngày sửa lỗi** là lỗ. Đổi **5 file mật độ ~10 %**
+lấy một bản viết theo chuẩn Approved là lãi.
+
+---
+
+**Vì sao hai commit chứ không một.** S0 **phải đỏ** — đó là bằng chứng của `G3`. Một commit đỏ
+là vi phạm [`§8 luật 1`](PLAN_v2.md). Nên S0 vào commit 1 **cùng với** một dòng `skip` có ghi lý
+do và hạn *(gỡ ở commit 2)*; hoặc S0 và S1–S5 gộp làm một commit và bằng chứng đỏ được ghi lại
+trong `buoc/` thay vì trong lịch sử git. **Cách 2 gọn hơn và tôi đề xuất cách 2** — bằng chứng
+đỏ chụp vào nhật ký bước, cây git vẫn xanh suốt.
+
+**Bốn quyết định này vào [`PLAN_v2 §7`](PLAN_v2.md) với mã `S-API` · `H1` · `H2` · `H3`, và ra
+khỏi §6.**
+
+---
+
+## 9 · Nợ độc lập phát hiện thêm ở bước này *(không làm trong Bước S)*
+
+| Việc | Đo được |
+|---|---|
+| `docs/explain/18-qc-review.md` · `19-qc-run-test.md` giải thích **2 lệnh đã bị tách bỏ ở Đợt 2** | `commands/` không còn `qc-review.tmpl` · `qc-run-test.tmpl`; `docs/explain/` chưa có file cho 5 lệnh mới **(N3)** |