@edupia-tutor/spec-driven-docs 0.14.7 → 0.14.8

package/core/steps/spawn-agent.md

@@ -71,14 +71,18 @@ Dựng payload và gọi Agent tool cho từng UC:
 ```json
 {
   "_agent_mode": true,
-  "command":      "generate-bdd",
-  "uc_id":        "{TICKET-ID}-UC{N}",
-  "target_file":  "{đường dẫn tuyệt đối tới PRD hoặc feature file}",
-  "uc_section":   { "line_start": {N}, "line_end": {N} },
-  "context":      { "<context gọn từ Bước A>" }
+  "command":         "generate-bdd",
+  "uc_id":           "{TICKET-ID}-UC{N}",
+  "target_file":     "{đường dẫn tuyệt đối tới PRD hoặc feature file}",
+  "uc_section":      { "line_start": {N}, "line_end": {N} },
+  "context":         { "<context gọn từ Bước A>" },
+  "active_platform": "{web|app|system — platform orchestrator đã chọn ở Platform Selection}",
+  "design_coverage": { "<Screen States + AC-UI behavioral orchestrator đã trích ở 'Design Spec — Gate & Load' (B1); rỗng nếu BE / không có design-spec>" }
 }
 ```
 
+> **Truyền state orchestrator đã phân giải (quan trọng):** orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec MỘT LẦN *trước* khi spawn. Phải kèm `active_platform` và `design_coverage` vào payload để sub-agent áp đúng (đặc biệt phủ Screen States + AC-UI cho FE/App). KHÔNG kèm → sub-agent sinh BDD thiếu phần design (PRD lớn mất B1).
+
 > **Phạm vi lệnh**: Chỉ `/generate-bdd` khởi động chế độ orchestration. `/generate-code` và `/dev-gen-test` có thể chạy như sub-agent (chúng tôn trọng `_agent_mode: true` từ Gate Bước 0), nhưng không spawn thêm sub-agent — phạm vi của chúng vốn đã là một UC duy nhất.
 
 Serialize JSON này và truyền làm `$ARGUMENTS` khi gọi lệnh sub-agent.
@@ -108,8 +112,9 @@ Khi `gate.md Bước 0` phát hiện `_agent_mode: true`:
 2. **Bỏ qua context-loader.md** — dùng trực tiếp `payload.context`
 3. **Chỉ giới hạn ở `payload.uc_id`** — không xử lý các UC khác trong file
 4. Chỉ đọc section PRD giữa `payload.uc_section.line_start` và `line_end`
-5. Thực thi logic thường của lệnh cho riêng UC này
-6. Trả về JSON kết quả có cấu trúc (định dạng Bước E ở trên)
+5. **Dùng state orchestrator đã phân giải:** `active_platform` = `payload.active_platform`; `design_coverage` = `payload.design_coverage`. **KHÔNG chạy lại** các Guard (PRD approved / Design-Spec) hay tự nạp lại design-spec / hỏi platform — orchestrator đã làm một lần ở session chính.
+6. Thực thi logic thường của lệnh cho riêng UC này (dùng `design_coverage` từ payload để phủ Screen States + AC-UI)
+7. Trả về JSON kết quả có cấu trúc (định dạng Bước E ở trên)
 
 ---
 

package/core/templates/prd.template.md

@@ -197,11 +197,14 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 
 # Change Log
 
-### v1.0 — {mô tả} ({date})
+> Hiện tại: **v1.0** ({date}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET}-{N}-{slug}.changelog.md) *(file kho chỉ tạo khi changelog vượt 5 version)*
 
-| Mục | Thay đổi |
-|-----|----------|
-| — | Bản đầu — sinh từ product-definition. |
+<!-- Bảng phẳng, MỘT dòng/version, MỚI NHẤT TRÊN CÙNG. Chỉ giữ tối đa 5 version gần nhất ở đây;
+     cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
+
+| Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
+|---------|------|---------------------------------|
+| 1.0 | {date} | Bản đầu — sinh từ product-definition. |
 
 ---
 

package/docs/01-getting-started/core-concepts.md

@@ -18,7 +18,7 @@ Các khái niệm cốt lõi trong 5 phút. Đào sâu hơn ở [../03-concepts]
 
 - Con người định nghĩa *WHAT* — acceptance criteria, business rules, platform requirements.
 - AI sinh ra *HOW* — BDD scenarios, tech design, code, tests — thích ứng theo platform.
-- Mỗi artifact được review trước khi sang phase kế tiếp (AI review gate ở mọi transition).
+- Mỗi artifact được review (AI tìm findings) rồi **người duyệt** (đặt `Status` / `@trace.status: approved`) trước khi sang phase kế tiếp; sửa nội dung sau khi duyệt → tự về `draft`. Lệnh tiêu thụ **cảnh báo mềm** nếu nguồn chưa approved.
 - Mỗi dòng code truy ngược về một scenario trong file `.feature`.
 
 **PRD platform-agnostic (Option C):** một PRD phục vụ mọi platform — chỉ mô tả nghiệp vụ, không có chi tiết UI hay API. FE/App đọc PRD → Design Spec → BDD; BE đọc PRD trực tiếp → BDD. Thêm platform mới sau không cần sửa PRD.
