@educa-corp/sdd-framework 0.4.2 → 0.5.0

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

@@ -1,70 +1,81 @@
-[← Docs Home](../README.md) · [Guides](./)
-
-# Guide · Tester / QA
-
-> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
-
----
-
-## Chuỗi bước của bạn (Your path)
-
-```mermaid
-flowchart LR
-    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
-    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
-    REP --> FB["/report-bug · /propose-scenario"]
-    FB --> SYNC["/sync"]
-```
-
----
-
-## Việc của bạn ở mỗi bước
-
-| Trạm | Bạn làm gì |
-|------|-----------|
-| [`/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** |
-| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
-| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
-| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
-| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL |
-| `/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 |
-
-Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
-
----
-
-## Nguyên tắc sống còn cho QA
-
-1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
-2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
-3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
-4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
-5. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
-
----
-
-## Câu hỏi bạn cần trả lời được
-
-- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
-- Rủi ro nào cao? Cần hỏi dev gì?
-- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
-- Bug này gắn với scenario/spec nào?
-- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
-
----
-
-## 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-run-test` khi chưa qua `/qc-review`.
-- ❌ Lẫn `qc_status` với `dev_selftest`.
-- ❌ Bug không gắn spec → khó truy vết, khó regression.
-
----
-
-## Lệnh của bạn (Your commands)
-
-`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
-
-→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Tester / QA
+
+> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
+    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
+    REP --> FB["/report-bug · /propose-scenario"]
+    FB --> SYNC["/sync"]
+```
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Trạm | Bạn làm gì |
+|------|-----------|
+| [`/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** |
+| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
+| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
+| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
+| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL |
+| `/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 |
+
+Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
+
+---
+
+## Nguyên tắc sống còn cho QA
+
+1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
+2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
+3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
+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-run-test` đặ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.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
+- Rủi ro nào cao? Cần hỏi dev gì?
+- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
+- Bug này gắn với scenario/spec nào?
+- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
+- Hành vi phát hiện được có **AC nào phủ** không? → quyết định Case A hay Case B:
+
+  | | Đi đâu | Ai xử |
+  |---|---|---|
+  | **Case A** — thiếu scenario cho AC **đã có** | `feedback/bdd-proposals/` | `/generate-bdd` tự chèn khi bạn đặt `Status: accepted` |
+  | **Case B** — requirement **MỚI**, không AC nào phủ | `feedback/prd-change-requests/` | PO chạy `/extend-prd` |
+
+  Case B **không tự vào BDD được** — scenario chưa có AC để trace tới. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót đó. `/validate-traces` sẽ nhắc lại kèm **số ngày chờ** chừng nào request còn `Open`.
+
+---
+
+## 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-run-test` khi chưa qua `/qc-review`.
+- ❌ Lẫn `qc_status` với `dev_selftest`.
+- ❌ Bug không gắn spec → khó truy vết, khó regression.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/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

@@ -1,105 +1,134 @@
-[← Docs Home](../README.md) · [Reference](./)
-
-# Reference · Commands — Bảng đầy đủ (Command Catalog)
-
-> 31 slash command, gom theo phase pipeline. Chi tiết cơ chế từng bước → [Pipeline Steps](../02-concepts/pipeline-steps/).
-
-Mọi lệnh chạy chung một **Gate** (model check → target → context-loader → checkpoint). Xem [Khung chung](../02-concepts/pipeline-steps/README.md#khung-chung-mọi-command-common-gate).
-
----
-
-## 0 · Setup & Foundation
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/setup-ai-first` | Dự án trống/có code | `.agent/`, `.claude/`, `project-context.yaml`, `CLAUDE.md` | Admin/Lead |
-| `/generate-architecture` | config + tài liệu (`--from`) + code | `architecture.md` (SSOT kiến trúc, theo tier) | SA/Lead |
-
-## 1 · Discovery
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/define-product` | Ý tưởng (+Figma) | `product-definition/*.md` (8 chặng) | PO |
-
-## 2 · Specification (PRD)
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-prd` | product-definition | PRD draft | PO |
-| `/refine-prd` | PRD | Findings 3 lăng kính DEV/SA/PO | PO+SA+Dev |
-| `/review-context` (PRD) | PRD | Findings P0–P5 → `Status: approved` | PO |
-
-## 3 · Design-Spec (chỉ FE/App)
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-design-spec` | PRD approved + Figma | `design-spec/*.md` | PO/PM |
-
-## 4 · BDD
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-bdd` | PRD approved (+design-spec) | `bdd/**/*.feature` | PO |
-| `/review-context` (BDD) | `.feature` | Findings B1–B6 → `@trace.status: approved` | PO/Dev |
-
-## 5 · Tech-Docs
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-tech-docs` | BDD approved + entity catalog | `tech-docs/{TICKET}-tech-design.md` | SA |
-| `/review-tech-docs` | tech-design | Findings đa chiều + ký T7 | SA/Lead |
-
-## 6 · Code
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
-| `/review-code` | Code | Findings (read-only) | Dev/Lead |
-| `/fix-bug` | Bug report | Fix + regression test | Dev |
-| `/map-testids` | UI code | testid map (FE) | Dev |
-| `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
-
-## 7 · Dev self-test
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/dev-gen-test` | Code + `.feature` | Bộ self-test | Dev |
-| `/dev-run-test` | Self-test | Kết quả + cột `dev_selftest` | Dev |
-| `/dev-smoke-test` | Service/app đang chạy | Kết quả smoke tại chỗ | Dev |
-
-## 8 · QC Automation
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
-| `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
-| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
-| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
-| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
-| `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
-
-## 9 · Quality & Trace
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/validate-traces` | `.trace/*.tsv` + spec/code/test | Ma trận coverage (read-only) | Dev/QA/Lead |
-| `/generate-spec-manifest` | Specs | Mục lục spec cho agent ngoài | SA/Lead |
-
-## 10 · Feedback & Ops
-
-| Lệnh | Input | Output | Owner |
-|------|-------|--------|-------|
-| `/report-bug` | Lỗi phát hiện | `feedback/bug-reports/` (spec-anchored) | Tester/QC |
-| `/propose-scenario` | Scenario thiếu | `feedback/bdd-proposals/` | Tester/QC |
-| `/learn` | Định hướng lặp lại | `project-lessons.md` | Tất cả |
-| `/sync` | (umbrella) | Pull + submodule + nổi feedback + Living Docs | Lead |
-| `/update-framework` | — | Sync bản npm mới | Lead |
-
----
-
-## Ký hiệu trạng thái trong report
-
-- 🛑 checkpoint (dừng, chờ `Y`) · 🔒 gate trạng thái (chặn downstream) · ⚪ read-only
-- ⚠️ cảnh báo mềm (không chặn) · ✅ pass · ❌ fail
-
-→ [Trace Schema](trace-schema.md) · [Modules](modules.md) · [Configuration](configuration.md) · [Model Selection](model-selection.md)
+[← Docs Home](../README.md) · [Reference](./)
+
+# Reference · Commands — Bảng đầy đủ (Command Catalog)
+
+> 32 slash command, gom theo phase pipeline. Chi tiết cơ chế từng bước → [Pipeline Steps](../02-concepts/pipeline-steps/).
+
+Mọi lệnh chạy chung một **Gate** (model check → target → context-loader → checkpoint). Xem [Khung chung](../02-concepts/pipeline-steps/README.md#khung-chung-mọi-command-common-gate).
+
+---
+
+## 0 · Setup & Foundation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/setup-ai-first` | Dự án trống/có code | `.agent/`, `.claude/`, `project-context.yaml`, `CLAUDE.md` | Admin/Lead |
+| `/generate-architecture` | config + tài liệu (`--from`) + code | `architecture.md` (SSOT kiến trúc, theo tier) | SA/Lead |
+
+## 1 · Discovery
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/define-product` | Ý tưởng (+Figma) | `product-definition/*.md` (8 chặng) | PO |
+
+## 2 · Specification (PRD)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-prd` | product-definition | PRD draft **mới** | PO |
+| `/extend-prd` | **PRD đã có** + `feedback/prd-change-requests/` | PRD v+1 (UC/AC/BR nối tiếp, `Status → draft`) | PO |
+| `/refine-prd` | PRD | Findings 3 lăng kính DEV/SA/PO | PO+SA+Dev |
+| `/review-context` (PRD) | PRD | Findings P0–P5 → `Status: approved` | PO |
+
+> **Chọn lệnh nào cho PRD:**
+> - PRD **chưa tồn tại** → `/generate-prd` (từ discovery). Nó **từ chối chạy** nếu file đã có.
+> - PRD đã có, muốn **thêm** UC/AC/BR mới → `/extend-prd`. Đánh số **nối tiếp**, ghi **add-only** kèm guard sau-ghi, tăng version + changelog nêu rõ scope.
+> - PRD đã có, muốn **sửa vấn đề** đã soi ra → `/refine-prd` → Review Board → `--resume`.
+>
+> `/refine-prd` **không** thêm được yêu cầu mới (nó tự cấm đụng section ngoài findings). `/generate-prd` **không** dùng lại được trên PRD đã có (sẽ mất changelog + đánh số lại BR → hỏng `@trace.business_rules` trong BDD đã sinh).
+
+## 3 · Design-Spec (chỉ FE/App)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-design-spec` | PRD approved + Figma | `design-spec/*.md` | PO/PM |
+
+## 4 · BDD
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-bdd` | PRD approved (+design-spec) | `bdd/**/*.feature` | PO |
+| `/review-context` (BDD) | `.feature` | Findings B1–B6 → `@trace.status: approved` | PO/Dev |
+
+## 5 · Tech-Docs
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-tech-docs` | BDD approved + entity catalog | `tech-docs/{TICKET}-tech-design.md` | SA |
+| `/review-tech-docs` | tech-design | Findings đa chiều + ký T7 | SA/Lead |
+
+## 6 · Code
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
+| `/review-code` | Code | Findings (read-only) | Dev/Lead |
+| `/fix-bug` | Bug report | Fix + regression test | Dev |
+| `/map-testids` | UI code | testid map (FE) | Dev |
+| `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
+
+## 7 · Dev self-test
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/dev-gen-test` | Code + `.feature` | Bộ self-test | Dev |
+| `/dev-run-test` | Self-test | Kết quả + cột `dev_selftest` | Dev |
+| `/dev-smoke-test` | Service/app đang chạy | Kết quả smoke tại chỗ | Dev |
+
+## 8 · QC Automation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
+| `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
+| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
+| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
+| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
+| `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
+
+## 9 · Quality & Trace
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/validate-traces` | `.trace/*.tsv` + spec/code/test | Ma trận coverage · `trace-report.json` · **`trace-history.jsonl`** (append) · đếm hàng đợi | Dev/QA/Lead |
+| `/validate-traces --realign-prd-version {UC}` | cờ ⓘ `PRD_STALE_REF` | Sửa **chỉ dòng `@trace.*`** — không đụng logic | Dev |
+| `/validate-traces --realign-techdoc-revision {UC}` | cờ ⓘ `TECHDOC_STALE_REF` | như trên | Dev |
+| `/generate-spec-manifest` | Specs | Mục lục spec cho agent ngoài | SA/Lead |
+
+## 10 · Feedback & Ops
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/report-bug` | Lỗi phát hiện | `feedback/bug-reports/` (spec-anchored) | Tester/QC |
+| `/propose-scenario` | Scenario thiếu | **A:** `feedback/bdd-proposals/` → `/generate-bdd` chèn · **B:** `feedback/prd-change-requests/` → PO chạy `/extend-prd` | Tester/QC |
+| `/learn` | Định hướng lặp lại | `project-lessons.md` | Tất cả |
+| `/sync` | (umbrella) | Pull + submodule + nổi feedback + Living Docs | Lead |
+| `/update-framework` | — | Sync bản npm mới | Lead |
+
+---
+
+## Ký hiệu trạng thái trong report
+
+- 🛑 checkpoint (dừng, chờ `Y`) · 🔒 gate trạng thái (chặn downstream) · ⚪ read-only
+- ⚠️ cảnh báo mềm (không chặn) · ✅ pass · ❌ fail
+- 🔴 cờ **chặn PR** — `SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`. Build xanh + test từng-UC xanh **không** đủ để bỏ qua chúng.
+- 🟠 cờ drift **không chặn PR** — `PRD_DRIFT` · `BDD_DRIFT` · `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` · `TECHDOC_STALE_VS_BDD` · `DESIGNSPEC_DRIFT` · `DESIGNSPEC_STALE_VS_BDD`. *"Code chưa theo kịp spec"*, khác *"code đang hỏng"*. **Hết cờ 🔴 ≠ sạch.**
+- ⓘ cờ **không phải lỗi** — `PRD_STALE_REF` · `TECHDOC_STALE_REF` (version lệch nhưng changelog không nêu UC này → chỉ con trỏ cũ) · `SEAM_PENDING` · `STUB_PENDING` (owner chưa gen).
+
+---
+
+## CLI maintenance (không phải slash command)
+
+Chạy qua `npx @educa-corp/sdd-framework <flag>`. Tất cả **dry-run mặc định** — thêm `--apply` để thực thi.
+
+| Flag | Việc |
+|------|------|
+| `--init` | Cài/nâng cấp `.agent/` + shortcut `.claude/commands/`. Backup file bạn đã sửa sang `.agent/.overwritten-*/` và liệt kê ra |
+| `--migrate-bdd-platform` | `bdd/*.feature` phẳng → `bdd/{platform}/`. Báo `OCCUPIED` / `LOST SPEC` thay vì đoán |
+| `--migrate-specs` | Bố cục artifact-type-first cũ (`specs/prd/`, `specs/bdd/`) → feature-package |
+| `--rename-prd-files` | `prd.md` → `{TICKET-ID}-{prd-slug}.md` |
+| `--help` | Danh sách đầy đủ |
+
+Trong repo framework: `npm run build` (assemble template + chạy self-check) · `npm run self-check` (chỉ kiểm contract trace).
+
+→ [Trace Schema](trace-schema.md) · [Modules](modules.md) · [Configuration](configuration.md) · [Model Selection](model-selection.md)