@educa-corp/sdd-framework 0.9.7 → 0.9.8

package/docs/02-concepts/pipeline-steps/08-qc-automation.md

@@ -3,13 +3,13 @@
 # Bước 8 · QC Automation — Dây chuyền kiểm thử 6 trạm (QC Pipeline)
 
 > **Tóm tắt.** Dây chuyền QC tự động 6 trạm: phân rã yêu cầu → lập kế hoạch → thiết kế test case → review → chạy Playwright → report. Ghi `qc_status` **chính thức** + evidence.
-> **Commands:** `/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review-testcase` → `/qc-design-script` → `/qc-run-script` → `/qc-review-script` → `/qc-report`
+> **Commands:** `/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review-testcase` → `/qc-automation-assess` → `/qc-design-script` → `/qc-review-script` → `/qc-run-script` → `/qc-report`
 
 | | |
 |---|---|
 | **Giai đoạn** | QC Automation |
 | **Owner** | 👤 QA / Tester |
-| **Đầu vào** | **Trạm 1–4:** spec (PRD/BDD `approved`) + **hợp đồng test-id §4.5.6** (đóng băng ở bước 5) — **chưa cần code**.<br/>**Trạm 5 `/qc-design-script` → `/qc-run-script` thêm:** code đã chạy được — **trạm duy nhất** cần |
+| **Đầu vào** | **Trạm 1–4:** spec (PRD/BDD `approved`) + **hợp đồng test-id §4.5.6** (đóng băng ở bước 5) — **chưa cần code**.<br/>**Trạm 6–8 `/qc-design-script` · `/qc-run-script` thêm:** code đã chạy được — **hai trạm duy nhất** cần |
 | **Đầu ra** | Test case, script Playwright, `qc_status`, evidence, product-gap |
 | **HITL** | 🟠 Vừa — cổng review case & script trước khi chạy |
 
@@ -17,11 +17,11 @@
 
 ## Mục đích (Purpose)
 
-Đây là **kiểm thử chính thức** (khác với dev smoke). Dùng module **`qc-playwright`** (Python + pytest-playwright + Page Object) — độc lập với module implementation của dev. Bước này:
+Đây là **kiểm thử chính thức** (khác với dev smoke). Dùng module QC theo nền — **`qc-playwright-ts`** (web·system) hoặc **`qc-wdio-appium`** (app), phân giải ở `steps/qc-scope.md` §2b — độc lập với module implementation của dev. Bước này:
 
 - Phân rã yêu cầu thành test case bám scenario, phát hiện **gap tài liệu**.
 - Chạy test thật, ghi **`qc_status` chính thức** + **evidence**.
-  ⚠️ Nhưng `/qc-design-script` → `/qc-run-script` **đọc cột `status` trước khi ghi `pass`** *(GAPS-v4 G55)*: row `DRIFT`/`ORPHANED` + test xanh → hạ về `not_run`, và **không** đóng bug nào ở lần chạy đó. `fail`/`skip` ghi bình thường.
+  ⚠️ Nhưng `/qc-run-script` và `/qc-run-manualtest` **đọc cột `status` trước khi ghi `pass`** *(GAPS-v4 G55)*: row `DRIFT`/`ORPHANED` + test xanh → hạ về `not_run`, và **không** đóng bug nào ở lần chạy đó. `fail`/`skip` ghi bình thường.
 - Phân loại FAIL thành **ba** nhãn — `script-bug` · `product-gap` · `flaky` — **sau khi đã chạy lại tối đa 2 lần**. Một test đỏ **một lần** chưa nói được nó đỏ vì cái gì.
 - Đẩy **product-gap** ngược về PO/Dev.
 
@@ -32,15 +32,15 @@
 - **UC-ID** + platform (QC pass khoá 1 platform).
 - Spec: PRD / `.feature` (từ spec repo, qua `spec_source`).
 - **Hợp đồng test-id**: `@trace.testid_attr` (header tech-doc, **tên** thuộc tính) + §4.5.6 Test Selectors (**giá trị** test-id, cột *Serves SC* là chỉ mục ngược). Đã chốt ở [bước 5](05-tech-docs.md) **trước khi có code**.
