@educa-corp/sdd-framework 0.2.3 → 0.2.5

package/docs/02-concepts/pipeline-steps/README.md

@@ -0,0 +1,92 @@
+[← Concepts](../) · [← Docs Home](../../)
+
+# ⭐ Pipeline Steps — Chi tiết từng bước (Step-by-step Reference)
+
+Đây là phần **lõi** của tài liệu Concepts. Mỗi trang mô tả **một bước** trong pipeline theo cùng một khuôn: bạn đưa gì vào, nhận gì ra, ai làm gì, framework xử lý ra sao, và điểm dừng của con người (HITL) nằm ở đâu.
+
+> Nếu bạn chỉ muốn nắm bức tranh lớn trước → đọc [Overview](../overview.md).
+> Nếu bạn muốn biết **vai trò của mình** đi qua những bước nào → đọc [Guides theo vai trò](../../03-guides/).
+
+---
+
+## Bản đồ pipeline (Pipeline Map)
+
+```mermaid
+flowchart TD
+    S["0 · Setup<br/>/setup-ai-first"] --> D["1 · Discovery<br/>/define-product"]
+    D --> SP["2 · Specification<br/>/generate-prd · /refine-prd · /review-context"]
+    SP --> DS["3 · Design-Spec<br/>/generate-design-spec<br/><i>(chỉ FE/App)</i>"]
+    SP --> B["4 · BDD<br/>/generate-bdd · /review-context"]
+    DS --> B
+    B --> T["5 · Tech-Docs<br/>/generate-tech-docs · /review-tech-docs"]
+    T --> C["6 · Code<br/>/generate-code · /review-code"]
+    C --> DV["7 · Dev self-test<br/>/dev-gen-test · /dev-run-test · /dev-smoke-test"]
+    DV --> Q["8 · QC Automation<br/>/qc-analyze → … → /qc-report"]
+    Q --> V["9 · Validate Traces<br/>/validate-traces"]
+    V -.->|"report-bug · propose-scenario · learn"| SP
+```
+
+**Đặc tính bất biến:** pipeline **một chiều** — output của bước N là input của bước N+1. Mỗi bước có **gate đầu vào** (validate) và **gate đầu ra** (findings/approval). Kênh feedback ngược (bước 10) **không tạo loop** mà để cải tiến spec và tri thức dự án.
+
+---
+
+## Danh sách các bước (Steps)
+
+| # | Bước | Command chính | Owner | HITL |
+|---|------|---------------|-------|:----:|
+| 0 | [Setup](00-setup.md) | `/setup-ai-first` | Admin/Lead | ⚪ một lần |
+| 1 | [Discovery](01-discovery.md) | `/define-product` | PO | 🔴 cao nhất |
+| 2 | [Specification](02-specification.md) | `/generate-prd` · `/refine-prd` · `/review-context` | PO (+SA/Dev review) | 🔴 cao |
+| 3 | [Design-Spec](03-design-spec.md) | `/generate-design-spec` | PO/PM | 🟠 vừa *(chỉ FE/App)* |
+| 4 | [BDD](04-bdd.md) | `/generate-bdd` · `/review-context` | PO (+Dev) | 🔴 cao |
+| 5 | [Tech-Docs](05-tech-docs.md) | `/generate-tech-docs` · `/review-tech-docs` | SA/Lead | 🟠 vừa |
+| 6 | [Code](06-code.md) | `/generate-code` · `/review-code` · `/fix-bug` | Dev | 🟡 mỏng |
+| 7 | [Dev self-test](07-dev-selftest.md) | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` | Dev | 🟡 mỏng |
+| 8 | [QC Automation](08-qc-automation.md) | `/qc-analyze` … `/qc-report` | QA/Tester | 🟠 vừa |
+| 9 | [Validate Traces](09-validate-traces.md) | `/validate-traces` | Dev/QA/Lead | ⚪ read-only |
+| 10 | [Feedback Loop](10-feedback-loop.md) | `/report-bug` · `/propose-scenario` · `/learn` · `/sync` | Tester/tất cả | ⚪ |
+
+> **HITL dày ở thượng nguồn, mỏng ở hạ nguồn** — vì sai ở PRD/BDD **nhân lên theo cấp số nhân** xuống code/test. Xem [Roles & HITL](../roles-and-hitl.md).
+
+---
+
+## Cách đọc mỗi trang (Page template)
+
+Mọi trang bước dùng chung các mục sau:
+
+| Mục | Trả lời câu hỏi |
+|-----|-----------------|
+| **Tóm tắt** | Bước này là gì trong một câu? Command nào? |
+| **Mục đích** (Purpose) | Tại sao bước này tồn tại? Bỏ nó thì mất gì? |
+| **Input** (Đầu vào) | Cần có gì trước khi chạy? |
+| **Output** (Đầu ra) | Chạy xong sinh ra file/trạng thái gì? |
+| **Ai làm gì** (Roles) | Con người và AI mỗi bên đảm nhận phần nào? |
+| **Câu hỏi cần trả lời** | Bước này giúp đội trả lời những câu hỏi nào? |
+| **Framework xử lý thế nào** (Mechanics) | Bên trong AI làm những gì? |
+| **HITL / Gate** | Con người dừng ở đâu, duyệt cái gì? |
+| **Anti-pattern** | Lỗi thường gặp cần tránh. |
+| **Bước tiếp theo** | Đi đâu sau khi xong. |
+
+---
+
+## Khung chung mọi command (Common Gate)
+
+Trước khi chạy phần logic riêng, **mọi** `/command` đều đi qua một **Gate** giống nhau. Hiểu Gate này một lần, bạn hiểu 90% "phần đầu" của mọi lệnh — các trang bước sẽ **không lặp lại** phần này:
+
+| Bước Gate | Làm gì | Ý nghĩa với người dùng |
+|-----------|--------|------------------------|
+| **0 · Sub-agent mode** | Nếu lệnh được gọi bởi orchestrator (payload JSON `_agent_mode`), bỏ qua phần hỏi-đáp và chạy đúng phạm vi được giao | Bạn không thấy trực tiếp — đây là cơ chế fan-out per-UC |
+| **0-B · Model check** | Khuyến nghị dùng model **Opus**. `Y` = đang dùng · `S` = bỏ qua (chấp nhận rủi ro) · khác = dừng | Checkpoint **mềm** — bảo vệ chất lượng suy luận |
+| **1 · Target file** | Xác định file mục tiêu từ `$ARGUMENTS` (path / UC-ID / ticket), hoặc liệt kê cho bạn chọn | Bạn có thể gọi lệnh không cần path — AI tự dò theo bố cục `specs/{domain}/{prd-slug}/…` |
+| **2 · Context loader** | Nạp context (rules, project-context, CLAUDE.md, entity, spec…) theo thứ tự tối ưu | "Thủ thư" chọn đúng-đủ-gọn context. Xem [Architecture](../architecture.md) |
+| **3 · CHECKPOINT** | Trình bày: target, phạm vi, file sẽ tạo/sửa → chờ bạn `Y` | Điểm dừng đầu tiên trước khi AI làm việc thật |
+
+> Các lệnh **read-only** (`/review-code`, `/validate-traces`, `/debug`) bỏ qua checkpoint ghi-file.
+
+---
+
+## Ký hiệu (Legend)
+
+- 🔴 HITL cao · 🟠 vừa · 🟡 mỏng · ⚪ không/đọc-thôi
+- 🛑 = checkpoint bắt buộc dừng · 🔒 = gate trạng thái (chặn downstream tới khi `approved`)
+- 🤖 = AI thực thi · 👤 = con người quyết định

package/docs/02-concepts/roles-and-hitl.md

@@ -0,0 +1,73 @@
+[← Glossary](glossary.md) · [Concepts](./) · [Traceability →](traceability.md)
+
+# Roles & HITL — Vai trò và điểm dừng con người
+
+> Ai làm gì ở mỗi giai đoạn, và tại sao điểm dừng của con người (HITL) **không cào bằng**.
+
+---
+
+## Ma trận Role × Pipeline
+
+| Role | Discovery | Specification | Design | Implementation | Dev-test | QC |
+|------|:---------:|:-------------:|:------:|:--------------:|:--------:|:--:|
+| **PO / Business** | 🟢 Lead | 🟢 Lead | 🟡 Review | ⚪ | ⚪ | 🟡 Review gap |
+| **SA / Architect** | 🟡 Consult | 🟡 Review (SA lens) | 🟢 Lead (tech-docs) | 🟡 Review | ⚪ | ⚪ |
+| **QA / Tester** | 🟡 Consult | 🟡 Feedback | 🟡 Review | 🟡 Review | 🟡 | 🟢 Lead (qc-*) |
+| **Dev** | ⚪ | 🟡 Review (DEV lens) | 🟡 Review | 🟢 Lead (code) | 🟢 Lead | 🟡 Triage |
+| **AI Agent** | 🤖 Co-pilot | 🤖 Draft PRD/BDD | 🤖 Draft design/tech | 🤖 Generate code | 🤖 Run smoke | 🤖 Run Playwright |
+
+🟢 Lead · 🟡 Consult/Review · ⚪ Không tham gia · 🤖 AI thực thi (luôn dưới HITL)
+
+---
+
+## Mật độ HITL (HITL Density)
+
+**Rule vàng:** sai ở thượng nguồn nhân lên cấp số nhân → checkpoint **dày** ở spec/design, **mỏng** ở code/test.
+
+```
+Discovery ████████████  🔴 cao nhất — chốt từng chặng
+PRD       ██████████    🔴 review-context sạch critical + approve
+BDD       █████████     🔴 UC decomposition + findings B1–B6
+Tech-Docs ██████        🟠 review đa chiều + ký T7
+Code      ███           🟡 comprehension checkpoint
+Dev-test  ██            🟡 dev tự chạy
+QC        █████         🟠 cổng review test & script
+```
+
+---
+
+## Hai loại điểm dừng (Checkpoint vs Gate)
+
+| | Checkpoint (🛑) | Gate (🔒) |
+|---|---|---|
+| **Cơ chế** | AI trình output, hỏi `Y/N` | Field trạng thái do người đặt |
+| **Ví dụ** | UC decomposition, comprehension | `Status: approved`, `@trace.status: approved` |
+| **Chặn downstream?** | Không — chỉ dừng tại chỗ | Có — chặn tới khi `approved` |
+
+> **Gate = trạng thái, không phải lệnh.** Không có `/approve-prd` — "duyệt" là người đặt `| Status | approved |` trong Metadata PRD (hoặc `@trace.status: approved` trong `.feature`).
+
+---
+
+## Nguyên tắc thiết kế checkpoint
+
+1. **Tường minh** — marker thống nhất (🛑/CHECKPOINT) để AI không "trượt qua".
+2. **Hỏi đúng câu** — không "OK chưa?" mà *"UC list đủ chưa? thiếu/thừa UC nào?"*.
+3. **Short-circuit** — AI tự detect không có gap thì được skip, nhưng phải nêu lý do.
+4. **Save state** — workflow dài (Discovery 8 chặng) lưu state để resume.
+5. **Reject = học** — con người sửa → cân nhắc `/learn` ghi lesson.
+
+---
+
+## Anti-pattern (cần tránh)
+
+- ❌ AI đi thẳng từ "ý tưởng" tới code, bỏ qua PRD/BDD.
+- ❌ Sinh code khi BDD còn `draft`.
+- ❌ Checkpoint chỉ "confirm Y/N" mà không trình output cụ thể.
+- ❌ Đưa chi tiết kỹ thuật vào PRD/BDD (sai altitude).
+- ❌ AI tự fix tự review — lặp lỗi; review là **read-only**.
+
+---
+
+## Đọc theo vai trò của bạn (Role Guides)
+
+→ [Product Owner](../../03-guides/product-owner.md) · [Developer](../../03-guides/developer.md) · [Architect](../../03-guides/architect.md) · [Tester/QA](../../03-guides/tester-qa.md)

package/docs/02-concepts/traceability.md

@@ -0,0 +1,94 @@
+[← Roles & HITL](roles-and-hitl.md) · [Concepts](./) · [Architecture →](architecture.md)
+
+# Traceability — Truy vết đầu-cuối (End-to-end Trace)
+
+> Từ scenario nhìn xuống biết code nào hiện thực; từ code nhìn lên biết scenario nào yêu cầu. Đây là một trong ba "trái tim" của framework.
+
+---
+
+## Trace tags theo artifact
+
+| Artifact | Trace tag |
+|----------|-----------|
+| **BDD scenario** | `@trace.id` · `@trace.scenario` · `@trace.business_rules` · `@trace.bdd_version` · `@trace.prd_version` |
+| **Code** (boundary only) | `@trace.implements` · `@trace.source` — *KHÔNG lưu version* (tránh dual SSOT) |
+| **Test** | `@trace.verifies` · `@trace.covers` |
+| **Bug fix** | `@trace.fixes` · `@trace.root_cause` · `@trace.regression` |
+
+→ Đầy đủ field & format: [Reference › Trace Schema](../04-reference/trace-schema.md).
+
+---
+
+## Boundary-only tagging
+
+Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag explosion**:
+
+| ✅ Tag | ❌ Không tag |
+|--------|-------------|
+| Controller / Handler / Middleware / Steps file | Entity / Repository / DTO / Interface / Base class |
+
+> Shared code (entity, repo) được dò qua **import chain** từ boundary — không cần tag riêng.
+
+---
+
+## Trace state — file `.tsv`
+
+`.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — mỗi UC × platform một sổ. Trong umbrella, nằm ở **spec repo dùng chung** (một nơi authoritative để PM/PO quản lý).
+
+| Cột | Chủ sở hữu | Ý nghĩa |
+|-----|-----------|---------|
+| `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
+| `implemented_by` | `/generate-code` | File code hiện thực SC |
+| `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
+| `qc_status` | `/qc-run-test`, `/report-bug` | Trạng thái QC **chính thức** (Playwright) |
+| `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
+| `gen_ver` | `/generate-code` | Version lúc sinh code (so với `spec_ver`) |
+| `test_count` | test | Số test phủ SC |
+| `last_updated` | nhiều | Mốc cập nhật |
+
+> **`dev_selftest` ≠ `qc_status`.** Dev smoke (nhanh, tự kiểm) và QC chính thức (Playwright, evidence) là **hai trục độc lập** — không lấn quyền nhau.
+
+---
+
+## Phân loại coverage (Coverage Status)
+
+`/validate-traces` phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+
+| # | Trạng thái | Điều kiện | Hành động |
+|---|-----------|-----------|-----------|
+| 1 | **UNTRACKED** | `gen_ver == —` | Chưa sinh code → `/generate-code` |
+| 2 | **DRIFT** | có code **và** `spec_ver != gen_ver` | Spec đổi → **regen trước khi test** |
+| 3 | **GAP** | có code **và** `test_count == — / 0` | Có code, chưa test → bù test |
+| 4 | **OK** | version khớp, có code, có test | Đủ phủ |
+
+> **DRIFT xét trước GAP:** SC có code + chưa test + spec vừa drift phải hiện `DRIFT` (không phải `GAP`) — vì `/generate-code` xử GAP = "skip codegen" còn DRIFT = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua.
+
+---
+
+## Single SSOT cho version
+
+- **Version chỉ ở spec level** (`bdd_version`/`prd_version`). Code **không** lưu version riêng — nó dùng `.tsv` (`gen_ver`) để so.
+- Lưu version cả spec lẫn code = **dual SSOT** → drift không đáng tin.
+
+---
+
+## Luồng truy vết (Trace Flow)
+
+```mermaid
+flowchart LR
+    PRD["PRD<br/>prd_version"] --> BDD["Scenario<br/>@trace.id + bdd_version"]
+    BDD --> CODE["Code boundary<br/>@trace.implements/source"]
+    CODE --> TEST["Test<br/>@trace.verifies"]
+    BDD -.-> TSV[".tsv state<br/>status/gen_ver/qc_status"]
+    CODE -.-> TSV
+    TEST -.-> TSV
+    TSV --> VM["/validate-traces<br/>Coverage Matrix"]
+```
+
+---
+
+## Đọc tiếp (Next)
+
+- [Architecture](architecture.md) — 3 lớp & context-loader
+- [Pipeline › Validate Traces](pipeline-steps/09-validate-traces.md) — dùng ma trận coverage
+- [Reference › Trace Schema](../04-reference/trace-schema.md) — field đầy đủ

package/docs/03-guides/architect.md

@@ -0,0 +1,98 @@
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Architect / SA
+
+> Bạn **sở hữu bức tranh kiến trúc** (`architecture.md`), **quyết trade-off thiết kế** và **chốt contract giữa các team**. Vai trò nặng ở **Kiến trúc nền** + **Tech-Docs**, cộng lăng kính SA khi review PRD.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/generate-architecture<br/>🟢 SSOT nền · 1 lần + refresh"] --> R["/refine-prd<br/>🟡 SA lens"]
+    R --> T["/generate-tech-docs<br/>🟢 Lead"]
+    T --> RT["/review-tech-docs<br/>🟢 + ký T7"]
+    RT --> C["/review-code<br/>🟡 khi cần"]
+```
+
+`/generate-architecture` là **bước nền một-lần** (rồi refresh khi kiến trúc đổi) — nằm ngoài vòng lặp per-feature, nhưng là thứ mọi tech-design về sau bám vào.
+
+---
+
+## Kiến trúc nền — `architecture.md` (bạn sở hữu)
+
+`architecture.md` là **nguồn chân lý (SSOT) kiến trúc cắt ngang** toàn hệ thống. `/generate-tech-docs` nạp nó để tech-design bám đúng kiến trúc thật, thay vì mỗi feature tự suy một kiểu.
+
+**Bạn KHÔNG điền tay 140 ô.** Chạy `/generate-architecture` — lệnh tự lo phần nặng, bạn chỉ **verify**:
+
+1. **Tự hút cái đã biết** — đọc `project-context.yaml` + `CLAUDE.md`, tài liệu có sẵn (`--from=docs/**/*.md`), và scan code (brownfield). Điền sẵn tối đa.
+2. **Chỉ hỏi cái chưa biết** — phỏng vấn bằng **câu dễ hiểu** (có ví dụ, Có/Không), và **bỏ qua** mọi câu đã có đáp án từ bước 1. Nếu còn mơ hồ, nó **đào sâu** đúng chỗ đó tới khi đủ để viết — bạn luôn gõ được *"để sau"* để hoãn.
+3. **Bạn verify** — mở file, sửa chỗ AI đoán sai (đối chiếu `<!-- nguồn -->`), rồi đổi `verified_by: AI-draft` → **tên bạn**. Chỉ khi đó doc mới thành **ràng buộc kiến trúc chính thức**; còn `AI-draft` thì tech-docs vẫn dùng nhưng gắn ⚠️.
+
+**Phân tầng (tier) — điền có ưu tiên, khỏi ngộp:**
+
+| Tier | Nghĩa | AI nạp khi sinh code? |
+|------|-------|----------------------|
+| **core** | Nền mọi feature cần (Tech Stack · Tầng · Đặt tên · API · DB) | ✅ |
+| **conditional** | Chỉ khi hệ thống có (Multi-tenant, Event Bus, Sharding, Auth…) | ✅ nếu bật; nếu không → để **STUB** |
+| **ops** | Vận hành, chỉ người đọc (Observability, Deploy, NFR…) | ❌ (không làm nhiễu context) |
+
+**Điền dần & làm mới:**
+- `/generate-architecture --section=multi-tenant` — lấp/refresh **đúng một mục** đang STUB, không phải làm lại cả file.
+- `/generate-architecture --from=<paths>` — nạp thêm tài liệu có sẵn để hút nội dung.
+- Chạy lại bất cứ lúc nào để **refresh**; nếu file đã verify, lệnh chỉ đề xuất **drift** (không đè bản bạn đã duyệt).
+- **Umbrella:** kiến trúc là code-level → chạy `/generate-architecture {service-path}` cho từng service.
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Bước | Bạn làm gì |
+|------|-----------|
+| Kiến trúc nền | `/generate-architecture` → **verify** `architecture.md` (đổi `verified_by` thành tên bạn). Refresh khi kiến trúc đổi |
+| Review PRD | Lăng kính **SA** trong `/refine-prd` — đọc PRD bằng **mắt kiến trúc** nhưng viết lại bằng **lời nghiệp vụ** (rủi ro, phụ thuộc, nhất quán hệ thống) |
+| [Tech-Docs](../02-concepts/pipeline-steps/05-tech-docs.md) | Lead `/generate-tech-docs` — chuẩn hoá entity/API/dependency; **reverse-document** khi API đã tồn tại. Nó tự nạp `architecture.md` (core+conditional) |
+| Review Tech-Docs | `/review-tech-docs` đa chiều; **ký cổng liên team T7** cho contract cross-service |
+| Code | `/review-code` khi cần soát kiến trúc |
+
+---
+
+## Nguyên tắc sống còn cho SA
+
+1. **`architecture.md` là SSOT kiến trúc** — bạn sở hữu và **verify** nó. `AI-draft` chưa verify chỉ là gợi ý; đổi `verified_by` = tên bạn để nó thành ràng buộc chính thức.
+2. **Tech-design LÀ API contract** — BE viết, FE/App đọc ở `/generate-code --phase=integration`. Chốt sai = đốt budget cả hai phía.
+3. **Một tech-design gộp full-stack cho cả PRD** (không per-UC/per-platform); §10 UC Coverage ánh xạ finding về từng UC.
+4. **Reverse-document khi API tồn tại** — mô tả as-is, không "tự chế" shape mới.
+5. **Ký T7 trước khi code** — contract cross-service phải được các team liên quan xác nhận.
+6. **Entity catalog là nguồn chân lý** — dùng nó khi sinh tech-docs để nhất quán với PRD/BDD.
+7. Với dependency cross-service → cân nhắc sinh **System BDD**.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Kiến trúc cắt ngang (tầng, multi-tenant, nguồn dữ liệu, auth) đã được ghi & verify trong `architecture.md` chưa?
+- Mỗi UC hiện thực bằng API/endpoint/DTO nào?
+- Entity/field/quan hệ/enum chuẩn là gì?
+- Contract BE↔FE có khớp & đủ cho mọi scenario không?
+- Dependency cross-service nào cần System BDD + ký T7?
+- Có trade-off kiến trúc nào PO/Dev chưa thấy?
+
+---
+
+## Anti-pattern
+
+- ❌ Để `architecture.md` mãi ở `verified_by: AI-draft` — tech-docs sẽ kế thừa giả định chưa ai xác nhận.
+- ❌ Điền tay cả template từ giấy trắng thay vì để `/generate-architecture` hút từ config/tài liệu/code.
+- ❌ Tự chế shape DTO/endpoint khi API đã tồn tại.
+- ❌ Bỏ cổng ký T7 → hai team hiểu contract khác nhau, rework tốn kém.
+- ❌ Đưa chi tiết kỹ thuật vào PRD khi review (SA lens viết bằng lời nghiệp vụ).
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/generate-architecture` · `/generate-tech-docs` · `/review-tech-docs` · `/refine-prd` (SA lens) · `/review-code` · `/generate-spec-manifest`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Architecture](../02-concepts/architecture.md)

package/docs/03-guides/developer.md

@@ -0,0 +1,76 @@
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Developer (FE / BE / App)
+
+> Bạn **nhận spec đã duyệt và sinh code từ nó**. Code là *hệ quả của spec*, không phải nguồn. Vai trò của bạn nặng ở **hạ nguồn** (Code → Dev-test) + review lăng kính DEV ở thượng nguồn.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    R["/refine-prd · /review-context<br/>🟡 DEV lens"] --> G["/generate-code<br/>🟢 Lead"]
+    G --> RC["/review-code<br/>🟡 read-only"]
+    RC --> T["/dev-gen-test → /dev-run-test<br/>🟢 Lead"]
+    T --> S["/dev-smoke-test<br/>🟢"]
+    S --> FX["/fix-bug<br/>🟢 khi có bug"]
+```
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Bước | Bạn làm gì |
+|------|-----------|
+| Review upstream | Lăng kính **DEV** trong `/refine-prd` — bắt chỗ mơ hồ khó hiện thực |
+| [Code](../02-concepts/pipeline-steps/06-code.md) | Chạy `/generate-code`; xác nhận **comprehension checkpoint** (drift new/drifted/synced); đảm bảo build pass |
+| Review code | `/review-code` (read-only) — soát kỹ, **không auto-fix** |
+| [Dev self-test](../02-concepts/pipeline-steps/07-dev-selftest.md) | `/dev-gen-test` → `/dev-run-test` (set `dev_selftest`) → `/dev-smoke-test` |
+| [Bug fix](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/fix-bug` — root cause → sửa → regression test |
+
+---
+
+## Nguyên tắc sống còn cho Dev
+
+1. **Không sinh code cho file không có `.feature` backing** (ngoài fix-bug/debug).
+2. **Boundary-only tagging** — tag `@trace.implements` ở controller/handler, không tag entity/repo.
+3. **Scope Lock** — chỉ implement UC target; code UC khác trong file dùng chung là **bất khả xâm phạm**. Đọc `@trace.implements` để bảo toàn, đừng xoá.
+4. **Version chỉ ở spec** — code không lưu version; drift dò qua `.tsv`.
+5. **Build phải pass** trước commit (`{conventions.build_command}`, ≤3 retry).
+6. `CLAUDE.md` (§2 layer/package, §3 coding standards, §5 error handling) là nguồn — AI *follow*, bạn giữ nó cập nhật.
+
+---
+
+## Frontend: hai phase
+
+| Phase | Khi nào | Việc |
+|-------|---------|------|
+| `--phase=ui` | BE contract chưa sẵn | Sinh UI + layer **mock API** từ System BDD |
+| `--phase=integration` | BE contract `approved` | Nối vào contract thật (đọc tech-design từ spec repo) |
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- SC nào **mới / drifted / synced** so với lần sinh trước?
+- Code theo **layer/package/convention** nào của stack này?
+- Contract (DTO/endpoint/error) lấy từ đâu — tech-design §4 hay System BDD?
+- Build pass chưa? Smoke pass chưa?
+
+---
+
+## Anti-pattern
+
+- ❌ Tag `@trace` mọi file → tag explosion.
+- ❌ Tái tạo file dùng chung "chỉ gồm scenario UC này" → xoá nhầm nghiệp vụ UC khác.
+- ❌ Coi `dev_selftest` thay QC chính thức.
+- ❌ Để AI tự review code nó vừa sinh.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/generate-code` · `/review-code` · `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` · `/fix-bug` · `/map-testids` · `/debug`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)

