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

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,57 @@
+[📚 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)
+
+---
+
+## 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ổ 4 người soi bài** (QA/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`).
+
+---
+
+*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)

package/docs/03-concepts/traceability.md

@@ -18,7 +18,7 @@ Mỗi artifact link tới mọi artifact khác qua `@trace.*` tags, và trạng
 
 ## Artifact chain & @trace tags
 
-Mỗi artifact mang `@trace.*` metadata liên kết về artifact trước nó:
+Mỗi artifact liên kết về artifact trước nó bằng metadata (PRD: bảng **Metadata**; BDD / tech-doc / code / test: `@trace.*` tags):
 
 ```
 product-definition.md
@@ -36,6 +36,8 @@ product-definition.md
 |-------|--------|---------|
 | `Domain` | bảng Metadata PRD | Domain của feature (auth, payment, …) — route vào đúng service submodule |
 | `Status` | bảng Metadata PRD | `draft` / `approved` — dev team chỉ code khi `approved` |
+| `@trace.status` | BDD `.feature` header | `draft` / `approved` — người đặt `approved` sau khi review-context BDD sạch; mirror vào `uc_status` |
+| `uc_status` | trace TSV (mirror) | gương của BDD `@trace.status` — `/validate-traces` đồng bộ → dashboard `approved_ucs` |
 | `@trace.service` / `@trace.module` | BDD / Tech Doc header | Service + module sẽ implement |
 | `@trace.prd_version` / `@trace.bdd_version` | BDD / code / test | Version của spec mà artifact được sinh từ — base cho drift detection |
 | `@trace.implements` | Code comment | Scenario mà code này implement: `={UC-ID}-SC{N}` |
@@ -106,6 +108,7 @@ Living Docs (VS Code panel) đọc trace TSV và hiển thị traceability healt
 - Drill down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, **Dev Self-Check**, **QC Status**, **Waiting on**, Status)
 - **Waiting on** (cột `qc_owner` + `qc_blocked_by`): cho PO/PM thấy case chưa pass đang **chờ dev** (product-gap → `BUG-{id}`) hay **chờ PO** confirm/clarify (spec gap → `GAP-{id}`). Aggregates `waiting_dev` / `waiting_po` ở header dashboard.
 - Status badges: ✅ OK · ⚠️ DRIFT · 🔴 GAP · — UNTRACKED · filter theo domain/PRD status/doc status · search theo UC/SC ID.
+- Số **UC approved** (`approved_ucs`) trên dashboard = số UC có BDD `@trace.status: approved`, đồng bộ từ `.feature` qua `/validate-traces` (xem `uc_status` ở bảng trace field trên).
 
 **Ba nơi chứa trace data — phân biệt authoritative vs mirror:**
 

package/docs/04-operations/bug-flow.md

@@ -56,6 +56,8 @@ Tester đọc spec chain **PRD → BDD → Code** để xác định layer của
 | Yêu cầu thay đổi | cũ | cũ | **PRD change** | PO → Dev | Tester |
 | ✅ rõ ràng | ✅ đúng | ❌ UI sai | **Design Spec bug** | PO/Designer → Dev | Tester |
 
+> **Sửa PRD/BDD/Design Spec → phải duyệt lại:** mọi case mà PO sửa PRD (Case 3/4), Dev sửa BDD (Case 2), hoặc PO/Designer sửa Design Spec (Case 5) → artifact đó **tự về `draft`** (PRD/Design `Status` ở Metadata; BDD `@trace.status`). Phải `/review-context` lại + người **đặt `approved`** trước khi downstream (tech-docs / code / QC) tiêu thụ. Proposal scenario: PO/Dev đặt `Status: accepted` → `/generate-bdd` tự nạp rồi lưu trữ.
+
 ---
 
 ## 3. Case 1 — Code Bug (Code ≠ BDD)

package/docs/05-reference/command-cheatsheet.md

@@ -22,10 +22,10 @@ flowchart LR
   A["/define-product<br/><b>PO</b>"] --> B["/generate-prd<br/><b>PO</b>"]
   B --> C["/refine-prd<br/><b>PO</b> + Board"]
   C --> D["/review-context (PRD)<br/><b>PO</b> · cổng chất lượng"]
-  D --> E["/generate-design-spec<br/><b>PO</b> (chỉ FE/App)"]
+  D -->|"PO đặt Status: approved"| E["/generate-design-spec<br/><b>PO</b> (chỉ FE/App)"]
   E --> F["/generate-bdd<br/><b>PO</b> · web→app→system"]
   F --> G["/review-context (BDD)<br/><b>SA/Dev</b>"]
-  G --> H["/generate-tech-docs<br/><b>Dev</b> · BE trước, FE sau"]
+  G -->|"đặt @trace.status: approved"| H["/generate-tech-docs<br/><b>Dev</b> · BE trước, FE sau"]
   H --> I["/review-tech-docs<br/><b>Dev</b> + Board"]
   I --> J["/generate-code<br/><b>Dev</b>"]
   J --> K["/review-code<br/><b>Dev</b> · 4 lens"]
@@ -41,11 +41,11 @@ flowchart LR
 
 ```
 PO ───────────────────────────────────────────────────────────────────────────
