@educa-corp/sdd-framework 0.2.4 → 0.2.5

package/docs/01-getting-started/installation.md

@@ -1,156 +1,91 @@
-[📚 Docs](../README.md) › [Getting Started](README.md) › Installation
+[← What is SDD](what-is-sdd.md) · [Getting Started](../README.md) · [Next: Quick Start →](quickstart.md)
 
-# Installation
+# Installation — Cài đặt & khởi tạo
 
-Cài đặt framework vào project và (tùy chọn) VS Code extension.
+> Yêu cầu: [Node.js](https://nodejs.org) (kiểm tra `node -v`) và [Claude Code](https://claude.com/claude-code).
 
-## Mục lục
-
-- [Prerequisites](#prerequisites)
-- [Cài framework](#cài-framework)
-- [Kiểm tra cài đặt](#kiểm-tra-cài-đặt)
-- [Upgrade](#upgrade)
-- [QC automation stack (tùy chọn)](#qc-automation-stack-tùy-chọn)
-- [VS Code extension (khuyến nghị)](#vs-code-extension-khuyến-nghị)
-- [Uninstall](#uninstall)
-
-## Prerequisites
-
-| Tool | Version | Link |
-|------|---------|------|
-| Node.js | bất kỳ (check: `node -v`) | [nodejs.org](https://nodejs.org) |
-| Claude Code CLI | Latest | [claude.ai/code](https://claude.ai/code) |
-| VS Code | ≥ 1.85 | [code.visualstudio.com](https://code.visualstudio.com) |
-| Git | bất kỳ | |
-
-> Claude Code cần subscription (Claude Pro / Team / API key).
+---
 
-## Cài framework
+## 1. Khởi tạo dự án (Init)
 
-Chạy từ **thư mục root của project**. Cách khuyến nghị là `--init` — cài framework vào `.agent/` (commit vào git, cả team dùng chung) và tạo shortcut trong `.claude/commands/`.
+**Single-service** (một repo, một stack):
 
 ```bash
-# Single-service project:
 npx @educa-corp/sdd-framework --init --module java-spring
+```
+
+**Multi-service monorepo** (nhiều service, nhiều stack):
 
-# Multi-service monorepo (cài vào từng subfolder trong 1 lệnh):
+```bash
 npx @educa-corp/sdd-framework --init \
   --services backend:java-spring,web-admin:react,app-mobile:flutter
 ```
 
-Kết quả:
-- `.agent/` — toàn bộ framework files (commit vào git, shared với team)
-- `.claude/commands/` — shortcut trỏ về `.agent/commands/`
-- `.agent/FRAMEWORK_VERSION` — tracking version để upgrade
+**Umbrella** (nhiều service submodule + một spec repo dùng chung):
 
 ```bash
-git add .agent/ .claude/commands/
-git commit -m "chore: init spec-driven-docs"
+npx @educa-corp/sdd-framework --init --umbrella
 ```
 
-> **Multi-repo / umbrella?** Xem hướng dẫn umbrella setup chi tiết trong [Operations › Sync & Update §4 Umbrella mode](../04-operations/sync-and-update.md#4-umbrella-mode--git-submodule).
+Lệnh init sẽ:
+1. Copy framework vào `.agent/` (`commands|steps|rules|hooks|templates|skills|modules`).
+2. Deploy cấu hình Claude Code vào `.claude/`.
+3. Sinh `.agent/project-context.yaml` từ template (single/umbrella).
+4. Cài các **module stack** đã chọn.
+5. Tạo `CLAUDE.md` (root; thêm overlay theo service khi umbrella).
 
-### Legacy install (global / per-project)
-
-```bash
-npx @educa-corp/sdd-framework           # global: ~/.claude/commands/
-npx @educa-corp/sdd-framework --project # project: ./.claude/commands/
-```
+---
 
-## Kiểm tra cài đặt
+## 2. Setup trong Claude Code
 
-Mở Claude Code tại project, gõ `/` — bạn sẽ thấy các lệnh:
+Mở dự án trong Claude Code rồi chạy:
 
 ```
 /setup-ai-first
-/define-product
-/generate-prd
-/generate-bdd
-...
 ```
 
-> Không thấy lệnh? Chạy lại lệnh cài (global lưu tại `~/.claude/commands/`, trên Windows: `ls "$env:USERPROFILE\.claude\commands\"`).
-
-## Upgrade
-
-Từ **trong Claude Code** (khuyến nghị — check version, xử lý umbrella mode, review diff):
+Lệnh này dẫn qua setup một-lần: tạo thư mục, cài `CLAUDE.md`, verify môi trường, chọn mode & module. Xem chi tiết cơ chế ở [Pipeline › Setup](../02-concepts/pipeline-steps/00-setup.md).
 
-```
-/update-framework
-```
+---
 
-Hoặc từ terminal:
+## 3. Điền config (bắt buộc trước feature đầu tiên)
 
-```bash
-bash scripts/upgrade.sh
-# hoặc:
-npx @educa-corp/sdd-framework@latest --init
-git diff .agent/ && git add .agent/ && git commit -m "chore: upgrade framework"
-```
+AI *follow* các file này — để trống thì nó *đoán*:
 
-> Chỉ upgrade framework command files. `project-context.yaml`, `CLAUDE.md`, domain-knowledge, và `.trace/` không bao giờ bị ghi đè. Để sync *content* của project (submodule code/specs) dùng `/sync`.
->
-> ⚠️ **QC skills & upgrade:** `--init` / `upgrade.sh` ghi đè **toàn bộ** `.agent/` — **gồm cả** `.agent/skills/qc/`. Nếu QC chỉnh skills trực tiếp trong `.agent/skills/qc/`, các thay đổi đó **mất** khi upgrade. Để giữ an toàn, trỏ `paths.qc_skills_dir` ra một repo/submodule QC **ngoài** `.agent/` (vd `qc-base/.claude/skills`) — upgrade không bao giờ chạm tới đó. Chi tiết: [../02-guides/tester/qc-automation.md#skill-sourcing--upgrade-safety](../02-guides/tester/qc-automation.md#skill-sourcing--upgrade-safety).
+| File | Điền gì |
+|------|---------|
+| `CLAUDE.md` (root) | Luật chung dự án |
+| `{service}/CLAUDE.md` (overlay) | §2 kiến trúc & thứ tự layer · §3 coding standards · §5 error handling |
+| `.agent/project-context.yaml` | paths, mode, services, `conventions.build_command`, tech_stack |
+| `specs/domain-knowledge/` | Business dictionary, entity catalog, tri thức miền |
 
-## QC automation stack (tùy chọn)
+→ Chi tiết: [Reference › Configuration](../04-reference/configuration.md).
 
-Bộ QC suite chính thức (`/qc-*`) là **native** trong framework. Hai lệnh cuối — `/qc-run-test` và `/qc-report` — dùng stack module **`qc-playwright`**, **độc lập với dev module**. Cài riêng:
+---
 
-```bash
-# 1. Python 3 + pytest-playwright
-pip install pytest-playwright
+## 4. Bắt đầu feature đầu tiên
 
-# 2. Cài browsers
-python3 -m playwright install
 ```
-
-`qc-playwright` = Python + pytest-playwright + Page Object (output: Playwright Trace + pytest-html). Chi tiết pipeline: [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
-
-## VS Code extension (khuyến nghị)
-
-**Spec Driven Docs Tools** là VS Code extension với 2 panels. Không bắt buộc nhưng khuyến nghị. VS Code tự cập nhật khi có version mới.
-
-```bash
-code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+/define-product
 ```
 
-Hoặc: `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → search **Spec Driven Docs Tools**.
-
-### Panel 1 — Review Board
-
-Đọc `*-findings.yaml` từ `.agent/review/` — hỗ trợ findings từ mọi review command (`/refine-prd`, `/review-context`, `/review-tech-docs`).
+→ Theo [Quick Start](quickstart.md).
 
-- Lens tabs: All / QA / DEV / SA / PO hoặc PRD / BDD / TECH.
-- Mỗi finding có badge `⚡ auto-fix` / `👤 human`.
-- 4 actions: Accept · Modify (có note) · Defer · Reject — kèm progress bar, full-text search.
-- **Smart Apply** spawn terminal chạy đúng lệnh `--resume`.
-
-Mở Review Board: sidebar panel (Activity Bar), hoặc right-click file `*-findings.yaml` → "Open Review Board", hoặc Command Palette. Nếu panel trống: file phải có đuôi `-findings.yaml`, nằm trong `.agent/review/`, và đóng hẳn rồi mở lại VS Code.
-
-### Panel 2 — Living Documentation
-
-Đọc `.trace/*.tsv` — dashboard traceability health toàn project.
-
-- Stat cards: PRDs, Use Cases, Scenarios, Code Cov%, Test Cov%, Drift, Gap.
-- Drill-down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, `dev_selftest`, `qc_status`, Waiting on, Status). *Waiting on* = `qc_owner` + `qc_blocked_by` (chờ dev → `BUG-{id}` / chờ PO → `GAP-{id}`).
-- Status badges: ✅ OK · ⚠️ DRIFT · 🔴 GAP · — UNTRACKED. Filter + search + live reload.
-
-Mở: `Ctrl+Shift+P` → **"Spec Driven Docs Tools: Open Living Documentation"**. Mở được cả ở umbrella root lẫn trong một service submodule riêng lẻ. Nếu trống, chạy `/generate-bdd` cho ≥1 feature để tạo file `.trace/{UC-ID}-{platform}.tsv` đầu tiên.
+---
 
-> Report canonical sinh vào spec module tại `{spec_source}/.living-docs/` (gitignored); bản mirror cục bộ ở `./.trace`. Chi tiết traceability: [core-concepts.md](core-concepts.md) và [../03-concepts/traceability.md](../03-concepts/traceability.md).
+## Nâng cấp & đồng bộ (Upgrade & Sync)
 
-## Uninstall
+| Lệnh | Việc | Ghi đè | KHÔNG đụng |
+|------|------|--------|-----------|
+| `/update-framework` | Sync bản npm mới | `.agent/commands\|steps\|hooks\|rules\|templates\|skills\|modules` | `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/` |
+| `/sync` (umbrella) | Pull + init submodule + nổi feedback + Living Docs | — | — |
 
-**Mac/Linux:**
-```bash
-rm -rf .agent/ .claude/commands/
-```
+Kiểm tra version mới nhất: `npm view @educa-corp/sdd-framework version`.
 
-**Windows (PowerShell):**
-```powershell
-Remove-Item -Recurse -Force .agent, .claude\commands
-```
+> **Quy tắc edit (critical):** `.tmpl` + `steps/` là source of truth. Sửa framework artifact phải sửa `.tmpl`/`steps` rồi `node bin/build.js`. Sửa thẳng `.agent/commands/*.md` sẽ **mất** khi rebuild/update.
 
 ---
 
-Cài xong? → [quickstart.md](quickstart.md) để chạy feature đầu tiên.
+## Đọc tiếp (Next)
+
+➡️ [Quick Start — feature đầu tiên end-to-end](quickstart.md)

package/docs/01-getting-started/quickstart.md

@@ -1,86 +1,72 @@
-[📚 Docs](../README.md) › [Getting Started](README.md) › Quick Start
-
-# Quick Start
-
-Chạy feature đầu tiên end-to-end theo happy path. Mở Claude Code tại root project và làm theo thứ tự.
+[← Installation](installation.md) · [Getting Started](../README.md)
+
+# Quick Start — Feature đầu tiên end-to-end
+
+> Golden path: từ ý tưởng tới code có test & trace. Mỗi bước có trang chi tiết trong [Pipeline Steps](../02-concepts/pipeline-steps/).
+
+Giả định đã [cài đặt](installation.md) và điền `CLAUDE.md` + `domain-knowledge/`.
+
+---
+
+## Golden path (12 bước)
+
+| # | Lệnh | Output | Ghi chú |
+|---|------|--------|---------|
+| 1 | `/define-product` | `product-definition/*.md` | Q&A 8 chặng, PO chốt từng chặng |
+| 2 | `/generate-prd` | PRD draft | Thuần ngôn ngữ nghiệp vụ |
+| 3 | `/refine-prd` | PRD refined | 3 lăng kính DEV/SA/PO → PO accept findings |
+| 4 | `/review-context <PRD>` | findings P0–P5 | 🔒 sạch critical → PO đặt `Status: approved` |
+| 5 | `/generate-design-spec` | `design-spec/` | **Chỉ FE/App** — bám Figma |
+| 6 | `/generate-bdd` | `bdd/*.feature` | 🛑 UC outline; PRD lớn → sub-agent per-UC |
+| 7 | `/review-context <feature>` | findings B1–B6 | Sạch critical → `@trace.status: approved` |
+| 8 | `/generate-tech-docs` → `/review-tech-docs` | `tech-docs/*.md` | SA review + cổng ký T7 |
+| 9 | `/generate-code` | code + `.trace/*.tsv` | 🛑 comprehension checkpoint + build verify |
+| 10 | `/dev-gen-test` → `/dev-run-test` | dev smoke | Set `dev_selftest` |
+| 11 | `/qc-analyze` … `/qc-report` | QC report + evidence | Set `qc_status` (Playwright) |
+| 12 | `/validate-traces` | coverage matrix | spec ↔ code ↔ test |
+
+```mermaid
+flowchart LR
+    A["1-4 · Idea → PRD approved"] --> B["5-7 · Design-Spec + BDD"]
+    B --> C["8 · Tech-Docs"] --> D["9 · Code"]
+    D --> E["10 · Dev smoke"] --> F["11 · QC"] --> G["12 · Validate"]
+```
 
-## Mục lục
+---
 
-- [Bước 0 — Setup project (một lần)](#bước-0--setup-project-một-lần)
-- [Happy-path command sequence](#happy-path-command-sequence)
-- [Bước tiếp theo](#bước-tiếp-theo)
+## Sửa spec hiện hữu (Drift handling)
 
-## Bước 0 — Setup project (một lần)
+Khi PO sửa `.feature`/PRD (bump version):
 
-```bash
-# 1. Cài framework (nếu chưa) — xem installation.md
-npx @educa-corp/sdd-framework --init
+1. `/generate-code <feature>` — so `spec ↔ .trace/*.tsv`.
+2. Phân loại OK / DRIFT / UNTRACKED.
+3. 🛑 Comprehension checkpoint — *"{N} SC drifted/new. Proceed?"*.
+4. Regen phần lệch → cập nhật `.tsv`.
 
-# 2. Mở project trong Claude Code, tạo cấu trúc + config files:
-/setup-ai-first
-```
+---
 
-`/setup-ai-first` tạo cấu trúc thư mục (`specs/`, `tech-docs/`, `.trace/`, `.agent/`, `CLAUDE.md`). Sau đó điền thông tin thực tế vào 4 file config:
+## Bug fix
 
-| File | Nội dung |
-|------|----------|
-| `CLAUDE.md` | Architecture layers, coding standards, git conventions |
-| `.agent/project-context.yaml` | Tech stack, services, paths, ticket prefix |
-| `specs/domain-knowledge/business-dictionary.md` | Canonical terms, banned terms |
-| `specs/domain-knowledge/core-entities.md` | Entity glossary (fields, relationships) |
+`/fix-bug {TICKET}` → đọc bug spec-anchored → tạo branch `fix/{TICKET}-<slug>` → root cause → sửa (tag `@trace.fixes`) → regression test + build verify → commit sau khi duyệt.
 
-> Project đã có sẵn `specs/`, `CLAUDE.md`, `.agent/project-context.yaml`? Bỏ qua bước này, vào thẳng happy path bên dưới. Chi tiết điền config + Figma setup: xem [../02-guides](../02-guides) và [../03-concepts](../03-concepts).
+---
 
-## Happy-path command sequence
+## Nếu AI ra output sai (Troubleshooting)
 
-Discovery → PRD → BDD → Tech Design → Code → Dev self-check:
-
-```
-# PHASE 1 — DISCOVERY
-/define-product
-    → specs/product-definition/{slug}.md
-
-# PHASE 2 — PRD
-/generate-prd specs/product-definition/{slug}.md
-    → specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-/refine-prd specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md         # AI suggestions → Review Board
-/refine-prd --resume specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  # apply + bump version
-/review-context specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md      # quality gate (P0–P5)
-/review-context --resume specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-    → ✅ 0 critical → PO đặt | **Status** | approved | trong Metadata → tiếp Phase 3
-
-# PHASE 3 — SPEC & DESIGN
-# (FE/App only) /generate-design-spec specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md → designer + PO sign-off
-/generate-bdd specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-    → specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-/review-context specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-/review-context --resume specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature   # apply + bump bdd_version + reset @trace.status draft
-    → ✅ 0 critical → đặt # @trace.status: approved trong .feature → tiếp Tech Design
-/generate-tech-docs specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-    → specs/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md   (1 doc full-stack/PRD)
-/review-tech-docs specs/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md
-/review-tech-docs --resume specs/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md
-
-# PHASE 4 — CODE
-/generate-code specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-    → src/...  (@trace.implements tags)
-/review-code                                       # fix CRITICAL / MAJOR
-
-# PHASE 5 — DEV SELF-CHECK (dev verify code của mình — KHÔNG phải QC suite chính thức)
-/dev-gen-test specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-    → src/test/...  (@trace.verifies tags)
-/dev-run-test                                      # sets dev_selftest in trace
-/dev-smoke-test                                    # optional — live endpoint check
-/validate-traces {domain}                          # coverage & drift
-```
+95% nguyên nhân ở **context**:
 
-Mỗi review command ghi findings vào `.agent/review/*-findings.yaml`. Mở **Review Board** (VS Code panel) → Accept / Modify / Defer / Reject từng finding → chạy `--resume` để apply. Quick-fix không qua Review Board: `/review-context --fix {file}` (chỉ apply auto-fixable).
+| Triệu chứng | Kiểm tra |
+|-------------|----------|
+| Sinh code sai entity field | Entity catalog có load + filter đúng domain? |
+| Sai naming/convention | `CLAUDE.md` (root+overlay) có ở cuối context? |
+| Bỏ qua rule X | Rule X có trong `required[]`? |
+| Sinh sai stack (umbrella) | Service overlay `CLAUDE.md` được nạp? |
+| Output khác nhau mỗi lần | Có tool ad-hoc đọc file? Phải qua context-loader |
 
-> **FE/App:** `/generate-code --phase=ui` (UI + mock adapter, tester test ngay) rồi `--phase=integration` (wire API thật sau sign-off).
+---
 
-## Bước tiếp theo
+## Đọc tiếp (Next)
 
-- Hiểu khái niệm phía sau pipeline → [core-concepts.md](core-concepts.md).
-- QC suite chính thức (`/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report`) → [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
-- Role guides, scenarios thực tế, multi-repo/umbrella → [../02-guides](../02-guides) và [../03-concepts](../03-concepts).
-- Full command reference → [../05-reference](../05-reference).
+- Hiểu từng bước sâu hơn → [Pipeline Steps](../02-concepts/pipeline-steps/)
+- Theo vai trò của bạn → [Guides](../03-guides/)
+- Tra cứu lệnh → [Reference › Commands](../04-reference/commands.md)

package/docs/01-getting-started/what-is-sdd.md

@@ -0,0 +1,75 @@
+[← Docs Home](../README.md) · [Next: Installation →](installation.md)
+
+# What is SDD — Framework là gì? (5 phút)
+
+> **SDD Framework** (`@educa-corp/sdd-framework`) là một **spec-driven development framework** đóng vai trò **đường ray** điều phối AI agent (Claude Code) đi từ **ý tưởng sản phẩm → PRD → Design-Spec → BDD → Tech-Docs → Code → Dev self-test → QC**, theo một **pipeline một chiều, có gate kiểm soát chất lượng và truy vết đầy đủ**.
+
+---
+
+## Khác gì với "dùng AI để code"?
+
+Dùng AI tự do (mở chat, gõ prompt, copy-paste) → AI suy diễn theo trực giác, output không bám requirement, sửa code làm spec lệch, lần sau AI hiểu sai. Framework này **áp đặt cấu trúc**:
+
+| | Dùng AI tự do | SDD Framework |
+|---|---|---|
+| **Nguồn chân lý** | Code (và trí nhớ vài senior) | **Spec** (PRD + BDD) — code là *hệ quả* |
+| **Truy vết** | Không | Mọi dòng code link `@trace` về scenario |
+| **Kiểm soát chất lượng** | Tuỳ người | **Gate bằng findings + approval** trước downstream |
+| **Điểm dừng con người** | Ngẫu nhiên | **HITL có chủ đích** — dày ở spec, mỏng ở code |
+| **Đổi requirement** | Đập đi làm lại | **Drift per-UC** — chỉ regen phần lệch |
+| **Trí nhớ dự án** | Trong đầu người | `/learn` + `domain-knowledge/` |
+
+---
+
+## Vấn đề framework giải quyết
+
+| Vấn đề | Cách giải |
+|--------|-----------|
+| AI viết lung tung, không bám requirement | Spec là **anchor cứng**; code link `@trace.source` về scenario |
+| Sửa code → spec lệch → AI hiểu sai lần sau | **Spec là single source of truth**; code không lưu version riêng |
+| Sửa spec → không biết code nào cần regen | **Trace state `.tsv` per-UC** → phát hiện OK/GAP/DRIFT/UNTRACKED |
+| PRD/BDD kém → code rác hàng loạt | **Quality gate** (`/review-context`) phải sạch critical + PO approve |
+| Lỗi/định hướng sai lặp lại | **`/learn`** ghi lesson, nạp lại vào context |
+| Đổi tech stack → viết lại workflow | **Module overlay** — skill đọc `stack-profile.yaml`, không hardcode |
+| Nhiều team, một nguồn spec | **Umbrella** — spec repo dùng chung + `/sync` |
+
+---
+
+## Triết lý cốt lõi (Core Philosophy)
+
+> **Viết spec trước. Sinh code từ spec. Truy vết mọi thứ.**
+> *(Write the spec first. Generate the code from the spec. Trace everything.)*
+
+- **Con người định nghĩa *cái gì*** — acceptance criteria, business rule, yêu cầu nền tảng.
+- **AI sinh ra *như thế nào*** — BDD, tech design, code, test — thích ứng theo platform.
+- **Mỗi artifact được review** trước khi sang phase sau.
+- **Mỗi dòng code truy vết** về một scenario trong `.feature`.
+- **Đa service**: mỗi service tiến hoá độc lập nhưng chung một workflow.
+
+---
+
+## Ba "trái tim" của hệ thống
+
+Bỏ một trong ba là hỏng:
+
+1. **HITL (điểm dừng con người)** — sai ở thượng nguồn nhân lên cấp số nhân. Bỏ = "tàu lao xuống vực".
+2. **Traceability (truy vết)** — biết mỗi dòng code thuộc scenario nào. Bỏ = "lạc rừng".
+3. **Context-loader (nạp đúng context)** — AI nhận đúng-đủ-gọn thông tin. Bỏ = "lái tàu trong sương mù".
+
+---
+
+## Framework KHÔNG giải quyết (Scope boundary)
+
+- Không thay **product judgment** (PO quyết cái gì đáng làm).
+- Không thay **architecture judgment** (SA quyết trade-off).
+- Không **debug runtime production**, không **CI/CD deploy**.
+- Không **ràng buộc AI model cứng** — chỉ khuyến nghị (model check mềm).
+
+---
+
+## Đọc tiếp (Next)
+
+- [Installation](installation.md) — cài đặt & khởi tạo dự án
+- [Quick Start](quickstart.md) — feature đầu tiên end-to-end
+- [Concepts › Overview](../02-concepts/overview.md) — mô hình toàn trình chi tiết
+- [Glossary](../02-concepts/glossary.md) — thuật ngữ

package/docs/02-concepts/architecture.md

@@ -0,0 +1,109 @@
+[← Traceability](traceability.md) · [Concepts](./) · [Pipeline Steps →](pipeline-steps/)
+
+# Architecture — Kiến trúc kỹ thuật (Internals)
+
+> Cách framework được tổ chức bên trong: 3 lớp, context-loader, template pipeline, module, hook. Đủ để hiểu *tại sao* framework hành xử như vậy.
+
+---
+
+## Mô hình 3 lớp (3-layer)
+
+```
+Command (orchestrator)   commands/*.md  ← build từ .tmpl
+    ├── Skill            skills/{discovery,prd,spec,design-spec,code,test,qc,debug,setup-ai-first}
+    └── Step             steps/*.md
+```
+
+| Lớp | Là gì | Ví dụ |
+|-----|-------|-------|
+| **Command** | Điều phối các phase của một workflow | `/generate-prd`, `/generate-code` |
+| **Skill** | Domain logic, **stateless**, chỉ consume context | write-prd, write-bdd |
+| **Step** | Infra tái dùng | `context-loader`, `gate`, `spawn-agent`, `review-fanout`, `business-language`, `capture-lesson`, `trace-mirror`, `report-footer` |
+
+**Tại sao tách:** đổi pipeline không đụng skill; tái dùng skill không kéo infra; đổi infra không đụng domain. **Skill không gọi Step** — orchestrator ghép cả hai.
+
+---
+
+## Phase chuẩn của một Command
+
+| Phase | Tên | Trách nhiệm |
+|-------|-----|-------------|
+| 0 | **Gate** | Validate input, model check mềm, service routing, nạp CLAUDE.md phân tầng |
+| 1 | **Context** | `context-loader` nạp file theo thứ tự ưu tiên |
+| 2 | **Execute** | Gọi skill — sinh artifact |
+| 3 | **Reflect** | (review workflow) fan-out + completeness-critic |
+| 4 | **Finalize** | Doc-sync, cập nhật trace, version bump |
+| 5 | **Verify & Report** | Build verify (≤3 retry), report, gợi ý workflow kế |
+| 6 | **Commit** | Commit theo convention (sau khi user duyệt) |
+
+> Workflow read-only (`/review-*`, `/validate-traces`, `/debug`) bỏ qua Execute-write / Verify / Commit.
+
+---
+
+## Context-loader — "trái tim" của framework
+
+Spec-driven thành/bại phụ thuộc **~80%** vào việc context được nạp **đúng — đủ — gọn — theo thứ tự**. Skill **không tự đọc file**; nó nhận một bundle đã sắp xếp từ `context-loader`.
+
+**Lost-in-the-Middle** — LLM recall **đầu** và **cuối** tốt hơn **giữa**:
+
+| Vị trí | Nội dung | Ý |
+|--------|----------|---|
+| **ĐẦU** | Input file (`.feature`/PRD), core entities (filtered), tech-doc section | "Build cái gì" |
+| **GIỮA** | project-context, rules, business dictionary, domain knowledge, lessons | Constraints |
+| **CUỐI** | CLAUDE.md (kiến trúc + coding standards), design-spec/UI | "Follow style này" |
+
+**Nguyên tắc quản lý size:** Required vs Optional rõ ràng (thiếu Required → halt) · filter theo domain/scope · trim section không load file thô · service overlay (umbrella) · budget có ngưỡng · lazy-load qua subagent.
+
+> Kim chỉ nam khi AI ra output lạ (sai pattern, lẫn UC khác, quên rule): **95% nguyên nhân ở context** — xem [Quick Start › Troubleshooting](../01-getting-started/quickstart.md#nếu-ai-ra-output-sai-troubleshooting).
+
+---
+
+## Template Pipeline
+
+```
+.tmpl (source) + steps/*.md  --[node bin/build.js, {{include:...}}]-->  commands/*.md + core/
+                                                                              │
+                                                                              ▼
+                                                              .agent/commands/*.md (runtime)
+```
+
+- Cơ chế `{{include:steps/...}}` ghép phẳng → single source of truth ở `.tmpl` + `steps/`.
+- **Không sửa tay** `commands/*.md` / `.agent/` — sửa `.tmpl`/`steps` rồi `node bin/build.js`. *(Quy ước + memory bảo vệ, không phải hook.)*
+
+---
+
+## Configuration (2 file)
+
+| File | Vai trò |
+|------|---------|
+| `.agent/project-context.yaml` | Runtime config — paths, mode (single/umbrella), services, conventions, tech_stack |
+| `CLAUDE.md` | root (luật chung) + `{service}/CLAUDE.md` overlay (kiến trúc + coding standards theo stack) |
+
+→ [Reference › Configuration](../04-reference/configuration.md).
+
+---
+
+## Module System
+
+Module = overlay tuỳ chọn mở rộng base. Mỗi module khai báo `module.yaml` + **`stack-profile.yaml`** (`artifact_types[]`, `generation_layers[]`, `build_verify`, `test_types{}`). Skill **đọc profile** thay vì hardcode → đổi stack chỉ cần thêm module.
+
+→ Danh sách 15 module: [Reference › Modules](../04-reference/modules.md).
+
+---
+
+## Hook System
+
+Bản hiện tại có **một hook**:
+
+| Event | Hook | Mục đích |
+|-------|------|----------|
+| PreToolUse (Read/Write/Edit/Bash) | `data-guard.js` | Chặn đọc/ghi/execute file nhạy cảm (secret, private key, `.env`) — exit 2 = hard block |
+
+Bổ trợ bằng **rules** nạp vào context (`rules/data-protection.md`, `rules/workflow.md`), không phải hook.
+
+---
+
+## Đọc tiếp (Next)
+
+- [Pipeline Steps](pipeline-steps/) — từng bước dùng các cơ chế này
+- [Reference](../04-reference/) — schema, module, config chi tiết

package/docs/02-concepts/glossary.md

@@ -0,0 +1,87 @@
+[← Overview](overview.md) · [Concepts](./) · [Roles & HITL →](roles-and-hitl.md)
+
+# Glossary — Thuật ngữ (Terminology)
+
+> Định nghĩa ngắn gọn các thuật ngữ dùng xuyên suốt framework. Sắp theo nhóm.
+
+---
+
+## Artifact (Sản phẩm của pipeline)
+
+| Thuật ngữ | Nghĩa |
+|-----------|-------|
+| **Product Definition** | Khung intent 8 chặng từ `/define-product` — *chưa phải PRD* |
+| **PRD** (Product Requirements Document) | Đặc tả nghiệp vụ: Metadata · AC · UC · BR · Wireframe · Change Log |
+| **Design-Spec** | Đặc tả visual bám Figma (chỉ FE/App), 2 tầng ngôn ngữ |
+| **BDD** (`.feature`) | Kịch bản hành vi viết bằng Gherkin, mang `@trace.*` |
+| **Tech-Docs / Tech-Design** | Thiết kế kỹ thuật full-stack: API contract, entity, data, dependency |
+| **Living Docs** | Tài liệu tự cập nhật qua `/sync` (umbrella) |
+
+---
+
+## Đơn vị nghiệp vụ (Business units)
+
+| Thuật ngữ | Nghĩa |
+|-----------|-------|
+| **UC** (Use Case) | Một tính năng/luồng nghiệp vụ; đơn vị phân rã chính |
+| **SC** (Scenario) | Một kịch bản hành vi kiểm chứng được, thuộc một UC |
+| **BR** (Business Rule) | Ràng buộc nghiệp vụ (vd: link hết hạn 15 phút) |
+| **BL** (Business Logic) | Cơ chế nghiệp vụ, cùng ngăn altitude với BR |
+| **AC** (Acceptance Criteria) | Tiêu chí nghiệm thu — "thế nào là làm xong đúng" |
+| **Altitude** | 4 ngăn không lộn: AC (nghiệm thu) · BR/BL (cơ chế) · Scope (ranh giới) · Dictionary (định nghĩa) |
+
+---
+
+## Traceability
+
+| Thuật ngữ | Nghĩa |
+|-----------|-------|
+| **@trace.\*** | Tag metadata gắn artifact về nguồn (id/scenario/source/business_rules…) |
+| **Boundary-only tagging** | Chỉ tag `@trace` ở boundary (controller/handler); shared code dò qua import chain |
+| **`.tsv` (trace state)** | Sổ trạng thái per-UC×platform: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` |
+| **Drift** | Spec đổi sau khi sinh code (`spec_ver != gen_ver`) → cần regen |
+| **Coverage status** | UNTRACKED · GAP · DRIFT · OK (xem [Traceability](traceability.md)) |
+| **`dev_selftest`** | Kết quả smoke của **dev** (cột `.tsv`) |
+| **`qc_status`** | Kết quả QC **chính thức** (Playwright, có evidence) — độc lập `dev_selftest` |
+
+---
+
+## Kiểm soát & quy trình (Control)
+
+| Thuật ngữ | Nghĩa |
+|-----------|-------|
+| **HITL** (Human-in-the-Loop) | Điểm dừng để con người duyệt — dày ở thượng nguồn |
+| **Checkpoint** (🛑) | Điểm AI dừng, trình output, chờ `Y` |
+| **Gate** (🔒) | Trạng thái (`Status`/`@trace.status`) do người đặt, chặn downstream tới khi `approved` |
+| **Findings** | Danh sách lỗi có mã: PRD **P0–P5**, BDD **B1–B6**; sạch *critical* mới qua |
+| **Comprehension checkpoint** | AI báo "{X} new, {Y} drifted — Proceed?" trước khi sinh code |
+| **Model check** | Gate mềm khuyến nghị model Opus (Y/S/N) |
+| **Business Language Guard** | Chặn thuật ngữ kỹ thuật lọt vào PRD/BDD |
+| **Scope Lock** | Cấm implement/xoá UC khác trong file dùng chung |
+| **Completeness-critic** | Vòng critic "đã đủ chưa / có lộn tầng không" sau fan-out |
+| **Fan-out** | Spawn mỗi UC/dimension một sub-agent chạy song song |
+
+---
+
+## Kiến trúc & vận hành (Architecture & Ops)
+
+| Thuật ngữ | Nghĩa |
+|-----------|-------|
+| **Command / Skill / Step** | 3 lớp: orchestrator / domain logic / infra |
+| **context-loader** | "Thủ thư" chọn đúng-đủ-gọn context cho mỗi workflow |
+| **Module** | Overlay theo stack (java-spring, react, qc-playwright…), khai báo `stack-profile.yaml` |
+| **`project-context.yaml`** | Config runtime: paths, mode, services, conventions, tech_stack |
+| **`CLAUDE.md`** | Instruction cho agent: root (chung) + service overlay (stack) |
+| **Domain** | Nhóm nghiệp vụ; segment đầu trong `specs/{domain}/…` |
+| **prd-slug** | Tên folder feature-package (segment sau `{domain}`) |
+| **Single vs Umbrella** | Một repo · vs · nhiều service submodule + spec repo dùng chung (`spec_source`) |
+| **T7 sign-off** | Cổng ký liên team cho contract cross-service |
+| **`/learn` lesson** | Guardrail ghi vào `project-lessons.md`, nạp lại vào context |
+| **data-guard** | Hook chặn đọc/ghi file nhạy cảm (secret/.env) |
+
+---
+
+## Đọc tiếp (Next)
+
+- [Roles & HITL](roles-and-hitl.md) · [Traceability](traceability.md) · [Architecture](architecture.md)
+- [Pipeline Steps](pipeline-steps/) — thuật ngữ trong ngữ cảnh