package/docs/03-guides/product-owner.md

@@ -0,0 +1,68 @@
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Product Owner / BA
+
+> Bạn **định nghĩa cái gì đáng làm**. Vai trò của bạn nặng nhất ở **thượng nguồn** (Discovery → PRD → BDD) — nơi sai một ly đi một dặm.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/define-product<br/>🟢 Lead"] --> B["/generate-prd<br/>🟢 Lead"]
+    B --> C["/refine-prd<br/>🟢 accept findings"]
+    C --> D["/review-context PRD<br/>🔒 approve"]
+    D --> E["/generate-design-spec<br/>🟡 review (FE/App)"]
+    E --> F["/generate-bdd<br/>🟢 UC decomposition"]
+    F --> G["/review-context BDD<br/>🔒 approve"]
+```
+
+Sau khi BDD `approved`, bạn bàn giao xuống Dev/SA — nhưng vẫn nhận **product-gap** từ QC.
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Bước | Bạn làm gì | Quyết định |
+|------|-----------|------------|
+| [Discovery](../02-concepts/pipeline-steps/01-discovery.md) | Trả lời Q&A 8 chặng, **chốt từng chặng** | Vấn đề, user, UC, BR, AC, edge case, scope |
+| [Specification](../02-concepts/pipeline-steps/02-specification.md) | Duyệt PRD draft; **accept/reject từng finding** của `/refine-prd`; đặt `Status: approved` | Scope & terminology đúng chưa |
+| [Design-Spec](../02-concepts/pipeline-steps/03-design-spec.md) | Review spec visual bám Figma (FE/App) | Visual khớp intent |
+| [BDD](../02-concepts/pipeline-steps/04-bdd.md) | Chốt **UC decomposition**; đặt `@trace.status: approved` | Cấu trúc UC/SC đúng |
+| [QC](../02-concepts/pipeline-steps/08-qc-automation.md) | Nhận **product-gap**, quyết ưu tiên sửa | Gap nào là lỗi sản phẩm |
+
+---
+
+## Nguyên tắc sống còn cho PO
+
+1. **Viết thuần ngôn ngữ nghiệp vụ** — đừng nhét API/retry/timeout vào PRD/BDD. Business Language Guard sẽ chặn, nhưng bạn nên tự giữ altitude.
+2. **Bốn ngăn không lộn**: AC (nghiệm thu) · BR/BL (cơ chế) · Scope (ranh giới) · Dictionary (định nghĩa).
+3. **Gate là trạng thái, không phải lệnh** — "duyệt" = bạn tự đặt `| Status | approved |`. Chỉ đặt khi **sạch finding critical**.
+4. **Chốt từng chặng, đừng "để AI tự hiểu"** — AI sẽ suy diễn và bạn trả giá ở downstream.
+5. Khi bạn sửa cùng một kiểu nhiều lần → gợi ý team `/learn` để ghi lesson.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Tính năng này giải quyết pain point gì? Cho ai?
+- Gồm những UC/BR/AC nào? Edge case nào?
+- Cái gì **trong** scope, cái gì **ngoài**?
+- Mỗi scenario BDD có phủ đúng một AC/BR không?
+
+---
+
+## Anti-pattern
+
+- ❌ Đặt `approved` khi còn finding critical → phá gate, code rác.
+- ❌ Bỏ `/refine-prd` "vì PRD trông ổn".
+- ❌ Nhảy từ ý tưởng thẳng sang yêu cầu Dev code.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/define-product` · `/generate-prd` · `/refine-prd` · `/review-context` · `/generate-design-spec` · `/generate-bdd`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Glossary](../02-concepts/glossary.md)

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

@@ -0,0 +1,70 @@
+[← 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)