-- Code đã sinh & chạy được — **chỉ `/qc-design-script` → `/qc-run-script` cần**. Bốn trạm đầu (`/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review-testcase`) chạy **song song với FE** vì chỉ cần spec + hợp đồng test-id. Đó là chỗ hai nhánh của [bước 5](05-tech-docs.md) gặp lại.
-- `qc_dir` (working docs của QC) + module `qc-playwright`.
+- Code đã sinh & chạy được — **chỉ `/qc-design-script` và `/qc-run-script` cần**. Bốn trạm đầu (`/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review-testcase`) chạy **song song với FE** vì chỉ cần spec + hợp đồng test-id. Đó là chỗ hai nhánh của [bước 5](05-tech-docs.md) gặp lại.
+- `qc_dir` (working docs của QC) + module QC theo nền (`qc-playwright-ts` · `qc-wdio-appium`).
 
 ## Output (Đầu ra)
 
 | Artifact | Nội dung |
 |----------|----------|
 | `docs/{TICKET-ID}/{platform}/…` | `REQUIREMENT_ANALYSIS.md`, `DOC_GAP.md`, `TEST_PLAN.md`, `test-cases/*.Test.md` — **mỗi loại đúng một file cho cả (PRD × nền)**, các UC là hàng/mục bên trong (cột `UC`) |
-| Script Python pytest-playwright | Sinh từ `.Test.md` đã review |
+| Script TypeScript (`*.spec.ts`) | Sinh từ `.Test.md` đã review |
 | Cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` | Trạng thái QC **chính thức** |
 | Evidence + report | `/qc-report` — kèm product-gap đẩy về PO/Dev |
 
@@ -77,7 +77,7 @@ Dây chuyền **6 trạm**, output trạm trước là input trạm sau:
 | 3 | `/qc-design-test` | Thiết kế **test case** dạng Markdown (`*.Test.md`) | **Guard SC coverage** |
 | 4 | `/qc-review-testcase` | 🛑 **Cổng review test case** — verdict `APPROVED`/`NEEDS_FIX` là điều kiện tiên quyết của trạm sau | — |
 | 6 | `/qc-review-script` | 🛑 **Cổng review script** — biên bản riêng `REVIEW_SCRIPT_<FEATURE>.md` | — |
-| 5 | `/qc-design-script` → `/qc-run-script` | Sinh & chạy **pytest-playwright**, ghi **`qc_status`** chính thức | **chạy lại ×2 + 3 nhãn FAIL** |
+| 5–8 | `/qc-design-script` · `/qc-run-script` | Sinh rồi chạy **script TypeScript**, ghi **`qc_status`** chính thức | **chạy lại ×2 + 3 nhãn FAIL** |
 | 6 | `/qc-report` | Report + **evidence**, đẩy **product-gap** về PO/Dev | — |
 
 ### Hai Guard cơ học — chống bỏ sót **im lặng**
@@ -121,7 +121,7 @@ Cả sáu trạm nạp chung `skills/qc/_shared/self-review-principles.md` và c
 
 > ⚠️ **Self-review KHÔNG thay Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**. Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một guard — file đó ghi rõ ranh giới này ngay ở đầu.
 
-- Stack QC bắt buộc theo `modules/qc-playwright/stack-profile.yaml`: Python + pytest-playwright + Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+- Stack QC bắt buộc theo `stack-profile.yaml` của module đã phân giải (§2b): TypeScript + Playwright Test (web·system) / WebdriverIO + Appium (app); mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
 - **Locator lấy từ hợp đồng, không dò DOM**: thứ tự ưu tiên là §4.5.6 → `@trace.testid_attr` → mới tới các cách khác. Skill `qa-runner` đã bỏ hết chỉ dẫn "dò DOM trước".
 
 ---
@@ -138,7 +138,7 @@ Cả sáu trạm nạp chung `skills/qc/_shared/self-review-principles.md` và c
 
 - ❌ Lẫn `qc_status` với `dev_selftest` — hai trục độc lập.
 - ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
-- ❌ Chạy `/qc-design-script` → `/qc-run-script` khi chưa qua cổng `/qc-review-testcase`.
+- ❌ Chạy `/qc-design-script` khi chưa qua cổng `/qc-review-testcase`.
 - ❌ **Kết luận từ một lần chạy đỏ** — chưa loại nhiễu thì chưa phân biệt được `flaky` với lỗi thật.
 - ❌ **Tự dò selector từ DOM** thay vì đọc §4.5.6 — script giòn, dev đổi một class là vỡ mà không ai báo.
 - ❌ Dùng self-review làm lý do **bỏ qua** một Guard.

package/docs/02-concepts/pipeline-steps/10-feedback-loop.md

@@ -98,7 +98,7 @@ Framework là pipeline **một chiều** — nhưng vẫn cần đường **ph
 |---|---|---|
 | `🟢 Open` | `/report-bug` | tester/QC file bug |
 | `🟡 Fixed` | `/fix-bug` Phase 5.5 | fix đã commit + push |
-| `🟢 Closed` | **`/qc-design-script` → `/qc-run-script`** | QC chạy lại và `qc_status` của SC liên kết flip `pass` |
+| `🟢 Closed` | **`/qc-run-script`** | QC chạy lại và `qc_status` của SC liên kết flip `pass` |
 
 > **Dev không tự đóng bug của mình** — QC sở hữu verification. `/qc-run-script` đọc `qc_blocked_by` **trước** khi clear nó (cột đó chính là con trỏ tới bug; clear xong là mất đường về).
 >

package/docs/02-concepts/traceability.md

@@ -42,7 +42,7 @@ Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag expl
 | `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
 | `implemented_by` | `/generate-code` | File code hiện thực SC |
 | `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
-| `qc_status` | `/qc-design-script` → `/qc-run-script`, `/report-bug`, **`/map-testids`** | Trạng thái QC **chính thức** (Playwright). `/map-testids` **chỉ hạ về `not_run`**, không bao giờ ghi giá trị khẳng định — xem ô "Làm mất hiệu lực" dưới |
+| `qc_status` | `/qc-run-script` + `/qc-run-manualtest`, `/report-bug`, **`/map-testids`** | Trạng thái QC **chính thức** (Playwright). `/map-testids` **chỉ hạ về `not_run`**, không bao giờ ghi giá trị khẳng định — xem ô "Làm mất hiệu lực" dưới |
 | `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
 | `service` *(cột 23)* | `/generate-bdd` | Đội/submodule sở hữu SC — nguồn của `by_service` trên dashboard |
 | `design_spec_version` *(cột 24)* | `/generate-bdd` | Version design-spec lúc sinh BDD *(FE/App; `—` cho backend)* |