@@ -50,7 +50,7 @@ Mỗi artifact link tới artifact khác qua `@trace.*` tags:
 
 ```
 product-definition.md
-  └─► PRD.md (Service, Module trong metadata)
+  └─► PRD.md (Domain, Status, Service, Module — bảng Metadata)
         └─► specs/{domain}/{prd-slug}/bdd/{web|app|system}/{UC-ID}.feature (@trace.prd_version)
               └─► specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design*.md (@trace.bdd_version)
                     └─► src/ code — service submodule (@trace.implements)

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

@@ -45,16 +45,17 @@ Discovery → PRD → BDD → Tech Design → Code → Dev self-check:
     → 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 (P1–P4)
+/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
-    → ✅ APPROVED → tiếp Phase 3
+    → ✅ 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
+/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/{UC-ID}-tech-design.md
 /review-tech-docs specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md

package/docs/02-guides/bdd-input-checklist.md

@@ -0,0 +1,68 @@
+[📚 Docs](../README.md) › [Guides](README.md) › Checklist Input BDD (System/BE)
+
+# Checklist Input BDD (System / BE) — Để BDD Chuẩn Ngay Lần Đầu
+
+> Áp cho `/generate-bdd` khi chọn platform **`system`** (BDD cho BE). Chuẩn bị đúng đầu vào để không phải sinh lại.
+
+## Hiểu trước cho đúng: System BDD có HAI kiểu sinh
+
+Khi chọn platform `system`, lệnh tự phân loại:
+
+- **BE thuần** (feature không có web/app) → System BDD **sinh thẳng từ PRD** (AC / Business Rules / Business Logic).
+- **BE trong feature đa-platform** → System BDD **tổng hợp từ web + app BDD đã có** (BE suy ra để phục vụ các luồng client).
+
+→ Biết mình ở kiểu nào mới chuẩn bị đúng.
+
+---
+
+## Phần CHUNG — cả hai kiểu đều cần
+
+**1. PRD đã duyệt + Luật/AC rõ ràng** *(đòn bẩy số 1)*
+System BDD phủ **mỗi AC và mỗi Business Rule → ít nhất 1 scenario**. PRD mơ hồ ở Business Rules / Logic = BDD mơ hồ. Đây là chỗ quyết định nhiều nhất.
+
+**2. Loại API đã chốt đúng trong PRD**
+- **"Đã có sẵn"** (brownfield) → bảng **Existing API Contract trong PRD phải đầy đủ**, không còn dấu "⛔ còn thiếu". Lệnh dùng bảng này làm chuẩn và **bỏ qua bước tổng hợp**. Còn thiếu = BDD dễ bịa / sai shape.
+- **"Tự làm mới"** → contract thiết kế sau; BDD chỉ tả hành vi nghiệp vụ.
+
+**3. Từ điển + danh sách thực thể đã cập nhật**
+System BDD viết bằng **ngôn ngữ sự kiện nghiệp vụ** ("hệ thống nhận X → trả về Y"), **không** dùng từ giao diện (click/tap), **không** chốt cứng shape JSON kỹ thuật. Tên thực thể / trường / enum phải đúng `core-entities.md`.
+
+**4. Domain khớp cấu hình service** *(chế độ umbrella)*
+Domain trong PRD phải khớp một service trong config; lệch là lệnh **dừng**.
+
+---
+
+## Phần RIÊNG theo kiểu
+
+### Nếu BE trong feature đa-platform (tổng hợp)
+
+**5. Đã sinh web + app BDD TRƯỚC — đúng thứ tự outside-in**
+Nếu sinh `system` khi **chưa có** web/app BDD → lệnh tưởng là "BE thuần", sinh từ PRD và **bỏ lỡ** các kỳ vọng client thật (token, profile, redirect…). Phải theo thứ tự **web → app → system**.
+
+**6. Sẵn sàng quyết "xung đột cross-platform"**
+Nếu web và app **kỳ vọng khác nhau** (response / lỗi / luật) → lệnh **dừng ở CHECKPOINT** bắt PO chọn cách hoà: gộp chung / phân biệt theo platform / tách endpoint. Web+app BDD nên nhất quán, hoặc PO sẵn sàng quyết ngay — nếu không sẽ tắc.
+
+### Nếu BE thuần
+
+Bỏ qua câu 5–6. Dồn lực vào câu 1–3: PRD Business Rules / Logic + contract + thực thể.
+
+---
+
+## Checklist nhanh — trước khi `/generate-bdd` (system)
+
+- [ ] PRD `approved`, mỗi AC/BR đủ rõ để suy ra scenario
+- [ ] Loại API đã chốt; brownfield → bảng Existing API Contract **đầy đủ** (hết ⛔)
+- [ ] `business-dictionary` + `core-entities` cập nhật (sự kiện / thực thể)
+- [ ] Domain khớp cấu hình service (umbrella)
+- [ ] *(đa-platform)* web + app BDD đã sinh + review **trước** system
+- [ ] *(đa-platform)* sẵn sàng quyết xung đột cross-platform
+
+---
+
+## Sau khi sinh BDD
+
+`/review-context` (BDD) bắt nốt sạn (coverage, Gherkin R1–R10, thuật ngữ); khi 0 critical → người duyệt đặt `# @trace.status: approved` rồi mới sang Tech Docs / Code / QC. Chuẩn bị tốt checklist trên thì bước review nhẹ.
+
+---
+
+← [Guides](README.md) · Liên quan: [Checklist Input PRD](prd-input-checklist.md) · [Checklist Input Tech-Docs (BE)](tech-docs-input-checklist.md)

package/docs/02-guides/developer/README.md

@@ -10,6 +10,8 @@ Tài liệu dành cho **Developer (FE / BE / App)** — vai trò, commands, trac
 |---|---|
 | [Commands](commands.md) | Bảng lệnh cho dev · project lessons · xử lý feedback tester · khi nào dùng `--phase` |
 | [BDD & Trace System](bdd-and-trace.md) | Tại sao BDD quan trọng với dev · `@trace.*` fields · trace chain · khi nào `/validate-traces` |
+| [Checklist input BDD (System/BE)](../bdd-input-checklist.md) | Chuẩn bị để `/generate-bdd` (system) chuẩn ngay lần đầu |
+| [Checklist input Tech-Docs (BE)](../tech-docs-input-checklist.md) | BDD khác tech-doc thế nào · chuẩn bị để `/generate-tech-docs` (BE) ra API contract chuẩn lần đầu |
 | [Workflow](workflow.md) | Luồng làm việc cơ bản từ nhận PRD đến tạo PR |
 | [Tình huống thực tế](scenarios.md) | 8 scenario: nhận PRD mới, đọc System/Web BDD, PRD đổi, API sign-off, bug từ tester, design spec, brownfield, umbrella, validate-traces |
 | [Checklist trước khi tạo PR](pr-checklist.md) | Checklist verify trước khi mở PR |