-  /define-product → /generate-prd → /refine-prd → /review-context(PRD)
+  /define-product → /generate-prd → /refine-prd → /review-context(PRD) → PO đặt Status: approved
                                                    → /generate-design-spec (FE/App)
                                                    → /generate-bdd (web→app→system)
 SA/Dev ────────────────────────────────────────────────────────────────────────
-  /review-context(BDD) → /generate-tech-docs → /review-tech-docs
+  /review-context(BDD) → đặt @trace.status: approved → /generate-tech-docs → /review-tech-docs
                        → /generate-code → /review-code → /dev-gen-test → /dev-run-test
 QC/Tester ──────────────────────────────────────────────────────────────────────
   /qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
@@ -66,11 +66,11 @@ Có **4 lệnh review** cho **4 loại artifact khác nhau**. Đây là điểm
 | **PRD — chất lượng trước khi approve** | `/review-context specs/auth/login/{TICKET-ID}-login.md` | P-checks: banned term, mơ hồ, mâu thuẫn PRD khác, thiếu section, routing theo `Domain` (bảng Metadata) | PO |
 | **BDD `.feature`** | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | B-checks: mỗi AC/BR → có ≥1 scenario? Gherkin R1–R10, compliance C1–C5 | SA/Dev |
 | **Tech design** | `/review-tech-docs specs/auth/login/tech-docs/FEAT-01-UC1-tech-design.md` | T-checks: đúng layer/architecture, entity, trace BDD, cross-team API sign-off | Dev/SA |
-| **Code** | `/review-code FEAT-01-UC1` | 4 lens: Security · Performance · Architecture · Test coverage | Dev |
+| **Code** | `/review-code FEAT-01-UC1` | 4 lăng kính: Traceability · Layer Architecture · Coding Standards · Spec Compliance | Dev |
 
 > **Vì sao PRD có 2 lệnh review?** `/refine-prd` làm **trước** (cải thiện nội dung, fan-out 4 lens). `/review-context` làm **sau** như **cổng chất lượng cuối** trước khi approve + sang BDD. Thứ tự: `generate-prd → refine-prd → review-context → approve`.
 >
-> **Vì sao `/review-context` dùng cho cả PRD lẫn BDD?** Nó tự nhận loại theo file: `.md` trong `prd/` → PRD mode (P-checks); `.feature` → BDD mode (B-checks). Cùng một "cổng chất lượng", hai bộ tiêu chí.
+> **Vì sao `/review-context` dùng cho cả PRD lẫn BDD?** Nó tự nhận loại theo file: `.md` ở gốc feature folder → PRD mode (P-checks); `.feature` → BDD mode (B-checks). Cùng một "cổng chất lượng", hai bộ tiêu chí.
 
 ---
 
