@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/docs/05-reference/command-cheatsheet.md

@@ -1,147 +0,0 @@
-[📚 Docs](../README.md) › [Reference](README.md) › Command Cheat-Sheet
-
-# Command Cheat-Sheet — luồng & chọn lệnh
-
-> Bối rối không biết **chạy lệnh nào, theo thứ tự nào, ai chạy**? Trang này là bản đồ 1 trang. Chi tiết Input/Output từng lệnh: [Command Reference](commands.md).
-
-- [Luồng end-to-end (ai chạy gì)](#luồng-end-to-end-ai-chạy-gì)
-- [Tôi muốn REVIEW thứ này → dùng lệnh nào?](#tôi-muốn-review-thứ-này--dùng-lệnh-nào)
-- [Vòng review chuẩn: 3 bước (review → Board → resume)](#vòng-review-chuẩn-3-bước-review--board--resume)
-- [Giải mã flag: mặc định vs --fix vs --resume](#giải-mã-flag-mặc-định-vs---fix-vs---resume)
-- [QC pipeline — 6 bước tuần tự](#qc-pipeline--6-bước-tuần-tự)
-- [dev-* vs qc-* — đừng nhầm](#dev--vs-qc---đừng-nhầm)
-
----
-
-## Luồng end-to-end (ai chạy gì)
-
-Mỗi mũi tên = "xong cái trước mới sang cái sau". Nhãn dưới mỗi lệnh là **vai trò** chạy nó.
-
-```mermaid
-flowchart LR
-  A["/define-product<br/><b>PO</b>"] --> B["/generate-prd<br/><b>PO</b>"]
-  B --> C["/refine-prd<br/><b>PO</b> + Board"]
-  C --> D["/review-context (PRD)<br/><b>PO</b> · cổng chất lượng"]
-  D -->|"PO đặt Status: approved"| E["/generate-design-spec<br/><b>PO</b> (chỉ FE/App)"]
-  E --> F["/generate-bdd<br/><b>PO</b> · web→app→system"]
-  F --> G["/review-context (BDD)<br/><b>SA/Dev</b>"]
-  G -->|"đặt @trace.status: approved"| H["/generate-tech-docs<br/><b>Dev</b> · BE trước, FE sau"]
-  H --> I["/review-tech-docs<br/><b>Dev</b> + Board"]
-  I --> J["/generate-code<br/><b>Dev</b>"]
-  J --> K["/review-code<br/><b>Dev</b> · 4 lens"]
-  K --> L["/dev-gen-test → /dev-run-test<br/><b>Dev</b> · self-check"]
-  L --> M["/qc-* (6 bước)<br/><b>QC/Tester</b>"]
-  M --> N["/validate-traces<br/><b>Tech Lead</b>"]
-```
-
-> **BE bỏ qua Design Spec** (bước E) — đọc PRD trực tiếp rồi `/generate-bdd`. **Full-stack/không tách mock** → `/generate-code` một lần (bỏ qua FE 2-phase). Cross-cutting (`/sync`, `/fix-bug`, `/debug`, `/learn`, `/report-bug`, `/propose-scenario`) chạy bất cứ lúc nào, không nằm trong chuỗi này.
-
-<details>
-<summary>Bản text (ASCII fallback)</summary>
-
-```
-PO ───────────────────────────────────────────────────────────────────────────
-  /define-product → /generate-prd → /refine-prd → /review-context(PRD) → PO đặt Status: approved
-                                                   → /generate-design-spec (FE/App)
-                                                   → /generate-bdd (web→app→system)
-SA/Dev ────────────────────────────────────────────────────────────────────────
-  /review-context(BDD) → đặt @trace.status: approved → /generate-tech-docs → /review-tech-docs
-                       → /generate-code → /review-code → /dev-gen-test → /dev-run-test
-QC/Tester ──────────────────────────────────────────────────────────────────────
-  /qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
-Tech Lead ──────────────────────────────────────────────────────────────────────
-  /validate-traces
-```
-</details>
-
----
-
-## Tôi muốn REVIEW thứ này → dùng lệnh nào?
-
-Có **4 lệnh review** cho **4 loại artifact khác nhau**. Đây là điểm hay nhầm nhất:
-
-| Tôi muốn review… | Cách dùng (ví dụ) | Nó kiểm cái gì | Ai chạy |
-|---|---|---|---|
-| **PRD — nội dung & độ đầy đủ** | `/refine-prd specs/auth/login/{TICKET-ID}-login.md` | 3 lens DEV·SA·PO (đọc bằng mắt kỹ thuật, viết bằng lời nghiệp vụ): luồng đủ rõ để build chưa? nhất quán nghiệp vụ? scope & mục tiêu rõ? | PO |
-| **PRD — chất lượng trước khi approve** | `/review-context specs/auth/login/{TICKET-ID}-login.md` | P-checks: banned term, mơ hồ, mâu thuẫn PRD khác, thiếu section, routing theo `Domain` (bảng Metadata) | PO |
-| **BDD `.feature`** | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | B-checks: mỗi AC/BR → có ≥1 scenario? Gherkin R1–R10, compliance C1–C5 | SA/Dev |
-| **Tech design** | `/review-tech-docs specs/auth/login/tech-docs/FEAT-01-tech-design.md` | T-checks: đúng layer/architecture, entity, trace BDD, cross-team API sign-off | Dev/SA |
-| **Code** | `/review-code FEAT-01-UC1` | 4 lăng kính: Traceability · Layer Architecture · Coding Standards · Spec Compliance | Dev |
-
-> **Vì sao PRD có 2 lệnh review?** `/refine-prd` làm **trước** (cải thiện nội dung, fan-out 3 lens). `/review-context` làm **sau** như **cổng chất lượng cuối** trước khi approve + sang BDD. Thứ tự: `generate-prd → refine-prd → review-context → approve`.
->
-> **Vì sao `/review-context` dùng cho cả PRD lẫn BDD?** Nó tự nhận loại theo file: `.md` ở gốc feature folder → PRD mode (P-checks); `.feature` → BDD mode (B-checks). Cùng một "cổng chất lượng", hai bộ tiêu chí.
-
----
-
-## Vòng review chuẩn: 3 bước (review → Board → resume)
-
-Mọi lệnh review (`/refine-prd`, `/review-context`, `/review-tech-docs`) đều chạy **cùng một vòng 3 bước**. Lệnh review **không sửa file** — nó chỉ ghi ra findings; bạn duyệt ở Review Board; rồi `--resume` mới áp dụng.
-
-```
-①  /refine-prd {file}                 ②  Mở Review Board (extension)        ③  /…  --resume {file}
-   ───────────────────────────           ──────────────────────────────        ──────────────────────────
-   PHÂN TÍCH (read-only)        →         DUYỆT từng finding:            →       ÁP DỤNG cái đã accept
-   ghi .agent/review/                     ✓Accept ✎Modify ⏸Defer ✗Reject        + bump version + reset draft + changelog
-   {slug}-findings.yaml                   💬 Giải thích (nếu khó hiểu)
-```
-
-- **① không đụng vào file gốc.** An toàn chạy bất cứ lúc nào.
-- **② Review Board** = panel của extension *Spec Driven Docs Tools*. Right-click file `*-findings.yaml` → Open Review Board, hoặc bấm thông báo khi findings vừa tạo. Finding khó hiểu → bấm **💬 Giải thích** (no-tech + đề xuất phương án, chờ confirm).
-- **③ `--resume`** đọc các finding `accepted`/`modified` và áp vào file gốc, rồi bump version. Nút **⚡ Apply** trên Board tự chạy đúng lệnh `--resume` này cho bạn.
-
----
-
-## Giải mã flag: mặc định vs --fix vs --resume
-
-Cùng một lệnh `/review-context` (và họ review nói chung) có **3 chế độ**. Đây là khác biệt:
-
-| Chế độ | Lệnh | Làm gì | Khi nào |
-|---|---|---|---|
-| **Phân tích** (mặc định, không flag) | `/review-context {file}` | Chỉ phân tích → ghi findings. **Không sửa file.** | Bước ① mọi vòng review |
-| **`--fix`** | `/review-context --fix {file}` | Phân tích **rồi tự áp ngay** các finding `auto_fixable` (banned term, metadata, coverage matrix…). Bỏ qua Board. | Dev muốn dọn nhanh lỗi máy-sửa-được, không cần người quyết |
-| **`--resume`** | `/review-context --resume {file}` | **Không phân tích lại.** Đọc findings file, áp các finding **người đã accept** ở Board. | Bước ③ sau khi duyệt ở Board |
-
-> **Nhớ nhanh:** `--fix` = "máy tự sửa cái an toàn **ngay**" · `--resume` = "áp cái **tôi đã duyệt**". Không flag = "chỉ xem, đừng động vào file".
-
----
-
-## QC pipeline — 6 bước tuần tự
-
-QC là **chuỗi 6 lệnh chạy theo thứ tự** sau khi BDD `@trace.status: approved`. Output bước trước là input bước sau:
-
-```
-/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
-   scope         test         test-case        duyệt        chạy +          report
-   + gaps        plan         chi tiết         TC/script    qc_status       HTML
-```
-
-| # | Lệnh | Ra cái gì |
-|---|---|---|
-| 1 | `/qc-analyze` | `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md` |
-| 2 | `/qc-plan` | `TEST_PLAN.md` (scope, layer, ưu tiên) |
-| 3 | `/qc-design-test` | `test-cases/*.Test.md` |
-| 4 | `/qc-review` | Verdict APPROVED / NEEDS_FIX (inline) |
-| 5 | `/qc-run-test` | Script Python + ghi `qc_status` vào trace TSV |
-| 6 | `/qc-report` | `report.html` (Playwright trace + pytest-html) |
-
-> Chi tiết: [chương QC Automation](../02-guides/tester/qc-automation.md). Stack `qc-playwright`, độc lập với module code của dev.
-
----
-
-## dev-* vs qc-* — đừng nhầm
-
-Hai luồng test **tách biệt**, ghi **hai cột khác nhau** trong trace TSV:
-
-| | `/dev-*` (dev self-check) | `/qc-*` (QC chính thức) |
-|---|---|---|
-| Ai chạy | **Dev** — tự kiểm code mình | **QC/Tester** |
-| Lệnh | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` | `/qc-analyze` … `/qc-report` (6 bước) |
-| Ghi signal | `dev_selftest` (pass/fail/not_run) | `qc_status` (pass/fail/skip/not_run) |
-| Là coverage chính thức? | **KHÔNG** — chỉ tín hiệu "dev đã smoke" | **CÓ** — coverage authoritative |
-
-> Cả hai hiển thị **cạnh nhau** trong Living Docs. `dev_selftest: pass` **không** thay thế QC. Xem [Traceability](../03-concepts/traceability.md#hai-tín-hiệu-test-dev_selftest-vs-qc_status).
-
----
-
-*Xem thêm:* [Command Reference (chi tiết)](commands.md) · [Concepts › Pipeline](../03-concepts/pipeline.md) · [Developer › Workflow](../02-guides/developer/workflow.md)

package/docs/05-reference/commands.md

@@ -1,234 +0,0 @@
-[📚 Docs](../README.md) › [Reference](README.md) › Command Reference
-
-# Command Reference
-
-> Mọi slash command của framework, gom theo phase. Mỗi command kèm **Cách dùng (ví dụ cụ thể)**, **Output**, và **When to use**. Phần cuối mô tả **Command Internals** — kiến trúc step file dùng chung bởi mọi command.
->
-> Ví dụ dùng chung một feature xuyên suốt: domain `auth`, ticket `FEAT-01`, use case `FEAT-01-UC1` (đăng nhập). Thay bằng file/UC-ID của bạn.
-
----
-
-## Mục lục
-
-- [Setup & Maintenance](#setup--maintenance)
-- [Phase 1 — Discovery](#phase-1--discovery)
-- [Phase 2 — PRD](#phase-2--prd)
-- [Phase 2b — Design Spec (FE/App)](#phase-2b--design-spec-feapp)
-- [Phase 3 — BDD Spec](#phase-3--bdd-spec)
-- [Phase 4 — Tech Design](#phase-4--tech-design)
-- [Phase 5 — Code](#phase-5--code)
-- [Phase 6 — Dev Self-Check](#phase-6--dev-self-check)
-- [Phase 6b — QC Automation (official QC suite)](#phase-6b--qc-automation-official-qc-suite)
-- [Phase 7 — Traceability Audit](#phase-7--traceability-audit)
-- [Phase 8 — Tester / QC Feedback](#phase-8--tester--qc-feedback)
-- [Debugging & Cross-cutting](#debugging--cross-cutting)
-- [Command Internals — Step Architecture](#command-internals--step-architecture)
-
-> **Lưu ý số phase:** README dùng cả "Phase 5b / Phase 6b" (sơ đồ workflow) và "Phase 6b" (bảng tổng quan) cho QC Automation. Ở đây dùng nhãn **Phase 6b** cho QC suite để khớp bảng "Phase overview". Dù số khác nhau, ý nghĩa không đổi: QC suite là pipeline `/qc-*` riêng biệt với dev self-check `/dev-*`.
-
----
-
-## Setup & Maintenance
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/setup-ai-first` | `/setup-ai-first` | Project structure + config files | First-time project setup |
-| `/sync` | `/sync` | Git pull + submodule update + Living Docs sync | **Daily driver** — đồng bộ *nội dung* project (code/specs trong submodule) |
-| `/update-framework` | `/update-framework` | Refreshed `.agent/` command files from npm | **Occasionally** — nâng cấp *bản thân framework* khi có version mới |
-| `/sync-figma-components {module}` | `/sync-figma-components react` | Updated `figma-components/{module}.md` | After Figma design system changes |
-| `/sync-figma-tokens {url?}` | `/sync-figma-tokens` *(hoặc kèm URL Figma)* | Updated `figma-tokens.md` | After design token changes |
-
-> **`/sync` vs `/update-framework` là hai thứ khác nhau:**
-> - `/sync` cập nhật **nội dung project** — pull code/specs mới từ git remote + refresh Living Docs. Nguồn = git remotes của bạn. Chạy thường xuyên.
-> - `/update-framework` cập nhật **framework tooling** — refresh `.agent/commands/`, `steps/`, `modules/` lên version mới nhất. Nguồn = npm registry. Chạy hiếm. Không bao giờ đụng `project-context.yaml`, `CLAUDE.md`, domain-knowledge, hay `.trace/`.
-
----
-
-## Phase 1 — Discovery
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/define-product` | `/define-product` | `specs/product-definition/{TICKET-ID}-{slug}.md` | Starting any new feature. AI dẫn PO qua 7 phase Q&A có cấu trúc — không cần spec viết sẵn. |
-
----
-
-## Phase 2 — PRD
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/generate-prd` | `/generate-prd specs/product-definition/FEAT-01-login.md` | `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
-| `/refine-prd` | `/refine-prd specs/auth/login/{TICKET-ID}-login.md` | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 3 review lens (DEV/SA/PO) + completeness-critic loop, mở Review Board. |
-| `/refine-prd --resume` | `/refine-prd --resume specs/auth/login/{TICKET-ID}-login.md` | Applied findings + bumped version | Sau khi review trong Review Board (nút ⚡ Apply tự chạy lệnh này). |
-| `/review-context` (PRD) | `/review-context specs/auth/login/{TICKET-ID}-login.md` | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate trước Phase 3. Checks: routing P0 (umbrella), banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4), custom (P5). 0 critical → PO đặt `Status: approved`. `--fix`/`--resume` reset Status→draft khi sửa PRD. |
-| `/review-context --fix` | `/review-context --fix specs/auth/login/{TICKET-ID}-login.md` | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
-| `/review-context --resume` | `/review-context --resume specs/auth/login/{TICKET-ID}-login.md` | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
-
-> **Change Log gọn (rolling-window):** PRD chỉ giữ **5 version gần nhất** trong `# Change Log` (bảng phẳng 1 dòng/version); lịch sử cũ hơn được `/refine-prd` & `/review-context` tự dồn sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md` (thư mục con của feature-package). Nhờ vậy PRD **không phình** theo các vòng refine, Dev/QC khỏi nạp lịch sử thừa vào context. `/generate-bdd` đọc 5 row gần để bắt drift; nếu BDD cũ hơn cửa sổ này → khuyến nghị gen lại toàn bộ (F).
-
----
-
-## Phase 2b — Design Spec (FE/App)
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/generate-design-spec` | `/generate-design-spec specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md` | FE/App: sau khi PRD approved (guard mềm), trước BDD. Ghi `Built from PRD: vX` (phát hiện lỗi thời); re-run có Version Check theo PRD. PO cấp **node-level Figma frame link** (`?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, Status giữ `draft`. **Self-Review Gate** tự rà trước khi ghi; `/generate-bdd` chỉ **cảnh báo mềm** nếu design-spec chưa approved. |
-
-> BE teams bỏ qua Phase 2b — đọc PRD trực tiếp rồi `/generate-bdd`.
-
----
-
-## Phase 3 — BDD Spec
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/generate-bdd` | `/generate-bdd specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` (multi-service: `{prd-slug}/bdd/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. **Thứ tự outside-in: web → app → system**; `system` **tổng hợp từ web+app BDD** (web&app lệch contract → CHECKPOINT chọn union/platform-hint/separate-endpoints, ghi `@system.resolution:`; chỉ-BE → từ PRD). PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). FE/App: nuốt AC-UI + Screen States từ design-spec (gate approved+fresh+sanity). Proposal tester: chỉ nạp `Status: accepted` rồi lưu trữ. |
-| `/review-context` (BDD) | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `.agent/review/{uc-id}-review-bdd-findings.yaml` | Quality gate trước Phase 4. Checks: PRD coverage (mỗi AC + BR → ≥1 SC), Gherkin R1–R10, compliance C1–C5. 0 critical → đặt `@trace.status: approved`. |
-| `/review-context --fix` | `/review-context --fix specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Auto-fix terminology, metadata, coverage matrix + reset `@trace.status` & `uc_status` → draft | Dev quick-fix. |
-| `/review-context --resume` | `/review-context --resume specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | Applies accepted findings + bump bdd_version + reset `@trace.status` & `uc_status` → draft | SA review. |
-
----
-
-## Phase 4 — Tech Design
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/generate-tech-docs` | `/generate-tech-docs specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | **1 doc full-stack/PRD**: `specs/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` | After BDD approved. **Input = 1..n file BDD tech lead trỏ** (batch, cảnh báo >5), gộp vào doc chung của PRD (append qua nhiều lần chạy). Doc chứa API contract (§4.1–§4.4) + client design (§4.5 component/state/API-map/**§4.5.6 Test Selectors** per platform) + §5 sequence xuyên tầng. Brownfield (`@trace.api_source: existing`) → reverse-document phần API. |
-| `/map-testids {UC-ID}` | `/map-testids FEAT-01-UC1` | Cập nhật §4.5.6 Test Selectors trong tech-doc gộp + patch forwarding/usage-site + ghi `figma-components/{module}.md` | FE/App, cho component **reuse** / code **có sẵn** (brownfield): reverse-document id đang có, gán id còn thiếu, đảm bảo component dùng chung forward được test-id. Bổ trợ cho `/generate-tech-docs` (chỉ gán id cho code mới). |
-| `/review-tech-docs` | `/review-tech-docs specs/auth/login/tech-docs/FEAT-01-tech-design.md` | `.agent/review/{TICKET-ID}-tech-review-findings.yaml` | After generate-tech-docs — mở Review Board. Review cả doc/PRD (findings gom theo UC). |
-| `/review-tech-docs --resume` | `/review-tech-docs --resume specs/auth/login/tech-docs/FEAT-01-tech-design.md` | Applies accepted findings + bump revision | Sau khi review trong Review Board. |
-
----
-
-## Phase 5 — Code
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/generate-code` | `/generate-code specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `src/...` (tags `@trace.implements`) | After tech-design approved. Guard mềm: BDD `@trace.status` approved; FE/App design-spec approved+fresh+sanity. Default = full impl/BE. |
-| `/generate-code --phase=ui` | `/generate-code --phase=ui specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | UI + mock API adapter | FE: BE chưa sẵn sàng — sinh UI + mock adapter. Mock **shape**: BE contract nếu có (chuẩn) → else System BDD + warn; fixture values luôn từ System BDD. Tester test FE ngay được. |
-| `/generate-code --phase=integration` | `/generate-code --phase=integration specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Wires real API | FE: sau khi T7 sign-off gate approved — thay mock adapter bằng real API calls. |
-| `/review-code` | `/review-code FEAT-01-UC1` | Review report: Critical / Major / Minor | After generate-code. Check: mỗi scenario có endpoint, trace tags, layer rules, error handling khớp CLAUDE.md §5. Fix CRITICAL + MAJOR trước khi merge. |
-
----
-
-## Phase 6 — Dev Self-Check
-
-> Đây là **developer self-check / smoke** — dev tự kiểm tra code mình vừa sinh ra. **Không phải** official QC suite (đó là Phase 6b `/qc-*`). Signal = `dev_selftest`, tách biệt với `qc_status`.
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/dev-gen-test` | `/dev-gen-test specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `src/test/...` (tags `@trace.verifies`) | After generate-code. Tự chọn test framework đúng platform. |
-| `/dev-run-test` | `/dev-run-test FEAT-01-UC1` | Self-check report — ghi `dev_selftest` (pass/fail/not_run) + `dev_selftest_at` vào trace TSV | After dev-gen-test. |
-| `/dev-smoke-test` | `/dev-smoke-test FEAT-01-UC1` | Live endpoint check | Optional — sau deploy. |
-
----
-
-## Phase 6b — QC Automation (official QC suite)
-
-> Pipeline `/qc-*` **là** official QC suite. Chạy **theo thứ tự** sau khi BDD `@trace.status: approved` (review-context BDD sạch + người duyệt; `/qc-analyze` cảnh báo mềm nếu chưa). Tách biệt hoàn toàn với dev self-check: QC sở hữu `qc_status`, dev sở hữu `dev_selftest`. `/qc-run-test` & `/qc-report` dùng module `qc-playwright`, độc lập với dev implementation module. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/qc-analyze` | `/qc-analyze FEAT-01-UC1` | **2 file** trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`): `REQUIREMENT_ANALYSIS.md` (gộp requirement + BR + data-flow + AC) + `DOC_GAPS.md` | After BDD `@trace.status: approved` (guard mềm) — đầu pipeline QC. |
-| `/qc-plan` | `/qc-plan FEAT-01-UC1` | `{qc_dir}/{UC-ID}/TEST_PLAN.md` (scope, layers, priorities, questions-for-dev) | After `/qc-analyze`. |
-| `/qc-design-test` | `/qc-design-test FEAT-01-UC1` | `{qc_dir}/{UC-ID}/test-cases/*.Test.md` mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
-| `/qc-review` | `/qc-review FEAT-01-UC1` | Verdict APPROVED / NEEDS_FIX + findings (**inline — không sinh file**) | After `/qc-design-test` (test-case) hoặc `/qc-run-test` (script). |
-| `/qc-run-test` | `/qc-run-test FEAT-01-UC1` | Script Python (`pages/`, `tests/`) + ghi `qc_status` (pass/fail/skip/not_run) + `qc_run_at` vào trace TSV, keyed by `@trace.verifies={UC-ID}-SC{N}` | After `/qc-review`. |
-| `/qc-report` | `/qc-report FEAT-01-UC1` | QC report `reports/<feature>/report.html` (Playwright Trace + pytest-html) | After `/qc-run-test`. |
-
----
-
-## Phase 7 — Traceability Audit
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/validate-traces {domain}` | `/validate-traces auth` *(hoặc `/validate-traces FEAT-01-UC1`)* | Coverage matrix + drift report + `trace-report.json` | Anytime — verify traceability. Đọc mọi `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` rồi tính status OK / DRIFT / GAP / UNTRACKED. |
-
----
-
-## Phase 8 — Tester / QC Feedback
-
-> Cả hai đều **read-only trên canonical specs/code**. Chúng chỉ ghi vào `feedback/` của shared spec repo và **commit + push** → PO/Dev thấy qua `/sync`. Tester/QC không bao giờ sửa `.feature` trực tiếp. QC cũng dùng hai lệnh này: `/qc-run-test` FAIL = product-gap và `/qc-analyze` DOC_GAPS blocker đều route sang `/report-bug` hoặc `/propose-scenario` (xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md)).
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/report-bug {UC-ID} {desc}` | `/report-bug FEAT-01-UC1 "nhập sai mật khẩu vẫn đăng nhập được"` | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester hoặc QC tìm thấy bug (gồm QC product-gap). Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
-| `/propose-scenario {UC-ID} {desc}` | `/propose-scenario FEAT-01-UC1 "khoá tài khoản sau 5 lần sai mật khẩu"` | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin (mang `Status: proposed`) | Tester hoặc QC tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. Vòng đời: `proposed` → PO/Dev đặt `accepted` → `/generate-bdd` nạp rồi đặt `incorporated` + lưu trữ. |
-
----
-
-## Debugging & Cross-cutting
-
-| Command | Cách dùng (ví dụ) | Output | When to use |
-|---------|-------------------|--------|-------------|
-| `/fix-bug {BUG-ID\|ticket\|desc}` | `/fix-bug BUG-012` *(hoặc ticket / mô tả lỗi)* | Code fix trên branch + regression test; nếu nhận `{BUG-ID}` → set report State `🟢 Open` → `🟡 Fixed` (QC re-verify pass mới → `🟢 Closed`) | Khi tìm thấy bug/ticket, hoặc route một filed bug report. |
-| `/debug` | `/debug "NullPointerException ở LoginService"` | Debug session | Deep debugging. |
-| `/learn {text}` | `/learn "AI hay dùng var, phải dùng const"` | Appends guardrail vào project lessons file | Khi AI lặp lại lỗi bạn muốn chặn. |
-| `/generate-spec-manifest` | `/generate-spec-manifest` | `spec-manifest.yaml` | Sinh manifest làm entry point cho external/tester agents. |
-
-> **Project Lessons:** lessons lưu ở `paths.lessons_file` (default `specs/domain-knowledge/lessons-learned.md`; per-service `.agent/project-lessons.md` trong umbrella mode). Context-loader **Step 6.7** load mọi lesson đầu **mỗi** command như hard constraint. Đây là *project memory*, không phải fine-tuning model.
-
----
-
-## Command Internals — Step Architecture
-
-Mọi command trong `.agent/commands/` được compose từ **step file** dùng chung trong `.agent/steps/`. Các step này là nền móng — mọi command gọi chúng tuần tự trước khi chạy logic riêng.
-
-### Step files at a glance
-
-| File | Role | Called by |
-|------|------|-----------|
-| `gate.md` | Universal entry — model check, file resolution, context load, user checkpoint | Every command |
-| `context-loader.md` | Multi-step context loading (stack → service routing → service conventions → arch → safety → domain → UI → recap) | `gate.md` Step 2 |
-| `spawn-agent.md` | Sub-agent orchestration cho PRD lớn | `generate-bdd`, `generate-code`, `dev-gen-test` |
-| `capture-lesson.md` | Append/refine guardrail vào project lessons file | `learn`, `review-code`, `fix-bug`, `debug` |
-| `report-footer.md` | Standard output format (status badge, artifact list, next command) | Every command |
-
-### gate.md — Universal Entry Procedure
-
-| Step | What it does |
-|------|-------------|
-| **Step 0** | Sub-agent mode check — nếu `$ARGUMENTS` là JSON payload có `_agent_mode: true`, skip Steps 1–3 và dùng slim context trực tiếp |
-| **Step 0-B** | Model check — prompt chuyển sang `claude-opus`; `S` để skip |
-| **Step 1** | Resolve target file từ `$ARGUMENTS`; nếu thiếu, list candidates và hỏi user |
-| **Step 2** | Execute `context-loader.md` — load mọi project context vào working memory |
-| **Step 3** | CHECKPOINT — hiện summary (target file, stack, module, domains), chờ `Y` |
-
-### context-loader.md — Context Loading Sequence
-
-Load context theo thứ tự ưu tiên nghiêm ngặt (anti-lost-in-middle: facts critical load trước, RECAP restate cuối):
-
-| Step | Priority | What loads |
-|------|----------|-----------|
-| 1 | PROJECT-CONFIG | `project-context.yaml` → stack, conventions, domains, services, paths |
-| 1.5 | SERVICE ROUTING | *(umbrella only)* detect active domain, route `trace_dir` (+ code) → service submodule, store `service_root`. Khi `spec_source` set: `specs_dir` (BDD) / `tech_docs_dir` / PRD / design-spec / domain-knowledge / feedback → **spec repo** (cross-team), KHÔNG per-service |
-| 1.6 | SERVICE CONVENTIONS | *(umbrella only)* load `{service_root}/.agent/project-context.yaml` → override `test_command`, `build_command`, `paths.trace_dir` |
-| 2 | PROJECT-CONFIG | `.agent/modules/{module}/stack-profile.yaml` → framework-specific layer patterns |
-| 3 | **CRITICAL** | `CLAUDE.md` → architecture layers, coding standards, naming |
-| 4 | SAFETY | `.agent/rules/data-protection.md` → sensitive file patterns |
-| 5 | DOMAIN | `business-dictionary.md` → canonical + banned terms |
-| 6 | DOMAIN | `core-entities.md` → entity catalog |
-| 6.7 | **GUARDRAILS** | `lessons_file` → accumulated lessons (via `/learn`) as hard constraints |
-| 6-B | UI COMPONENTS | `figma-components/{module}.md` → Figma → code component + import path |
-| 6-C | UI TOKENS | `figma-tokens.md` → design tokens |
-| 7 | **RECAP** | `[CTX LOADED]` block printed để khóa critical facts vào working memory |
-
-Status values của RECAP: `FULL` · `PARTIAL — missing: {list}` · `MINIMAL` (chỉ project-context.yaml).
-
-### spawn-agent.md — Sub-Agent Orchestration
-
-Khi PRD vượt ngưỡng complexity, `generate-bdd` / `generate-code` / `dev-gen-test` tự chuyển từ single-session sang orchestration mode.
-
-| Signal | Threshold | Action |
-|--------|-----------|--------|
-| UC count in PRD | > 3 UCs | Spawn 1 sub-agent per UC |
-| PRD length | > 300 lines | Spawn agents regardless of UC count |
-
-Orchestrator: Step A build slim context JSON → Step B scan PRD → UC list → Step C announce plan → Step D spawn 1 sub-agent/UC (parallel, mỗi agent chỉ đọc UC section của mình) → Step E collect + merge results.
-
-### report-footer.md — Standard Output Format
-
-Mọi command kết thúc bằng footer: `Status` badge (`✅ Complete` · `⚠️ Warnings` · `❌ Failed`), danh sách **Output Artifacts** (created/updated), và field **Next** gợi ý command kế tiếp.
-
----
-
-*Xem thêm:* [Trace TSV Schema](trace-schema.md) · [Stack Modules](modules.md) · [02 · Guides](../02-guides/) (theo vai trò).

package/docs/05-reference/model-selection.md

@@ -1,74 +0,0 @@
-# Chọn model cho từng step (Opus vs Sonnet)
-
-> Bảng khuyến nghị model chạy cho mỗi command trong pipeline. Mục tiêu: **đặt Opus đúng chỗ đắt giá** (nơi một quyết định sai làm hỏng code/spec thật) và **để Sonnet gánh phần cơ học** (điền template, chấm luật, chạy lệnh, tổng hợp). Không phải "to hơn cho chắc" — chọn theo bản chất công việc.
-
-## Nguyên tắc chọn
-
-**Dùng Opus khi step có BẤT KỲ dấu hiệu nào dưới đây:**
-
-1. **Ghi/sửa artifact khó đảo** — code thật hoặc spec có thẩm quyền (PRD, tech-doc). Sai là mất công truy vết/khôi phục.
-2. **Phải hoà giải với bối cảnh có sẵn** — không clobber code UC khác, không đẻ package trùng, ghi **superset**. Cần giữ trạng thái hiện có trong đầu rồi suy giao phần.
-3. **Tổng hợp / khử mơ hồ** — biến input mơ hồ thành quyết định đã chốt (discovery → PRD, PRD → tech design).
-4. **Rủi ro bịa** — phải phân biệt "suy được từ nguồn" vs "khai [GAP], KHÔNG bịa". Đây là chỗ Sonnet hay tự chế cho liền mạch.
-5. **Truy nguyên nhân gốc** — debug, fix-bug: đọc triệu chứng → lần ra nguyên nhân thật.
-
-**Sonnet là đủ khi step chủ yếu là:**
-
-- Điền template theo ánh xạ nguồn→đích rõ ràng.
-- Chấm luật / checklist (trích ID vi phạm, tính status theo công thức).
-- Đọc-thuần: report, tổng hợp, bookkeeping trace/TSV.
-- Chạy lệnh và thuật lại output.
-
-> **Bằng chứng thực nghiệm:** ba bug nặng nhất của project này (clobber code UC trước, package fragmentation, hardcode) đều xảy ra ở **generate-code** khi chạy model yếu — chúng là lỗi *suy luận về bối cảnh*, không phải lỗi cú pháp. Guard cơ học (Guard sau-ghi, `_seams.tsv`, Self-Review Gate) giảm rủi ro nhưng vẫn cần model đủ sức **chủ động chấp hành**, không đọc cho có.
-
-## Bảng tra nhanh
-
-### 🔴 Opus — bước quyết định, ghi artifact khó đảo
-
-| Command | Vì sao Opus |
-|---|---|
-| `generate-code` | Ghi code thật; phải EXTEND superset (không clobber UC khác), quyết định nối hàng thật vs đẻ stub (seam), khớp package by-layer, không hardcode. Ca đắt giá nhất. |
-| `generate-tech-docs` | Tech design gộp full-stack; rủi ro bịa/thiếu cao (retro đã flag). Self-Review Gate + GAP Register chỉ hiệu quả khi model đủ sức tự bác bỏ mình. |
-| `fix-bug` | Sửa code thật theo nguyên nhân gốc; cùng rủi ro clobber như generate-code. |
-| `debug` | Truy nguyên nhân gốc từ triệu chứng — suy luận nhiều tầng. |
-| `generate-prd` | Tổng hợp discovery → PRD; khử mơ hồ, chốt scope/business rules mà hạ nguồn bám theo. |
-| `refine-prd` | Phê bình 3-lens; giá trị nằm ở chất lượng chỉ trích, không phải điền chữ. |
-| `review-tech-docs` | T1–T9 gồm reconciliation + gap-honesty; phải bắt được chỗ tech-doc bịa/thiếu. |
-| `define-product` | Đặt nền product-definition — sai lệch lan xuống toàn bộ pipeline. Ít chạy nhưng đòn bẩy cao. |
-
-### 🟡 Tùy độ phức tạp — mặc định Sonnet, nâng Opus khi domain khó
-
-| Command | Mặc định | Nâng Opus khi |
-|---|---|---|
-| `generate-design-spec` | Sonnet | Luồng UI/UX nhiều nhánh, ràng buộc trạng thái phức tạp. |
-| `generate-bdd` | Sonnet | Domain nhiều edge/nhánh lỗi khó suy từ PRD. |
-| `review-context` | Sonnet | Cần đánh giá sâu độ phủ scenario, không chỉ liệt kê. |
-| `review-code` | Sonnet | Review logic/nghiệp vụ (không chỉ chấm CV/BR style). |
-| `propose-scenario` | Sonnet | Sinh scenario cho nghiệp vụ nhiều biến thể. |
-| `qc-analyze` | Sonnet | Phân tích rủi ro test sâu, không chỉ phân loại. |
-| `qc-review` | Sonnet | Đánh giá chất lượng test-case cần suy luận. |
-
-### 🟢 Sonnet là đủ — cơ học, chấm luật, đọc-thuần
-
-| Command | Bản chất |
-|---|---|
-| `dev-gen-test` | Sinh test từ BDD — ánh xạ scenario→test khá thẳng. |
-| `dev-run-test` · `dev-smoke-test` · `qc-run-test` | Chạy test, thuật output. |
-| `qc-plan` · `qc-design-test` · `qc-report` | Điền plan/case/report theo khuôn. |
-| `map-testids` | Ánh xạ test-id. |
-| `validate-traces` | Tính status theo công thức + Seam Audit theo luật rõ. |
-| `generate-spec-manifest` | Tổng hợp manifest cơ học. |
-| `review-code` (style) | Trích ID vi phạm CV/BR — chấm luật. |
-| `sync` · `update-framework` · `setup-ai-first` | Thao tác file/scaffold theo quy trình. |
-| `report-bug` · `learn` | Điền báo cáo / tra cứu. |
-
-> **Truly trivial** (`report-bug`, `generate-spec-manifest`, `sync`): Haiku cũng chạy được nếu cần tiết kiệm — nhưng lợi ích so với Sonnet không đáng kể.
-
-## Ngoại lệ đáng nhớ
-
-- **generate-code trên greenfield cô lập → Sonnet ổn.** Khi UC đầu tiên của module trống: không sibling code, không seam ra ngoài, không EXTEND file có sẵn → không có gì để clobber. Hễ **module đã có code UC khác** (đúng tình huống segment-service) → về lại Opus.
-- **review-* nói chung**: nếu chỉ chấm checklist cơ học thì Sonnet đủ; nếu là "cổng chặn merge" mà bỏ sót gây hậu quả thật → Opus.
-
-## Tóm tắt một dòng
-
-**Ghi code/spec khó đảo hoặc phải hoà giải bối cảnh → Opus. Điền khuôn, chấm luật, chạy lệnh, tổng hợp → Sonnet.**

package/docs/05-reference/modules.md

@@ -1,110 +0,0 @@
-[📚 Docs](../README.md) › [Reference](README.md) › Stack Modules
-
-# Stack Modules
-
-> Mỗi module dưới `modules/` ship một `stack-profile.yaml` chứa layer pattern, naming rule, và test pattern riêng cho framework đó. Framework detect platform type từ `tech_stack.module` (hoặc `active_module` trong multi-service) và adapt mọi artifact sinh ra.
-
----
-
-## Mục lục
-
-- [Danh sách module](#danh-sách-module)
-- [Platform type grouping](#platform-type-grouping)
-- [qc-playwright — QC automation stack](#qc-playwright--qc-automation-stack)
-
----
-
-## Danh sách module
-
-15 module (xác minh bằng listing thư mục `modules/`):
-
-| Module | Language / Framework | Platform type |
-|--------|----------------------|---------------|
-| `java-spring` | Java + Spring Boot | backend |
-| `golang` | Go + Gin/Echo | backend |
-| `dotnet` | C# + .NET / ASP.NET Core | backend |
-| `php-laravel` | PHP + Laravel | backend |
-| `context-engineering` | Generic AI/LLM projects | backend |
-| `react` | TypeScript + React | web-frontend |
-| `nextjs` | TypeScript + Next.js | web-frontend |
-| `vue` | TypeScript + Vue 3 | web-frontend |
-| `nuxt` | TypeScript + Nuxt 3 + @nuxt/ui | web-frontend |
-| `angular` | TypeScript + Angular | web-frontend |
-| `flutter` | Dart + Flutter | mobile |
-| `react-native` | TypeScript + React Native / Expo | mobile |
-| `ios-swiftui` | Swift + SwiftUI | mobile |
-| `android-compose` | Kotlin + Jetpack Compose | mobile |
-| `qc-playwright` | Python + pytest-playwright + Page Object | QC / E2E (xem dưới) |
-
----
-
-## Platform type grouping
-
-`platform_type` được suy ra từ module và quyết định cách adapt BDD vocabulary, tech-design sections, và test templates.
-
-| `platform_type` | Modules |
-|-----------------|---------|
-| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
-| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
-| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
-
-Ví dụ adapt theo platform type:
-
-- **BDD vocabulary** — backend dùng "submits a request" / "receives response"; web dùng "clicks" / "types into" / "navigates to"; mobile dùng "taps" / "enters" / "opens".
-- **Tech-design sections** — backend: §4 API Endpoints / §5 Service Flow / §6 Data Model…; web-frontend: §4 Screen/Component Breakdown / §5 State Management…; mobile: §4 Screen/Widget Breakdown / §5 State & Data Flow….
-- **Test templates** — Java → JUnit 5 + Mockito + `@WebMvcTest`; web → Vitest/Jest + Testing Library + Playwright/Cypress; Flutter → `testWidgets`; iOS → `XCTestCase`; Android → Compose rule + `@HiltAndroidTest`.
-
----
-
-## qc-playwright — QC automation stack
-
-`qc-playwright` là **stack QC automation độc lập** với dev implementation module. Nó power native QC pipeline (`/qc-run-test`, `/qc-report`) và được chọn qua `tech_stack.qc_module` hoặc per `/qc-*` run — không phụ thuộc vào stack dev (java-spring, react, flutter…). Per-layer guides nằm ở `skills/qc/<stage>/`. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
-
-**Stack** (từ `modules/qc-playwright/stack-profile.yaml`): Python 3 + pytest-playwright + Page Object Model. Report = Playwright Trace + pytest-html (**không** dùng Allure, không hand-written dashboard, không `record_video`).
-
-**Build commands:**
-
-| Mục đích | Command |
-|----------|---------|
-| Test | `python3 -m pytest` |
-| E2E | `python3 -m pytest -m e2e` |
-| Report | `python3 -m pytest --html=reports/<feature>/report.html --self-contained-html` |
-| Show trace | `python3 -m playwright show-trace <test-results/<nodeid>/trace.zip>` |
-
-**Key architecture rules:**
-- **Markdown-first** — không sinh Python cho tới khi có `.Test.md` đã review cho feature.
-- Không hard-code URL/credential/timeout — đọc từ `Env.*` và `CONFIG[...]`.
-- Không `time.sleep()` — dùng Playwright auto-wait / `expect()`.
-- Mỗi test độc lập qua pytest-playwright fixtures (`page` / `logged_in_page` / …).
-- Page Object extends slim `BasePage`; tách 3 layer: locators `_x()`, actions `verb_noun()`, assertions `assert_x()` dùng `expect()`.
-- Locator priority: `data-testid` → role → label/text → CSS → tránh XPath.
-- Group test theo `(role, account)` để login/logout không interleave giữa các role.
-- Cover 100% TC trong `.Test.md` — mỗi TC kết thúc Pass/Fail/Skip, không để Draft.
-
-**Naming:** test case id `TC_<FEATURE>_<NNN>` · test class `TestFeatureHappyCase` · test function `test_TC<NNN>_<snake_case>` · page object `<feature>_page.py` (`<Feature>Page` extends `BasePage`).
-
-**Folder structure:**
-```
-{paths.qc_dir}/{UC-ID}/test-cases/ ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
-pages/                      ← Page Object Model (base_page.py + <feature>_page.py)
-tests/                      ← pytest scripts, 1-1 với test-cases/ (conftest.py + test_<feature>.py)
-utils/                      ← config_loader, logger, steps, test_ordering, report helpers
-test_data/                  ← JSON datasets
-config/config.yaml          ← browser, timeout, video/screenshot/trace toggles
-reports/  test-results/     ← generated (gitignored): html report, trace.zip, screenshots
-```
-
-**Test layers:** functional (gui-screen / gui-feature / api) · integration (api/db/gui/kafka) · e2e (journey) · non-functional · exploratory.
-
-**Trace tags** (map QC test về scenario, drive `qc_status`):
-```python
-# @trace.verifies={UC-ID}-SC{N}
-# @trace.source=<official .feature path>
-# @trace.test_type=functional|integration|e2e|non-functional
-```
-
-> `/qc-run-test` ghi `pass|fail|skip|not_run` + `qc_run_at` vào `{trace_dir}/{UC-ID}-{platform}.tsv` (song song với `dev_selftest`), surfaced trong Living Docs là kết quả QC automation **chính thức**. Mỗi FAIL được phân loại script-bug (fix selector/logic) vs product-gap (giữ FAIL + evidence, không bao giờ fake-pass).
-
----
-
-*Xem thêm:* [Trace TSV Schema](trace-schema.md) (`qc_status` vs `dev_selftest`) · [Command Reference](commands.md) (pipeline `/qc-*`) · [02 · Guides · QC Automation](../02-guides/tester/qc-automation.md).