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

package/core/steps/report-footer.md

@@ -60,7 +60,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

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/core/templates/project-context.yaml

@@ -14,7 +14,7 @@
 # 3. When a workflow says "→ key.subkey", look up that key
 #    and use the resolved value as the actual path
 # 4. All paths are RELATIVE to workspace root
-# 5. For "{domain}", substitute from spec's @trace.domain
+# 5. For "{domain}", substitute the feature's domain (PRD: row `Domain` in Metadata / folder path; .feature: @trace.domain)
 # =============================================================
 
 project:
@@ -132,7 +132,7 @@ domains:
 # With spec_source set, only ONE override is needed instead of four separate dir vars.
 #
 # services:                                   # domain → service submodule routing
-#   {{DOMAIN_1}}:                             # must match @trace.domain in PRD files
+#   {{DOMAIN_1}}:                             # must match the PRD's `Domain` (Metadata row) / folder path segment
 #     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
 #     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
 #     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —

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)
@@ -93,7 +93,7 @@ my-project-umbrella/          ← mở Claude Code ở đây
 ```
 
 - **Spec module** (`{spec_source}/`): chứa PRD, Design Spec, **ALL BDD (web/app/system)**, tech-docs (BE API contract + FE tech-design), domain-knowledge, feedback — shared để mọi umbrella đọc cùng nguồn. Report canonical của Living Docs cũng sinh tại `{spec_source}/.living-docs/`.
-- **Routing:** context-loader đọc `@trace.domain` từ PRD → tra trong `services` config → route **code** vào đúng service submodule; **BDD + tech-docs + specs + `.trace/` + feedback** đều ở spec module (cross-team, một chỗ cho PM). PRD phải có `@trace.domain` khớp một key trong `services`.
+- **Routing:** context-loader đọc row `Domain` (bảng Metadata) từ PRD → tra trong `services` config → route **code** vào đúng service submodule; **BDD + tech-docs + specs + `.trace/` + feedback** đều ở spec module (cross-team, một chỗ cho PM). PRD phải có row `Domain` khớp một key trong `services`.
 
 Setup umbrella đầy đủ, file ownership, two-layer commit, multi-platform → [Operations › Sync & Update §4 Umbrella mode](../04-operations/sync-and-update.md#4-umbrella-mode--git-submodule).
 

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

@@ -57,11 +57,12 @@ Framework dùng metadata `@trace.*` để liên kết PRD → BDD → Code. (Chi
 
 | Field | Vị trí | Ý nghĩa |
 |---|---|---|
-| `@trace.domain` | PRD frontmatter | Domain của feature (auth, payment, ...) — dùng để route vào đúng service submodule |
+| `Domain` | bảng Metadata PRD | Domain của feature (auth, payment, ...) — dùng để route vào đúng service submodule |
 | `@trace.module` | BDD / Tech Doc header | Module trong codebase sẽ implement |
 | `@trace.prd` | BDD / Tech Doc header | Link về PRD gốc |
 | `@trace.bdd` | Code comment / test | Link về BDD scenario |
-| `@trace.status` | PRD frontmatter | `draft` / `approved` — chỉ code khi `approved` |
+| `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` |
@@ -70,7 +71,7 @@ Framework dùng metadata `@trace.*` để liên kết PRD → BDD → Code. (Chi
 ### Ví dụ trace chain hoàn chỉnh
 
 ```
-specs/auth/login/{TICKET-ID}-login.md                              ← @trace.domain: auth, @trace.status: approved
+specs/auth/login/{TICKET-ID}-login.md                              ← Metadata: Domain: auth, Status: approved
     ↓
 specs/auth/login/bdd/system/FT-001-UC1-login.feature ← @trace.prd: FT-001 · web/app/system riêng (system tổng hợp từ web+app)
     ↓

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/scenarios.md

@@ -21,7 +21,7 @@
    (lấy PRD + BDD mới nhất từ PO)
 
 2. /review-context my-project-specs/specs/payment/checkout/{TICKET-ID}-checkout.md
-   → Kiểm tra @trace.status = approved (không code khi còn draft)
+   → Kiểm tra Status = approved (bảng Metadata PRD; không code khi còn draft)
    → Đọc kỹ AC, UC, BR
 
 3. Đọc BDD tương ứng theo platform của mình:
