@educa-corp/sdd-framework 0.9.6 → 0.9.8

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-11
+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,9 +25,9 @@ updated: 2026-09-11
 
 ```bash
 node bin/build.js            # đúc .tmpl → .md → core/
-node bin/self-check.js       # R1–R16
+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–T14 trên sổ trace thật
+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–T14 trên sổ trace thật
 
 | | 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
 
@@ -73,20 +85,73 @@ node bin/lint-trace.js       # T1–T14 trên sổ trace thật
 
 ---
 
-## Việc dọn bắt buộc — kèm Đợt 2, bỏ là self-check đỏ
+## Việc dọn bắt buộc — đo lại tại HEAD 0.9.6
+
+> **Bốn trong năm dòng đã xong từ trước mà chưa ai tích.** Cột *Ghi* là số của lần lập bảng
+> (2026-09-11); cột *Đo lại* là số đếm thật trên `commands/*.tmpl` + `skills/` ngày 2026-09-15,
+> **đo trước khi sửa file này** — xem cách đếm ở cuối mục. Để nguyên `[ ]` thì người sau đi làm
+> lại bốn việc đã xong.
 
-| | Việc | Lượng |
-|:-:|---|---|
-| [ ] | Sửa file skill còn gọi `TC_<FEATURE>.md` thay `.Test.md` | 14 file |
-| [ ] | Sửa tham chiếu skill treo `qa-script-runner/report/coverage-evaluator.md` | 1 chỗ |
-| [ ] | Bổ nhãn `*Checkpoint: …*` cho lệnh còn thiếu | 6 file |
-| [ ] | Gỡ comment provenance 10+ dòng ở đầu file lệnh → chuyển vào `bin/qc-base-map.json` | 12 file |
-| [ ] | Thay gate cắt tay (5.4 KB) bằng `{{include:steps/gate.md}}` (11.1 KB) | 12 file |
+| | Việc | Ghi | Đo lại 2026-09-15 |
+|:-:|---|---|---|
+| [x] | Sửa file skill còn gọi `TC_<FEATURE>.md` thay `.Test.md` | 14 file | **0 file.** Đúng 2 chỗ còn chuỗi đó, **cả hai** trong `qc-design-test` và là **phản ví dụ có chủ ý** — *"ghi ra thứ không trạm nào tìm thấy"*. Đừng `grep` rồi báo lỗi lại |
+| [x] | Sửa tham chiếu skill treo `qa-script-runner/report/coverage-evaluator.md` | 1 chỗ | **Không phải lỗi — chưa bao giờ hỏng.** Mọi tham chiếu nằm gọn trong `upstream/qc-base/`, và `upstream/qc-base/skills/qa-gate/coverage-evaluator.md` có thật. Không có commit sửa nào để đi tìm |
+| [ ] | Bổ nhãn `*Checkpoint: …*` cho lệnh còn thiếu | 6 file | **18 file** — chỉ 15/33 lệnh có nhãn; số cũ nhỏ hơn thực tế 3 lần *(lần lập bảng đếm trên tập lệnh QC rồi ghi như thể đếm toàn bộ 33 lệnh)*. **Không lệnh nào trong 18 đó được miễn**: cả 5 lệnh mức `none` — `review-code` `validate-traces` `debug` `review-context` `review-tech-docs` — đều ĐÃ có nhãn. 18 là nợ thật |
+| [x] | Gỡ comment provenance 10+ dòng ở đầu file lệnh → `bin/qc-base-map.json` | 12 file | **0 file.** Không tmpl nào còn khối `<!-- -->` ở đầu; provenance rút còn đúng 1 dòng `ported_from:` ở 6 lệnh QC, phần còn lại đã nằm trong `bin/qc-base-map.json` (snapshot `596149f`) |
+| [x] | Thay gate cắt tay (5.4 KB) bằng `{{include:steps/gate.md}}` (11.1 KB) | 12 file | **0 lệnh còn gate cắt tay.** 31/33 tmpl dùng `{{include:steps/gate.md}}`. Hai lệnh còn lại — `sync`, `update-framework` — không phải cắt tay: chúng **không có gate nào cả**, xem cảnh báo dưới |
+
+> ⚠️ **Phát sinh khi đo — KHÔNG thuộc đợt dọn này.** `sync` và `update-framework` đều GHI file
+> (`{service.path}/.agent/project-context.yaml`, `{living_docs_dir}/trace-report.json`, và
+> `--init` copy đè cả `.agent/`) nhưng **không include gate và không có tên trong
+> `gate.checkpoint_levels`** → rơi vào mặc định `normal`, mức lỏng nhất. Đây đúng hình dạng lỗi
+> mà R18 sinh ra để bắt (G67 · G77 · G78 · G79). Xử ở việc **khai nốt registry
+> `artifact_writers`**, không phải ở đây.
+
+<details>
+<summary>Cách đếm — chạy lại được, ra đúng số trên</summary>
+
+```bash
+# 1 — gate: 31 file có include; 2 file thiếu là sync, update-framework
+grep -l "include:steps/gate.md" commands/*.tmpl | wc -l
 
-## Câu còn phải chốt với chị QC
+# 2 — TC_<FEATURE>.md: đúng 2 hit, cả hai trong qc-design-test (phản ví dụ)
+grep -rn 'TC_<FEATURE>.md' skills/ commands/
 
-| | Câu hỏi | Chặn bước nào |
-|:-:|---|---|
-| [ ] | `/qc-run-manualtest` ghi kết quả test tay thế nào — nhập từng TC, hay đọc từ file checklist? | d2-b2 |
-| [ ] | Smoke suite đặt tên gì (không được nhầm `/dev-smoke-test` đã có) | d4-b2 |
-| [ ] | Ngưỡng dung lượng chốt bao nhiêu (đo lại sau d2-b2, ước ~1313 KB) | d2-b2 |
+# 3 — coverage-evaluator: file đích tồn tại ⇒ tham chiếu không treo
+ls upstream/qc-base/skills/qa-gate/coverage-evaluator.md
+
+# 4 — nhãn Checkpoint: 15 có / 18 thiếu trên 33 lệnh
+for f in commands/*.tmpl; do grep -qE '^s**Checkpoint:' "$f" || basename "$f" .tmpl; done | wc -l
+
+# 5 — provenance: 0 dòng <!-- ở đầu tmpl
+head -30 commands/*.tmpl | grep -c '^<!--'
+```
+
+**Vì sao mục này phải mang theo cách đếm:** không máy nào canh file kế hoạch. `self-check` canh
+schema, `lint-trace` canh sổ trace, `test/run.js` canh build — cả ba xanh trong lúc bảng này sai
+bốn dòng. Ghi kết quả đo mà không ghi cách đo thì người sau vẫn phải đo lại từ đầu, tức ô tích
+không tiết kiệm được gì.
+
+</details>
+
+## Câu đã chốt với chị QC  *(2026-09-16)*
+
+| | Câu hỏi | Trả lời | Chặn bước nào |
+|:-:|---|---|---|
+| [x] | `/qc-run-manualtest` ghi kết quả test tay thế nào — nhập từng TC, hay đọc từ file checklist? | **Nhập từng TC.** Nguyên văn: *"ghi kết quả test tay em nhé. Chị sợ đọc checklist mà lệch thông tin lại ghi kết quả sai."* | d2-b2 — **hết chặn** |
+| [x] | Smoke suite đặt tên gì (không được nhầm `/dev-smoke-test` đã có) | **`/qc-smoke-test`** — đúng quy ước hai làn `qc-`/`dev-` | d4-b2 — **hết chặn** |
+| [x] | Ngưỡng dung lượng chốt bao nhiêu | **Không cần hỏi — đo được.** `1309 / 1450 KB` sau d2-b1 (còn 141 KB). Đo lại sau khi viết 3 lệnh của d2-b2 | d2-b2 |
+
+> **Vì sao câu 1 quan trọng hơn vẻ ngoài của nó.** Phương án *"đọc file checklist"* nghe tiện hơn
+> (điền offline, nhiều người điền dần), và đó là phương án được khuyến nghị lúc đầu. Chị QC chỉ ra
+> một rủi ro nặng hơn sự tiện: một file điền tay là **nguồn thứ hai có thể trôi** — TC bị đánh số
+> lại sau một lần `/qc-design-test`, TC mới thêm, dòng cũ còn sót — và khi nó lệch thì lệnh ghi
+> `qc_status` cho **đúng SC sai**. Kiểu hỏng đó là **Nói dối** (sổ trace báo `pass` cho scenario
+> chưa ai chạy); cái giá của phương án hỏi-từng-TC chỉ là **Ồn**. Đổi một rủi ro nói dối lấy một
+> rủi ro phiền là đúng chiều, và cùng họ với `positive_assertion_guards` — luật đã có sẵn để
+> **không bao giờ** ghi `pass` khi dữ liệu nền không chắc.
+>
+> **Điều chỉnh giữ nguyên tính an toàn đó:** lệnh **ghi ngay vào sổ trace sau mỗi câu trả lời**,
+> không gom cuối phiên; chạy lại thì chỉ hỏi những SC còn `not_run` — tức **tự resume**. Như vậy
+> sổ trace là nguồn duy nhất (không artifact trung gian nào để trôi) mà vẫn làm được nhiều buổi,
+> nhiều người. Mỗi lần ghi kèm người chạy + ngày, khớp luật *"`pass` phải có bằng chứng"*.

package/docs/plans/qc-surgery/PLAN_v2.md

@@ -0,0 +1,295 @@
+---
+title: PLAN v2 — phần còn lại của đợt đại phẫu QC
+updated: 2026-09-17
+trang_thai: Đợt 0–2 xong · **Bước S XONG 2026-09-17** · kế tiếp Đợt 3
+---
+
+# PLAN v2 — cái gì còn lại, theo thứ tự nào, và vì sao
+
+← [`01-checklist.md`](01-checklist.md) · [`02-lo-trinh.md`](02-lo-trinh.md) · [`00-nhat-ky.md`](00-nhat-ky.md)
+
+> **Vì sao có file này.** `01-checklist.md` theo dõi **bước nào xong**; nó không chứa được
+> *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** — và đã suýt xảy ra ba lần *(xem §5)*.
+>
+> **Cách dùng:** trước mỗi bước, đọc §3 *(thứ tự)* → §4 *(nguồn)* → §5 *(bẫy đã biết)*. Sau mỗi
+> bước, cập nhật §1 và §2.
+
+---
+
+## 1 · Hiện trạng đo được — 2026-09-17 *(sau Bước S)*
+
+```
+lệnh            37        · trong đó QC 10
+skill qc        78 file   · qa-script-designer 18 · qa-script-runner 3 · qa-reviewer/script 13
+module qc       2         · qc-playwright-ts (web+api) · qc-wdio-appium (app)
+rule self-check R1–R22 + forbidden_patterns 17 entry (11 cũ + 6 của S0, có trường scope)
+test            244/244 PASS
+ngân sách       1372 / 1450 KB   (còn 78 KB)
+```
+
+> **Bốn lệnh kiểm XANH cả bốn** từ 2026-09-17 — lần đầu kể từ khi dựng đèn S0. Trong suốt Bước S
+> `self-check` cố ý đỏ *(`G3`)*, và số đỏ giảm đúng theo từng việc: **27 → 19 → 18 → 14 → 9 → 2 → 0**.
+
+> **Phép đếm của ngân sách** *(`test/run.js:697`)*: tổng `size` của **`core/commands/*.md`** —
+> **chỉ thế**. `core/skills/` **không** tính. Nên thêm skill không chạm ngưỡng; rủi ro duy nhất
+> là **3 file lệnh** phình lên. Ghi rõ ở đây vì đã đọc nhầm thành *"cả bộ"* một lần.
+
+**Bốn lệnh kiểm phải xanh sau mỗi bước:**
+
+```bash
+node bin/build.js            # đúc .tmpl → .md → core/
+node bin/self-check.js       # R1–R22
+node test/run.js             # 244 test
+node bin/lint-trace.js       # T1–T20 trên sổ trace thật
+```
+
+---
+
+## 2 · Lệnh QC: cái nào **đúng và đủ**, cái nào chưa
+
+> **"Chạy được" ≠ "đúng và đủ".** Một lệnh sinh output theo stack đã bị thay thì **chưa xong**,
+> dù mọi rule đều xanh. Bảng này dùng tiêu chí thứ hai.
+
+| # | Lệnh | Trạng thái | Chặn bởi |
+|:-:|---|---|---|
+| 1 | `/qc-analyze` | ✅ đủ | — |
+| 2 | `/qc-plan` | ✅ đủ | — |
+| 3 | `/qc-design-test` | ✅ đủ | — |
+| 4 | `/qc-review-testcase` | ✅ đủ *(mới, Đợt 2 b1)* | — |
+| 5 | `/qc-automation-assess` | ✅ đủ *(mới, Đợt 2 b3)* | — |
+| 6 | `/qc-design-script` | ✅ đủ *(Bước S · S2+S4)* — sinh theo nền, 3 lane | — |
+| 7 | `/qc-review-script` | ✅ đủ *(Bước S · S3)* — tiêu chí theo nền, severity + 4 verdict | — |
+| 8 | `/qc-run-script` | ✅ đủ *(Bước S · S2+S4)* | — |
+| 8b | `/qc-run-manualtest` | ✅ đủ *(mới, Đợt 2 b2)* | — |
+| 9 | `/qc-report` | ❌ bản cũ — chưa có coverage kép + verdict | **Đợt 3** |
+
+**QC test được ngay hôm nay — một lát cắt dọc trọn vẹn, không chạm stack:**
+
+```
+1 analyze → 2 plan → 3 design-test → 4 review-testcase → 5 automation-assess
+  → 6 design-script → 7 review-script → 8 run-script ∥ 8b run-manualtest
+```
+
+**Tám trạm đầu đã đúng và đủ.** Chỉ `/qc-report` *(trạm 9)* còn chờ Đợt 3. Phép thử quyết định
+vẫn như cũ: chạy hết rồi mở sổ trace — **mọi SC của TC `Automatable: N` phải có
+`qc_status ≠ not_run`**.
+
+---
+
+## 3 · Thứ tự còn lại
+
+### ✅ Bước S — Áp stack đã chốt · **XONG 2026-09-17**
+
+Sáu việc, bốn commit, thứ tự `S-ORDER`: **S0 → S1 → S5 → S3 → S2 → S4**.
+
+| Việc | Làm gì | Đèn sau đó |
+|---|---|:-:|
+| **S0** | Đèn cơ học cấm dấu vết stack cũ — 6 entry `forbidden_patterns` có trường `scope` mới, chạy qua `R5` sẵn có | 27 → 19 |
+| **S1** | `qc-playwright` **gỡ** → `qc-playwright-ts` *(web+api)* + `qc-wdio-appium` *(app)*; bảng phân giải nền vào `qc-scope.md` §2b | 18 |
+| **S5** | Dọn ăn theo *(4 lệnh · `trace-schema` · `qc-base-map` · 5 `docs/`)* + **đánh số lại dây chuyền 10 trạm** | 14 |
+| **S3** | `qa-reviewer/script/` 5 file phẳng → **xoá, viết mới** 12 file theo 3 nền + `_shared/review-rules.md` | 9 |
+| **S2** | `qa-runner` **gỡ** → `qa-script-designer` *(18)* + `qa-script-runner` *(3)* | 2 |
+| **S4** | 2 lệnh cuối: gỡ bảng `testid_attr` trùng bản, đổi 6 dòng còn lại | **0** ✅ |
+
+Hồ sơ: [`exec-S`](exec-S-ap-stack-typescript.md) · [`S0`](exec-S0-guard-cam-stack-cu.md) ·
+[`S1`](exec-S1-hai-module-thay-qc-playwright.md) · [`S2`](exec-S2-qa-runner-thanh-script-designer-runner.md) ·
+[`S3`](exec-S3-viet-lai-tieu-chi-review-script.md) · [`S5`](exec-S5-an-theo-don-dau-vet-stack-cu.md)
+
+**Chín quyết định** sinh ra ở bước này, xem §7: `S-API` · `H1` · `H2` · `H3` · `S-SCOPE` ·
+`S3′` · `S-PATH` · `S-VERDICT` · `S-ORDER` · `S-SHARED`.
+
+> **Ba điều Bước S dạy được, ghi ở đây vì chúng áp cho Đợt 3 và 4:**
+>
+> **① Dựng đèn trước, dọn sau** *(`G3`)* — và **lấy số đỏ làm thước đo tiến độ**, không chỉ làm
+> cổng chặn. Mỗi việc phải làm con số giảm **đúng bằng phần nó nhận**; giảm ít hơn là sót, nhiều
+> hơn là đã lấn sang việc khác. Phép này bắt được lỗi **ba lần** trong Bước S.
+>
+> **② Cảnh báo `scope khớp 0 file`** chạy đúng cả hai chiều: tự tắt khi thư mục ra đời, tự bật
+> khi thư mục bị xoá. Bật lên **chính là bằng chứng** việc xoá đã xảy ra thật.
+>
+> **③ Đèn có ba giới hạn đã biết** — nó canh **tên công nghệ**, nên **không** bắt được: luật đã
+> hết đúng mà không chứa tên nào *(ca "Không Allure")* · hai file của ta nói khác nhau *(ca
+> `stack-profile` ↔ tiêu chí review)* · port hụt một mục. Cả ba ghi ở §3 nợ. **Chưa dựng rule
+> cho chúng** — chưa biết có tái diễn không.
+
+### Đợt 3 — `/qc-report`
+
+Coverage kép + 8 ngưỡng + verdict `PASS`/`FAIL`/`INCOMPLETE`. Phụ thuộc **cứng** vào d2-b2 *(đã
+xong)* và **nên chờ Bước S** — verdict dựng trên kết quả của `/qc-run-script`, đừng dựng trên
+một trạm còn sai stack.
+
+File: [`exec-d3-b1-qc-report-gate-decision.md`](exec-d3-b1-qc-report-gate-decision.md)
+
+### Đợt 4 — 4 bước utility
+
+| Bước | Việc | Trạng thái chặn |
+|---|---|---|
+| d4-b1 | `/qc-design-testdata` | phụ thuộc d2-b3 ✅ |
+| d4-b2 | **`/qc-smoke-test`** | ✅ **hết chặn** — chị QC chốt tên 2026-09-16. Trạm 6 đã gắn tag `@smoke` cho `P0` |
+| d4-b3 | `/qc-metrics` + `bin/lint-metrics.js` | — |
+| d4-b4 | `bin/lint-spec.js` — máy quét injection | phụ thuộc d1-b5 ✅ |
+
+### Nợ độc lập — làm lúc nào cũng được
+
+| Việc | Đo được |
+|---|---|
+| **18 lệnh thiếu nhãn `*Checkpoint: …*`** | 19/37 có nhãn. Số cũ trong checklist ghi "6 file" — sai gấp 3 |
+| Sửa `08-qc-automation.md` + `tester-qa.md`: *"Trạm 1–4 chưa cần code"* | Đúng phải là **1–7**; chỉ **8 · 8b · 9** cần app chạy đượ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`; 5 lệnh mới chưa có file `explain` *(phát hiện 09-16 khi soạn Bước S)* |
+| **Lane DEV:** `generate-bdd.tmpl:270` suy `active_platform` theo *"`platform_type` của stack-profile"* | **0/16 module khai `platform_type`** — luật trỏ vào field không tồn tại ở đâu. Đúng lớp lỗi `R1`/`R3` nhưng ngoài tầm chúng *(phát hiện 09-17 khi soạn S1)* |
+| 🔴 **Lane INSTALLER — `G44` thoái hoá im lặng.** `.gitignore:23` loại `.agent/.install-manifest.json` khỏi git, trong khi `index.js:624` dặn *"Commit `.agent/` to git"*. Manifest lệch với đĩa trên mọi máy khác ⇒ điều kiện (3) *"hash khớp manifest"* sai với **cả file chưa ai đụng** ⇒ prune backup-rồi-giữ thay vì xoá | **Bằng chứng 09-17:** `.agent/modules/qc-playwright/stack-profile.yaml` `sha1=e195bcc8…`, `git diff HEAD` **trống** (không ai sửa), vẫn bị xếp *"đã sửa"* và giữ lại sau `--init`. Hệ quả: lệnh bị bỏ **vì nó sai** vẫn nằm trong `.claude/commands/` của cả đội. Hướng xử: đưa manifest vào git, **hoặc** đối chiếu theo `core/` thay vì theo manifest |
+| **4 lệnh kiểm không phủ `.agent/`** | `build.js` dựng `core/`; chỉ `--init` đồng bộ sang `.agent/` kèm prune. Sau một bước **xoá** file framework, phải chạy thêm `node bin/index.js --init` rồi kiểm `.agent/` *(09-17)* |
+| ~~`tech_stack.qc_module` hứa trong comment~~ | ✅ **XONG** — file mang comment đó đã bị gỡ cùng `modules/qc-playwright/` ở S1; cơ chế chọn module nay là bảng §2b của `steps/qc-scope.md` |
+| 🟡 **5 chỗ khác còn dùng mẫu "im lặng khi đạt"** | `qc-design-script:134,141` · `qc-review-testcase:94,106` · `qc-stamp:101,134`. **Chưa sửa** — chúng không phải cổng vào cửa mà là guard *có phạm vi* (*"không có §4.5 → không kiểm gì"*), và chúng chạy giữa một lệnh đã in nhiều thứ khác nên bỏ qua vẫn thấy. Rà lại nếu có ca thật *(09-17, `G-GATE`)* |
+| 🔴 **Lane `job` · `queue` có TC nhưng CHƯA có bộ sinh script** | Trạm 3 hỗ trợ đủ 3 hình dạng; trạm 6 mới có lane `api`. Đã cắm cổng: trạm 6 **DỪNG** khi gặp TC lane `job`/`queue` thay vì lặng lẽ sinh API Object cho thứ không có endpoint. Đường vòng hiện tại: chạy tay qua `/qc-run-manualtest`, hoặc đánh `Automatable: N` kèm lý do. **Mở lane script khi có dự án thật cần** *(09-17, ca LESS-22)* |
+| 🟡 **Từ vựng System BDD chỉ có trigger "ngoài gọi vào"** | `generate-bdd.tmpl:197` cho đúng hai dạng — `the system receives {event}` · `a {actor} submits {action}`. Đo: `schedule`·`cron`·`định kỳ`·`queue` = **0 lần**. Nên BDD của một job **bị ép** viết như thể có người gọi, và đó là gốc của ca LESS-22. Bù bằng câu hỏi ở trạm 3 *(`S-SHAPE`)*; **sửa gốc là lane DEV**, chưa làm *(09-17)* |
+| 🟡 **Không rule nào đối chiếu `stack-profile` với tiêu chí review** | S3 chốt `S-PATH` làm **5 dòng của S1 hết đúng** *(`tests/<feature>/` → `tests/{TICKET-ID}/`)*, và không gì bắt được — chỉ lộ khi đọc lại bằng mắt. Đèn canh **tên công nghệ**, không canh **hai file của ta nói khác nhau**. **Chưa dựng rule** — chưa biết lớp lỗi này có tái diễn không *(09-17, S2 §0.4②)* |
+| 🟡 **Đèn không bắt được luật đã hết đúng nếu nó không chứa tên công nghệ** | Ca thật: `qc-review-script.tmpl` từng ghi *"Không Allure"* *(nay sai với mobile)* và thứ tự locator của web áp cho cả ba nền. Cả hai **không** chứa chữ bị cấm nên `R5` im *(09-17, S3 B5)* |
+| 🟡 **Đèn không bắt được "port hụt một mục"** | File thiếu mục vẫn hợp lệ, vẫn được nạp, vẫn sinh script chạy được. Thứ duy nhất canh là **đếm lại từng mục trên bộ mới** — đã làm ở S2 #4, nhưng đó là phép thủ công, không có rule *(09-17)* |
+| **`docs/` nằm ngoài phạm vi đèn** | Cố ý *(S0 §1.2)*: `docs/` là nơi duy nhất **cần** nói *"trước đây là X"*. Giá phải trả: stack cũ quay lại qua đường tài liệu thì không ai biết. Rà lại sau Đợt 4 |
+| **Nhóm A + D** — 4 dòng ở 5 tầng tài liệu vẫn khai stack cũ | `qa-planner/test-plan.md` ×3 *(Test Plan là tài liệu chị QC **ký** — đang mô tả `pytest-html`)* · `qa-reviewer/test-case/functional.md:18` ×1. Ngoài tầm đèn sau `S-SCOPE`, không chặn ai *(09-17)* |
+| **Nhóm B** — 10 dòng `@pytest.mark.flaky` / `conftest.py` làm quy ước viết TC | **Chủ: chị QC.** Không phải đổi cú pháp: `@pytest.mark.flaky(reruns=2)` = *tự chạy lại, vẫn trong suite*; `@flaky` của chuẩn mới §11 = *quarantine, exclude khỏi main suite*. Cộng thêm: **retry ×2 đã chuyển sang runner ở Đợt 1 b3** → marker là nguồn thứ hai cho cùng một quyết định. **Hệ quả đang chấp nhận:** `.Test.md` dặn ghi marker pytest mà script TS không hiểu *(09-17)* |
+
+---
+
+## 4 · Nguồn tài liệu — cái nào dùng cho việc nào
+
+### 4.1 `upstream/qc-base-new/` — chị trưởng phòng QC gửi, **7 file** *(mới nhận 2026-09-16)*
+
+| File | Status | Dùng cho |
+|---|---|---|
+| **`Automation-Standards.md`** *(527 dòng)* | Approved | **Bước S — web.** §1 Tech Stack · §2 Project Structure · §4 Page Object · §5 Test Spec · §6 Locator · §7 Assertion · §8 Wait · §9 Code Quality · §10 Anti-patterns · §11 Flaky Policy |
+| **`Mobile-Automation-Standards.md`** *(656 dòng)* | Approved | **Bước S — mobile.** Thêm §6 API Helper · §9 Gesture Helper · §12 Environment Validation Checklist |
+| **`API-Testing-Standards.md`** *(714 dòng)* | Approved | **Bước S — lane API** *(xem ⚠️ dưới)*. §4 API Object Pattern · §8 Test Design Techniques · §9 Security Testing |
+| `AGT-005-automation_builder.md` | Draft | làm giàu **`/qc-design-script`** — Skills Inventory · Rules · Boundary · Error Handling · Evaluation Criteria |
+| `AGT-010-api_automation_builder.md` | **Approved** | nhánh **API** của `/qc-design-script` |
+| `AGT-006-code_reviewer.md` | Draft | làm giàu **`/qc-review-script`** — *"quality gate tự động, KHÔNG sửa code, chỉ phân tích và report"*, có **scoring rules** |
+| `AGT-007-defect_analyzer.md` | Draft | **CHƯA CÓ LỆNH TƯƠNG ỨNG** — gần `/qc-metrics` (d4-b3). Xem §6 |
+
+> **Ba file Standards là nguồn TỐT HƠN bộ đề xuất** cho Bước S: chúng là *Official Project
+> Knowledge*, status **Approved**, và nêu cả phiên bản cụ thể *(Appium v2.x · WebdriverIO v9.x ·
+> TypeScript v5.x · UiAutomator2)*. Bộ đề xuất chỉ nói tên stack.
+
+> ⚠️ **PHÁT SINH — lane API là nhánh thứ BA.** `API-Testing-Standards.md` khai một *API Object
+> Pattern* riêng và `AGT-010` là agent riêng (**Approved**, không phải Draft). Framework hiện chỉ
+> tách `web`/`mobile`. Cần quyết: API là **nền thứ ba** *(`qa-script-designer/api/*`)* hay là
+> **một layer trong web** *(đã có `qa-designer/functional/api.md` + `qa-designer/api/*`)*.
+> **Chưa chốt — không tự quyết.**
+
+### 4.2 `D:\base\qcframework_proposal\` — đề xuất của đội QC
+
+12 file lệnh + `skills/qc/{qa-script-designer,qa-script-runner,qa-automation-assess,qa-testdata,qa-metrics,_shared}`.
+Vẫn dùng cho **bố cục thư mục skill** và **khuôn lệnh**; phần **nội dung stack** ưu tiên
+`qc-base-new/` vì nó Approved.
+
+### 4.3 `upstream/qc-base/` — bản port gốc
+
+Provenance ở `bin/qc-base-map.json` *(snapshot `596149f`)*. Chỉ tra cứu lịch sử.
+
+---
+
+## 5 · Bẫy đã biết — đọc trước mỗi bước
+
+### Bẫy 1 · **Bản kế hoạch mang số đo thì có hạn dùng, và nó không tự báo**
+
+Ba lần liên tiếp:
+
+| Kế hoạch | Khai | Thật |
+|---|---|---|
+| `exec-d2-b1` | `grep '"qc-review"' schema` → **0**, *"tách không đụng schema"* | **3** *(7 chỗ kể cả nhắc tên)* |
+| `exec-d2-b2` | `qc-run-test` xuất hiện **21 chỗ** | **34** |
+| `exec-d2-b2` §4.6 | 5 việc dọn bắt buộc | **4/5 đã xong từ trước** |
+| **`PLAN_v2` §3** *(chính file này!)* | `qa-runner` **6 file · 44 KB** → đích **12 file · 88 KB** | **8 file · 26.3 KB** → **14 file · 56.5 KB** |
+
+**Luật:** chạy lại **mọi lệnh đếm** trong kế hoạch **trước** khi làm theo nó.
+
+> 🔴 **Lần thứ tư, và lần này nạn nhân là chính file viết ra luật.** Nguyên nhân thật: số được
+> **chép từ bản kế hoạch trước** chứ không đo lại. Viết luật ra không miễn nhiễm với luật đó.
+> Từ nay **mọi `exec-*` mở đầu bằng một bảng đo lại**, kể cả khi bản trước vừa viết hôm qua.
+
+### Bẫy 2 · Một lệnh **không phải là file của nó**
+
+`{{include:steps/*}}` mang theo thao tác ghi. Kết luận *"lệnh này không ghi gì"* chỉ có giá trị
+khi đo trên bản **đã đúc** (`core/commands/*.md`). *(Đã sai một lần với `/review-code` và
+`/debug` — cả hai ghi `{lessons_path}` qua `capture-lesson.md`.)*
+
+### Bẫy 3 · Kế hoạch mô tả sai **bản chất** thứ nó định giữ
+
+`exec-d2-b2` §4.4 khai `skills/qc/qa-runner/**` là *"bộ hướng dẫn chạy test"*, **9 file**, kết
+luận **GIỮ**. Thật ra: **6 file**, và là bộ **SINH MÃ Python** — dòng đầu file:
+*"Gen Script — convert `.Test.md` → Python pytest + Playwright"*.
+Nó là **đối tượng phải thay**, không phải thứ giữ lại.
+
+### Bẫy 4 · `{{include:…}}` là **chỉ thị**, không phải chữ
+
+Viết nó xen trong câu *(vd để giải thích lệnh ghi file ở đâu)* làm build **inline nguyên file**
+vào giữa câu — một dòng Checkpoint từng nuốt trọn 113 dòng. Có test canh *(`test/run.js`)*.
+
+### Bẫy 5 · Hỏi *"tách được không"* khác hỏi *"tách rồi cái còn lại có dùng được không"*
+
+**F3** kết luận tách commit đổi-stack là đúng *(ràng buộc nguyên tử chỉ áp cho tên lệnh ↔
+contract)*. Đúng về commit — nhưng để lại **3 lệnh sinh output theo stack đã bỏ**, tức **chưa
+xong**. Ràng buộc nguyên tử nói về **thứ tự commit**, không nói về **độ hoàn thành**.
+
+---
+
+## 6 · Câu chưa có lời đáp
+
+> **Bốn câu chặn Bước S đã chốt 2026-09-17** → chuyển xuống §7 với mã `S-API` · `H1` · `H2` ·
+> `H3`. Bằng chứng và các phương án không chọn giữ ở
+> [`exec-S-ap-stack-typescript.md §1`](exec-S-ap-stack-typescript.md).
+
+| Câu | Chặn gì | Ai trả lời |
+|---|---|---|
+| **`AGT-007-defect_analyzer` đưa vào đâu?** — *"intelligence layer, chuyển defect data thành insight, feed back vào Knowledge Base"*. Gần `/qc-metrics` (d4-b3) nhưng rộng hơn | d4-b3 | anh + chị QC |
+| Ngưỡng dung lượng khi vượt 1450 KB | bất kỳ bước nào | đo lại rồi chốt, **kèm lý do đo được** |
+
+---
+
+## 7 · Quyết định đã chốt — đừng mở lại
+
+| Mã | Quyết định | Ngày |
+|---|---|---|
+| **D1** | `writes` là **list object**, `mode`+`regenerable` ở **cấp artifact** | 09-15 |
+| **D4** | thêm `when` ở cấp artifact; luật (B) chỉ ép `hard` khi `when: always` | 09-15 |
+| **E1** | tái cấu trúc skill `script/` → `web`/`mobile` **dời sang Bước S** | 09-16 |
+| **E2** | `/qc-review-script` ghi **file riêng** `REVIEW_SCRIPT_<FEATURE>.md` | 09-16 |
+| **E3** | gỡ `/qc-review` ngay, không giữ cầu | 09-16 |
+| **F1** | `/qc-run-manualtest` **hỏi từng TC**, ghi ngay, tự resume — **không** đọc file checklist *(chị QC: "sợ đọc checklist mà lệch thông tin lại ghi kết quả sai")* | 09-16 |
+| **F2** | `positive_assertion_guards.owner` thành **mảng** *(hai chủ cho cột `qc_status`)* | 09-16 |
+| **G1** | `Automatable` sống ở **đúng một chỗ** — `AUTOMATION_ASSESSMENT.md` | 09-16 |
+| **G2** | `/qc-automation-assess` mức **`hard` + narrowing** | 09-16 |
+| **G3** | dựng rule **trước** khi vá, để chứng minh nó bắt lỗi đang sống | 09-16 |
+| **S-API** | lane API là **nền thứ ba ở tầng skill** (`qa-script-designer/api/*`, khoá theo `active_platform: system`) nhưng **dùng chung module `qc-playwright-ts`** — cùng Playwright+TS *(AD-API-001)*, hai module là chép hai lần một dãy phiên bản. `qa-designer/api/*` **không bị đụng** (khác trục: thiết kế TC ≠ sinh mã) | **09-17** |
+| **H1** | Bước S đổi **lệnh + module cho cả 3 lane trong một commit** *(Bẫy 5)*; **nội dung skill khác độ sâu** — web+api đầy đủ, mobile port khung. Lane mobile **phải tự khai là hẹp** *(§8 luật 4)* | **09-17** |
+| **H2** | **gỡ hẳn** `modules/qc-playwright` — theo tiền lệ `E3`; 3/82 entry `qc-base-map` đều `targets: []` nên `R16` không đỏ | **09-17** |
+| **H3** | **không** port `qa-script-runner/smoke.md` ở Bước S — để **d4-b2**, tránh skill mồ côi | **09-17** |
+| **S-SCOPE** | Đổi stack **chỉ ở tầng script** *(trạm 5–9)*, theo `qc-base-new`. **5 tầng tài liệu KHÔNG đổi**: phân tích yêu cầu · doc-gap · test plan · thiết kế TC · review TC. Căn cứ đo được: 5 tầng đó là **41 file · 0 file chạy được** (100 % `.md`), **0 lệnh QC gọi script framework**, và `qc-base-new` **không nhắc Python một lần nào** — nên *"Python vs TypeScript"* không phải một trục có thật ở đấy. Phạm vi đèn S0 thu theo: **đỏ 27 → 19 file** | **09-17** |
+| **S-PATH** | Bố cục thư mục test: **gốc theo chuẩn Approved, `tests/` phân tách theo `{TICKET-ID}`, `pages/`·`api/`·`screens/` để PHẲNG**. Bất đối xứng có chủ ý: một spec **thuộc về** một PRD; một Page Object **được dùng bởi** nhiều PRD. **KHÔNG khai `qc_automation_dir`** — gốc đã nằm ở `§layout` của module *(cùng lập luận đã bỏ `tech_stack.qc_module`)*. Bộ đề xuất dùng key này ở **29 file**, `R4` là lưới bắt | **09-17** |
+| **S-VERDICT** | Lane QC dùng **4 verdict** của `AGT-006` cho **cả** `/qc-review-testcase` lẫn `/qc-review-script`; lane DEV **giữ 2**. Verdict suy từ **số đếm severity**, không từ điểm; điểm `XX/100` giữ để so hai vòng. Ngưỡng đi tiếp **`≥ APPROVED_WITH_SUGGESTIONS`** *(`AGT-005:132`)*. Ánh xạ nhãn cũ: `FAIL ≡ BLOCKER ∪ MAJOR` · `WARN ≡ MINOR ∪ SUGGESTION` | **09-17** |
+| **S-ORDER** | Thứ tự Bước S đổi thành **S0→S1→S5→S3→S2→S4**. Đo được: **16/18 file đỏ không có phụ thuộc nào** — chỉ S4 bị ép. Lý do đổi: S5 rẻ và đã được S1 quyết hết; **S3 trước S2** là `G3` áp ở tầng nội dung *(viết tiêu chí chấm trước bộ sinh)*. **Đã trả cổ tức**: S3 lộ ra `S-PATH` — một quyết định S2 phụ thuộc, mà nếu làm S2 trước thì bộ sinh đã nướng sẵn một câu trả lời | **09-17** |
+| **G-GATE** | **Cổng vào cửa PHẢI in bằng chứng, kể cả khi đạt.** Mẫu cũ *"đủ → im lặng, đi tiếp"* nghe hợp lý *(cổng là điều kiện, không phải phép đo)* nhưng **cổng đạt trong im lặng không phân biệt được với cổng chưa bao giờ chạy**. Ca thật 09-17: lệnh chạy khi `qc_artifact_dir` **chưa tồn tại**, tự tường thuật *"đủ ba file đầu vào"*, đi tiếp, không dấu vết. Phân biệt: **phép đo** in con số · **cổng vào cửa** in bằng chứng đã chạy. Cổng không bằng chứng thì nó là một lời đề nghị | **09-17** |
+| **S-SHAPE** | `system` **KHÔNG đồng nghĩa với API** — nó có ít nhất **ba hình dạng**: `api` *(ai đó gọi vào)* · `job` *(tự chạy theo lịch)* · `queue` *(nằm chờ message)*. Sửa `S-API`, vốn ánh xạ `system → api` vô điều kiện. **Máy không suy được** vì từ vựng System BDD (`generate-bdd.tmpl:197`) chỉ có hai trigger, **cả hai đều là "ngoài gọi vào"** — nên **QC trả lời ở trạm 3**, câu trả lời ghi vào `Tags` → `<lane>`, trạm 5/6 **ĐỌC chứ không suy lại**. Chỉ hỏi khi `system` **và** 0 dấu hiệu endpoint; `--yes` thì DỪNG. **Cố ý KHÔNG sửa `generate-bdd`** *(lane DEV, đổi mọi dự án, BDD đã viết không tự đổi)* — bù bằng người, và nếu về sau nhiều dự án dạng job thì lúc đó sửa gốc mới đáng | **09-17** |
+| **S-SHARED** | Luật dùng cho nhiều file thì viết **một bản** ở `_shared/`, file lane trỏ vào. Áp ở ba chỗ: `qa-reviewer/script/_shared/review-rules.md` *(11 lane dùng)* · `qa-script-designer/_shared/*-conventions.md` · bảng `testid_attr` **gỡ khỏi lệnh** ở S4 vì nó từng có hai bản và hai bản **đã lệch nhau** | **09-17** |
+| **S3′** | `qa-reviewer/script/` — **xoá 5 file, viết mới**, không vá. Vì mật độ nhiễm **11,2 %** và **9,2 %** ở 2 file: tái bố cục dưới tên *"sửa"* dẫn thẳng vào bẫy B1 *(đúng từ vựng TS, đúng cấu trúc Python)* | **09-17** |
+| — | smoke suite tên **`/qc-smoke-test`** *(chị QC)* | 09-16 |
+| — | stack **TypeScript** + Playwright/WDIO+Appium — *chốt chính thức, xác nhận email* | **09-10** |
+
+---
+
+## 8 · Luật vẫn giữ nguyên qua mọi bước
+
+1. ~~**Mỗi commit đều xanh** — 4 lệnh kiểm.~~ → **sửa 2026-09-17 (`S-WIP`):**
+   **Không mở PR, không publish khi 4 lệnh kiểm chưa xanh.** Commit WIP trên **nhánh việc** thì
+   được, miễn nhãn ghi rõ đỏ vì sao.
+   *Vì sao đổi:* đèn `S0` đỏ **theo thiết kế** (`G3`) và **chỉ hết đỏ khi S5 xong** — nên luật cũ
+   ép phơi toàn bộ S0→S5 ngoài git. Đã phơi **19 giờ / 29 file**, và một session của đợt này
+   **đã chết vì hết token**. Đo chỗ luật thật sự cắn: `npm run build` = `build.js && self-check.js`
+   → đỏ ⇒ **chặn `prepublishOnly`**; CI `on: pull_request` *(mọi nhánh)* + `push: branches:[main]`
+   ⇒ **`git push` lên nhánh việc KHÔNG kích CI**. Đường chung gãy ở **PR và publish**, không ở
+   từng commit của nhánh việc — nên luật mới **chặt hơn ở đúng chỗ**, lỏng hơn ở chỗ không ai đau.
+2. **Trình bày trước → duyệt → mới làm**, theo khuôn `_TEMPLATE-BUOC.md` của `sdd-re-engine`.
+3. **Ngân sách cổng cứng vô điều kiện = 3.** Vượt là `R20` đỏ; nâng được nhưng phải kèm lý do —
+   và đó là **một quyết định, không phải một hệ quả**.
+4. **Khai một phạm vi hẹp và nói rõ là hẹp** thì trung thực hơn khai đầy đủ mà chưa rà.