@educa-corp/sdd-framework 0.9.5 → 0.9.7

package/core/commands/qc-plan.md

@@ -1,14 +1,14 @@
----
-version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# /qc-plan — QC Test Plan & Risk Analysis
-
-> Stage 2 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-planner của team QC.
-
-## Gate
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-plan — QC Test Plan & Risk Analysis
+
+> Stage 2 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-design-script → qc-review-script → qc-run-script → qc-report). Port từ qa-planner của team QC.
+
+## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
 Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
@@ -88,7 +88,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ờ** |
 
@@ -96,6 +96,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ì**.
@@ -160,96 +166,137 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
 - "N" → dừng, hỏi người dùng muốn thay đổi gì.
 - Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
-
-
-*Lưu ý: Với lệnh này, target ở Bước 1 là một **TICKET-ID** (mã PRD) — hoặc UC-ID / file feature, cả hai quy về TICKET-ID ở §Phạm vi QC. Đọc output của qc-analyze (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) từ `{qc_artifact_dir}` và file `.feature` của đúng nền đó.*
-
-## Context
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một **TICKET-ID** (mã PRD) — hoặc UC-ID / file feature, cả hai quy về TICKET-ID ở §Phạm vi QC. Đọc output của qc-analyze (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) từ `{qc_artifact_dir}` và file `.feature` của đúng nền đó.*
+
+## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
 `project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi
-placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
-
----
-
-## Phạm vi QC
-
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+---
+
+## Phạm vi QC
+
 **BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
-`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--force`).
 Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
-cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
-
-> **Trạm này chạy CẢ PRD, đúng như trạm 1** *(B11)* — một `TEST_PLAN.md` cho mỗi (PRD × nền).
-> `qa-planner/test-plan.md` vốn viết *"Test Plan cho một **feature**"* và template của nó là
-> `# Test Plan – <Feature>` với metadata `Feature / Project / Module`: đây là quay về đúng
-> tầng mà skill gốc được viết cho.
->
-> `uc_list` ở đây **phải khớp** bảng *Phạm vi phân tích* trong `DOC_GAP.md`. Lệch nhau nghĩa là
-> BDD đã đổi trạng thái sau lần chạy trạm 1 → nêu ra và khuyên chạy lại `/qc-analyze`, đừng
-> âm thầm lập plan cho một tập UC khác với tập đã phân tích.
-
----
-
-## Role
-
-Bạn là **QC Planner** — stage 2. Từ output của qc-analyze, tạo TEST PLAN:
-phân tích rủi ro, scenario what-if, scope/strategy test theo từng layer, và `questions-for-dev`
-cho mọi gap open/blocker. Bạn trả lời *"rủi ro ở đâu, phải hỏi gì?"* — bạn không
-thiết kế test case cụ thể (đó là qc-design-test).
-
-## Skills (`{paths.qc_skills_dir}/qa-planner/`)
-
-- `test-plan.md` — khung plan: scope theo từng test layer (functional / integration /
-  e2e / non-functional), what-if, entry/exit criteria, và danh sách questions-for-dev
-  suy ra từ `DOC_GAP.md`.
-- `risk-model.md` — **cách tính** mức rủi ro: 7 nguồn rủi ro · khả năng × thiệt hại → P0–P3 ·
-  và dùng mức đó chia **độ sâu** test. `test-plan.md` có khung bảng `§6`; file này là cách điền.
-  Nạp cùng lúc, không phải thay thế.
-
-## Output
-
-Ghi **đúng MỘT** test plan cho cả PRD vào `{qc_artifact_dir}TEST_PLAN.md`
-(= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/TEST_PLAN.md`). Giới hạn plan trong các
-scenario của **các UC trong phạm vi** (`{UC-ID}-SC{N}` từ `.feature` của nền này) để
-qc-design-test thiết kế case theo từng scenario.
-
-Bắt buộc:
-- **Bảng `§3 Test items` có cột `UC`** — một plan giờ phủ nhiều UC, không có cột đó thì không
-  ai biết vùng test nào thuộc UC nào.
-- **`§2 Phạm vi`** liệt kê rõ UC `⏸ Chưa xét` ở phần *Out of scope*, kèm lý do (BDD chưa
-  approved). *Không có dòng này thì một UC bị bỏ trông giống một UC không có gì để test.*
-- **`§5 Entry criteria` chặn theo từng UC**, không chặn cả PRD: gap 🔴 Blocker ở UC3 không
-  dừng việc thiết kế test cho UC1. Ghi `Ready` / `Blocked` cho **mỗi** UC.
-
-## Self-Review *(trước khi in Report)*
-
-Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
-
-- **Bịa:** mỗi dòng rủi ro neo được vào một `BR`/`AC`/`GAP` **có thật** trong
-  `REQUIREMENT_ANALYSIS.md`/`DOC_GAP.md` — không phải rủi ro chung chung tự nghĩ ra kiểu *"hiệu
-  năng có thể chậm"*? Mỗi `questions-for-dev` suy ra từ một gap cụ thể?
-- **Nhảy bước:** đã đọc **cả hai** file đầu vào (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) và lọc
-  theo cột `UC` — không chỉ đọc file thứ nhất?
-- **Số liệu:** `{risks}`/`{questions}` in ở report = đúng số dòng thật trong `TEST_PLAN.md` vừa
-  ghi, không phải đếm nhẩm?
-
-## Report
-
+cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
+
+---
+
+## Stamp phiên bản nguồn
+
+**BẮT BUỘC — đọc `.agent/steps/qc-stamp.md` và thực thi phần áp cho lệnh này**,
+rồi mới tiếp tục phần bên dưới.
+
+Nó có **hai vế**: §1 **ghi** khối `Nguồn & phiên bản` vào artifact lệnh này sinh ra ·
+§2 **so** stamp của artifact lệnh này ĐỌC với version hiện tại của spec.
+Bỏ vế ghi thì trạm sau không có gì để so; bỏ vế so thì stamp thành một con số không ai
+đọc — và một bộ TC lỗi thời sẽ chạy xanh rồi ghi `pass` **hợp lệ theo mọi phép kiểm**.
+
+> **Trạm này chạy CẢ PRD, đúng như trạm 1** *(B11)* — một `TEST_PLAN.md` cho mỗi (PRD × nền).
+> `qa-planner/test-plan.md` vốn viết *"Test Plan cho một **feature**"* và template của nó là
+> `# Test Plan – <Feature>` với metadata `Feature / Project / Module`: đây là quay về đúng
+> tầng mà skill gốc được viết cho.
+>
+> `uc_list` ở đây **phải khớp** bảng *Phạm vi phân tích* trong `DOC_GAP.md`. Lệch nhau nghĩa là
+> BDD đã đổi trạng thái sau lần chạy trạm 1 → nêu ra và khuyên chạy lại `/qc-analyze`, đừng
+> âm thầm lập plan cho một tập UC khác với tập đã phân tích.
+
+---
+
+## Role
+
+Bạn là **QC Planner** — stage 2. Từ output của qc-analyze, tạo TEST PLAN:
+phân tích rủi ro, scenario what-if, scope/strategy test theo từng layer, và `questions-for-dev`
+cho mọi gap open/blocker. Bạn trả lời *"rủi ro ở đâu, phải hỏi gì?"* — bạn không
+thiết kế test case cụ thể (đó là qc-design-test).
+
+## Skills (`{paths.qc_skills_dir}/qa-planner/`)
+
+- `test-plan.md` — khung plan: scope theo từng test layer (functional / integration /
+  e2e / non-functional), what-if, entry/exit criteria, và danh sách questions-for-dev
+  suy ra từ `DOC_GAP.md`.
+- `risk-model.md` — **cách tính** mức rủi ro: 7 nguồn rủi ro · khả năng × thiệt hại → P0–P3 ·
+  và dùng mức đó chia **độ sâu** test. `test-plan.md` có khung bảng `§6`; file này là cách điền.
+  Nạp cùng lúc, không phải thay thế.
+
+## Output
+
+Ghi **đúng MỘT** test plan cho cả PRD vào `{qc_artifact_dir}TEST_PLAN.md`
+(= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/TEST_PLAN.md`). Giới hạn plan trong các
+scenario của **các UC trong phạm vi** (`{UC-ID}-SC{N}` từ `.feature` của nền này) để
+qc-design-test thiết kế case theo từng scenario.
+
+Bắt buộc:
+- **Bảng `§3 Test items` có cột `UC`** — một plan giờ phủ nhiều UC, không có cột đó thì không
+  ai biết vùng test nào thuộc UC nào.
+- **`§2 Phạm vi`** liệt kê rõ UC `⏸ Chưa xét` ở phần *Out of scope*, kèm lý do (BDD chưa
+  approved). *Không có dòng này thì một UC bị bỏ trông giống một UC không có gì để test.*
+- **`§5 Entry criteria` chặn theo từng UC**, không chặn cả PRD: gap 🔴 Blocker ở UC3 không
+  dừng việc thiết kế test cho UC1. Ghi `Ready` / `Blocked` cho **mỗi** UC.
+
+### Chạy lại — ghi đè ở đây AN TOÀN, và đây là lý do
+
+*(Ba trạm QC khác — `/qc-analyze` · `/qc-design-test` · `/qc-design-script` — đều ở mức **chặn CỨNG** kèm
+§Chạy lại. Trạm này **không**, và đó là kết luận có chủ ý, không phải chỗ sót.)*
+
+`TEST_PLAN.md` **không có ô nào người nhập tay**: `questions-for-dev` là danh sách **gửi đi** — câu
+trả lời quay về qua `DOC_GAP.md` hoặc kênh chat, **không ai điền ngược vào file này**; stamp phiên
+bản và cột `Ready`/`Blocked` đều do lệnh **tự tính** từ `DOC_GAP.md`. Nên chạy lại = lập lại, không
+mất gì.
+
+*Khai máy đọc: `bin/trace-schema.json` → `artifact_writers.enrolled.qc-plan.has_human_content = false`
+— và **R18 ép khai `why`** chính vì một ngoại lệ có chủ ý trông y hệt một chỗ sót.*
+
+> **⚠️ Khai lại nếu điều này hết đúng.** Có ai bắt đầu điền tay vào `TEST_PLAN.md` — một cột quyết
+> định, một ghi chú duyệt, một câu trả lời dán vào — thì lệnh này **phải** lên `checkpoint_levels.hard`
+> và có §Chạy lại như `/qc-analyze`. Đánh giá "an toàn" ở trên đúng **hôm nay**, không đúng vĩnh viễn.
+
+  > **`Blocked` là mức ƯU TIÊN, KHÔNG phải lệnh cấm** *(G66)*. Nó nghĩa *"UC này chưa sẵn sàng
+  > để **nghiệm thu**"*, không phải *"chưa được **thiết kế**"*. `/qc-design-test` vẫn chạy được và
+  > **nên** chạy — TC chạm gap mang dấu `🚫 Block` trỏ về hàng gap, và cơ chế đó chỉ có nghĩa khi
+  > trạm 3 thực sự chạy trên UC `Blocked`.
+  >
+  > Cái bị chặn là **chạy test**, không phải **viết test**. Chờ PO trả lời mất ngày tới tuần; cấm
+  > thiết kế trong lúc chờ là ném đi đúng phần song song mà `/map-testids` mở ra. Và đây là cùng
+  > lập luận đã dùng ngay ở gạch trên — chặn theo UC chứ không theo PRD — chỉ áp thêm một bậc:
+  > một blocker trong UC1 cũng không dừng việc thiết kế **phần còn lại** của UC1.
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mỗi dòng rủi ro neo được vào một `BR`/`AC`/`GAP` **có thật** trong
+  `REQUIREMENT_ANALYSIS.md`/`DOC_GAP.md` — không phải rủi ro chung chung tự nghĩ ra kiểu *"hiệu
+  năng có thể chậm"*? Mỗi `questions-for-dev` suy ra từ một gap cụ thể?
+- **Nhảy bước:** đã đọc **cả hai** file đầu vào (`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`) và lọc
+  theo cột `UC` — không chỉ đọc file thứ nhất?
+- **Số liệu:** `{risks}`/`{questions}` in ở report = đúng số dòng thật trong `TEST_PLAN.md` vừa
+  ghi, không phải đếm nhẩm?
+
+## Report
+
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
-Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
-
-```
-/qc-plan Hoàn tất — {TICKET-ID} ({active_platform})
-Phạm vi: {n} UC trong plan{nếu có: " · ⏸ {m} chưa xét"}
-Plan: {risks} rủi ro · {questions} câu hỏi mở cho dev · layers: {list}
-File: {paths.qc_dir}/{TICKET-ID}/{active_platform}/TEST_PLAN.md
-Sẵn sàng: {danh sách UC Ready} | Chặn: {danh sách UC Blocked + GAP-ID chặn nó}
-Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
-Next: /qc-design-test {UC-ID}   ← thiết kế test case, chạy cho từng UC đã Ready
-      (gửi questions-for-dev cho PO/Dev cho các UC còn Blocked)
-```
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-plan Hoàn tất — {TICKET-ID} ({active_platform})
+Phạm vi: {n} UC trong plan{nếu có: " · ⏸ {m} chưa xét"}
+Plan: {risks} rủi ro · {questions} câu hỏi mở cho dev · layers: {list}
+File: {paths.qc_dir}/{TICKET-ID}/{active_platform}/TEST_PLAN.md
+Sẵn sàng: {danh sách UC Ready} | Chặn: {danh sách UC Blocked + GAP-ID chặn nó}
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next: /qc-design-test {UC-ID}   ← thiết kế test case, từng UC một
+      Ưu tiên UC `Ready`. UC `Blocked` VẪN thiết kế được — TC chạm gap mang dấu
+      🚫 Block và chưa chạy tới khi gap Answered.
+      (song song: gửi questions-for-dev cho PO/Dev để gỡ blocker)
+```

package/core/commands/qc-report.md

@@ -6,7 +6,7 @@ ported_from: ai-automation-qc-base
 
 # /qc-report — QC Test Report & Evidence
 
-> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ bước report của qa-runner team QC.
+> Stage 6 (cuối) của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review-testcase → qc-design-script → qc-review-script → qc-run-script → qc-report). Port từ bước report của qa-runner team QC.
 
 ## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
@@ -88,7 +88,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ờ** |
 
@@ -96,6 +96,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ì**.
@@ -162,7 +168,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
 
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Sinh report từ lần chạy `/qc-run-test` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Sinh report từ lần chạy `/qc-run-script` gần nhất. Dùng module **qc-playwright** (pytest-html + Playwright Trace — không Allure, không dashboard viết tay).*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,