@@ -82,7 +82,7 @@ Mọi lệnh review (`/refine-prd`, `/review-context`, `/review-tech-docs`) đ
 ①  /refine-prd {file}                 ②  Mở Review Board (extension)        ③  /…  --resume {file}
    ───────────────────────────           ──────────────────────────────        ──────────────────────────
    PHÂN TÍCH (read-only)        →         DUYỆT từng finding:            →       ÁP DỤNG cái đã accept
-   ghi .agent/review/                     ✓Accept ✎Modify ⏸Defer ✗Reject        + bump version + changelog
+   ghi .agent/review/                     ✓Accept ✎Modify ⏸Defer ✗Reject        + bump version + reset draft + changelog
    {slug}-findings.yaml                   💬 Giải thích (nếu khó hiểu)
 ```
 
@@ -108,7 +108,7 @@ Cùng một lệnh `/review-context` (và họ review nói chung) có **3 chế
 
 ## QC pipeline — 6 bước tuần tự
 
-QC là **chuỗi 6 lệnh chạy theo thứ tự** sau khi BDD đã approved. Output bước trước là input bước sau:
+QC là **chuỗi 6 lệnh chạy theo thứ tự** sau khi BDD `@trace.status: approved`. Output bước trước là input bước sau:
 
 ```
 /qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report

package/docs/05-reference/commands.md

