@educa-corp/sdd-framework 0.9.6 → 0.9.8

package/core/commands/validate-traces.md

@@ -4,7 +4,7 @@ Check read-only độ phủ giữa spec, code, và test — gồm cả PRD versi
 
 ## Gate
 
-*Checkpoint: **không chặn** — read-only (ghi trace-report.json + TSV status, không đụng spec/code). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+*Checkpoint: **không chặn** — **không phải vì read-only**. Lệnh ghi `trace-report.json`, `.trace-mirror/`, và **append** `trace-history.jsonl`; với `--reconcile-code` còn ghi row TSV và `_seams.tsv`. Nó không chặn vì mọi thao tác ghi VÔ ĐIỀU KIỆN đều hoặc dựng lại được, hoặc là `append` — và hai thao tác nguy hơn đều nằm sau `--reconcile-code`. Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -85,7 +85,7 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 | Mức | Lệnh nào | `--yes` bỏ qua được? |
 |---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **KHÔNG phải vì read-only**: cả ba đều CÓ ghi file. Chúng không chặn vì thao tác ghi của chúng hoặc nằm sau một câu hỏi `(Y/N)`, hoặc nằm sau một cờ, hoặc là `append`/dựng-lại-được | — (vốn không có) |
 | **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
@@ -93,6 +93,12 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 `--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
 headless: `claude -p "/generate-code UC1 --yes"`.
 
+> **Tên lệnh trong bảng trên có máy canh — `R19`.** Mỗi hàng bảng vừa nêu một mức vừa nêu
+> tên lệnh sẽ bị đối chiếu với `gate.checkpoint_levels`; lệch là build đỏ. Lý do có rule này:
+> ngày 2026-09-16 hai lệnh đổi mức, schema và `commands/*.tmpl` đều sửa, **build vẫn xanh**,
+> mà bảng này lẫn `rules/workflow.md` đều còn liệt chúng ở mức cũ. `R11` chỉ canh
+> `commands/*.tmpl` ↔ schema — *biết có máy canh không bằng biết máy canh **đến đâu***.
+
 > **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
 > ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
 > **nghĩa là gì**.
@@ -796,7 +802,7 @@ Không tìm thấy seam/stub nào → bỏ qua im lặng.
 Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
 Đồng thời **đồng bộ `uc_status` ← `@trace.status`** của file `.feature` tương ứng (header `.feature` là nguồn-sự-thật về duyệt BDD — người đặt `approved` sau khi review sạch, giống PO đặt PRD Metadata `Status`). Nhờ vậy `approved_ucs` trên dashboard phản ánh đúng thay vì luôn = 0.
 Và **đồng bộ `prd_status` ← `| **Status** |`** của PRD tương ứng (`{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md`) — đối xứng với `uc_status`: PRD Metadata là nguồn-sự-thật về duyệt PRD. Không có bước này thì `prd_status` là **write-once** (chỉ `/generate-bdd` ghi một lần) và sẽ giữ `approved` vĩnh viễn sau khi `/refine-prd` hay `/review-context --fix` reset PRD về `draft`. *(Step 4 đã đọc file PRD này rồi — không phát sinh I/O.)*
-**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
+**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-script` + `/qc-run-manualtest` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
 
 ### Step 6b — Ghi mốc `spec_baseline` cho lần audit sau
 
@@ -901,7 +907,7 @@ qc_passing       = rows where qc_status == pass
 qc_failing       = rows where qc_status == fail
 qc_skipped       = rows where qc_status == skip
 qc_not_run       = rows where qc_status in (not_run, —)
-# qc_status is the OFFICIAL QC automation result (set by /qc-run-test),
+# qc_status is the OFFICIAL QC automation result (set by /qc-run-script + /qc-run-manualtest),
 # shown alongside — never merged with — dev_selftest.
 waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
 waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify

package/core/modules/qc-playwright-ts/module.yaml

@@ -0,0 +1,13 @@
+name: "QC Playwright (TypeScript)"
+version: "1.0.0"
+description: "QC automation — Playwright + TypeScript. Phục vụ HAI nền: web (automation/) và API/system (api-automation/)"
+language: "TypeScript"
+framework: "Playwright Test"
+stack_type: "qc-automation"
+default_layer_order:
+  - Test case Markdown (.Test.md) — nguồn sự thật, review xong mới sinh code
+  - Test data (data/*.data.ts)
+  - Page Object (pages/*.page.ts)  ·  API Object (api/*.api.ts)
+  - Fixture (fixtures/*.fixture.ts)
+  - Spec (tests/[feature]/*.spec.ts)
+test_framework: "Playwright Test + expect"

package/core/modules/qc-playwright-ts/stack-profile.yaml

@@ -0,0 +1,99 @@
+# QC automation module — Playwright + TypeScript.
+#
+# Nguồn: upstream/qc-base-new/Automation-Standards.md (Approved) §1 §2.3 §3 §6.1 §9.2
+#        upstream/qc-base-new/API-Testing-Standards.md (Approved) §1 §2.1 §7.2 §7.3
+#
+# Module này phục vụ HAI nền — web và system(API) — vì cả hai dùng CÙNG stack
+# (AD-API-001: "Playwright API mode thay vì framework riêng, để tái dùng infrastructure
+# với Web testing"). Tách làm hai module là khai dãy phiên bản Playwright/TS hai lần.
+# Nền mobile ở modules/qc-wdio-appium (stack khác hẳn: WebdriverIO + Appium).
+#
+# CHỌN NỀN LÚC CHẠY: theo `active_platform` đã phân giải ở trạm 1 (steps/qc-scope.md).
+# KHÔNG có key cấu hình riêng cho việc này — một pass QC đã khoá đúng một nền, hỏi lại
+# bằng một field thứ hai là tạo hai đáp án cho một câu.
+#
+#   web · webview  →  layout.web       app · app-ios · …  →  qc-wdio-appium
+#   system         →  layout.api
+
+versions:
+  playwright: "latest"        # Playwright Test — runner + assertion + reporter, không thêm Jest/Mocha
+  typescript: "v5.x"          # strict mode
+
+build:
+  web:
+    test:       "npx playwright test"
+    e2e:        "npx playwright test tests/ --grep @e2e"
+    report:     "npx playwright show-report"
+    show_trace: "npx playwright show-trace test-results/<test>/trace.zip"
+  api:
+    test:       "npx playwright test --config=api-automation/playwright.config.ts"
+    report:     "npx playwright show-report"
+
+layout:
+  # §2.3 của Automation-Standards — mirror test-suites/, KHÔNG đổi tên thư mục.
+  web: |
+    automation/
+    ├── playwright.config.ts
+    ├── package.json  ·  tsconfig.json
+    ├── pages/        ← Page Object: base.page.ts · <feature>.page.ts
+    ├── tests/        ← spec, mirror test-suites/: {TICKET-ID}/<feature>-happy-path.spec.ts
+    ├── data/         ← <feature>.data.ts  (ref TDS artifact)
+    ├── fixtures/     ← base.fixture.ts
+    ├── helpers/      ← <helper>.ts
+    └── reports/      ← sinh ra, gitignored
+
+  # §2.1 của API-Testing-Standards — thư mục gốc RIÊNG, "tách biệt với automation/ (web)
+  # để tránh xung đột config và dependency". api/ thay cho pages/; không có Page Object.
+  api: |
+    api-automation/
+    ├── playwright.config.ts     ← config riêng của API mode
+    ├── package.json  ·  tsconfig.json
+    ├── api/          ← API Object: base.api.ts · <resource>.api.ts
+    ├── tests/        ← {TICKET-ID}/<feature>-{happy-path,negative,security}.spec.ts
+    ├── data/         ← <resource>.data.ts
+    ├── fixtures/     ← api.fixture.ts  (shared API context, auth token)
+    ├── helpers/      ← schema.helper.ts · auth.helper.ts
+    └── reports/      ← sinh ra, gitignored
+
+naming:
+  # §9.2 (web) · §7.2 (api). File kebab-case; class PascalCase; method camelCase verb-first.
+  page_object:  "pages/<feature>.page.ts      → class <Feature>Page extends BasePage"
+  api_object:   "api/<resource>.api.ts        → class <Resource>API extends BaseAPI"
+  spec:         "tests/{TICKET-ID}/<feature>-<scenario>.spec.ts"
+  test_data:    "data/<resource>.data.ts"
+  fixture:      "fixtures/<name>.fixture.ts"
+  helper:       "helpers/<name>.helper.ts"
+  test_case_md: "{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md"
+
+locator_priority:
+  # §6.1 — chỉ áp cho nền web. API không có locator.
+  web: "getByRole → getByLabel → getByPlaceholder → getByTestId → getByText → locator('[css]') (last resort, ghi lý do)"
+  note: "Giá trị test-id lấy từ bảng Test Selectors §4.5.6 của tech-doc, KHÔNG scan runtime.
+         Tên thuộc tính đọc từ `@trace.testid_attr`; nếu ≠ data-testid thì phải gọi
+         `expect.configure`/`selectors.setTestIdAttribute` trước khi dùng getByTestId."
+
+reporting:
+  web: "Playwright HTML Report"     # §1 + OQ-01 đã đóng 2026-06-02: Phase 1 KHÔNG cần Allure
+  api: "Playwright HTML Report"     # Allure defer Phase 2
+
+trace_tags:
+  # Dấu comment là `//` (TypeScript) — stack cũ dùng `#`. Bộ parse bám chuỗi `@trace.*`,
+  # không bám dấu comment (bin/lint-trace.js:733), nên đổi dấu là an toàn; lane DEV đã
+  # dùng `//` từ trước.
+  verifies:  "// @trace.verifies={UC-ID}-SC{N}"
+  source:    "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
+  test_type: "// @trace.test_type=functional|integration|e2e|non-functional"
+
+artifact_id_prefix:
+  # §7.3 API-Testing-Standards — dãy API độc lập với web/mobile.
+  api: "TS-API · SCN-API · TC-API · AUT-API · TDS-API"
+
+# Luật VIẾT CODE (Page Object 3 lớp, assertion, wait, anti-pattern, flaky policy) KHÔNG ở
+# đây — chúng ở skills/qc/qa-script-designer/_shared/web-conventions.md.
+# Ranh giới: hồ sơ này trả lời "chạy ở đâu, đặt tên gì"; skill trả lời "viết thế nào".
+# Vì sao tách: hồ sơ được đọc NGUYÊN vào ngữ cảnh mỗi lần chạy lệnh, còn skill nạp MỘT
+# file theo lane — nhồi luật vào đây bắt mọi lần làm web phải đọc cả luật của nền khác.
+
+# qc_status: /qc-run-script ghi pass|fail|skip|not_run + qc_run_at vào
+# {trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv — song song với dev_selftest,
+# và đây là kết quả QC CHÍNH THỨC hiện trên Living Docs.

package/core/modules/qc-wdio-appium/module.yaml

@@ -0,0 +1,20 @@
+name: "QC WebdriverIO + Appium (mobile)"
+version: "1.0.0"
+description: "QC automation cho nền app — WebdriverIO v9 + Appium v2 + UiAutomator2, TypeScript"
+language: "TypeScript"
+framework: "WebdriverIO + Appium"
+stack_type: "qc-automation"
+default_layer_order:
+  - Test case Markdown (.Test.md) — nguồn sự thật, review xong mới sinh code
+  - Test data (data/*.data.ts)
+  - Screen Object (screens/*.screen.ts)
+  - Helper (api · device · gesture)
+  - Spec (tests/[feature]/*.spec.ts)
+test_framework: "WebdriverIO + Appium + Allure"
+
+# ⚠️ PHẠM VI HẸP — KHAI RÕ (PLAN_v2 §8 luật 4).
+# Module này được port theo KHUNG từ Mobile-Automation-Standards.md (Approved) ở Bước S,
+# và CHƯA được chạy thử trên một dự án mobile thật. Ba mục riêng của nền mobile (§6 API
+# Helper · §9 Gesture Helper · §12 Environment Validation) đã có mặt, nhưng các con số
+# trong đó (toạ độ swipe, timeout) là giá trị mặc định của chuẩn, chưa hiệu chỉnh theo
+# thiết bị thật. Lần đầu chạy thật: đối chiếu lại §12 trước khi tin kết quả.

package/core/modules/qc-wdio-appium/stack-profile.yaml

@@ -0,0 +1,107 @@
+# QC automation module — WebdriverIO + Appium, nền app (mobile).
+#
+# Nguồn: upstream/qc-base-new/Mobile-Automation-Standards.md (Approved)
+#        §1 §2 §3 §6 §7.1 §9 §10.2 §12
+#
+# ⚠️ ĐÂY KHÔNG PHẢI BẢN COPY CỦA qc-playwright-ts. Chuẩn mobile dài hơn chuẩn web 129 dòng,
+# và phần dôi ra không phải văn vẻ: §6 API Helper · §9 Gesture Helper · §12 Environment
+# Validation Checklist. Một hồ sơ mobile copy từ web sẽ im lặng thiếu ba mục đó, và cái
+# thiếu chỉ lộ ra khi có người chạy thật trên máy thật — tức SAU khi đã tin là xong.
+#
+# CHỌN NỀN LÚC CHẠY: theo `active_platform` ở trạm 1 (steps/qc-scope.md).
+#   app · app-ios · app-android  →  module này
+#   web · webview · system       →  qc-playwright-ts
+
+versions:
+  appium:      "v2.x"          # latest
+  webdriverio: "v9.x"          # latest — test runner
+  typescript:  "v5.x"
+  android_driver: "UiAutomator2"   # driver@latest
+  emulator:    "Genymotion"        # trial, latest
+
+build:
+  test:      "npx wdio ./wdio.config.ts"
+  android:   "npx wdio ./wdio.android.config.ts"
+  dry_run:   "npx wdio ./wdio.config.ts --dry-run"
+  appium:    "npx appium"
+  report:    "npx allure generate reports/allure-results --clean && npx allure open"
+
+layout:
+  mobile: |
+    projects/[ProjectName]/mobile-automation/
+    ├── wdio.config.ts            ← WebdriverIO + Appium
+    ├── wdio.android.config.ts    ← override riêng Android
+    ├── package.json              ← dependency mobile RIÊNG
+    ├── tsconfig.json  ·  .env.example
+    ├── screens/      ← Screen Object (≈ Page Object): base.screen.ts · <feature>.screen.ts
+    ├── tests/        ← {TICKET-ID}/<feature>-{happy-path,negative,api-sync}.spec.ts
+    ├── data/         ← <feature>.data.ts  (dùng chung chuẩn với web)
+    ├── fixtures/     ← base.fixture.ts
+    ├── helpers/      ← api.helper.ts · device.helper.ts · gesture.helper.ts
+    └── reports/      ← Allure output, gitignored
+
+naming:
+  # §10.2 — khác web: hậu tố "Screen", không phải "Page".
+  screen_object: "screens/<feature>.screen.ts  → class <Feature>Screen extends BaseScreen"
+  spec:          "tests/{TICKET-ID}/<feature>-<scenario>.spec.ts"
+  test_data:     "data/<feature>.data.ts"
+  helper:        "helpers/<name>.helper.ts"
+  test_case_md:  "{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md"
+
+locator_priority:
+  # §7.1 — KHÁC HẲN web. Không có getByRole/getByLabel.
+  order: "~accessibilityId → id (resource-id) → xpath (last resort, ghi lý do)"
+  note: "`~accessibilityId` dùng Android content-desc và YÊU CẦU dev gán. Giá trị lấy từ
+         bảng Test Selectors §4.5.6 của tech-doc, tên thuộc tính đọc từ `@trace.testid_attr`
+         (RN: testID · Flutter: Key/Semantics(identifier:) · native iOS: accessibilityIdentifier)."
+
+# ── Ba mục CHỈ mobile mới có. Thiếu bất kỳ mục nào là hồ sơ chưa xong. ──
+
+api_helper:
+  # §6 — mobile verify dữ liệu server bằng Playwright request, TÁI DÙNG từ automation/ (web).
+  file: "helpers/api.helper.ts"
+  impl: "class ApiHelper dùng `request`/`APIRequestContext` của @playwright/test;
+         baseUrl = process.env.API_BASE_URL"
+  why:  "spec `*-api-sync.spec.ts` đối chiếu thứ hiện trên màn hình với thứ server thật có —
+         một màn hình hiển thị đúng dữ liệu CŨ vẫn là bug, và UI assertion không bắt được."
+
+gesture_helper:
+  # §9 — web không cần mục này.
+  file: "helpers/gesture.helper.ts"
+  impl: "class GestureHelper — scrollDown · swipeLeft · … dựng bằng
+         browser.action('pointer', { parameters: { pointerType: 'touch' } })"
+  note: "Toạ độ mặc định trong chuẩn (x=540, startY=800, endY=300, duration=500) là giá trị
+         của MỘT cấu hình màn hình. Hiệu chỉnh theo thiết bị thật trước khi tin kết quả."
+
+environment_validation:
+  # §12 — Gate 6B. Chạy TRƯỚC mọi lần execute mobile.
+  gate: "6B"
+  checklist:
+    - "Genymotion emulator đang chạy và `adb devices` thấy thiết bị"
+    - "APK đúng version đã install trên emulator"
+    - "App khởi động thành công (smoke check bằng tay)"
+    - "API_BASE_URL gọi được TỪ emulator: `adb shell curl ${API_BASE_URL}/health`"
+    - "Test data đã seed trên server (nếu cần)"
+    - ".env đã cấu hình đúng environment hiện tại"
+    - "Appium server connect được: `npx appium` chạy không lỗi"
+    - "WDIO dry-run pass: `npx wdio ./wdio.config.ts --dry-run`"
+  why: "Tám mục này là ranh giới giữa 'test đỏ' và 'môi trường chưa sẵn sàng'. Bỏ qua thì
+        mọi FAIL đều trông như product-gap, và QC đi mở bug cho một cái emulator chưa bật."
+
+reporting:
+  # §1 — ⚠️ NGƯỢC với luật "No Allure" của stack cũ và của nền web.
+  tool: "Allure Report v2.x"
+  note: "Nền web dùng Playwright HTML Report (OQ-01 đóng 2026-06-02: Allure defer Phase 2).
+         Nền mobile thì Allure là BẮT BUỘC theo §1. Hai nền khác nhau ở điểm này — đừng
+         'thống nhất' chúng lại; đó là quyết định của chuẩn, không phải chỗ sót."
+
+trace_tags:
+  verifies:  "// @trace.verifies={UC-ID}-SC{N}"
+  source:    "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
+  test_type: "// @trace.test_type=functional|integration|e2e|non-functional"
+
+# Luật VIẾT CODE ở skills/qc/qa-script-designer/_shared/mobile-conventions.md.
+# Ranh giới: hồ sơ này trả lời "chạy ở đâu, đặt tên gì"; skill trả lời "viết thế nào".
+
+# qc_status: /qc-run-script ghi pass|fail|skip|not_run + qc_run_at vào
+# {trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv

package/core/rules/workflow.md

@@ -11,7 +11,7 @@ Ba mức, định nghĩa đầy đủ ở `steps/gate.md` Bước 3a — **đây
 
 | Mức | Lệnh nào | `--yes` bỏ qua? |
 |---|---|:---:|
-| **Không chặn** | read-only (`/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs`) | — |
+| **Không chặn** | `/review-code` · `/validate-traces` · `/debug` — **không** vì read-only (cả ba đều ghi file), mà vì thao tác ghi nằm sau `(Y/N)` / sau một cờ / là `append` | — |
 | **Chặn thường** | mọi lệnh sinh/sửa artifact | ✅ |
 | **Chặn CỨNG** | ghi đè file đã có · `--resume` · migrate · prune | ❌ |
 
@@ -95,7 +95,7 @@ kém, hay một bản **dán nhãn sai**?"* — vế sau thì không `--force`
 - Field có consumer mà **không có producer** là lỗi chặn build — đó chính là hình dạng
   của G1 (`@trace.sc_version`: 3 consumer, 0 producer, DRIFT chết mà không ai báo).
 - **Làm mất hiệu lực ≠ ghi đè.** Cột trace có chủ sở hữu rõ ràng — `dev_selftest`/`dev_selftest_at`
-  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-test` · `test_count`/`test_classes`
+  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-script` + `/qc-run-manualtest` · `test_count`/`test_classes`
   thuộc `/dev-gen-test` — và **chỉ chủ được ghi giá trị KHẲNG ĐỊNH** (`pass`/`fail`/số lượng).
   Nhưng lệnh nào làm giá trị đó **HẾT ĐÚNG** (spec đổi, code đổi) thì **BẮT BUỘC** hạ nó về giá
   trị "chưa biết" (`not_run` / `—`). Giữ một `pass` đã hết hiệu lực là **báo cáo sai**, không phải

package/core/skills/qc/_shared/self-review-principles.md

@@ -8,7 +8,7 @@ adapted: danh sách lệnh theo pipeline HIỆN TẠI (6 trạm QC) · bổ sung
 # Self-Review — 3 nhóm lỗi AI cần tự kiểm trước khi in Report
 
 Skill **tự chứa**, dùng chung cho các lệnh QC: `qc-analyze` · `qc-plan` · `qc-design-test` ·
-`qc-review` · `qc-run-test` · `qc-report` — và hai nhánh phụ `report-bug` · `propose-scenario`.
+`qc-review-testcase` · `qc-run-script` · `qc-report` — và hai nhánh phụ `report-bug` · `propose-scenario`.
 
 Mỗi file lệnh có mục `## Self-Review` **riêng**, liệt kê tiêu chí **cụ thể cho output của chính
 nó**. File này định nghĩa **3 nhóm lỗi gốc** mà mọi tiêu chí cụ thể đó phải phủ được ít nhất một
@@ -36,7 +36,7 @@ Bảng phân định hiện tại — đừng dùng self-review cho những vi
 | BR mà BDD nhắc nhưng phân tích bỏ sót | **Guard BR-tag** (so với tag `@trace.business_rules`) | `/qc-analyze` |
 | Scenario chưa có test case nào phủ | **Guard SC coverage** (đếm TC trỏ tới từng SC) | `/qc-design-test` |
 | Bảng §4.5.6 trỏ SC không tồn tại · header thiếu `@trace.testid_attr` · bảng lệch code | **T15–T18** | `bin/lint-trace.js` |
-| Ghi `pass` trên row `DRIFT`/`ORPHANED` | **T12** + `positive_assertion_guards` | `bin/lint-trace.js` + `/qc-run-test` |
+| Ghi `pass` trên row `DRIFT`/`ORPHANED` | **T12** + `positive_assertion_guards` | `bin/lint-trace.js` + `/qc-run-script` |
 | Sổ trace sai cấu trúc / enum / trùng `sc_id` | **T1–T8** | `bin/lint-trace.js` |
 
 Còn lại — **không có nguồn đối chiếu cơ học** — mới là việc của self-review: rủi ro bịa ra,

package/core/skills/qc/qa-analyst/DOC_GAP.template.md

@@ -11,7 +11,7 @@ upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
 > Giữ một bản kém hơn làm mặc định là để người không biết có cờ nhận bản kém.
 >
 > **Một chỗ CỐ Ý khác upstream:** mức nặng nhất dùng từ **`Blocker`**, không phải `Critical`.
-> Lý do: `/qc-run-test` đọc `🔴 Blocker` để đặt *"scenario đang chờ PO"* vào sổ kết quả trace.
+> Lý do: `/qc-run-script` đọc `🔴 Blocker` để đặt *"scenario đang chờ PO"* vào sổ kết quả trace.
 > Đổi từ là đứt liên kết đó. Ba mức còn lại giữ nguyên upstream.
 >
 > **Phạm vi: MỘT file cho cả (PRD × nền)** *(B11)*, không phải một file mỗi UC. Đây là quay về

package/core/skills/qc/qa-analyst/data-flow.md

@@ -60,7 +60,7 @@ Ghi vào **mục Data Flow** của `{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`
 - Sơ đồ/list luồng dữ liệu cho mỗi kịch bản chính.
 - Danh sách integration point + state change + failure point.
 - Gợi ý loại test cần cho từng điểm (gui-feature / integration / e2e) khi sang qa-designer.
-- Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho qa-runner.
+- Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho `qa-script-designer`.
 
 Chặng nào luồng/hành vi chưa rõ (vd lỗi xử lý ra sao, retry, partial commit) →
 ghi vào `{qc_artifact_dir}DOC_GAP.md` (loại MISSING / OPEN QUESTION).

package/core/skills/qc/qa-analyst/spec-issue-reporter.md

@@ -18,7 +18,7 @@ có cấu trúc, đủ thông tin để người nhận trả lời được nga
 > mỗi UC là các hàng phân biệt bằng cột `UC`. Không còn một-file-mỗi-UC.
 >
 > **Một chỗ cố ý khác upstream:** mức nặng nhất dùng `🔴 Blocker`, không phải `Critical` —
-> `/qc-run-test` đọc đúng từ đó để đặt *"scenario đang chờ PO"* vào sổ trace.
+> `/qc-run-script` đọc đúng từ đó để đặt *"scenario đang chờ PO"* vào sổ trace.
 
 ## Đầu vào
 

package/core/skills/qc/qa-automation-assess/matrix.md

@@ -0,0 +1,123 @@
+---
+name: automation-feasibility-matrix
+description: Đánh giá từng test case đã APPROVED là Automatable Y/N, kèm lý do chuẩn hoá và %Automated/Total. Dùng bởi /qc-automation-assess.
+---
+
+# Automation Feasibility Matrix
+
+Skill **tự chứa** cho `/qc-automation-assess`: đánh giá từng TC trong `TC_<FEATURE>.Test.md` đã
+qua cổng `/qc-review-testcase` là `Automatable: Y/N`, kèm lý do chuẩn hoá và `%Automated/Total`.
+
+## Khi nào trigger
+
+Sau `/qc-review-testcase` — TC đã `APPROVED` và chưa từng qua automation-assess, **hoặc** TC bị
+gắn cờ `🔄 Re-assess` vì scenario nó verify đang `DRIFT` (BDD/spec đã đổi).
+
+## Tiêu chí đánh giá — trả lời TUẦN TỰ, dừng ở câu đầu tiên là "Có"
+
+Câu nào trả lời "Có" thì **đó là lý do `N`**, và không cần xét tiếp:
+
+1. **Có bước nào đòi input từ con người / bên thứ ba mà script không tự lấy được?**
+   (OTP SMS thật · captcha · chữ ký tay · sinh trắc học trên thiết bị thật)
+   → `N`, nhãn **`Cần OTP/captcha thủ công`**
+2. **Có phụ thuộc hệ thống / thiết bị ngoài tầm kiểm soát của script?**
+   (app khác trên máy thật · máy POS vật lý · email/SMS thật không có test inbox)
+   → `N`, nhãn **`Phụ thuộc hệ thống ngoài`**
+3. **UI/flow có đang thay đổi liên tục?** (redesign · A/B test). Script viết hôm nay nhiều khả
+   năng vỡ trong < 2 tuần vì một thay đổi UI **đã biết trước**
+   → `N`, nhãn **`UI không ổn định`** — ghi rõ mốc dự kiến ổn định để re-assess
+4. **Element cần thao tác có test-id ổn định không, và dev có cam kết thêm nếu thiếu không?**
+   Không có **VÀ** không có cam kết → `N`, nhãn **`Thiếu test-id contract``**
+   > Khác với ca *"sẽ có nhưng chưa"* — ca đó vẫn `Y`, ghi chú chờ `IMPROVE-xxx`.
+5. **ROI có dương không?** Áp công thức dưới; âm rõ ràng → `N`, nhãn **`Effort > ROI`**
+6. Không rơi vào 1–5 → **`Y`**
+
+## Công thức ROI *(ước lượng nhanh, không cần chính xác tuyệt đối)*
+
+```
+ROI ≈ (tần suất chạy lại × chi phí test tay mỗi lần)
+      − (chi phí viết script + chi phí bảo trì dự kiến)
+```
+
+| Tín hiệu ROI **thấp** | Tín hiệu ROI **cao** |
+|---|---|
+| TC chỉ chạy **một lần** (migration một-lần, config set một lần) — viết script tốn hơn chạy tay 1 lần | TC có **nhiều biến thể dữ liệu** (boundary/negative): test tay tốn tuyến tính theo số biến thể, script chạy lại gần như miễn phí |
+
+**Thứ tự ưu tiên khi có nhiều TC `Y` mà chưa đủ thời gian làm hết:** `P0` trước, rồi `P1`/`P2`.
+TC `P0` gần như luôn ROI dương và là ứng viên trực tiếp cho smoke suite (`/qc-smoke-test` chạy
+mỗi build).
+
+> ⚠️ **`P0` mà rơi vào `N` là tín hiệu đáng chú ý hơn bình thường.** Tính năng lõi không có
+> smoke test tự động là rủi ro cao cho cả mục tiêu *"phát hiện lỗi sớm mỗi build"*. Ghi rõ lý do
+> **và** cân nhắc đề xuất `IMPROVE-xxx` để gỡ rào cản, thay vì chấp nhận `N` vĩnh viễn.
+
+## Tín hiệu ổn định — dùng cho tiêu chí 3
+
+| Ổn định | KHÔNG ổn định |
+|---|---|
+| Màn hình đã ship ≥ 1 release, không đổi lớn gần đây | Đang trong sprint thiết kế lại UI |
+| Có test-id contract §4.5.6 đã chốt | Element identify bằng text/class tạm thời |
+| Flow nghiệp vụ ổn định | Business rule đang thử nghiệm (feature flag % rollout) |
+
+## Guard — Re-assessment tự động theo `DRIFT`
+
+TC có scenario `@trace.verifies={UC-ID}-SC{N}` mà row đó trong sổ trace đang `status: DRIFT`
+→ **re-assess lại từ đầu 6 tiêu chí**, KHÔNG tái dùng phán quyết cũ.
+
+Vì sao không tái dùng: spec đổi có thể đổi **cả sáu** câu hỏi — ví dụ một BR mới thêm bước OTP
+biến một TC đang `Y` thành `N`.
+
+| Đổi | Xử lý cột `Script file` |
+|---|---|
+| `Y → N` | **GIỮ** path cũ + ghi chú `⚠️ Script đã lỗi thời — cân nhắc gỡ ở lần /qc-design-script kế tiếp`. **KHÔNG tự xoá file** — để người quyết định |
+| `N → Y` | giữ `—`, chờ `/qc-design-script` điền |
+
+## Output format
+
+```markdown
+# Automation Assessment — {TICKET-ID} ({active_platform})
+
+| TC ID | UC | Automatable | Lý do (nếu N) | Trace SC | Script file | Ghi chú |
+|---|---|:---:|---|---|---|---|
+| TC_LOGIN_001 | UC1 | Y | — | UC1-SC1 | — *(chưa qua qc-design-script)* | |
+| TC_LOGIN_004 | UC1 | N | Cần OTP/captcha thủ công | UC1-SC4 | — *(không automate)* | Giữ trong bộ manual |
+| TC_LOGIN_002 | UC1 | Y | — | UC1-SC2 | — *(chưa qua qc-design-script)* | 🔄 Re-assess (DRIFT, spec đổi {ngày}) — đã re-check: vẫn Y |
+
+**%Automated/Total: {automatable}/{đã đánh giá} = {pct}%**
+**Loại khỏi lượt:** {k} TC của UC chưa APPROVED — {danh sách UC + trạng thái thật}
+```
+
+### Cột `Script file` — ai ghi, khi nào
+
+```
+/qc-automation-assess  →  luôn khởi tạo "—"  (script chưa tồn tại ở bước này)
+/qc-design-script      →  ĐIỀN path thật sau khi sinh
+/qc-run-script         →  ĐỌC cột này để biết chạy file nào — KHÔNG tự suy path
+```
+
+Đây là **chỉ mục ngược duy nhất** từ TC → file code thật; chiều xuôi (code → SC) đã có sẵn qua
+tag `@trace.verifies`. Không có cột này thì `/qc-run-script` phải suy đường dẫn từ quy ước đặt
+tên — suy sai thì chạy sai bộ test, hoặc **chạy 0 test mà vẫn báo xanh**.
+
+> **Đường dẫn theo module đã phân giải ở `steps/qc-scope.md` §2b** — `qc-playwright-ts`
+> *(web · system)* hoặc `qc-wdio-appium` *(app)*, mục `§layout.{web|api|mobile}` của
+> `stack-profile.yaml` tương ứng. **Đừng viết cứng tên module ở đây.**
+>
+> *(Tên file theo `§naming` của module: `<feature>.page.ts` + `<feature>-<scenario>.spec.ts`
+> (web) · `<resource>.api.ts` (system) · `<feature>.screen.ts` (app).)*
+>
+> *(Đề xuất gốc của đội QC viết theo TypeScript + Playwright Test / WebdriverIO. Việc đổi stack
+> là một bước RIÊNG, cố ý tách khỏi đợt tách lệnh — xem quyết định F3, Đợt 2 · b2. Khi stack
+> đổi, chỉ đoạn này và `stack-profile.yaml` cần sửa; cơ chế cột `Script file` không đổi.)*
+
+## Nhãn lý do mới phát sinh
+
+Không khớp nhãn nào trong 5 nhãn chuẩn → **tạo nhãn mới mô tả đúng lý do** *(đừng ép vào nhãn
+có sẵn)*, rồi liệt kê nó trong report để bổ sung vào danh sách lần sau.
+
+> **Vì sao chuẩn hoá nhãn.** Để **đếm được**. *"3 TC không automate vì **thiếu test-id**"* là
+> một tín hiệu hành động được — đi đàm phán với dev. *"3 TC vì lý do kỹ thuật"* thì không.
+>
+> Riêng nhãn `Thiếu test-id contract` nối thẳng với Đợt 0 (hợp đồng test-id §4.5.6): nếu Đợt 0
+> làm đúng thì nhãn này phải **giảm dần theo thời gian** — tức nó đồng thời là **phép đo cho
+> chính Đợt 0**.

package/core/skills/qc/qa-designer/e2e/journey.md

@@ -43,4 +43,4 @@ Mỗi journey → 1 TC bám Format; Expected = chuỗi verify point; chuẩn b
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 6 E2E**. Mỗi journey một TC; tiền điều kiện · kết quả/định tuyến kỳ vọng · BR · phụ thuộc gap · priority ghi dạng trường danh sách.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/exploratory/explore-to-functional.md

@@ -43,4 +43,4 @@ Chuyển draft → TC chính thức bám **format file `TC_<FEATURE>.Test.md`**:
 
 Ghi TC đã chuyển thành functional vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 3 Functional**.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/{qa-runner → qa-designer}/exploratory/session.md

@@ -28,9 +28,15 @@ expected/actual) · `#QUESTION`, `#IDEA` placeholder · summary cuối session.
 ## Mode 2 — Convert Findings
 Input: session note (#BUG + #IDEA).
 - **Bug report** mỗi #BUG: title, severity, priority, steps to reproduce, expected/actual, hypothesis root cause.
-- **Functional TC mới:** mỗi #BUG đã fix → 1–2 TC regression; mỗi #IDEA → TC nếu đủ rõ (hoặc backlog).
-  Đặt đúng layer; bám format TC (Test Data list, Trace BR, 🚫 Block); trace "Origin: Exploratory session <date>".
+- **Functional TC mới → KHÔNG viết luật ở đây.** Dùng `explore-to-functional.md` Phase 4 — nó có
+  format `TC_<FEATURE>.Test.md` đầy đủ (metadata list, Trace BR, 🚫 Block, Test Data, Steps,
+  Expected 1 bullet, Trace matrix). Chỉ thêm một điều riêng của đường này: mỗi TC sinh từ session
+  phải mang `Origin: Exploratory session <date>`.
 - **Weekly summary** (nếu yêu cầu): overview, top findings, coverage gap, recommendations.
 
+> **Vì sao Mode 2 trỏ đi chứ không tự viết** *(Bước S · S2, 2026-09-17)*: bản cũ mô tả lại format TC
+> bằng một câu rút gọn, trong khi `explore-to-functional.md` Phase 4 đã có bản đủ. Hai bản của một
+> format thì bản ngắn sẽ lạc hậu trước — và người đọc bản ngắn không biết mình đang đọc bản cũ.
+
 ## Output
 Mode 1: file session note. Mode 2: bug reports + file TC trong `{qc_artifact_dir}test-cases/` + summary.

package/core/skills/qc/qa-designer/functional/api.md

@@ -16,7 +16,7 @@ Nạp cùng `shared/` (khuôn + độ chính xác + từ điển hành động)
 
 ## Khi KHÔNG trigger
 - Test qua giao diện → `functional/gui-screen`/`gui-feature`
-- Luồng dữ liệu API ↔ DB/service khác → `integration/api` · message/event → `integration/kafka`
+- Luồng dữ liệu API ↔ DB/service khác → `integration/api` · message/event → `integration/queue`
 
 ---
 
@@ -111,4 +111,4 @@ Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>_API.Test.md` — **Nhóm 1 En
 
 File này chỉ sinh khi có cờ `--api` hoặc `--all`. Mẫu TC: `../api/endpoint.md` · chuỗi auth: `../api/auth-chain.md` · tra mã: `../api/http-status-codes.md` · header: `../api/common-headers.md`.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/functional/gui-feature.md

@@ -46,4 +46,4 @@ Liệt kê các màn/route + thứ tự điều hướng · state/dữ liệu tr
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 3 Functional** (luồng đa màn trong cùng một feature).
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.

package/core/skills/qc/qa-designer/functional/gui-screen.md

@@ -51,4 +51,4 @@ chức năng (input/action/display/nav) · constraint (required/min-max/format/e
 
 Ghi vào `{qc_artifact_dir}test-cases/TC_<FEATURE>.Test.md` — **Nhóm 1 GUI** · **Nhóm 2 Validation** · **Nhóm 3 Functional**.
 
-**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review`.
+**Dạng danh sách, KHÔNG bảng** — file TC không được có ký tự `|` (`shared/tc-metadata-format.md` §Nguyên tắc format file). Cuối file: Trace matrix + danh sách TC bị block, cũng dạng danh sách. Bàn giao `/qc-review-testcase`.