@educa-corp/sdd-framework 0.1.0

package/docs/03-concepts/architecture.md

@@ -0,0 +1,248 @@
+[📚 Docs](../README.md) › [Concepts](README.md) › Architecture
+
+# Architecture
+
+> **Nguyên tắc**: Đọc file này để hiểu toàn bộ framework trước khi đọc bất kỳ file chi tiết nào.
+
+Cách framework được xây dựng: 6 lớp runtime, build pipeline `*.tmpl → *.md → core/`, module plug-in system, hook data-protection, và sub-agent orchestration.
+
+## Mục lục
+
+- [Layer diagram (L0 → L5)](#layer-diagram-l0--l5)
+- [Data flow — một command chạy như thế nào](#data-flow--một-command-chạy-như-thế-nào)
+- [Build system](#build-system)
+- [Module plug-in system](#module-plug-in-system)
+- [Hook system — data protection](#hook-system--data-protection)
+- [Sub-agent orchestration](#sub-agent-orchestration)
+- [Directory map](#directory-map)
+- [Maintenance guide](#maintenance-guide)
+
+---
+
+## Layer diagram (L0 → L5)
+
+Mỗi command chạy qua 6 lớp, từ bảo vệ dữ liệu đến sinh artifact:
+
+```
+LAYER 0 — PROTECTION                              (luôn chạy trước)
+  hooks/data-guard.js     → PreToolUse hook: chặn đọc file nhạy cảm
+  rules/data-protection.md → quy tắc declarative cho AI agent
+                          │ safe ↓   blocked → ✋ STOP
+LAYER 1 — ENTRY POINT                             (user trigger)
+  commands/*.tmpl          (slash commands: /generate-bdd, /generate-code, …)
+  skills/*/SKILL.tmpl      (auto-trigger theo description match)
+                          │ cả hai build bởi bin/build.js
+LAYER 2 — SHARED STEPS                            (DRY, injected)
+  steps/gate.md            → resolve target file + CHECKPOINT
+  steps/context-loader.md  → load project config + rules
+  steps/report-footer.md   → standard output format
+  Injected ở build time qua {{include:steps/X.md}}  (*.tmpl → *.md, gitignored)
+                          │ context loaded
+LAYER 3 — PROJECT CONTEXT                 (đọc từ consumer project)
+  .agent/project-context.yaml  → paths, tech_stack, domains
+  CLAUDE.md (root)             → umbrella-wide shared rules (base layer)
+  {service_root}/CLAUDE.md     → service architecture + coding standards (overlay, wins)
+  rules/data-protection.md     → AI không được đọc gì
+  .agent/modules/{stack}/      → stack rules (plug-in, optional)
+                          │ context-aware
+LAYER 4 — EXECUTION                               (command logic)
+  Discovery   /define-product
+  PRD / BDD   /generate-prd · /refine-prd · /generate-bdd · /generate-tech-docs
+  Code        /generate-code · /review-code
+  Dev check   /dev-gen-test · /dev-run-test · /dev-smoke-test  → set dev_selftest
+  QC suite    /qc-analyze → /qc-plan → /qc-design-test → /qc-review →
+              /qc-run-test → /qc-report                        → set qc_status
+  Trace/Debug /validate-traces · /fix-bug · /debug
+                          │
+LAYER 5 — OUTPUT                          (artifacts in consumer proj)
+  Spec module (cross-team, via {spec_source}):
+    specs/product-definition/
+    specs/{domain}/{prd-slug}/ — feature package gom mọi artifact của một PRD:
+      {TICKET-ID}-{prd-slug}.md · bdd/ (web/app/system) · tech-docs/ (1 doc full-stack/PRD: API contract + client design) · design-spec/
+    feedback/
+    .trace/{domain}/{prd-slug}/*.tsv (authoritative, committed — một chỗ cho PM) · .living-docs/ (gitignored)
+  Service submodule (per-service):
+    src/ (chỉ code) · .agent/review/
+  QC automation outputs:
+    QC test cases / scripts (Python pytest-playwright, Page Object)
+    → QC analysis / test-cases ghi vào {qc_dir}/{UC-ID}/ (mặc định docs/,
+      visible — KHÔNG nằm trong .agent/)
+    → guides per-layer ở skills/qc/<stage>/ · qc_status trong .trace/*.tsv
+```
+
+> **Dev self-check vs QC chính thức:** `/dev-*` set `dev_selftest` (smoke, dev tự kiểm code của mình); 6 lệnh `/qc-*` là QC automation pipeline CHÍNH THỨC (port từ agent của team QC; QC repo nay chỉ còn reference) → set `qc_status`. Hai tín hiệu **orthogonal**, cả hai surface trong Living Docs. Chi tiết: [traceability.md](traceability.md).
+
+---
+
+## Data flow — một command chạy như thế nào
+
+Ví dụ `/generate-bdd specs/payment/process-payment/{TICKET-ID}-process-payment.md`:
+
+```
+User types: /generate-bdd specs/payment/process-payment/{TICKET-ID}-process-payment.md
+  │
+[L0] data-guard.js check tool calls real-time → đọc .env/*.key → BLOCK + warn
+  │
+[L1] commands/generate-bdd.md (assembled từ .tmpl + injected steps) được Claude đọc
+  │
+[L2] gate.md → resolve file path từ $ARGUMENTS
+     context-loader.md → đọc project-context.yaml, CLAUDE.md,
+                         rules/data-protection.md, modules/{stack}/stack-profile.yaml
+  │
+[L3] Claude biết: tech_stack, domains, architecture rules, sensitive files, stack patterns
+  │
+[L4] generate-bdd logic: đọc PRD → extract UC/BR/AC → apply BDD rules R1–R10
+  │
+[L5] Output: specs/payment/process-payment/bdd/PAY-01-UC1.feature
+```
+
+Chi tiết về step-architecture (gate / context-loader / report-footer) và sub-agent model: xem [pipeline.md](pipeline.md#command-internals--step-architecture).
+
+---
+
+## Build system
+
+`*.tmpl` (committed) được assemble thành `*.md` (gitignored) bởi `bin/build.js`:
+
+```
+Source (committed)                Build output (gitignored)
+commands/*.tmpl       ──┐
+skills/**/SKILL.tmpl  ──┤  node bin/build.js  →  commands/*.md · skills/**/SKILL.md
+steps/*.md (shared)   ──┘
+
+Trigger:
+  npm run build         ← manual
+  prepublishOnly hook   ← auto trước npm publish
+  bin/index.js install  ← auto khi user chạy npx
+```
+
+> Build output cũng bao gồm `core/` — bản distributable được copy vào `.agent/` của consumer khi `--init`.
+
+---
+
+## Module plug-in system
+
+Stack module là plug-in tùy chọn: cài qua `--module`, đọc ở runtime bởi `context-loader.md`.
+
+```
+Available modules (modules/):
+  java-spring, angular, react, nextjs, vue, nuxt, dotnet, golang,
+  php-laravel, flutter, react-native, ios-swiftui, android-compose,
+  context-engineering, qc-playwright
+
+Usage:
+  npx @educa-corp/sdd-framework --module java-spring
+    └─ copies modules/java-spring/ → consumer/.agent/modules/java-spring/
+
+Runtime, context-loader.md đọc:
+  .agent/modules/{tech_stack.module}/stack-profile.yaml
+  .agent/modules/{tech_stack.module}/architecture-snippets/
+```
+
+> **`qc-playwright`** là stack module cho native QC pipeline (`/qc-run-test`, `/qc-report`) — Python + pytest-playwright + Page Object — **ĐỘC LẬP** với dev implementation module (java-spring / react / flutter / …). Per-layer guides ở `skills/qc/<stage>/`. Danh sách module đầy đủ: [../05-reference/modules.md](../05-reference/modules.md).
+
+---
+
+## Hook system — data protection
+
+```
+Consumer project setup:
+  .claude/settings.json   ← registers hook (template)
+  hooks/data-guard.js     ← copied khi install
+
+Runtime — mỗi tool use (Read, Write, Edit, Bash):
+  data-guard.js checks:
+    .env* · *.key · *.pem · *secret* · *password* · *credential*
+    application-prod.* · appsettings.Production.*
+       │
+    safe → allow      blocked → exit(2) + warn user
+```
+
+---
+
+## Sub-agent orchestration
+
+Khi một command quá nặng cho single context window, orchestrator spawn các sub-agent độc lập (mỗi agent có context window riêng):
+
+```
+Main session (orchestrator — lightweight, chỉ coordinate)
+  ├─ spawn spec-agent   ──→ /refine-prd analysis      → returns findings.yaml
+  ├─ spawn codegen-agent ──→ /generate-code UC1        → returns src/ changes
+  └─ spawn test-agent   ──→ /dev-gen-test UC1          → returns self-check test files
+```
+
+**Lợi ích:** main session không bị bloat bởi large file reads · mỗi agent focus 1 task, ít hallucination · parallel cho nhiều UC.
+
+Pattern này được hiện thực hóa qua `steps/spawn-agent.md` và tự kích hoạt cho `/generate-bdd`, `/generate-code`, `/dev-gen-test` khi PRD vượt ngưỡng phức tạp (> 3 UC hoặc > 300 dòng). Chi tiết flow + tiết kiệm context: [pipeline.md](pipeline.md#spawn-agentmd--sub-agent-orchestration).
+
+---
+
+## Directory map
+
+```
+spec-driven-docs/
+├── docs/                    ← Toàn bộ tài liệu (bắt đầu ở docs/README.md)  ◀◀◀
+│   ├── 01-getting-started/
+│   ├── 02-guides/
+│   ├── 03-concepts/         ← file này (architecture.md)
+│   ├── 04-operations/
+│   └── 05-reference/
+├── bin/
+│   ├── build.js             ← assembles *.tmpl → *.md
+│   └── index.js             ← npm installer + hook installer
+├── commands/
+│   └── *.tmpl               ← slash commands
+├── hooks/
+│   ├── data-guard.js        ← PreToolUse sensitive file protection
+│   └── settings.json        ← hook registration template
+├── modules/
+│   └── {stack}/             ← java-spring, react, …, qc-playwright
+│       ├── module.yaml
+│       ├── stack-profile.yaml
+│       └── architecture-snippets/
+├── rules/
+│   ├── data-protection.md   ← what AI must NEVER read/write
+│   └── workflow.md          ← general AI behavior rules
+├── skills/
+│   ├── {name}/SKILL.tmpl    ← Claude plugin skills
+│   └── qc/<stage>/          ← per-layer QC automation guides
+├── steps/
+│   ├── gate.md              ← shared: file resolve + checkpoint
+│   ├── context-loader.md    ← shared: load all project context
+│   ├── spawn-agent.md       ← shared: sub-agent orchestration
+│   ├── capture-lesson.md    ← shared: record a guardrail (/learn etc.)
+│   └── report-footer.md     ← shared: standard output format
+└── templates/
+    ├── project-context.yaml ← consumer project config template
+    ├── architecture.template.md
+    └── platform-guide.template.md
+```
+
+> **Build output (gitignored):** `commands/*.md`, `skills/**/SKILL.md`, và `core/`. Consumer-side tester artifacts nằm trong shared spec repo tại `feedback/bug-reports/` và `feedback/bdd-proposals/`.
+
+> **Umbrella mode — API contract (tech-docs) là cross-team artifact:** khi `setup.spec_source` được set, tech-docs LUÔN route về spec repo tại `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/` (cùng feature-package với PRD / BDD / design-spec), KHÔNG per-service — để FE/App đọc contract qua spec submodule ở `/generate-code --phase=integration`. Chỉ khi không có `spec_source` thì tech-docs mới nằm per-service.
+
+> **Living Docs / trace data location:** khi `spec_source` set, `.trace/*.tsv` **authoritative** nằm **một chỗ** ở `{spec_source}/.trace/` (committed trong spec repo — PM quản lý tập trung; mỗi scenario mang `@trace.service`). Report `trace-report.json` sinh vào `{spec_source}/.living-docs/` (gitignored) + panel mirror cục bộ `./.trace`. Chỉ khi không có `spec_source` thì `.trace` mới per-service. Chi tiết: [traceability.md](traceability.md#living-docs--canonical-trong-spec-module--panel-mirror).
+
+---
+
+## Maintenance guide
+
+| Muốn thay đổi gì | Sửa file nào |
+|------------------|-------------|
+| Logic của 1 command cụ thể | `commands/{name}.tmpl` |
+| Logic của 1 skill cụ thể | `skills/{name}/SKILL.tmpl` |
+| Gate / checkpoint pattern | `steps/gate.md` |
+| Context loading | `steps/context-loader.md` |
+| Report format | `steps/report-footer.md` |
+| Sensitive file patterns | `hooks/data-guard.js` + `rules/data-protection.md` |
+| Stack-specific rules | `modules/{stack}/stack-profile.yaml` |
+| QC automation rules (per-layer) | `skills/qc/<stage>/` + `modules/qc-playwright/` |
+| Project setup template | `templates/project-context.yaml` |
+| Build system | `bin/build.js` |
+| Installer | `bin/index.js` |
+
+Sau khi sửa bất kỳ `.tmpl` hoặc `steps/*.md`:
+```bash
+npm run build   # regenerate tất cả *.md
+```

package/docs/03-concepts/mechanisms-explained.md

@@ -0,0 +1,124 @@
+[📚 Docs](../README.md) › [Concepts](README.md) › Cơ Chế (Dễ Hiểu)
+
+# Giải Thích Cơ Chế Framework — Ngôn Ngữ Dễ Hiểu
+
+> Nơi gom các giải thích **cơ chế hoạt động** của framework bằng lời dễ hiểu + ví von đời thường. Bổ sung cho các trang concepts "chính quy" ([pipeline](pipeline.md), [traceability](traceability.md), [architecture](architecture.md)) — trang này ưu tiên *trực giác*, không phải đặc tả.
+
+## Mục lục
+
+- [1. PRD lớn → chia việc cho nhiều "thợ phụ" (orchestration / sub-agent)](#1-prd-lớn--chia-việc-cho-nhiều-thợ-phụ-orchestration--sub-agent)
+- [2. AC / BR / Scope ở khác tầng — "4 ngăn" (altitude)](#2-ac--br--scope-ở-khác-tầng--4-ngăn-altitude)
+- [3. Coding convention đặt ở đâu để update không nuốt mất](#3-coding-convention-đặt-ở-đâu-để-update-không-nuốt-mất)
+- [4. Tech-doc "một bản vẽ / PRD" — gộp full-stack, lớn dần, và cách review nó](#4-tech-doc-một-bản-vẽ--prd--gộp-full-stack-lớn-dần-và-cách-review-nó)
+
+---
+
+## 1. PRD lớn → chia việc cho nhiều "thợ phụ" (orchestration / sub-agent)
+
+**Cơ chế:** Khi PRD **nhỏ**, một mình AI làm hết từ đầu tới cuối. Khi PRD **lớn** (> 3 Use Case hoặc > 300 dòng), AI chuyển sang **chế độ điều phối**: session chính thành "sếp" nhẹ, **spawn mỗi Use Case một sub-agent** ("thợ phụ") có context window riêng để làm song song cho nhanh và đỡ tốn bộ nhớ.
+
+**Ví von:** Việc nhỏ thì một người ôm trọn. Việc lớn thì **sếp chia mỗi thợ một Use Case**.
+
+**Điểm mấu chốt — sếp làm phần chung MỘT LẦN, rồi "photo" đưa thợ:**
+- **Sếp làm trước, một lần** (ở session chính, đọc cả PRD): kiểm tra **cổng duyệt** (PRD approved?), **nạp Design Spec** (đã duyệt + còn mới + soi nhanh) → rút ra phần màn hình + AC-UI cần phủ (gọi là `design_coverage`), và chốt **platform** (web/app/system).
+- **Khi giao việc**, sếp **kèm sẵn cho mỗi thợ**: platform + `design_coverage` đã rút. Thợ **không** phải tự đi đọc lại design-spec, **không** phải hỏi lại "đã duyệt chưa".
+- Mỗi thợ chỉ đọc đúng **1 Use Case** trong PRD + dùng đồ sếp đưa → sinh BDD cho UC đó.
+
+**Vì sao thiết kế vậy:**
+- **Rẻ:** thợ khỏi đọc lại cả design-spec (đỡ token), khỏi bắt người dùng bấm Y/N nhiều lần (cổng duyệt hỏi 1 lần ở sếp).
+- **Không sót:** phần phủ design (Screen States loading/lỗi/trống + AC-UI) áp **cho cả PRD lớn**, không chỉ PRD nhỏ.
+
+> **Cạm bẫy đã từng có (và cách tránh):** nếu sếp quên "photo" `design_coverage`/platform khi giao việc → thợ làm theo trí nhớ thiếu → BDD của PRD lớn **rớt mất phần design** (dù PRD nhỏ vẫn đúng). Bài học: state nào orchestrator đã phân giải mà bước sau cần → **phải nhét vào payload giao cho sub-agent**, đừng để rơi.
+
+*Chi tiết kỹ thuật:* [pipeline › spawn-agent](pipeline.md#spawn-agentmd--sub-agent-orchestration) · [architecture › sub-agent orchestration](architecture.md#sub-agent-orchestration).
+
+---
+
+## 2. AC / BR / Scope ở khác tầng — "4 ngăn" (altitude)
+
+**Cơ chế:** Nội dung PRD có **4 "ngăn"**, mỗi loại thông tin ở đúng một ngăn:
+- **AC** (Acceptance Criteria) = *biên bản nghiệm thu* → "đạt khi nào" (kết quả nhìn/đo được) + trỏ số hiệu BR.
+- **BR / BL** (Business Rule / Logic) = *bản vẽ kỹ thuật* → "chạy thế nào" (thử lại mấy lần, timeout, cờ ai giữ, nhánh lỗi).
+- **Scope (In/Out)** = *ranh giới lô đất* → "làm gì / không làm gì" (một dòng, đọc lướt hiểu ngay).
+- **BUSINESS DEFINITION / business-dictionary** = *giải nghĩa từ*.
+
+**Vì sao dễ hỏng:** `/refine-prd` giống một **tổ 3 người soi bài** (DEV/SA/PO) + một người canh *"đã đủ chưa?"* (completeness-critic). Cả tổ **chỉ biết THÊM chi tiết** — mà câu hỏi mặc định *"AC đủ chi tiết chưa?"* tự nó **kéo chi tiết bản-vẽ-kỹ-thuật vào biên-bản-nghiệm-thu**. Qua nhiều vòng `--resume`, **AC dày lên bằng BR** → hai ngăn hội tụ, tài liệu trùng lặp + AC hết dùng được như checklist. In Scope tụt tầng cùng lý do (bị nhét định nghĩa cơ chế).
+
+> **Gốc rễ:** tổ soi bài tối ưu *"đủ từng section"* nhưng **thiếu lực đối trọng giữ ranh giới vai trò** — không ai kéo "mỗi thứ về đúng ngăn", nên chi tiết cứ trôi xuống, ngăn BR hút hết.
+
+**Cách giữ ranh giới (7 luật, 2 nhóm):**
+- **Dọn (hạ nguồn):** AC chỉ ghi outcome + ref BR (cấm cơ chế) · lúc áp fix → cơ chế bỏ vào BR/BL · lính gác bắt AC lỡ chứa cơ chế · Scope chỉ là ranh giới.
+- **Sửa gốc (thượng nguồn):** đổi **câu hỏi** của tổ soi bài (hỏi "AC có outcome test được chưa", chi tiết → BR/BL) · thêm **người canh "đừng lộn ngăn"** vào critic (không chỉ "đủ chưa" mà "có lộn tầng không") · **bắt AC ≈ BR** (trùng nội dung → làm mỏng AC).
+
+> **Đừng hiểu nhầm là "cắt bớt":** chi tiết retry/timeout/nhánh lỗi **KHÔNG bị xoá** — nó **di dời** từ AC xuống BR/BL. Vì `/generate-bdd` sinh test theo *mỗi BR → ≥1 scenario*; nhánh lỗi/retry chính là nguồn đẻ test. Bỏ hẳn = mất test.
+
+*Chi tiết áp ở đâu:* lăng kính + completeness-critic (`steps/review-fanout.md`, `commands/refine-prd.tmpl`) · P-check (`commands/review-context.tmpl`) · format AC/Scope (`templates/prd.template.md`, `commands/generate-prd.tmpl`).
+
+---
+
+## 3. Coding convention đặt ở đâu để update không nuốt mất
+
+**Cơ chế:** File trong project chia làm **hai loại chủ sở hữu**. `/update-framework` (kéo bản framework mới về) **ghi đè** nhóm "của framework" và **không đụng** nhóm "của bạn":
+
+| Của framework — **bị ghi đè** mỗi lần update | Của bạn — **được giữ** nguyên |
+|---|---|
+| `.agent/commands · steps · hooks · rules · templates · skills` | `CLAUDE.md` |
+| `.agent/modules/{stack}/` (`module.yaml`, `stack-profile.yaml`, snippets) | `.agent/project-context.yaml` |
+| `.agent/FRAMEWORK_VERSION`, `.claude/commands/` | `specs/domain-knowledge/`, `.trace/` |
+
+**Ví von:** Framework là **bộ đồ nghề đi thuê** — mỗi lần đổi bộ mới, đồ thuê bị thay sạch, nhưng **đồ riêng của bạn** (ghi chú dán trên tường = `CLAUDE.md`, sổ tay dự án = `project-context.yaml`) thì không ai động.
+
+**Điểm mấu chốt — đặt convention ở chỗ vừa GIỮ vừa ĐƯỢC ĐỌC:**
+- **`CLAUDE.md`** là nhà chính: `/generate-code`, `/review-code`, `/generate-tech-docs`, `/fix-bug` nạp trực tiếp `§2 Architecture` (thứ tự layer + rule), `§3 Coding Standards` (naming, wrapper, forbidden), `§5 Error Handling` (exception, HTTP code). Framework sinh sẵn skeleton các §; bạn chỉ điền chi tiết stack (vd Java Spring Boot).
+- **`project-context.yaml`** `conventions:` giữ lệnh `build_command` / `test_command` / `run_command` — `/generate-code` chạy đúng lệnh này khi tự-kiểm.
+- **Convention dài** (cả trang) → tách file dưới `specs/domain-knowledge/` (cũng được giữ + context-loader nạp), rồi trỏ tới từ `CLAUDE.md` cho gọn.
+
+> **Cạm bẫy hay gặp:** nhét convention riêng vào `.agent/modules/{stack}/` (vì thấy nó "nói về stack của mình"). Sai — module là **default chung của stack do framework phát hành**, nằm trong nhóm bị ghi đè; convention của team sẽ **bay sạch** ở lần update kế. Của-stack (framework) khác của-team (bạn) — để riêng.
+
+*Chi tiết:* danh sách ghi-đè/giữ (`commands/update-framework.tmpl`) · nơi đọc convention (`commands/generate-code.tmpl` §2/§3/§5) · skeleton CLAUDE.md (`commands/setup-ai-first.tmpl`) · `conventions:` (`templates/project-context.yaml`).
+
+---
+
+## 4. Tech-doc "một bản vẽ / PRD" — gộp full-stack, lớn dần, và cách review nó
+
+**Cơ chế:** Một PRD chỉ có **một** technical design document — `{TICKET-ID}-tech-design.md`, nằm trong `specs/{domain}/{prd-slug}/tech-docs/`, cạnh `bdd/` và `design-spec/`. File này **gộp full-stack**: backend (API §4.1–§4.4, data model §3, DB) *và* client (§4.5 component/state/Figma/test-id cho mỗi platform), nối với nhau bằng **sequence diagram xuyên tầng** ở §5 (client → service → API → external → DB). Một dev đọc **một** file là hiểu và code được cả tính năng.
+
+**Ví von:** không phải nhiều bản vẽ rời (mỗi phòng một tờ) mà **một bản vẽ tổng mặt bằng** cho cả căn nhà — móng, điện, nước, nội thất trên cùng một khổ giấy, có mũi tên chỉ chúng nối nhau ra sao.
+
+**Input là BDD tech lead trỏ, KHÔNG phải cả PRD:** `/generate-tech-docs` nhận **1..n file BDD** người dùng chỉ định (batch, cảnh báo nếu > 5 để khỏi phình context) — trỏ System BDD → vẽ §4 API; trỏ Web/App BDD → append §4.5 client. Chạy nhiều lần, **doc lớn dần** (append), không đè phần cũ. **§10 UC Coverage** là "sổ điểm danh" để lệnh biết UC nào đã vẽ, UC nào còn thiếu.
+
+**Vì sao gộp thay vì tách BE/FE per-UC:** một tính năng vốn liền mạch (bấm nút ở web → gọi API → ghi DB); tách ra nhiều file khiến dev phải ghép hình. Gộp lại: §4.5.4 (client gọi API) map thẳng lên §4.1 (endpoint) trong **cùng** tài liệu — không lệch, không đi tìm file anh em.
+
+**Review chạy trên doc gộp thế nào (`/review-tech-docs`):**
+- **Phạm vi = cả PRD, không phải 1 UC:** đọc `@trace.ucs` (danh sách UC) để biết doc phủ những câu nào, ra **một** file findings `{TICKET-ID}-tech-review-findings.yaml` — nhưng **mỗi finding gắn `uc_id`** để biết lỗi thuộc câu nào (như phiếu chấm cho cả xấp bài, mỗi lỗi ghi rõ "câu số mấy").
+- **T3 truy vết BDD 2 chiều** với **mọi** BDD của PRD (system/web/app): doc có behavior nào không có scenario? scenario nào chưa được vẽ (§5/§10)? — các file BDD này thuộc *chính PRD* nên phạm vi có giới hạn.
+- **Duyệt xong → đóng dấu revision cho mọi UC:** doc bump `@trace.revision`; review ghi `tech_doc_revision = revision mới` vào TSV của **từng** UC trong `@trace.ucs` (sổ trace vẫn per-UC). Chừa cột `fe_tech_doc_revision` cho `/generate-code --phase=integration` ghi (lúc FE wire API thật theo §4.5.4) — **2 cột, cùng đọc 1 file, ghi ở 2 thời điểm**.
+
+**Điểm mấu chốt — check trùng endpoint liên-PRD kiểu "tra sổ địa chỉ, không vào từng nhà" (T4):** vì doc rất dài, muốn bắt 2 PRD vô tình định nghĩa cùng endpoint khác shape, review **không** đọc trọn tech-doc của mọi PRD khác (nổ context). Thay vào đó: trích danh sách endpoint (§4.1) của doc đang review → `grep` các path đó trong tech-doc PRD khác (chỉ đọc dòng match) → **chỉ khi trùng path** mới nạp đúng đoạn §4 của doc kia để so. Bình thường tốn vài dòng grep; chỉ "trả tiền" khi thật sự va chạm.
+
+> **Cạm bẫy đã tránh:** ban đầu định cho T4 nạp full mọi tech-doc cùng domain để so — mỗi doc 500–800 dòng × N PRD = context nổ. Bài học: khi cần đối chiếu chéo nhiều tài liệu lớn, **lọc bằng chỉ mục rẻ (grep path) trước, nạp full chỉ khi có hit** — đừng load tất cả rồi mới so.
+
+> **Cạm bẫy #2 — trùng số SC khi gộp platform (số căn hộ giữa hai toà):** mã scenario `{UC}-SC{N}` **chỉ độc nhất trong (UC × platform)** — `system UC1-SC1` và `web UC1-SC1` là **hai scenario khác nhau**. Gộp cả 3 platform vào 1 doc rồi liệt kê SC phẳng → nhập nhằng (như Toà A căn 101 vs Toà B căn 101, gộp danh bạ chỉ ghi "101"). **Cách tránh — giữ lane theo platform:** §5 chia `5.A system / 5.B web / 5.C app`, mỗi SC ghi kèm platform (`web · UC1-SC1`); §10 có cột **Platform** (mỗi `(platform, SC)` một dòng); review T3 match SC trong đúng lane, không so chéo. *(Cùng gốc collision này từng nằm ở **tầng trace**: sổ TSV per-UC key thuần `sc_id` → scenario các platform **đè/xoá nhau** (gen web xoá luôn scenario system). **Đã fix bằng cách tách sổ theo platform** — `{UC-ID}-{platform}.tsv`, mỗi platform một sổ (system/web/app). Hết đè/xoá; Living Docs gắn field `platform` mỗi row để hiển thị coverage tách bạch. Chi tiết: [Trace Schema](../05-reference/trace-schema.md).)*
+
+**Điều hướng doc gộp (mục lục + độ hạt):** vì doc là cấp PRD nhưng consumer (`generate-code`/`map-testids`/`qc`) xử **một UC**, **§10 UC Coverage là mục lục**: tra UC → scenario → section/§5-lane của nó (endpoint liên quan = §4.1 mà §5-lane của UC gọi tới). §4.5 **nhóm theo platform** (một nhóm `§4.5 — web`, một `§4.5 — app`), mỗi màn/UC là sub-block; §4.5.6 là **một bảng chung/platform** với cột "Serves SC (UC·SC)" để lọc theo UC. *Ví von: bản vẽ cả toà nhà phải có mục lục "tầng ở trang mấy"; nội thất gom theo tầng, mỗi phòng một trang.*
+
+**Cách `/generate-code` tiêu thụ doc gộp:** code sinh cho **1 UC** nhưng mở **cùng** file gộp rồi lật đúng phần UC đó — không còn đi tìm file per-UC/per-platform:
+- **Khuôn mock (`--phase=ui`):** shape request/response lấy từ **§4.1/§4.2/§4.3** (API contract) để mock giống API thật, đỡ nắn lại lúc ráp. Chưa có §4 → suy từ System BDD + cảnh báo.
+- **Đấu nối thật (`--phase=integration`):** map client method → endpoint theo **§4.5.4** (sơ đồ đấu nối của platform), endpoint/shape tra §4.1–§4.3 **cùng doc**. Chưa có §4.5.4 → map thẳng từ §4.1 + warn.
+- **Test-id:** emit đúng id trong **§4.5.6** (thay §2b cũ) để QC Page Object khớp ngay. (`/map-testids` backfill §4.5.6 cho component tái dùng/brownfield; `/qc-design-test` + `/qc-run-test` đọc §4.5.6 để dựng locator; `/validate-traces` so `@trace.revision` của doc gộp với 2 cột để bắt drift.)
+- **Đóng dấu bản vẽ:** ghi `tech_doc_revision` (lúc gen BE) / `fe_tech_doc_revision` (lúc FE integration) = `@trace.revision` của doc → `/validate-traces` bắt drift khi code lắp theo bản cũ.
+
+*Ví von ba mục: §4 = **kích thước ô cửa** (đóng khung mock cho khít) · §4.5.4 = **sơ đồ đấu dây** (nối API thật) · §4.5.6 = **bảng số phòng** (QC tìm element).*
+
+**Quy tắc nhận dạng & vài edge (rút ra khi soi BDD thật):**
+- **Định danh đọc từ header, không cắt tên file:** `{TICKET-ID}` ← `@trace.prd`, `{UC-ID}` ← `@trace.id` (đều slug-free). Vì TICKET-ID có gạch nối (`FEAT-01-2`) và **slug/title một UC khác nhau theo platform** (UC3: system `sua-cau-bo-qua` vs web `sua-cau-quay-lai-bo-qua`) — cắt chuỗi dễ sai. Gom UC theo `@trace.id` → system/web/app cùng id = **một** UC; title lấy canonical từ **PRD**.
+- **`@trace.bdd_version` là map theo platform** (`system=1.5, web=1.9`) chứ không một số — mỗi feature giữ version riêng, gộp phẳng sẽ che mất platform nào còn cũ.
+- **PRD client-only (không có system BDD):** đừng bịa BE contract — §4.1 chỉ ghi endpoint client **tiêu thụ** (external/team khác/existing), hoặc "N/A — client-only". Đối xứng với backend-only (bỏ §4.5).
+
+> ✅ **Trạng thái migrate:** **toàn bộ command** đã theo mô hình doc gộp — `/generate-tech-docs`, `/review-tech-docs`, `/generate-code`, `/validate-traces`, `/map-testids`, `/qc-design-test`, `/qc-run-test`, `/generate-bdd`. Còn lại: một số **trang guide/reference** (getting-started, developer/tester guides, command reference, sync-and-update) vẫn mô tả layout per-UC cũ — sẽ quét đồng bộ sau (không ảnh hưởng hành vi lệnh).
+
+*Chi tiết:* sinh doc (`commands/generate-tech-docs.tmpl` + `templates/tech-design.template.md`) · review (`commands/review-tech-docs.tmpl` — T3/T4/T7 + Resume TSV) · vị trí trong dây chuyền ([pipeline › Phase 4](pipeline.md)) · chuẩn bị input ([Checklist Input Tech-Docs](../02-guides/tech-docs-input-checklist.md)).
+
+---
+
+*Có thêm cơ chế nào được giải thích kiểu dễ hiểu → thêm một mục mới ở đây.*