@@ -343,7 +343,7 @@ code .   ← hoặc claude .
 # → sync Living Docs panel
 
 # 4. Framework tự detect umbrella mode từ project-context.yaml
-# Khi chạy /review-context với PRD có @trace.domain: be
+# Khi chạy /review-context với PRD có Domain: be (bảng Metadata)
 # → CODE route tới mass-product-be/  ·  BDD đọc từ spec repo mass-product-spec/specs/{domain}/{prd-slug}/bdd/ (spec_source set)
 ```
 

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])
 ```
 
@@ -45,7 +45,7 @@ Nhận thông báo PRD + BDD mới từ PO
         │
         ▼
 /review-context {prd-file}
-→ Kiểm tra @trace.domain, @trace.status = approved
+→ Kiểm tra Domain, Status = approved (bảng Metadata PRD)
 → Đọc hiểu AC, UC, BR trong PRD
 → Đọc BDD tương ứng trong specs/{domain}/{prd-slug}/bdd/{platform}/
 → Nếu có gì không rõ: hỏi PO TRƯỚC khi tiếp tục
@@ -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 |
 
@@ -32,8 +34,8 @@ PO/BA                     Dev team
 
 **PO/BA chịu trách nhiệm:**
 - Đảm bảo PRD platform-agnostic (không chứa UI details hay API specs)
-- Đặt `@trace.domain` đúng để dev team routing hoạt động
-- Cập nhật `@trace.status: approved` trước khi handoff
+- Đặt row `Domain` (bảng Metadata) đúng để dev team routing hoạt động
+- Cập nhật `Status: approved` (bảng Metadata) trước khi handoff
 - **Generate BDD cho tất cả platforms** theo thứ tự **outside-in: web → app → system** — System BDD được **tổng hợp từ web+app BDD** (project chỉ-BE thì system gen thẳng từ PRD). Xem [scenarios](scenarios.md).
 - Thông báo dev team khi có PRD hoặc BDD mới/update
 
@@ -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/product-owner/handoff-checklist.md

@@ -5,10 +5,10 @@
 Trước khi thông báo dev team bắt đầu, kiểm tra:
 
 **Metadata:**
-- [ ] `@trace.id` có và đúng format (vd: FEAT-01)
-- [ ] `@trace.domain` có và khớp với domain names đã thống nhất với dev team
-- [ ] `@trace.status: approved` (không phải draft/in-review)
-- [ ] `@trace.version` có (vd: 1.0)
+- [ ] Row `Ticket` (bảng Metadata) có và đúng format (vd: FEAT-01)
+- [ ] Row `Domain` có và khớp với domain names đã thống nhất với dev team
+- [ ] Row `Status` = `approved` (không phải draft)
+- [ ] Row `Version` có (vd: 1.0)
 
 **Nội dung PRD:**
 - [ ] Tất cả `{{PLACEHOLDER}}` đã được điền
@@ -23,7 +23,7 @@ Trước khi thông báo dev team bắt đầu, kiểm tra:
 - [ ] Không có P3 conflict với PRD khác trong cùng domain
 
 **Cho FE/App thêm:**
-- [ ] Design Spec đã tạo và `@trace.status: approved` (không còn `draft`)
+- [ ] Design Spec đã tạo và `Status: approved` trong Metadata (không còn `draft`)
 - [ ] Mỗi screen có Figma link node-level (`?node-id=`) — không screen nào bị flag ❌ Missing
 - [ ] Designer đã sign-off (gate này bị BLOCKED nếu còn screen thiếu node-id link)
 

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

@@ -40,13 +40,13 @@ Mở findings file, xem xét từng finding: `accepted` → apply · `modified`
 ```
 /review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
-Kiểm tra: `@trace.status`, `@trace.domain`, completeness.
+Kiểm tra: `Status`, `Domain` (bảng Metadata), completeness.
 
 **Bước 5 — Approve PRD:**
 ```yaml