@@ -59,17 +59,19 @@
 | `/generate-prd` | `/generate-prd specs/product-definition/FEAT-01-login.md` | `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
 | `/refine-prd` | `/refine-prd specs/auth/login/{TICKET-ID}-login.md` | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 4 review lens + completeness-critic loop, mở Review Board. |
 | `/refine-prd --resume` | `/refine-prd --resume specs/auth/login/{TICKET-ID}-login.md` | Applied findings + bumped version | Sau khi review trong Review Board (nút ⚡ Apply tự chạy lệnh này). |
-| `/review-context` (PRD) | `/review-context specs/auth/login/{TICKET-ID}-login.md` | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate bắt buộc trước Phase 3. Checks: banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4). |
+| `/review-context` (PRD) | `/review-context specs/auth/login/{TICKET-ID}-login.md` | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate trước Phase 3. Checks: routing P0 (umbrella), banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4), custom (P5). 0 critical → PO đặt `Status: approved`. `--fix`/`--resume` reset Status→draft khi sửa PRD. |
 | `/review-context --fix` | `/review-context --fix specs/auth/login/{TICKET-ID}-login.md` | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
 | `/review-context --resume` | `/review-context --resume specs/auth/login/{TICKET-ID}-login.md` | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
 
+> **Change Log gọn (rolling-window):** PRD chỉ giữ **5 version gần nhất** trong `# Change Log` (bảng phẳng 1 dòng/version); lịch sử cũ hơn được `/refine-prd` & `/review-context` tự dồn sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md` (thư mục con của feature-package). Nhờ vậy PRD **không phình** theo các vòng refine, Dev/QC khỏi nạp lịch sử thừa vào context. `/generate-bdd` đọc 5 row gần để bắt drift; nếu BDD cũ hơn cửa sổ này → khuyến nghị gen lại toàn bộ (F).
+
 ---
 
 ## Phase 2b — Design Spec (FE/App)
 
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
-| `/generate-design-spec` | `/generate-design-spec specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md` | FE/App: sau khi PRD approved, trước BDD. PO phải cấp **node-level Figma frame link** (URL có `?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, spec ở draft và chặn sign-off + `/generate-bdd`. |
+| `/generate-design-spec` | `/generate-design-spec specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md` | FE/App: sau khi PRD approved (guard mềm), trước BDD. Ghi `Built from PRD: vX` (phát hiện lỗi thời); re-run có Version Check theo PRD. PO cấp **node-level Figma frame link** (`?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, Status giữ `draft`. **Self-Review Gate** tự rà trước khi ghi; `/generate-bdd` chỉ **cảnh báo mềm** nếu design-spec chưa approved. |
 
 > BE teams bỏ qua Phase 2b — đọc PRD trực tiếp rồi `/generate-bdd`.
 
@@ -79,10 +81,10 @@
 
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
-| `/generate-bdd` | `/generate-bdd specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` (multi-service: `{prd-slug}/bdd/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. **Thứ tự outside-in: web → app → system**; `system` **tổng hợp từ web+app BDD** (web&app lệch contract → CHECKPOINT chọn union/platform-hint/separate-endpoints, ghi `@system.resolution:`; chỉ-BE → từ PRD). PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). |
-| `/review-context` (BDD) | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `.agent/review/{uc-id}-review-bdd-findings.yaml` | Quality gate bắt buộc trước Phase 4. Checks: PRD coverage (mỗi AC + BR → ≥1 SC), Gherkin R1–R10, compliance C1–C5. |
-| `/review-context --fix` | `/review-context --fix specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Auto-fix terminology, metadata, coverage matrix | Dev quick-fix. |
-| `/review-context --resume` | `/review-context --resume specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | Applies accepted findings + bump bdd_version | SA review. |
+| `/generate-bdd` | `/generate-bdd specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` (multi-service: `{prd-slug}/bdd/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. **Thứ tự outside-in: web → app → system**; `system` **tổng hợp từ web+app BDD** (web&app lệch contract → CHECKPOINT chọn union/platform-hint/separate-endpoints, ghi `@system.resolution:`; chỉ-BE → từ PRD). PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). FE/App: nuốt AC-UI + Screen States từ design-spec (gate approved+fresh+sanity). Proposal tester: chỉ nạp `Status: accepted` rồi lưu trữ. |
+| `/review-context` (BDD) | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `.agent/review/{uc-id}-review-bdd-findings.yaml` | Quality gate trước Phase 4. Checks: PRD coverage (mỗi AC + BR → ≥1 SC), Gherkin R1–R10, compliance C1–C5. 0 critical → đặt `@trace.status: approved`. |
+| `/review-context --fix` | `/review-context --fix specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Auto-fix terminology, metadata, coverage matrix + reset `@trace.status` & `uc_status` → draft | Dev quick-fix. |
+| `/review-context --resume` | `/review-context --resume specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | Applies accepted findings + bump bdd_version + reset `@trace.status` & `uc_status` → draft | SA review. |
 
 ---
 
@@ -101,7 +103,7 @@
 
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
-| `/generate-code` | `/generate-code specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `src/...` (tags `@trace.implements`) | After tech-design approved. Default = full impl/BE. |
+| `/generate-code` | `/generate-code specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `src/...` (tags `@trace.implements`) | After tech-design approved. Guard mềm: BDD `@trace.status` approved; FE/App design-spec approved+fresh+sanity. Default = full impl/BE. |
 | `/generate-code --phase=ui` | `/generate-code --phase=ui specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | UI + mock API adapter | FE: BE chưa sẵn sàng — sinh UI + mock adapter. Mock **shape**: BE contract nếu có (chuẩn) → else System BDD + warn; fixture values luôn từ System BDD. Tester test FE ngay được. |
 | `/generate-code --phase=integration` | `/generate-code --phase=integration specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Wires real API | FE: sau khi T7 sign-off gate approved — thay mock adapter bằng real API calls. |
 | `/review-code` | `/review-code FEAT-01-UC1` | Review report: Critical / Major / Minor | After generate-code. Check: mỗi scenario có endpoint, trace tags, layer rules, error handling khớp CLAUDE.md §5. Fix CRITICAL + MAJOR trước khi merge. |
@@ -122,11 +124,11 @@
 
 ## Phase 6b — QC Automation (official QC suite)
 
-> Pipeline `/qc-*` **là** official QC suite. Chạy **theo thứ tự** sau khi BDD approved (`/review-context` (BDD) APPROVED). Tách biệt hoàn toàn với dev self-check: QC sở hữu `qc_status`, dev sở hữu `dev_selftest`. `/qc-run-test` & `/qc-report` dùng module `qc-playwright`, độc lập với dev implementation module. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
+> Pipeline `/qc-*` **là** official QC suite. Chạy **theo thứ tự** 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). Tách biệt hoàn toàn với dev self-check: QC sở hữu `qc_status`, dev sở hữu `dev_selftest`. `/qc-run-test` & `/qc-report` dùng module `qc-playwright`, độc lập với dev implementation module. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
 
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
-| `/qc-analyze` | `/qc-analyze FEAT-01-UC1` | **2 file** trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`): `REQUIREMENT_ANALYSIS.md` (gộp requirement + BR + data-flow + AC) + `DOC_GAPS.md` | After BDD approved — đầu pipeline QC. |
+| `/qc-analyze` | `/qc-analyze FEAT-01-UC1` | **2 file** trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`): `REQUIREMENT_ANALYSIS.md` (gộp requirement + BR + data-flow + AC) + `DOC_GAPS.md` | After BDD `@trace.status: approved` (guard mềm) — đầu pipeline QC. |
 | `/qc-plan` | `/qc-plan FEAT-01-UC1` | `{qc_dir}/{UC-ID}/TEST_PLAN.md` (scope, layers, priorities, questions-for-dev) | After `/qc-analyze`. |
 | `/qc-design-test` | `/qc-design-test FEAT-01-UC1` | `{qc_dir}/{UC-ID}/test-cases/*.Test.md` mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
 | `/qc-review` | `/qc-review FEAT-01-UC1` | Verdict APPROVED / NEEDS_FIX + findings (**inline — không sinh file**) | After `/qc-design-test` (test-case) hoặc `/qc-run-test` (script). |