@@ -34,6 +36,7 @@ PO/BA                     Dev
 - Đọc và hiểu PRD + BDD từ spec submodule trước khi bắt đầu
 - **KHÔNG tự generate BDD** — BDD đã được PO generate trong spec repo
 - Đảm bảo code trace về đúng BDD scenario, BDD trace về đúng PRD
+- **Duyệt BDD:** sau khi `/review-context` (BDD) sạch critical, Dev-lead/SA đặt `# @trace.status: approved` trong `.feature` (cổng trước tech-docs / code / QC)
 - Báo PO/BA khi PRD hoặc BDD có gì không rõ hoặc mâu thuẫn — không tự suy diễn
 
 **Dev KHÔNG làm:**

package/docs/02-guides/developer/bdd-and-trace.md

@@ -62,6 +62,7 @@ Framework dùng metadata `@trace.*` để liên kết PRD → BDD → Code. (Chi
 | `@trace.prd` | BDD / Tech Doc header | Link về PRD gốc |
 | `@trace.bdd` | Code comment / test | Link về BDD scenario |
 | `Status` | bảng Metadata PRD | `draft` / `approved` — chỉ code khi `approved` |
+| `@trace.status` | BDD `.feature` header | `draft` / `approved` — Dev-lead/SA đặt approved sau review-context BDD sạch; mirror → `uc_status` (dashboard) |
 | `dev_selftest` | Trace TSV | `pass` / `fail` / `not_run` — kết quả dev self-check, set bởi `/dev-run-test`. Surfaced trong Living Docs để QC biết dev đã chạy self-check — **KHÔNG phải coverage chính thức** |
 | `dev_selftest_at` | Trace TSV | Timestamp lần chạy `/dev-run-test` gần nhất |
 | `qc_status` | Trace TSV | `pass` / `fail` / `skip` / `not_run` — kết quả **QC chính thức**, set bởi `/qc-run-test` (do QC chạy, KHÔNG phải dev). Orthogonal với `dev_selftest` và với coverage `status` |

package/docs/02-guides/developer/commands.md

@@ -8,11 +8,11 @@
 | `/update-framework` | Nâng cấp **bản thân framework** (`.agent/commands/`, steps/, modules/) từ npm | Khi có version framework mới — không đụng project-context/CLAUDE.md |
 | `/review-context {prd-file}` | Đọc + xác nhận PRD + BDD đủ rõ trước khi code — fan-out review dimension thành sub-agent song song + completeness-critic loop, findings file đầy đủ ngay trong 1 lần chạy | **Bước đầu tiên** khi nhận PRD mới |
 | `/generate-tech-docs {feature-file}` | **Platform-aware.** BE (`system`): API contract (endpoints, DB, caching). FE/App (`web`/`app`): client design (components, state, API-integration map theo BE contract, routing) — **GATED**: cần System BDD + BE contract approved trước, nếu thiếu sẽ HALT | BE: sau khi đọc System BDD. FE: sau `--phase=ui`, khi BE contract đã approved |
-| `/generate-code {bdd-file}` | Sinh code — BE hoặc FE khi API đã sẵn sàng | Sau khi tech docs `approved` |
+| `/generate-code {bdd-file}` | Sinh code — BE hoặc FE khi API đã sẵn sàng. Guard mềm: BDD `@trace.status` approved; FE/App design-spec approved+fresh+sanity | Sau khi tech docs `approved` |
 | `/generate-code {bdd-file} --phase=ui` | FE: gen UI + mock adapter. Mock **shape** từ BE contract nếu có (chuẩn) → else infer từ System BDD + warn (`mock_source=contract\|system-bdd`); fixture values luôn từ System BDD | Ngay sau khi đọc BDD (BE chưa cần deploy API) |
 | `/generate-code {bdd-file} --phase=integration` | FE: wire API thật thay mock | Sau khi sign-off gate `approved` |
 | `/dev-gen-test {bdd-file}` | **Dev self-check** — sinh test cases từ BDD để dev tự verify code mình vừa gen (KHÔNG phải bộ test chính thức của QC/dev-team) | Song song hoặc sau generate-code |
-| `/review-code {file}` | Review code theo 4 lens (Security/Perf/Arch/Test) | Trước khi tạo PR |
+| `/review-code {file}` | Review code theo 4 lăng kính (Traceability/Layer/Coding Standards/Spec Compliance) | Trước khi tạo PR |
 | `/review-tech-docs {tech-doc-file}` | Review chất lượng Tech Docs | Sau generate-tech-docs |
 | `/dev-run-test` | **Dev self-check** — chạy test do dev tự gen để xác nhận code mình hoạt động (smoke/self-verify, KHÔNG phải coverage chính thức) — *umbrella mode: tự `cd` vào service_root, dùng service's `test_command`*. Ghi `dev_selftest` (pass/fail) vào trace TSV | Sau khi code + tests sẵn sàng |
 | `/fix-bug {issue}` | Phân tích + fix bug có trace | Khi có bug report |
@@ -53,7 +53,7 @@ Tester gửi bug report (`/report-bug`) và đề xuất scenario (`/propose-sce
 
 Dev hành động theo phân loại:
 - **Bug report** → `/fix-bug {BUG-ID}` (report đã có sẵn spec-context + AC bị vi phạm + layer)
-- **Scenario proposal map vào AC sẵn có** → thêm scenario vào `.feature` (hoặc `/generate-bdd` lại), rồi `/generate-code` + `/dev-gen-test`
+- **Scenario proposal map vào AC sẵn có** → đặt `Status: accepted` trong file proposal → `/generate-bdd` tự chèn vào `.feature` rồi lưu trữ (`incorporated`); hoặc thêm tay. Rồi `/generate-code` + `/dev-gen-test`
 - **Proposal là yêu cầu mới (PRD change request)** → chuyển PO sửa PRD trước
 
 > Bug reports có thể đến từ hai nguồn: Tester dùng `/report-bug` trực tiếp, **hoặc** từ kết quả QC automation (`qc_status: fail` trong `.trace/*.tsv` → QC (hoặc tester) chạy `/report-bug` → `/sync` → dev thấy tại đây). Cả hai đều dùng cùng luồng `/fix-bug`.

package/docs/02-guides/developer/pr-checklist.md

@@ -7,6 +7,7 @@
 - [ ] `/review-code` → không có issue Critical hoặc Major chưa xử lý
 - [ ] Code trace về đúng BDD scenarios trong `my-project-specs/specs/{domain}/{prd-slug}/bdd/`
 - [ ] Code có `@trace.bdd` comment cho các function implement BDD scenario
+- [ ] BDD `@trace.status: approved` (đã duyệt) trước khi code/PR; FE/App: Design Spec `Status: approved` + `Built from PRD` khớp PRD hiện tại
 - [ ] Tech Docs đã được update nếu có thay đổi API/DB schema
 - [ ] **Không tự sửa BDD** — BDD là của PO, nếu cần update thì báo PO rồi pull lại
 

package/docs/02-guides/developer/workflow.md

@@ -27,7 +27,7 @@ flowchart TD
 
     TD --> E["/dev-gen-test → /dev-run-test<br/>dev tự kiểm (dev_selftest)<br/>ghi vào spec .trace"]
     E --> F["/validate-traces<br/>cập nhật Living Docs (.living-docs)"]
-    F --> G["/review-code — 4 lens:<br/>Security · Performance · Architecture · Test"]
+    F --> G["/review-code — 4 lăng kính:<br/>Traceability · Layer · Coding Standards · Spec Compliance"]
     G --> H([Tạo PR → notify PO/SA review])
 ```
 
@@ -98,7 +98,7 @@ FE/App track (web|app)   ── KHÔNG chặn chờ BE ──
         │
         ▼
 /review-code {files}
-→ 4 lens: Security / Performance / Architecture / Test Coverage
+→ 4 lăng kính: Traceability / Layer Architecture / Coding Standards / Spec Compliance
 → Fix issues trước khi tạo PR
         │
         ▼

package/docs/02-guides/prd-input-checklist.md

@@ -0,0 +1,94 @@
+[📚 Docs](../README.md) › [Guides](README.md) › Checklist Input PRD
+
+# Checklist Input PRD — Để PRD Chuẩn Ngay Lần Đầu
+
+> Muốn `/generate-prd` ra PRD tốt **ngay lần đầu**, đừng trông vào `/refine-prd` để vá — hãy chuẩn bị đúng đầu vào trước.
+
+## Hiểu trước cho đúng
+
+- **PRD sinh ra từ một file khảo sát (product-definition)** — output của `/define-product`. Bạn **không gõ thẳng** PRD.
+- **Không có "generate-prd cho BE" riêng.** PRD là tài liệu nghiệp vụ **dùng chung cho mọi platform** (một bản phục vụ cả FE/App/BE). Cái "system/BE" chỉ xuất hiện ở bước sau (`/generate-bdd`).
+- Vì vậy "PRD chuẩn ngay lần đầu" = **chuẩn bị tốt 7 thứ dưới đây trước khi chạy `/generate-prd`**.
+
+---
+
+## 7 câu tự hỏi trước khi bấm `/generate-prd`
+
+**1. Bản khảo sát đã làm xong chưa?**
+Đã chạy `/define-product` đi hết 7 bước, không bỏ dở. Máy sẽ **không cho** sinh PRD nếu còn dang dở.
+→ *Vì PRD là tài liệu để ký duyệt — không dựng từ thứ chưa chốt.*
+
+**2. "Luật" và "cách xử lý" của tính năng đã viết rõ chưa?** *(quan trọng nhất)*
+Hệ thống **phải làm gì / không được làm gì** (Business Rules), và **xử lý ra sao** trong từng trường hợp (Business Logic). Viết cụ thể, đừng để câu chung chung kiểu "xử lý hợp lý".
+→ *Đây là phần dev dựa vào để code. Mơ hồ ở đây = code sai ở đó.*
+
+**3. Đã liệt kê các trường hợp hỏng chưa?**
+Không chỉ lúc chạy ngon, mà cả lúc lỗi: thiếu dữ liệu, điều kiện không thoả, hai người bấm cùng lúc, service khác chết.
+→ *Hệ thống sống nhờ xử lý đúng mấy ca lỗi này; quên là lỗ hổng.*
+
+**4. Tính năng này cần gì từ service/đội khác không?**
+Ghi rõ: **cần dữ liệu/khả năng gì, lấy từ ai, để làm gì**. Nếu không cần thì ghi "Không có".
+→ *Tính năng hiếm khi đứng một mình; thiếu mục này dễ tắc giữa chừng.*
+
+**5. API của tính năng thuộc loại nào? — phải quyết trước**
+Chọn 1 trong 3:
+- **Đã có sẵn** (API chạy production rồi) → **đưa đường dẫn tới tài liệu API thật** (file swagger/openapi, link, hoặc thư mục code BE) **mà máy mở được**. Mở không được → PRD sẽ ghi "còn thiếu", chưa chuẩn.
+- **Tự làm mới** → để trống, thiết kế sau ở `/generate-tech-docs`.
+- **Đối tác đang làm song song** → chọn loại này (đừng chọn "đã có sẵn").
+→ *Đây là chỗ quyết định độ chuẩn nhiều nhất cho tính năng BE.*
+
+**6. Mỗi tiêu chí nghiệm thu (AC) có kiểm được đúng/sai rõ ràng không?**
+Tránh kiểu "nhanh", "ổn". Phải đo được.
+→ *AC mơ hồ thì sau này không ai biết tính năng "đạt" hay "chưa".*
+
+**7. Tên gọi và dữ liệu đã dùng đúng từ điển chung chưa?**
+Đảm bảo `business-dictionary.md` (từ chuẩn) và `core-entities.md` (danh sách thực thể/trường dữ liệu) đã cập nhật cho tính năng này.
+→ *Gọi sai tên một bảng/trường là lệch cả chuỗi sau.*
+
+---
+
+## Checklist nhanh
+
+- [ ] Khảo sát `/define-product` đã xong (7 bước, không gap)
+- [ ] Business Rules + cách xử lý viết rõ, không mơ hồ *(đòn bẩy lớn nhất)*
+- [ ] Đã liệt kê đủ các ca lỗi / trường hợp hỏng
+- [ ] Phụ thuộc service/đội khác ghi rõ (hoặc "Không có")
+- [ ] Đã quyết **loại API**; nếu "đã có sẵn" → đường dẫn contract **mở được**
+- [ ] Mỗi AC kiểm được đúng/sai rõ ràng
+- [ ] Từ điển chung + danh sách thực thể đã cập nhật
+- [ ] Định danh đúng: Domain (khớp cấu hình service), PO, mã Ticket
+
+---
+
+## Riêng tính năng BE — chú ý nhất ở đâu?
+
+BE không có Design Spec / màn hình đỡ phía trước, nên **PRD chính là spec**. Hai thứ quyết định độ chuẩn:
+
+1. **Business Rules + Business Logic (câu 2)** — vì BE đọc PRD thẳng rồi sinh System BDD từ đây.
+2. **Loại API (câu 5)** — BE "đã có sẵn" mà đường dẫn contract mở không được thì PRD sẽ kẹt ở trạng thái "còn thiếu".
+
+> Tính năng BE thuần **không có màn hình** → phần Wireframe để trống/N/A là đúng; đừng để máy bịa màn hình.
+
+---
+
+## Sau khi sinh PRD
+
+`/refine-prd` và `/review-context` là để **nhặt sạn** (làm rõ, bắt mâu thuẫn, thêm edge case) — **không phải** để vá cái thiếu từ khâu khảo sát. Chuẩn bị tốt 7 thứ trên thì hai bước này nhẹ tênh.
+
+---
+
+## Map sang các bước của `/define-product` *(cho ai muốn chính xác)*
+
+| Câu hỏi | Nằm ở bước nào của discovery |
+|---|---|
+| 1. Khảo sát xong | toàn bộ Phase 1–7, `Status: completed` |
+| 2. Luật + cách xử lý | Phase 4 (Business Rules) + Phase 5 (Business Logic) |
+| 3. Ca lỗi | Phase 2 (Edge Cases) |
+| 4. Phụ thuộc liên service | Phase 1, câu 8 |
+| 5. Loại API | hỏi lúc `/generate-prd` (API Source) |
+| 6. AC kiểm được | Phase 6 (Acceptance Criteria) |
+| 7. Từ điển / thực thể | Phase 0 (Knowledge Sync) + `business-dictionary.md` / `core-entities.md` |
+
+---
+
+← [Guides](README.md) · Liên quan: [Checklist Input BDD (System/BE)](bdd-input-checklist.md) · [Quy tắc viết PRD](product-owner/prd-writing-rules.md) · [Checklist handoff](product-owner/handoff-checklist.md)

package/docs/02-guides/product-owner/README.md

@@ -10,6 +10,8 @@ Tài liệu dành cho **Product Owner (PO)** và **Business Analyst (BA)** — v
 |---|---|
 | [Commands](commands.md) | Bảng lệnh cho PO/BA · project lessons · xử lý feedback tester |
 | [Tình huống thực tế](scenarios.md) | 12 scenario: tính năng mới, design spec, BDD, PRD thay đổi, brownfield, **System BDD synthesis & cross-platform conflict**, ... |
+| [Checklist input PRD](../prd-input-checklist.md) | 7 câu chuẩn bị để PRD chuẩn ngay lần đầu (kèm lưu ý BE) |
+| [Checklist input BDD (System/BE)](../bdd-input-checklist.md) | Chuẩn bị để `/generate-bdd` (system) chuẩn ngay lần đầu |
 | [Quy tắc viết PRD](prd-writing-rules.md) | Platform-agnostic · testable AC · negative path · BR numbering |
 | [Checklist handoff](handoff-checklist.md) | Checklist verify trước khi thông báo dev team bắt đầu |
 
@@ -51,7 +53,7 @@ PRD (WHAT + WHY)  →  BDD (HOW verified)  →  Code (HOW built)
    spec repo          spec repo             dev repo
 ```
 
-> **Sau khi BDD approved → QC chạy pipeline tự động:** Khi BDD của một UC được approve, QC team chạy bộ lệnh native `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — đọc official `.feature`, generate + run Playwright/pytest, rồi ghi `qc_status` (official QC coverage) vào Living Docs. PO không chạy QC, nhưng nên biết bước này tồn tại ở downstream. Chi tiết: [chương QC Automation](../tester/qc-automation.md).
+> **Sau khi BDD approved → QC chạy pipeline tự động:** Khi BDD của một UC được duyệt (đặt `@trace.status: approved` sau review-context BDD sạch), QC team chạy bộ lệnh native `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — đọc official `.feature`, generate + run Playwright/pytest, rồi ghi `qc_status` (official QC coverage) vào Living Docs. PO không chạy QC, nhưng nên biết bước này tồn tại ở downstream. Chi tiết: [chương QC Automation](../tester/qc-automation.md).
 
 **3 lý do chính BDD thuộc PO:**
 

package/docs/02-guides/product-owner/commands.md

@@ -22,7 +22,7 @@
 > **Project Lessons:** Nếu AI cứ lặp lại một kiểu sai khi gen PRD/BDD (vd: quên negative path, dùng sai thuật ngữ), chạy `/learn "AI hay X, đúng phải Y"` (category `prd`/`bdd`). Lesson được nạp vào đầu mọi lệnh → AI không lặp lại. Commit file lessons để cả team dùng chung.
 
 > **Xử lý feedback từ tester:** Tester `/report-bug` và `/propose-scenario` commit vào `{spec_source}/feedback/` của spec repo. PO/Dev **thấy chúng khi chạy `/sync`** (dòng `📥 New tester feedback` liệt kê bug + proposal mới kéo về). PO review proposal:
-> - **Map vào AC sẵn có** → coverage gap thật → để Dev thêm scenario vào `.feature` (hoặc regen).
+> - **Map vào AC sẵn có** → coverage gap thật → PO/Dev đặt `Status: accepted` trong file proposal → `/generate-bdd` tự chèn vào `.feature` rồi lưu trữ (`incorporated`); hoặc Dev thêm tay.
 > - Là **PRD change request** (behavior chưa có trong PRD) → PO thêm/sửa AC → bump version → `/generate-bdd` lại.
 
 ---

package/docs/02-guides/tech-docs-input-checklist.md

@@ -0,0 +1,82 @@
+[📚 Docs](../README.md) › [Guides](README.md) › Checklist Input Tech-Docs (BE)
+
+# Checklist Input Tech-Docs (BE) — Để API Contract Chuẩn Ngay Lần Đầu
+
+> Áp cho `/generate-tech-docs` trên một file **System BDD** (`@trace.platform: system`) — sinh ra **BE tech-doc = API contract**. Chuẩn bị đúng đầu vào để FE không phải chờ sửa lại.
+
+## Trước tiên: BDD khác tech-doc thế nào?
+
+Hai cái trả lời **hai câu hỏi khác nhau** về cùng một tính năng BE:
+
+| | **System BDD (BE)** | **BE Tech-docs (API contract)** |
+|---|---|---|
+| Trả lời | **CÁI GÌ** — hệ thống phải làm gì (hành vi nghiệp vụ) | **LÀM SAO** — hiện thực kỹ thuật |
+| Viết bằng | sự kiện nghiệp vụ: "hệ thống nhận X → trả về Y → báo lỗi Z" | endpoint/method/path, **shape** request/response, HTTP status, data model, DB, error code |
+| Chi tiết kỹ thuật? | **KHÔNG** | **CÓ** — nơi *duy nhất* chứa mấy thứ đó |
+| Ai làm | PO (spec repo) | Dev (`/generate-tech-docs`) |
+| Sinh từ đâu | từ PRD | **từ chính System BDD** |
+| Dùng để | kiểm chứng hành vi (QC test trace về đây) | BE code theo; **FE đọc để gọi API thật** |
+
+```
+PRD  →  System BDD (CÁI GÌ)  →  /generate-tech-docs  →  BE tech-doc (LÀM SAO)  →  code
+```
+
+**Ví von:** System BDD = *"đủ tiền → máy nhả nước; thiếu tiền → báo lỗi, trả tiền lại"* (hành vi). Tech-doc = *bản vẽ kỹ thuật của máy*: `POST /vend` nhận `{coin}` trả `{drink_id, change}`, thiếu tiền trả `402`.
+
+**Vì sao tách ra?** BDD không vỡ khi đổi chi tiết kỹ thuật (test ổn định); tech-doc là **contract liên đội** (FE phụ thuộc → cần sign-off T7); brownfield thì contract đã nằm sẵn trong PRD, tech-doc chỉ chép lại.
+
+> Một câu: **BDD nói "đúng thì ra cái gì", tech-doc nói "gọi thế nào để ra cái đó".**
+
+---
+
+## 7 câu tự hỏi trước khi `/generate-tech-docs` (BE)
+
+**1. System BDD đã duyệt + sạch lỗi chưa?**
+BDD phải `@trace.status: approved` và **không còn finding critical** từ `/review-context`. Lệnh sẽ **dừng (HALT)** nếu BDD còn lỗi critical chưa xử lý.
+→ *Tech-doc dẫn xuất từ BDD; BDD lỗi thì contract lỗi theo.*
+
+**2. BDD đã mô tả đủ hành vi chưa?**
+Mỗi scenario cần rõ: **kết quả trả về**, **các side-effect** (hệ thống lưu/đổi gì), và **tín hiệu lỗi** ("báo lỗi gì khi nào").
+→ *Đây là nguyên liệu để suy ra endpoint, mã lỗi, và data model. BDD thiếu = contract thiếu.*
+
+**3. API "đã có sẵn"? → bảng contract trong PRD phải đầy đủ**
+Nếu là brownfield (`API Source: existing`), `/generate-tech-docs` chỉ **chép lại** contract từ PRD (reverse-document). Bảng "Existing API Contract" còn dấu "⛔ còn thiếu" → tech-doc sẽ hổng.
+→ *Brownfield: đảm bảo contract đã trích đầy đủ từ nguồn thật.*
+
+**4. Danh sách thực thể / dữ liệu đã chuẩn chưa?**
+API contract cần **data model**: bảng/trường/kiểu/enum. Đảm bảo `core-entities.md` cập nhật đúng cho tính năng.
+→ *Sai tên một trường ở đây là lệch cả request/response lẫn DB.*
+
+**5. CLAUDE.md đã có kiến trúc + coding standard chưa?**
+Tech-doc mô tả thiết kế theo **layer/kiến trúc của project**. Lệnh đọc `CLAUDE.md` (§architecture, §coding standards) để bám đúng quy ước.
+→ *Thiếu → tech-doc tả kiến trúc chung chung, code sau lệch.*
+
+**6. Đúng stack module cho service chưa?**
+Service phải trỏ đúng module (java-spring / golang / dotnet / …) để lệnh lấy **mẫu layer** phù hợp.
+→ *Sai module = mẫu thiết kế sai stack.*
+
+**7. Phụ thuộc liên service đã ghi chưa?**
+Nếu BE gọi/được gọi bởi service khác (§1c của PRD) → contract phải phản ánh các điểm tích hợp đó.
+→ *Bỏ sót = contract thiếu chỗ nối, FE/đội khác tích hợp hụt.*
+
+---
+
+## Checklist nhanh — trước khi `/generate-tech-docs` (system/BE)
+
+- [ ] System BDD `@trace.status: approved` + **0 finding critical** (không lệnh sẽ HALT)
+- [ ] Mỗi scenario rõ: kết quả + side-effects + tín hiệu lỗi
+- [ ] Brownfield → bảng Existing API Contract trong PRD **đầy đủ** (hết ⛔)
+- [ ] `core-entities.md` cập nhật (data model: thực thể/trường/kiểu/enum)
+- [ ] `CLAUDE.md` có kiến trúc layer + coding standards
+- [ ] Service trỏ đúng stack module
+- [ ] Phụ thuộc liên service (§1c PRD) ghi rõ nếu có
+
+---
+
+## Sau khi sinh tech-doc
+
+`/review-tech-docs` chạy các check T1–T7. **T7 = cổng sign-off liên đội** (cross-team): greenfield/partner cần FE/App/SA confirm contract trước khi `@trace.status: approved`; brownfield (`existing`) thì skip T7 vì contract đã chốt sẵn. Contract chỉ thành "BE contract" mà FE chờ **sau khi approved**.
+
+---
+
+← [Guides](README.md) · Liên quan: [Checklist Input BDD (System/BE)](bdd-input-checklist.md) · [Checklist Input PRD](prd-input-checklist.md)

package/docs/02-guides/tester/README.md

@@ -57,7 +57,7 @@ Design Spec           Code                    Viết test cases · chạy /qc-*
 
 | Command | Mục đích | Khi nào dùng |
 |---|---|---|
-| `/qc-analyze` | Phân tích spec chain (PRD + BDD + Tech Docs), xác định scope test | Bước 1, sau khi BDD đã approved |
+| `/qc-analyze` | Phân tích spec chain (PRD + BDD + Tech Docs), xác định scope test | Bước 1, sau khi BDD `@trace.status: approved` (cảnh báo mềm nếu chưa) |
 | `/qc-plan` | Lập test plan: liệt kê scenarios, layer, ưu tiên | Bước 2 |
 | `/qc-design-test` | Thiết kế test case chi tiết (Page Object, data, assertions) | Bước 3 |
 | `/qc-review` | Review test design trước khi code automation | Bước 4 |

package/docs/02-guides/tester/bug-reporting.md

@@ -29,7 +29,7 @@ Nếu `/report-bug` báo *coverage gap* (behavior đúng nhưng chưa có scenar
 /propose-scenario FT-001 login với email có khoảng trắng ở cuối vẫn phải thành công
 ```
 
-- Nếu behavior **đã nằm trong một AC của PRD** → lệnh draft Gherkin (tag `@proposed @from-test`), ghi vào `{spec_source}/feedback/bdd-proposals/` → commit + push. PO/Dev review rồi đưa vào `.feature`.
+- Nếu behavior **đã nằm trong một AC của PRD** → lệnh draft Gherkin (tag `@proposed @from-test`, mang `Status: proposed`), ghi vào `{spec_source}/feedback/bdd-proposals/` → commit + push. PO/Dev review → đặt `Status: accepted` → `/generate-bdd` tự chèn vào `.feature` rồi lưu trữ (`incorporated`).
 - Nếu behavior **chưa có trong PRD** → lệnh **ghi** một *PRD change request* (`State: Open`) vào `{spec_source}/feedback/prd-change-requests/{UC-ID}-{slug}.md` → commit + push (KHÔNG chỉ in ra). PO thấy nó khi `/sync`, thêm/sửa AC rồi `/generate-bdd` lại.
 
 > Tester không tự ghi vào BDD — chỉ đề xuất. Giữ đúng ownership.

package/docs/02-guides/tester/qc-automation.md

@@ -79,7 +79,7 @@ functional / integration / e2e / non-functional / exploratory.
 
 ## Entry Point
 
-Pipeline QC bắt đầu ngay khi BDD của một UC được approved (`/review-context (BDD)` APPROVED):
+Pipeline QC bắt đầu khi BDD của một UC đã duyệt — `# @trace.status: approved` (sau `/review-context (BDD)` sạch critical + người duyệt đặt). `/qc-analyze` đọc field này và **cảnh báo mềm** nếu chưa approved:
 
 ```
 /qc-analyze {UC-ID}   →  … → /qc-report {UC-ID}  →  /validate-traces {UC-ID}

package/docs/03-concepts/README.md

@@ -9,6 +9,7 @@ Hiểu **cách framework được xây dựng và vận hành** — kiến trúc
 - [architecture.md](architecture.md) — 6 lớp (Protection → Output), module plug-in system, build pipeline (`*.tmpl` → `*.md` → `core/`), directory map, sub-agent orchestration, hook data-protection.
 - [pipeline.md](pipeline.md) — các phase Discovery → PRD → Design-Spec → BDD → Tech-Docs → Code → Dev self-check → QC automation → Tester feedback; review gates; và step-architecture model (gate / context-loader / spawn-agent / report-footer) đằng sau mỗi command.
 - [traceability.md](traceability.md) — `@trace.*` tags, trace TSV, hai tín hiệu `dev_selftest` vs `qc_status`, Living Docs (canonical trong spec-module + panel mirror), và `/validate-traces`.
+- [mechanisms-explained.md](mechanisms-explained.md) — giải thích các **cơ chế** framework bằng **ngôn ngữ dễ hiểu** + ví von đời thường (bổ sung cho các trang trên; ưu tiên trực giác).
 
 ## Đọc gì trước?
 

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

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

package/docs/03-concepts/pipeline.md

@@ -2,7 +2,7 @@
 
 # Pipeline
 
-Vòng đời feature đi qua các phase, mỗi transition có một **AI review gate**:
+Vòng đời feature đi qua các phase, mỗi transition lớn có **AI review (tìm findings) + cổng duyệt do người quyết** (xem note "Cổng duyệt" bên dưới):
 **Discovery → PRD → Design-Spec → BDD → Tech-Docs → Code → Dev self-check → QC automation → Tester feedback.** Phần sau mô tả từng phase và **step-architecture model** đằng sau mỗi command.
 
 ## Mục lục
@@ -25,7 +25,7 @@ Vòng đời feature đi qua các phase, mỗi transition có một **AI review
 | **0. Setup** *(one-time)* | Tech Lead | `/setup-ai-first`, `/sync`, `/sync-figma-*` | Config files, submodules, component catalog |
 | **1. Discovery** | PO + AI | `/define-product` | `specs/product-definition/{TICKET-ID}-{slug}.md` |
 | **2. PRD** | AI → SA/PO review | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` |
-| **2b. Design Spec** *(FE/App only)* | AI → Designer/PO sign-off | `/generate-design-spec` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md` |
+| **2b. Design Spec** *(FE/App only)* | AI → Designer/PO sign-off | `/generate-design-spec` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md` |
 | **3. BDD Spec** | AI → SA/Dev review | `/generate-bdd`, `/review-context` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` |
 | **4. Tech Design** *(platform-aware)* | AI → SA/Lead review | `/generate-tech-docs`, `/review-tech-docs` | BE: `specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (API contract) · FE/App: `{UC-ID}-tech-design-{platform}.md` (client design — **gated** trên System BDD + BE contract) |
 | **5. Code** | AI → Dev review | `/generate-code` *(FE: `--phase=ui`/`--phase=integration`)*, `/review-code` | `src/...` |
@@ -37,6 +37,8 @@ Vòng đời feature đi qua các phase, mỗi transition có một **AI review
 
 > **PRD là platform-agnostic (Option C):** Một PRD phục vụ mọi platform — chỉ mô tả business outcome, không UI/API. FE/App: PRD → Design Spec (2b) → BDD. BE: PRD → BDD (skip 2b). Thêm platform sau không cần đổi PRD.
 
+> **Cổng duyệt (human sign-off):** mỗi transition lớn có một **cổng do người quyết** — review (AI tìm findings) → người đặt trạng thái `approved` → bước sau. Ba cổng: **PRD** `Status: approved` (PO) · **Design Spec** `Status: approved` (PO+Designer) · **BDD** `@trace.status: approved` (Dev-lead). **Sửa nội dung sau khi duyệt → tự reset về `draft`** (PRD/Design/BDD đều vậy). Các lệnh tiêu thụ (`/generate-bdd`, `/generate-design-spec`, `/generate-tech-docs`, `/generate-code`, `/qc-analyze`) **cảnh báo mềm** nếu nguồn chưa `approved` (cho phép prototype, KHÔNG chặn cứng). Mỗi artifact còn ghi version nguồn để phát hiện **drift**: PRD `applied_to_version` (findings), Design Spec `Built from PRD`, BDD/tech-doc Version Check.
+
 ---
 
 ## Workflow chi tiết
@@ -55,22 +57,23 @@ Phase 2: PRD
   /review-context {prd} ────→ .agent/review/{prd-slug}-review-context-findings.yaml
        --fix (auto-fixable)  |  Review Board → --resume (apply + bump)
        Checks: banned terms (P1) · ambiguity AC/BR (P2) · conflicts (P3) · completeness (P4)
-       ✅ APPROVED → Phase 3   ·   ❌ NEEDS_FIX → fix + re-run
+       ✅ 0 critical → PO đặt Status: approved (Metadata) → Phase 2b/3   ·   ❌ NEEDS_FIX → fix + re-run
 
 Phase 2b/3: Design Spec & BDD
-  /generate-design-spec ────→ specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md
+  /generate-design-spec ────→ specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md
        (FE/App only — PO supplies node-level Figma link ?node-id= per screen;
-        AI fetches each frame via Figma MCP. Screen with no readable link → ❌ Missing;
-        sign-off + /generate-bdd blocked tới khi mọi screen có link)
-              [Designer review + PO sign-off]
+        AI fetches each frame via Figma MCP. Screen with no readable link → ❌ Missing → Status giữ draft;
+        ghi "Built from PRD: vX" để phát hiện lỗi thời; generate-bdd cảnh báo mềm nếu design-spec chưa approved)
+              [Designer review + PO sign-off → Status: approved]
   /generate-bdd ────────────→ specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
        THỨ TỰ OUTSIDE-IN (khi có client): web → app → system
          System BDD được TỔNG HỢP từ web+app BDD (client-facing trước → BE/system suy ra để phục vụ)
          (project chỉ-BE, không web/app: system gen thẳng từ PRD)
        (apply platform vocabulary: web "clicks" / mobile "taps" / backend "submits a request")
+       FE/App: đọc AC-UI + Screen States từ design-spec để phủ scenario (gate: approved + Built-from-PRD còn mới + sanity)
   /review-context {feature} → .agent/review/{uc-id}-review-bdd-findings.yaml
        Checks: PRD coverage (mỗi AC + BR bullet → ≥1 scenario) · Gherkin R1–R10 · compliance C1–C5
-       ✅ APPROVED → Phase 4
+       ✅ 0 critical → đặt @trace.status: approved (.feature) → Phase 4
 
 Phase 4: Tech Design  (platform-aware — đọc @trace.platform)
   BE (system):
@@ -124,7 +127,7 @@ Cross-cutting (any role, anytime)
 
 ## QC automation pipeline (Phase 5b)
 
-Bộ test QC **chính thức** — native pipeline, chạy như một **branch sau khi BDD được approve** (`/review-context` (BDD) APPROVED), song song / sau khi dev `/generate-code`. 6 stage tuần tự, port từ agent của team QC (QC repo nay chỉ còn reference):
+Bộ test QC **chính thức** — native pipeline, chạy như một **branch sau khi BDD `@trace.status: approved`** (review-context BDD sạch + người duyệt; `/qc-analyze` cảnh báo mềm nếu chưa), song song / sau khi dev `/generate-code`. 6 stage tuần tự, port từ agent của team QC (QC repo nay chỉ còn reference):
 
 ```
 BDD approved (specs/{domain}/{prd-slug}/bdd/*.feature)