package/docs/03-guides/developer.md

@@ -88,7 +88,7 @@ public TokenDto login(...) { }
 - ❌ Để AI tự review code nó vừa sinh.
 - ❌ Tạo PR khi `/validate-traces` còn cờ 🔴 (`SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`) — build xanh không chứng minh luồng ghép chạy đúng.
 - ❌ Coi FE `fe_phase = ui` là xong vì status đã `OK` — test đang chạy trên **mock**.
-- ❌ Tự đóng bug mình vừa fix — `/fix-bug` chỉ đặt `🟡 Fixed`; `🟢 Closed` là của `/qc-design-script` → `/qc-run-script`.
+- ❌ Tự đóng bug mình vừa fix — `/fix-bug` chỉ đặt `🟡 Fixed`; `🟢 Closed` là của `/qc-run-script`.
 
 ---
 

package/docs/03-guides/tester-qa.md

@@ -9,14 +9,39 @@
 ## Chuỗi bước của bạn (Your path)
 
 ```mermaid
-flowchart LR
-    M["§4.5.6 đã chốt<br/>(/map-testids, bước 5)"] --> A
-    A["/qc-analyze<br/>Guard BR-tag"] --> P["/qc-plan"] --> D["/qc-design-test<br/>Guard SC coverage"]
-    D --> R["/qc-review-testcase<br/>🛑 cổng"] --> RUN["/qc-run-script<br/>chạy lại ×2 · 3 nhãn<br/>ghi qc_status"] --> RS["/qc-review-script<br/>🛑 cổng"] --> REP["/qc-report<br/>product-gap"]
+flowchart TD
+    M["§4.5.6 đã chốt — /map-testids, bước 5"] --> A
+
+    A["1 · /qc-analyze 🛑<br/>Guard BR-tag"] --> P["2 · /qc-plan"]
+    P --> D["3 · /qc-design-test 🛑<br/>Guard SC coverage"]
+    D --> R["4 · /qc-review-testcase<br/>Verdict: APPROVED / NEEDS_FIX"]
+    R -- NEEDS_FIX --> D
+    R -- APPROVED --> AS["5 · /qc-automation-assess 🛑<br/>Automatable Y/N + nhãn lý do<br/>%Automated/Total"]
+
+    AS -- "Automatable: Y" --> DS["6 · /qc-design-script 🛑<br/>sinh script · điền cột Script file"]
+    AS -- "Automatable: N" --> MT["8b · /qc-run-manualtest<br/>hỏi TỪNG TC · ghi NGAY từng câu"]
+
+    DS --> RS["7 · /qc-review-script<br/>Verdict: APPROVED / NEEDS_FIX"]
+    RS -- NEEDS_FIX --> DS
+    RS -- APPROVED --> RUN["8 · /qc-run-script<br/>đọc cột Script file<br/>chạy lại ×2 · 3 nhãn<br/>đóng bug 🟡 → 🟢"]
+
+    RUN -- "ghi qc_status" --> TSV[("sổ trace<br/>UC-ID-platform.tsv")]
+    MT  -- "ghi qc_status" --> TSV
+    TSV --> REP["9 · /qc-report<br/>product-gap"]
+
     REP --> FB["/report-bug · /propose-scenario"]
     FB --> SYNC["/sync"]
 ```
 
