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

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)

package/docs/03-concepts/traceability.md

@@ -18,11 +18,11 @@ 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
-  └─► PRD.md (@trace.domain, @trace.status; Service/Module trong metadata)
+  └─► PRD.md (Domain, Status, Service/Module — đều trong bảng Metadata)
         └─► specs/{domain}/{prd-slug}/bdd/{web|app|system}/{UC-ID}.feature (@trace.prd_version, @trace.module)
               └─► specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design*.md (@trace.bdd_version)
                     └─► src/ code — service submodule (@trace.implements)
@@ -34,8 +34,10 @@ product-definition.md
 
 | Field | Vị trí | Ý nghĩa |
 |-------|--------|---------|
-| `@trace.domain` | PRD frontmatter | Domain của feature (auth, payment, …) — route vào đúng service submodule |
-| `@trace.status` | PRD frontmatter | `draft` / `approved` — dev team chỉ code khi `approved` |
+| `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/04-operations/sync-and-update.md

@@ -256,7 +256,7 @@ Topology giả định cho mọi ví dụ dưới đây:
 **① PO — 1 tầng (spec repo)**
 ```bash
 cd my-project-specs && git pull
-# /generate-prd · /generate-design-spec · /generate-bdd (web/app/system) · set @trace.status: approved
+# /generate-prd · /generate-design-spec · /generate-bdd (web/app/system) · set Status: approved (bảng Metadata)
 git add specs/payment/checkout/{TICKET-ID}-checkout.md \
         specs/payment/checkout/design-spec/FT-042-checkout-design.md \
         specs/payment/checkout/bdd/system/FT-042-UC1-checkout-system.feature \
@@ -400,7 +400,7 @@ git pull
 /refine-prd {prd-file}                   # review 4 lens: QA/DEV/SA/PO
 /review-context {prd-file}               # chất lượng + P0 check
 /review-context --fix {prd-file}         # auto-fix vấn đề nhỏ
-# → update @trace.status: approved khi PRD sẵn sàng
+# → update Status: approved (bảng Metadata) khi PRD sẵn sàng
 /generate-design-spec {prd-file}         # FE/App
 /generate-bdd {prd-file}                 # outside-in: web → app → system (System BDD tổng hợp từ web+app)
 
@@ -417,7 +417,7 @@ cd my-project-web
 git add my-project-specs && git commit -m "chore: sync specs" && git push
 
 /review-context my-project-specs/specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-# → P0: @trace.domain khớp services config? @trace.status: approved?
+# → P0: Domain (bảng Metadata) khớp services config? Status: approved?
 # Đọc Web BDD do PO generate (KHÔNG tự generate BDD):
 #   my-project-specs/specs/{domain}/{prd-slug}/bdd/web/{TICKET-ID}-UC*.feature
 

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
@@ -63,14 +63,14 @@ Có **4 lệnh review** cho **4 loại artifact khác nhau**. Đây là điểm
 | Tôi muốn review… | Cách dùng (ví dụ) | Nó kiểm cái gì | Ai chạy |
 |---|---|---|---|
 | **PRD — nội dung & độ đầy đủ** | `/refine-prd specs/auth/login/{TICKET-ID}-login.md` | 4 lens QA·DEV·SA·PO: AC có test được? edge case? scope rõ? | PO |
-| **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 `@trace.domain` | PO |
+| **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edupia-tutor/spec-driven-docs",
-  "version": "0.14.6",
+  "version": "0.14.8",
   "description": "AI-First Spec-Driven Development workflow framework for Claude Code",
   "bin": {
     "spec-driven-docs": "./bin/index.js"