-# Trong file PRD, cập nhật:
-@trace.status: approved
-@trace.version: 1.0
+# Trong bảng Metadata của PRD, cập nhật:
+#   | **Status**  | approved |
+#   | **Version** | 1.0      |
 ```
 
 **Bước 6 — Tạo Design Spec (FE/App):**
@@ -55,7 +55,7 @@ Kiểm tra: `@trace.status`, `@trace.domain`, completeness.
 ```
 Agent hỏi platform (web / app). PO phải cung cấp **Figma link node-level** (URL chứa `?node-id=`, lấy bằng right-click vào frame → "Copy link to selection") cho **mỗi screen**. Screen nào thiếu link → bị flag ❌ Missing, Status giữ `draft`, `/generate-bdd` bị BLOCKED cho đến khi đủ link.
 
-Sau khi Designer review + confirm đủ Figma node-id links → `@trace.status: approved`.
+Sau khi Designer review + confirm đủ Figma node-id links → đặt `Status: approved` trong Metadata Design Spec.
 
 **Bước 7 — Generate BDD:**
 ```
@@ -84,7 +84,7 @@ git push
 
 ```
 /define-product         → product definition
-/generate-prd           → PRD với @trace.domain: auth
+/generate-prd           → PRD với Domain: auth (bảng Metadata)
 /review-context --fix   → auto-fix
 /generate-design-spec   → design spec cho FE (nếu có designer)
 /generate-bdd → web     → specs/auth/FEAT-01-login/bdd/web/
@@ -115,7 +115,7 @@ git push
 ```
 Output: `specs/auth/FEAT-01-login/design-spec/FEAT-01-design-spec-web.md`
 
-Mỗi screen cần Figma link node-id. Screen thiếu → flag ❌ Missing, BLOCKED. Sau khi Designer review → `@trace.status: approved`.
+Mỗi screen cần Figma link node-id. Screen thiếu → flag ❌ Missing, BLOCKED. Sau khi Designer review → đặt `Status: approved` trong Metadata Design Spec.
 
 **Bước 2 — Generate BDD:**
 ```
@@ -162,7 +162,8 @@ Lặp lại cho đến khi `recommendation: APPROVED`.
 
 **Bước 1 — Đổi status về draft:**
 ```yaml
-@trace.status: draft
+# Trong bảng Metadata PRD:
+#   | **Status** | draft |
 ```
 
 **Bước 2 — Sửa nội dung:**
@@ -178,9 +179,9 @@ Lặp lại cho đến khi `recommendation: APPROVED`.
 
 **Bước 4 — Approve và thông báo:**
 ```yaml
-@trace.status: approved
-@trace.version: 1.1     # minor bump vì chỉ thêm AC
-                         # major bump (2.0) nếu thay đổi cơ bản
+# Trong bảng Metadata PRD:
+#   | **Status**  | approved |
+#   | **Version** | 1.1      |   # minor bump (chỉ thêm AC); major (2.0) nếu thay đổi cơ bản
 ```
 ```bash
 git add specs/auth/FEAT-01-login/FEAT-01-login.md
@@ -225,7 +226,7 @@ services:
     specs_dir: "loyalty-service/specs/bdd"
 ```
 
-**Bước 3 — Viết PRD bình thường với `@trace.domain: loyalty`.**
+**Bước 3 — Viết PRD bình thường với `Domain: loyalty` (bảng Metadata).**
 
 > **Lưu ý:** Nếu dev team chưa cập nhật services config → `/review-context` P0 check sẽ cảnh báo domain không match.
 
@@ -281,7 +282,7 @@ specs/
 
 ```bash
 # Xem nhanh tất cả PRDs và status:
-grep -r "@trace.status" specs/ --include="*.md"
+grep -rn "\*\*Status\*\*" specs/ --include="*.md"
 ```
 
 ---
@@ -290,10 +291,11 @@ grep -r "@trace.status" specs/ --include="*.md"
 
 **Checklist trước khi thông báo:**
 ```yaml
-@trace.id: FEAT-01          ✅ có
-@trace.domain: auth         ✅ khớp với services keys của dev team
-@trace.status: approved     ✅ đã approved
-@trace.version: 1.0         ✅ có version number
+# Bảng Metadata PRD:
+#   | **Ticket**  | FEAT-01  |   ✅ có (đúng format)
+#   | **Domain**  | auth     |   ✅ khớp services keys của dev team
+#   | **Status**  | approved |   ✅ đã approved
+#   | **Version** | 1.0      |   ✅ có version number
 ```
 
 ```