+> **Hai nhánh gặp lại ở SỔ TRACE.** TC máy chạy được đi nhánh `Y` (trạm 6→7→8); TC phải chạy tay
+> đi thẳng sang **8b**. Cả hai ghi vào **cùng một cột `qc_status`** — đó là lý do `/qc-report` đọc
+> được **một** con số coverage cho cả hai. Không có trạm 8b thì mọi TC `Automatable: N` nằm
+> `not_run` vĩnh viễn và report chấm cả PRD là **FAIL**, không cách nào sửa.
+
+> **🛑 = chặn CỨNG (`--yes` không bỏ qua được) — nhưng cả bốn đều chỉ nổ khi ĐÃ CÓ THỨ ĐỂ MẤT:**
+> `DOC_GAP.md` / `.Test.md` / bảng đánh giá / file script **đã tồn tại**. Chạy một lượt đầu trọn
+> vẹn: **0 cổng cứng nổ**.
+
 > **Ba trạm đầu KHÔNG chờ code.** Hợp đồng test-id (§4.5.6) được chốt ở bước Tech-Docs, **trước** `/generate-code`. Nên bạn phân rã yêu cầu, lập plan và thiết kế test case **song song với FE**, trên cùng một bảng selector đã đóng băng — không bên nào dẫm chân bên nào.
 
 ---
