@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/docs/03-concepts/architecture.md

@@ -1,248 +0,0 @@
-[📚 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

@@ -1,124 +0,0 @@
-[📚 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.*