@@ -150,7 +152,7 @@
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
 | `/report-bug {UC-ID} {desc}` | `/report-bug FEAT-01-UC1 "nhập sai mật khẩu vẫn đăng nhập được"` | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester hoặc QC tìm thấy bug (gồm QC product-gap). Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
-| `/propose-scenario {UC-ID} {desc}` | `/propose-scenario FEAT-01-UC1 "khoá tài khoản sau 5 lần sai mật khẩu"` | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin | Tester hoặc QC tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. |
+| `/propose-scenario {UC-ID} {desc}` | `/propose-scenario FEAT-01-UC1 "khoá tài khoản sau 5 lần sai mật khẩu"` | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin (mang `Status: proposed`) | Tester hoặc QC tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. Vòng đời: `proposed` → PO/Dev đặt `accepted` → `/generate-bdd` nạp rồi đặt `incorporated` + lưu trữ. |
 
 ---
 

package/docs/05-reference/trace-schema.md

@@ -51,7 +51,7 @@ sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selft
 | 16 | `tech_doc_revision` | **BE** API-contract revision tại thời điểm codegen | `—` | generate-code / review-tech-docs (BE doc) |
 | 17 | `fe_tech_doc_revision` | **FE** client tech-design revision (`{UC-ID}-tech-design-{platform}.md`) tại thời điểm FE integration | `—` | generate-code `--phase=integration` / review-tech-docs (FE doc) |
 | 18 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
-| 19 | `uc_status` | Trạng thái UC: `draft` / `approved` / … | `draft` (UC mới) | generate-bdd |
+| 19 | `uc_status` | Trạng thái duyệt BDD của UC — **gương của `@trace.status`** (`.feature`): `draft` / `approved` | `draft` (UC mới) | generate-bdd (init) · validate-traces (sync ← `@trace.status`) · review-context (reset draft khi `--fix`/`--resume`) |
 | 20 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
 | 21 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
 | 22 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
@@ -105,6 +105,7 @@ Mọi artifact link với nhau qua `@trace.*` tags.
 # @trace.id: FEAT-001-UC1
 # @trace.service: web-admin
 # @trace.module: react
+# @trace.status: draft          # draft/approved — người đặt approved sau review-context BDD sạch; mirror → uc_status
 # @trace.prd_version: 1.2
 # @trace.bdd_version: 3
 # @trace.api_source: existing   # brownfield: API đã tồn tại, contract lấy từ PRD