@@ -28,9 +53,12 @@ flowchart LR
 | [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu**. **Guard BR-tag** đối chiếu rule BDD đã gắn tag ↔ rule bạn phân tích ra; thiếu thì tự bổ sung từ PRD và in danh sách |
 | `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
 | `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`). **Guard SC coverage** bắt mọi scenario trong phạm vi phải có ≥1 TC — **không có đường thoát**: SC bị gap chặn thì TC **vẫn viết đủ**, mang dấu `🚫 Block` |
-| `/qc-review-testcase` | 🛑 **Cổng review test case** — trước khi chạy |
-| `/qc-review-script` | 🛑 **Cổng review script** — sau khi sinh script |
-| `/qc-design-script` → `/qc-run-script` | Chạy pytest-playwright, ghi **`qc_status`**; **chạy lại tối đa 2 lần rồi mới phân loại FAIL thành 3 nhãn** (`script-bug` · `product-gap` · `flaky`), và **bạn xác nhận nhãn** trước khi lệnh ghi trace. **Đọc cột `status` trước khi ghi `pass`** — row `DRIFT`/`ORPHANED` + test xanh → `not_run`, và **không đóng bug nào** ở lần chạy đó *(đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai)* |
+| `/qc-review-testcase` | **Cổng review test case.** Ghi `**Verdict:** APPROVED`/`NEEDS_FIX` — trạm sau ĐỌC dòng này, nên nó là contract chứ không phải định dạng cho đẹp |
+| `/qc-automation-assess` | Quyết định **cái nào máy chạy, cái nào phải tay** — `Automatable: Y/N` kèm **nhãn lý do chuẩn hoá** (để đếm được: *"3 TC vì thiếu test-id"* hành động được, *"3 TC vì lý do kỹ thuật"* thì không). Ra `%Automated/Total`. TC của UC chưa `APPROVED` bị **loại khỏi lượt và liệt kê ra** — mẫu số chỉ gồm TC đã xét |
+| `/qc-design-script` | Sinh script **chỉ cho `Automatable: Y`**, gắn tag `@smoke`/`@regression` theo `Priority`, rồi **điền cột `Script file`** — chỉ mục ngược duy nhất TC → file code |
+| `/qc-review-script` | **Cổng review script** — biên bản **riêng** `REVIEW_SCRIPT_<FEATURE>.md`, không chung file với cổng test case |
+| `/qc-run-manualtest` | Chạy tay TC `Automatable: N`. Lệnh **hỏi từng TC** và **ghi ngay sau mỗi câu trả lời** *(chạy lại thì tự resume)* — không đọc file checklist, vì một file điền tay là nguồn thứ hai có thể trôi. `pass` **bắt buộc kèm bằng chứng** vào `MANUAL_EVIDENCE.md` |
+| `/qc-run-script` | **Đọc cột `Script file`** để biết chạy file nào — không tự suy đường dẫn. Chạy script TypeScript, ghi **`qc_status`**; **chạy lại tối đa 2 lần rồi mới phân loại FAIL thành 3 nhãn** (`script-bug` · `product-gap` · `flaky`), và **bạn xác nhận nhãn** trước khi lệnh ghi trace. **Đọc cột `status` trước khi ghi `pass`** — row `DRIFT`/`ORPHANED` + test xanh → `not_run`, và **không đóng bug nào** ở lần chạy đó *(đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai)* |
 | `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
 | [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
 
@@ -45,12 +73,12 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
    - **Một lần đỏ chưa đủ để kết luận.** Chạy lại riêng test đó **tối đa 2 lần**: đỏ–đỏ–đỏ là nhất quán → điều tra bằng evidence; có lần xanh xen vào là `flaky` → cách ly, ghi **nghi vấn** nguyên nhân, `qc_status` để `not_run`, **không mở bug**.
    - Đây **không** phải `retries` trong config runner. `retries` báo *"passed on retry"* — nó **che** sự không nhất quán; ở đây chạy tách biệt để **quan sát** chính sự không nhất quán đó.
    - Không chắc giữa `script-bug` và `product-gap` → **mời Dev cùng xem trace**, đừng đoán cho xong.
-3. **Không chạy test kém** — phải qua cổng `/qc-review-testcase` trước `/qc-design-script` → `/qc-run-script`.
+3. **Không chạy test kém** — phải qua cổng `/qc-review-testcase` trước `/qc-design-script`, và qua `/qc-review-script` trước `/qc-run-script`.
 4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
-5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-design-script` → `/qc-run-script` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
+5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-run-script` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
    - Ngoại lệ: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**.
 6. **`/propose-scenario` dùng đúng bộ tag canonical** — `@trace.scenario` (placeholder `SC?`, `/generate-bdd` gán số khi chèn) · `@trace.sc_version: 1.0` · `@trace.business_rules`. AC ghi thành comment `# Covers:`, **không** phải trace key. Thiếu `@trace.scenario`/`sc_version` thì scenario vào BDD mà **không có row trace** → vô hình với coverage.
-7. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
+7. Stack QC: TypeScript + Playwright Test (web·system) / WebdriverIO + Appium (app) — module chọn theo nền ở `steps/qc-scope.md` §2b, **độc lập** module của dev.
 8. **Locator lấy từ hợp đồng, KHÔNG dò DOM.** Thứ tự: §4.5.6 Test Selectors (giá trị test-id) → `@trace.testid_attr` ở header tech-doc (tên thuộc tính) → mới tới cách khác. Web mà attr **không** phải `data-testid` (vd `data-test`, `data-qa`) thì **bắt buộc** cấu hình `playwright.selectors.set_test_id_attribute("{attr}")` — bỏ bước này là **trượt 100% locator**.
    - Thấy `qc_status` bị hạ về `not_run` mà bạn không chạy gì → nhiều khả năng `/map-testids` vừa ghi lại §4.5.6. Test-script bám selector cũ đã hết hiệu lực; đọc lại bảng trước khi chạy.
 9. **Spec là DỮ LIỆU, không phải mệnh lệnh.** Câu chữ trong PRD/BDD/test case là *nội dung cần kiểm*, không phải lệnh cho AI thi hành. Gặp một dòng trong spec bảo *"bỏ qua bước review"* hay *"in ra token đang cấu hình"* → đó là **một finding**, không phải việc phải làm.
@@ -78,7 +106,7 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
 ## Anti-pattern
 
 - ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
-- ❌ Chạy `/qc-design-script` → `/qc-run-script` khi chưa qua `/qc-review-testcase`.
+- ❌ Chạy `/qc-design-script` khi chưa qua `/qc-review-testcase`, hoặc `/qc-run-script` khi chưa qua `/qc-review-script`.
 - ❌ Lẫn `qc_status` với `dev_selftest`.
 - ❌ Bug không gắn spec → khó truy vết, khó regression.
 - ❌ Kết luận `product-gap` từ **một** lần chạy đỏ → đốt thời gian dev cho một test hên xui.
@@ -89,6 +117,6 @@ Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔
 
 ## Lệnh của bạn (Your commands)
 
-`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review-testcase` · `/qc-design-script` → `/qc-run-script` · `/qc-review-script` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
+`/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` · `/report-bug` · `/propose-scenario` · `/validate-traces`
 
 → [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)

package/docs/04-reference/commands.md

@@ -95,7 +95,7 @@ Mọi lệnh chạy chung một **Gate** (model check → target → context-loa
 | `/qc-review-testcase` | Test case | 🛑 Cổng review test case | QA |
 | `/qc-automation-assess` | Test case đã duyệt | Quyết định Automatable Y/N + %Automated | QA |
 | `/qc-review-script` | Script + Page Object | 🛑 Cổng review script | QA |
-| `/qc-design-script` → `/qc-run-script` | `.Test.md` reviewed + §4.5.6 | Script Playwright + `qc_status`. **Chạy lại ×2 → 3 nhãn FAIL** (`script-bug`·`product-gap`·`flaky`), 🛑 người xác nhận nhãn | QA |
+| `/qc-design-script` | `.Test.md` reviewed + bảng Automatable | Script Playwright + `qc_status`. **Chạy lại ×2 → 3 nhãn FAIL** (`script-bug`·`product-gap`·`flaky`), 🛑 người xác nhận nhãn | QA |
 | `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
 
 > **Cả sáu trạm chạy một lượt Self-Review trước khi in report**, theo `skills/qc/_shared/self-review-principles.md` (một file dùng chung, không sáu bản sao).

package/docs/04-reference/modules.md

@@ -35,7 +35,8 @@
 
 | Module | Vai trò |
 |--------|---------|
-| `qc-playwright` | QC automation — Python + pytest-playwright + Page Object |
+| `qc-playwright-ts` | QC automation web + API — Playwright Test + TypeScript (`layout.web` · `layout.api`) |
+| `qc-wdio-appium` | QC automation app — WebdriverIO v9 + Appium v2 + UiAutomator2, TypeScript |
 | `context-engineering` | Hỗ trợ context-loader |
 
 ---

package/docs/explain/17-qc-design-test.md

@@ -2,13 +2,13 @@
 
 # 17 · `/qc-design-test` — Trạm 3: Thiết kế test case (Markdown)
 
-> **Một câu.** Thiết kế **test case dạng Markdown** (`.Test.md`) từ plan — chưa sinh Python; script đến sau ở `/qc-design-script` → `/qc-run-script`.
+> **Một câu.** Thiết kế **test case dạng Markdown** (`.Test.md`) từ plan — chưa sinh script; script đến sau ở `/qc-design-script`.
 
 ---
 
 ## Vấn đề giải quyết
 
-Tách "thiết kế test case" (con người đọc/review được) khỏi "code test" (máy chạy). `.Test.md` là bản thiết kế mà `/qc-review` duyệt và `/qc-design-script` → `/qc-run-script` biến thành script.
+Tách "thiết kế test case" (con người đọc/review được) khỏi "code test" (máy chạy). `.Test.md` là bản thiết kế mà `/qc-review` duyệt và `/qc-design-script` biến thành script.
 
 ---
 

package/docs/explain/19-qc-run-test.md

@@ -2,7 +2,7 @@
 
 # 19 · `/qc-design-script` · `/qc-run-script` · `/qc-run-manualtest` — Trạm 5–7: sinh · chạy · chạy tay
 
-> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
+> **Một câu.** Biến `.Test.md` đã review thành **script TypeScript**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
 
 ---
 
@@ -18,7 +18,7 @@
 ## Vị trí & tiền đề
 
 - **Vị trí:** Phase QC, **ba trạm** — 5 sinh script · 6 chạy script · 7b chạy tay. `/qc-design-script` chạy sau `/qc-review-testcase` (case APPROVED); `/qc-run-script` chạy sau `/qc-review-script` (script APPROVED).
-- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
+- **Stack:** module QC theo nền (`qc-playwright-ts` · `qc-wdio-appium`, xem `steps/qc-scope.md` §2b) — **độc lập** module dev.
 
 ---
 
@@ -26,7 +26,7 @@
 
 **Input:** `.Test.md` đã review + skill `qa-runner` + bảng Test Selectors §4.5.6 (**giá trị** test-id, từ `/map-testids`) + **`@trace.testid_attr`** ở header tech-doc (**tên thuộc tính** chứa chúng).
 
-**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + panel mirror (`.trace-mirror/`).
+**Output:** script TypeScript + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + panel mirror (`.trace-mirror/`).
 
 > **`@trace.testid_attr` — đọc, KHÔNG suy từ platform.** §4.5.6 cho **giá trị** test-id; field này cho **tên thuộc tính** chứa chúng. `get_by_test_id()` của Playwright mặc định dò `data-testid` **nhưng cấu hình được** — dự án dùng `data-test`/`data-qa` thì phải `set_test_id_attribute("{attr}")` trước, không thì **trượt 100% locator**.
 >
@@ -36,7 +36,7 @@
 
 ## Các bước xử lý (chi tiết)
 
-1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+1. **Role & stack** — module theo nền (`stack-profile.yaml`): TypeScript, Playwright/WDIO fixture, Page/Screen/API Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
 2. **Skills** — nạp một file skill `qa-runner` theo layer.
 3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
 4. **Chạy.** Test đỏ **một lần** chưa nói được nó đỏ vì cái gì → **chạy lại riêng test đó, tối đa 2 lần**, rồi mới phân loại thành **ba** nhãn:

package/docs/explain/20-qc-report.md

@@ -14,7 +14,7 @@ Kết quả chạy cần được trình bày có bằng chứng và **định t
 
 ## Vị trí & tiền đề
 
-- **Vị trí:** Phase QC (trạm 6, cuối), sau `/qc-design-script` → `/qc-run-script`.
+- **Vị trí:** Phase QC (trạm 6, cuối), sau `/qc-run-script` và `/qc-run-manualtest`.
 
 ---
 

package/docs/explain/23-fix-bug.md

@@ -35,7 +35,7 @@ Sửa bug ad-hoc dễ tái phát và mất truy vết. Command áp một quy tr
 4. **Phase 4 · Regression Test** — thêm test tái hiện bug để chống tái phát.
 5. **Phase 4.5 · Cập nhật sổ trace** — regression test phải hiện lên coverage (xem dưới).
 6. **Phase 5 · Build & Commit** — build verify; umbrella **push 2 tầng** (Tầng 1: fix branch trong service submodule nơi code sống; Tầng 2: umbrella pointer).
-7. **Phase 5.5 · Đặt `🟡 Fixed`** — nếu fix một `{BUG-ID}` đã file. **Không** đặt `Closed` — bước đó thuộc `/qc-design-script` → `/qc-run-script`.
+7. **Phase 5.5 · Đặt `🟡 Fixed`** — nếu fix một `{BUG-ID}` đã file. **Không** đặt `Closed` — bước đó thuộc `/qc-run-script`.
 8. **Phase 6 · Đề xuất Lesson** — nếu lỗi tái diễn → `capture-lesson` (L1–L5).
 
 ### Phase 4.5 — vì sao `/fix-bug` phải ghi sổ trace
@@ -49,7 +49,7 @@ Sửa bug ad-hoc dễ tái phát và mất truy vết. Command áp một quy tr
 | `dev_selftest` → `not_run` · `dev_selftest_at` → `—` | code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
 | `last_updated` | hôm nay |
 
-**Hai nhóm cột cấm đụng:** `qc_*` (QC sở hữu — `/qc-design-script` → `/qc-run-script` flip khi re-verify **và** chính nó đóng bug) · `spec_ver`/`gen_ver` (**fix bug không đổi spec** — đụng vào là tạo `DRIFT` giả).
+**Hai nhóm cột cấm đụng:** `qc_*` (QC sở hữu — `/qc-run-script` và `/qc-run-manualtest` flip khi re-verify; riêng `/qc-run-script` đóng bug) · `spec_ver`/`gen_ver` (**fix bug không đổi spec** — đụng vào là tạo `DRIFT` giả).
 
 Vì `dev_selftest` bị reset, Next của lệnh là **`/dev-run-test`** để lấy lại tín hiệu xanh, rồi mới tạo PR.
 

package/docs/plans/qc-surgery/01-checklist.md

@@ -1,10 +1,16 @@
 ---
 title: Checklist 20 bước — đợt đại phẫu QC
-updated: 2026-09-16
+updated: 2026-09-17
 ---
 
 # Checklist — đang ở đâu
 
+> 🧭 **Phần CÒN LẠI đã chuyển sang [`PLAN_v2.md`](PLAN_v2.md)** — file này theo dõi *bước nào xong*;
+> PLAN_v2 giữ *quyết định đã chốt*, *nguồn tài liệu nào dùng cho việc nào*, và *những chỗ bản kế
+> hoạch cũ khai sai*. Ba thứ đó là thứ **quên là làm lại**.
+>
+> **Đọc PLAN_v2 TRƯỚC mỗi bước.**
+
 > Tích `[x]` khi một bước **đã xong VÀ 4 lệnh kiểm đều xanh**. Đừng tích khi "code đã sửa
 > nhưng chưa chạy kiểm".
 >
@@ -19,7 +25,7 @@ updated: 2026-09-16
 
 ```bash
 node bin/build.js            # đúc .tmpl → .md → core/
-node bin/self-check.js       # R1–R18  (R17/R18 thêm ở 0.9.6)
+node bin/self-check.js       # R1–R22 + forbidden_patterns (6 entry S0 có scope)
 node test/run.js             # gồm test ngân sách dung lượng core/commands
 node bin/lint-trace.js       # T1–T20 trên sổ trace thật  (T19/T20 thêm ở 0.9.6)
 ```
@@ -52,15 +58,21 @@ node bin/lint-trace.js       # T1–T20 trên sổ trace thật  (T19/T20 thêm
 
 | | Bước | File exec | Phụ thuộc |
 |:-:|---|---|---|
-| [ ] | 1. `/qc-review` → `/qc-review-testcase` + `/qc-review-script` | [`exec-d2-b1-tach-qc-review.md`](exec-d2-b1-tach-qc-review.md) | Đợt 1 xong |
-| [ ] | 2. ⚠️ `/qc-run-test` → `design-script` + `run-script` + `run-manualtest` — **một commit duy nhất** | [`exec-d2-b2-tach-qc-run-test-atomic.md`](exec-d2-b2-tach-qc-run-test-atomic.md) | d2-b1 |
-| [ ] | 3. Thêm `/qc-automation-assess` + cột `Script file` | [`exec-d2-b3-qc-automation-assess.md`](exec-d2-b3-qc-automation-assess.md) | d2-b2 |
+| [x] | 1. `/qc-review` → `/qc-review-testcase` + `/qc-review-script` | [`exec-d2-b1-tach-qc-review.md`](exec-d2-b1-tach-qc-review.md) | Đợt 1 xong |
+| [x] | 2. ⚠️ `/qc-run-test` → `design-script` + `run-script` + `run-manualtest` — **một commit duy nhất** | [`exec-d2-b2-tach-qc-run-test-atomic.md`](exec-d2-b2-tach-qc-run-test-atomic.md) | d2-b1 |
+| [x] | 3. Thêm `/qc-automation-assess` + cột `Script file` | [`exec-d2-b3-qc-automation-assess.md`](exec-d2-b3-qc-automation-assess.md) | d2-b2 |
+
+## Bước S — Áp stack đã chốt  *(chen giữa Đợt 2 và Đợt 3 · **CHẶN Đợt 3**)*
+
+| | Bước | File exec | Phụ thuộc |
+|:-:|---|---|---|
+| [x] | S. TypeScript + Playwright/WDIO+Appium — 3 lane `web`/`mobile`/`api`; gỡ `qc-playwright` + `qa-runner` | [`exec-S-ap-stack-typescript.md`](exec-S-ap-stack-typescript.md) | Đợt 2 xong · 4 quyết định **chốt 09-17** ✅ |
 
 ## Đợt 3 — Nâng cấp `/qc-report`
 
 | | Bước | File exec | Phụ thuộc |
 |:-:|---|---|---|
-| [ ] | 1. Coverage kép + 8 ngưỡng + verdict PASS/FAIL/INCOMPLETE | [`exec-d3-b1-qc-report-gate-decision.md`](exec-d3-b1-qc-report-gate-decision.md) | **d2-b2 (cứng)** |
+| [ ] | 1. Coverage kép + 8 ngưỡng + verdict PASS/FAIL/INCOMPLETE | [`exec-d3-b1-qc-report-gate-decision.md`](exec-d3-b1-qc-report-gate-decision.md) | **d2-b2 (cứng)** · **Bước S** |
 
 ## Đợt 4 — Utility