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

package/core/steps/review-fanout.md

@@ -112,6 +112,13 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
    List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
    contradictions, missing edge/negative paths, coverage holes, terminology drift,
    structural omissions, and any issue that a fix to an existing finding would expose.
+   ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
+   content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
+   names/owners, error branches) written INSIDE an acceptance criterion or a scope line
+   instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
+   (same content, converged); a term definition crammed into In/Out Scope. For these, the
+   suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
+   outcome + BR ref) — NOT to delete it, and NOT to add more detail.
    Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
    nothing new.
    ```

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/feature.template

@@ -1,259 +1,120 @@
 # ============================================================
-# BDD Feature Template — KVLoyalty AI Native Pipeline (v2)
+# @trace.id: {TICKET-ID}-UC{N}
+# @trace.title: <Feature name>
+# @trace.revision: 1  ← field tĩnh; dùng @trace.bdd_version để theo dõi version (tăng bởi /review-context --fix hoặc --resume)
+# @trace.domain: <domain>
+# @trace.platform: {active_platform — web | app | system | (bỏ trong umbrella mode)}
+# @trace.service: {active_service — bỏ trong spec repo mode}
+# @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
+# @trace.status: draft
+# @trace.author: AI-generated
+# @trace.created_at: {YYYY-MM-DD}
+# @trace.prd: {TICKET-ID}
+# @trace.prd_version: {đọc từ metadata PRD "| **Version** |"}
+# @trace.bdd_version: {1.0 nếu gen mới; tăng 0.1 khi gen lại — vd 1.0 → 1.1}
+# @trace.business_rules: {TICKET-ID}-UC{N}-BR1, {TICKET-ID}-UC{N}-BR2
+# @trace.dataset: {domain}.testdata.yaml
 # ============================================================
-# Instructions:
-#   1. Copy this file và rename: {TICKET_ID}-UC{N}-feature-name.feature
-#   2. Điền @trace metadata (required)
-#   3. Khai báo Context của UC (1 lần, đầu file)
-#   4. Tạo/cập nhật dataset YAML cùng domain: specs/features/{domain}.testdata.yaml
-#   5. Viết Scenario — mỗi SC PHẢI có dòng `# Side-effects:` ngay trên
-#   6. Đặt file ở: specs/features/{domain}/
-#   7. Chạy: /generate-code
-# ============================================================
-#
-# RULE VIẾT BDD BẮT BUỘC (xem bdd-writing-guide.md PART A + C):
-#   R1  Given/When/Then Semantics  — Given=state, When=action, Then=outcome (mỗi SC đủ G/W/T)
-#   R2  One Behavior Per Scenario  — 1 SC = 1 behavior; KHÔNG chain When-Then
-#   R3  Ubiquitous Language        — KHÔNG dùng UI selector / API name / tech term
-#   R4  Outside-in Naming          — Tên SC mô tả business outcome, KHÔNG có "click"/"(Case X)"/component name
-#   R5  Declarative over Imperative — Mô tả WHAT (intent business), KHÔNG HOW (UI mechanic)
-#   R6  Observable Outcomes Only   — Then assert outcome quan sát được, KHÔNG UI trung gian/internal state
-#   R7  Key Examples / Concrete    — Dùng concrete values, KHÔNG "hợp lệ" chung chung
-#   R8  Independence               — SC chạy độc lập, KHÔNG phụ thuộc state SC khác
-#   R9  Test Data Completeness     — Data table có đủ field external system để derive expected Then
-#   R10 Scope Boundary Explicit    — Cross-UC reference dùng wording navigation + Note comment
-# PROJECT COMPLIANCE (must-pass, fail review nếu thiếu):
-#   C.1 Wireframe Coverage         — Mọi component/action wireframe có ≥1 SC
-#   C.2 PRD Traceability           — Mọi AC/BR (kèm bullet) map về ≥1 SC
-#   C.3 Business Dictionary        — Dùng đúng term, đề xuất term mới qua DICTIONARY-SUGGESTION
-#   C.4 Banned Terms Compliance    — 0 banned term (auto-grep): SKU/Customer/JS SDK/Cửa hàng/...
-#   C.5 NHÓM Grouping Convention   — Scenarios gom theo CHỦ ĐỀ NGHIỆP VỤ (NHÓM N) — xem §NHÓM GROUPING CONVENTION dưới
-# ============================================================
-
-# --- TRACE METADATA (REQUIRED) ---
-# @trace.id: {TICKET_ID}-UC{N}
-# @trace.title: <Tên tính năng bằng tiếng Việt>
-# @trace.revision: 1
-# @trace.domain: <identity|loyalty|membership|messaging|store-management>
-# @trace.service: <KVLoyalty.Identity|KVLoyalty.Loyalty|...>
-# @trace.status: draft|review|approved
-# @trace.author: <tên tác giả>
-# @trace.created_at: <YYYY-MM-DD>
-# @trace.prd: <TICKET-ID hoặc để trống>
-# @trace.prd_version: <version PRD tại thời điểm viết — để drift-detector so sánh>
-# @trace.business_rules: <{TICKET_ID}-UC{N}-BR{M}, ...>
-# @trace.dataset: <{domain}.testdata.yaml — bắt buộc nếu BDD reference dataset>
 
-# === CONTEXT (áp dụng cho toàn Feature) ===
+# === CONTEXT ===
 # Actor:     <vai trò thực hiện hành động, vd: Consumer, Staff, System>
 # Screens:   <các màn liên quan, vd: Cart → Confirm Order → Order Detail>
-# Entities:  <entity nghiệp vụ, vd: Order, OrderItem, Consumer, Branch>
-# Pre-state: <state chung trước khi vào các scenario>
+# Entities:  <business entity, vd: Order, OrderItem, Consumer>
+# Pre-state: <state dùng chung trước khi vào các scenario>
 
 # === SCOPE ===
-# In:  <những gì UC này cover>
-# Out: <những gì KHÔNG thuộc UC này — link sang UC khác / feature khác (R10)>
+# In:  <UC này phủ gì>
+# Out: <cái gì KHÔNG thuộc UC này — link tới UC/feature khác (R10)>
 
-# === BUSINESS DEFINITION (MANDATORY) ===
-# Quick reference các thuật ngữ dùng trong feature này. SoT chi tiết: business-dictionary.md
-# Mục đích: reader đọc 1 lần hiểu ngay khái niệm trước khi xem scenarios.
+# === BUSINESS DEFINITION ===
+# Tham chiếu nhanh các term dùng trong feature này. Chi tiết SoT: business-dictionary.md
+# <Term 1>: <định nghĩa ngắn>
+# <Term 2>: <định nghĩa ngắn>
 #
-# <Term 1> (English mapping): <định nghĩa ngắn gọn, vd cấu trúc, scope>
-# <Term 2>: <định nghĩa>
-# ...
-#
-# === Test data convention (R9) ===
-# Khai báo default value khi data table không có cột tương ứng.
-# VD: "SC không khai báo cột customerOrdered → ngầm hiểu customerOrdered = 0 (chưa có khách đặt)"
-# VD: "SC không khai báo cột toggle → ngầm hiểu toggle = Hiện (default Ẩn/Hiện trạng thái)"
-#
-# === Popup/Modal Lifecycle (B.2.4 — bắt buộc nếu feature là popup/modal) ===
+# --- Popup/Modal Lifecycle (tùy chọn — BẮT BUỘC nếu feature là popup/modal; Pre-merge yêu cầu) ---
 # - Open trigger:   <khi nào popup hiển thị, vd: click menu sidebar>
 # - Close trigger:  <khi nào popup đóng, vd: F5 / click X / ESC / navigate away>
 # - Refresh model:  <data refresh khi nào, vd: mỗi lần open (NO CACHE) / persisted / polling>
 # - State reset:    <state nào reset khi đóng/mở lại, vd: pagination, expand, dropdown selection>
-
-# === DISPLAY LOGIC MATRIX (optional — bắt buộc nếu display logic phụ thuộc ≥2 dimension, B.1.7) ===
-# Enumerate full matrix N×M case + map mỗi case → SC.
-# Tên SC theo pattern: `<cấu trúc>: <outcome>` — KHÔNG dùng "(Case X)" suffix.
-# VD ma trận `{số thuộc tính: 0/1/≥2} × {số đơn vị tính: 0/1/≥2}` = 9 case:
 #
-# | # | Dim1 | Dim2 | Format hiển thị                              | SC   |
-# |---|------|------|----------------------------------------------|------|
-# | 1 | 0    | 0    | `Tên hàng`                                   | SC{} |
-# | 2 | 0    | 1    | `Tên hàng (đơn vị)`                          | SC{} |
-# | ... | ... | ...  | ...                                          | ...  |
-
-# === DICTIONARY REFERENCES (R3 + C.4) ===
-# Liệt kê các term từ business-dictionary.md mà feature này dùng → pointer cho reviewer auto-check.
-# Banned terms (xem business-dictionary.md § Banned Terms) MUST NOT appear: 0 match khi grep.
-#
-# Terms dùng trong feature này:
-# - <Term 1> (xem dictionary line {N})
-# - <Term 2> (xem dictionary line {M})
-# - ...
-
-Feature: <Tên tính năng bằng tiếng Việt>
-  Với vai trò là <vai trò>
-  Tôi muốn <hành động>
-  Để <lợi ích nghiệp vụ>
-
-  # --- DATASET REFERENCE CONVENTION ---
-  # Ưu tiên dùng ALIAS (tiếng Việt) thay vì ID kỹ thuật, để BDD dễ đọc.
-  # Backtick ID chỉ dùng khi cần precision (vd: assertion về mã đơn).
-  #
-  # Ví dụ:
-  #   ✅ Given đơn hàng draft "Đơn COD giao hàng — 2× áo + 1× quần, total 650K"
-  #   ✅ Then đơn được gán mã `ZMA{id}` nhận từ Retail
-  #   ❌ Given đơn hàng draft là `ORD_COD_DRAFT_001`   ← khó đọc, hạn chế
+# --- Display Logic Matrix (tùy chọn — BẮT BUỘC nếu display logic phụ thuộc ≥2 chiều; Pre-merge yêu cầu) ---
+# Liệt kê đủ ma trận N×M case + map mỗi case → SC. Tên SC theo pattern `<cấu trúc>: <outcome>` (KHÔNG dùng "(Case X)").
+# | # | Dim1 | Dim2 | Format hiển thị        | SC   |
+# |---|------|------|------------------------|------|
+# | 1 | 0    | 0    | `Tên hàng`             | SC{} |
+# | 2 | 0    | 1    | `Tên hàng (đơn vị)`    | SC{} |
+# | ... | ...  | ...  | ...                    | ...  |
+
+Feature: <Feature name>
+  As a <role>
+  I want to <action>
+  So that <business value>
 
   Background:
-    Given <điều kiện tiên quyết chung — dùng alias từ dataset>
-    # Ví dụ: Given consumer "Khách mới đã cấp quyền Zalo" ở màn "Xác nhận đơn hàng"
-    #        của gian hàng "Cửa hàng Thời Trang (đang kích hoạt)"
-
-  # ============================================================
-  # § NHÓM GROUPING CONVENTION (C.5 — bắt buộc cho mọi feature ≥3 SCs)
-  # ============================================================
-  # Mục đích: organize scenarios theo CHỦ ĐỀ NGHIỆP VỤ để dễ navigate + scope-awareness, KHÔNG
-  # theo phân loại happy/negative/edge (deprecated section markers HAPPY-PATH / NEGATIVE-CASE / EDGE-CASE).
-  #
-  # Quy tắc:
-  #   1. **Gom theo chủ đề business** — mỗi NHÓM = 1 business theme (flow / state / behavior subset).
-  #      ✅ NHÓM 1: Khởi tạo gian hàng thành công với dữ liệu mặc định (BR1, BR2)
-  #      ✅ NHÓM 2: Resume khi onboarding bị gián đoạn (BR1 resume)
-  #      ✅ NHÓM 3: Xử lý lỗi khởi tạo (BR3)
-  #      ❌ NHÓM 1: HAPPY-PATH         ← chia theo loại path, không phải chủ đề
-  #      ❌ NHÓM 1: COD scenarios      ← UI feature, không phải business theme
-  #
-  #   2. **Mỗi NHÓM có thể chứa cả @happy + @edge + @negative SCs cùng chủ đề** — KHÔNG tách happy/edge ra 2 NHÓM riêng.
-  #      Ví dụ: NHÓM "Xử lý lỗi khi khởi tạo" chứa SC happy retry + SC edge X close + SC negative no retry.
-  #      Tag taxonomy (@happy/@edge/@cross-system per B.2.3) áp dụng ở SC level — KHÔNG ở NHÓM level.
-  #
-  #   3. **Format NHÓM header** (3 dòng comment box):
-  #         # ==========================================================
-  #         # NHÓM N: <Chủ đề> (<BR refs nếu áp dụng>)
-  #         # ==========================================================
-  #      Indent 2 spaces (cùng level với Background + Scenario).
-  #
-  #   4. **Đánh số NHÓM tuần tự** từ 1 → N. Không skip số. Reorder NHÓM được — KHÔNG ảnh hưởng SC IDs.
-  #
-  #   5. **SC trong NHÓM KHÔNG cần theo thứ tự ID** — VD NHÓM 2 có thể chứa SC8, SC4, SC11 nếu cùng chủ đề.
-  #      SC IDs tuần tự theo lifecycle (skill §3.4), KHÔNG theo NHÓM ordering.
-  #
-  #   6. **Khi nào skip NHÓM**: feature có <3 SCs → có thể bỏ NHÓM headers (không value to organize so few).
-  #      Đơn giản đặt SCs nối tiếp sau Background. Feature ≥3 SCs → BẮT BUỘC NHÓM.
-  #
-  # Pattern thường gặp (gợi ý theme — tuỳ chỉnh per UC):
-  #   - "Khởi tạo / Lưu thành công — các tổ hợp data hợp lệ" (gom happy + alternative)
-  #   - "Validation / Chặn lưu khi không hợp lệ" (gom negative + edge validation)
-  #   - "Xử lý lỗi — API fail / system error" (gom negative + recovery)
-  #   - "Hủy thay đổi / Đóng modal không lưu" (gom edge UX)
-  #   - "Hành vi popup / dialog — multi-select / persist / boundary" (gom edge UX behavior)
-  #   - "Hiệu ứng cross-system / Consumer view" (gom @cross-system SCs)
-  #   - "Idempotency & Concurrency" (gom edge concurrency)
-  #   - "State transition / Recovery completion" (gom @cross-UC behavior chains)
-  #
-  # Ví dụ NHÓM structure cho UC có 9 SCs (LOYAL-32-UC1 reference):
-  #   NHÓM 1: Lưu cấu hình thành công — các tổ hợp PTTT hợp lệ (BR1, BR2)    → SC1, SC2, SC3, SC4
-  #   NHÓM 2: Chặn lưu khi cấu hình không hợp lệ (BR1, BR2) + lỗi hệ thống   → SC5, SC6, SC7
-  #   NHÓM 3: Hủy thay đổi — đóng Modal không lưu                            → SC8
-  #   NHÓM 4: Initial State — Modal phản ánh cấu hình hiện tại               → SC10
+    Given <precondition dùng chung — dùng alias từ dataset, không phải ID kỹ thuật>
 
   # ==========================================================
-  # NHÓM 1: <Chủ đề business 1> (<BR refs nếu cần>)
+  # NHÓM 1: <Business theme> (<BR refs>)
   # ==========================================================
 
-  # Side-effects: <liệt kê NGẮN GỌN các hậu quả Then phải verify — 1 dòng>
-  # @trace.scenario: {TICKET_ID}-UC{N}-SC1
+  # Side-effects: <liệt kê ngắn các Then side-effect cần verify>
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC1
   # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
   @happy
-
-  Scenario: <Mô tả luồng chính — dùng động từ CHÍNH XÁC (tạo/nhận/gán/đồng bộ)>
-    Given <state đầu vào — dùng alias từ dataset, vd: "Đơn COD giao hàng — 2× áo + 1× quần">
-    When <hành động duy nhất>
-    Then <kết quả chính — dùng backtick ID khi cần precision, vd: mã `ZMA{id}`>
-      And <side-effect 1 đã khai báo ở header>
-      And <side-effect 2 đã khai báo ở header>
-      # ... đủ với danh sách Side-effects ở trên (Rule R2)
+  Scenario: <mô tả business outcome — dùng động từ chính xác: create/receive/assign/block>
+    Given <input state — alias từ dataset>
+    When <single action>
+    Then <main observable outcome>
+      And <side-effect 1 khai báo trong header>
 
   # Side-effects: <...>
-  # @trace.scenario: {TICKET_ID}-UC{N}-SC2
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC2
   # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
   @happy @alternative
-
-  Scenario: <Cùng chủ đề NHÓM 1 nhưng path khác — vd enum value khác (Rule R4 enum symmetry)>
-    Given <state đầu vào>
-    When <hành động>
-    Then <kết quả>
+  Scenario: <cùng theme NHÓM 1 nhưng path khác — vd: giá trị enum khác>
+    Given <state>
+    When <action>
+    Then <outcome>
 
   # ==========================================================
-  # NHÓM 2: <Chủ đề business 2 — VD: Xử lý lỗi / Validation> (<BR refs>)
+  # NHÓM 2: <Business theme 2> (<BR refs>)
   # ==========================================================
 
   # Side-effects: <...>
-  # @trace.scenario: {TICKET_ID}-UC{N}-SC3
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC3
   # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR2
   @edge
+  Scenario: <scenario boundary / error>
+    Given <state>
+    When <action>
+    Then <expected error handling>
 
-  Scenario: <Tình huống biên / lỗi cùng chủ đề NHÓM 2>
-    Given <state đầu vào>
-    When <hành động>
-    Then <xử lý lỗi mong đợi>
-
-  # ==========================================================
-  # NHÓM 3: <Chủ đề business 3 — VD: Cross-system / Hiệu ứng downstream> (<BR refs>)
-  # ==========================================================
-
-  # Side-effects: <...>
-  # @trace.scenario: {TICKET_ID}-UC{N}-SC4
-  # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
-  @happy @cross-system
-
-  Scenario: <Scenario span ≥2 service hoặc hiệu ứng đồng bộ cross-UC>
-    Given <state đầu vào>
-    When <hành động>
-    Then <kết quả tại service A>
-      And <kết quả đồng bộ sang service B>
-
-# === TECHNICAL HINTS (optional, giúp AI gen code chính xác hơn) ===
-# Dependencies: <UC/service phụ thuộc, vd: LOYAL-28 upstream>
-# Entities: <Entity1, Entity2>
-# Events: <EventName> (publish to <topic>)
-# Cache: <cache invalidation notes>
-# Validation: <validation rules>
-
-# === PRD COVERAGE (C.1 + C.2 — wireframe action + AC/BR checklist) ===
+# === PRD COVERAGE (C.1 + C.2) ===
 # AC mapping:
 #   AC1 (...) → SC1, SC2
 #   AC2 (...) → SC3
-# BR mapping (mỗi bullet trong BR PHẢI có ≥1 SC — C.2):
-#   BR1 (...) → SC1
-#   BR2 (...) → SC1, SC2
-# Wireframe mapping (mọi component/action có ≥1 SC — C.1):
-#   Screen "<tên màn>":
-#     [x] Click "<button A>"        → SC1
-#     [x] Click "<button B>"        → SC2
-#     [ ] Click "<" back             → MISSING ← BLOCK MERGE
-# Display Logic Matrix mapping (nếu áp dụng — B.1.7):
-#   Case 1 (...) → SC{N}
-#   Case 2 (...) → SC{N}
-# User Flow: <path name> → SC1, SC2, SC3
-
-# === BUSINESS RULES ===
-# {TICKET_ID}-UC{N}-BR1: <mô tả rule>
-# {TICKET_ID}-UC{N}-BR2: <mô tả rule>
-
-# === PRE-MERGE CHECKLIST (auto-verify) ===
-# - [ ] Mọi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.ac + @trace.business_rules
-# - [ ] Coverage Matrix có 0 dòng `[ ]` MISSING (C.1)
-# - [ ] Mọi AC/BR (kèm từng bullet) map về ≥1 SC (C.2)
-# - [ ] CI grep banned terms = 0 match (C.4) — xem business-dictionary.md § Banned Terms
-# - [ ] Nếu là popup/modal: Popup/Modal Lifecycle khai báo trong BUSINESS DEFINITION (B.2.4)
-# - [ ] Nếu display logic ≥2 dimension: Display Logic Matrix enumerated (B.1.7)
-# - [ ] Feature ≥3 SCs có NHÓM grouping theo chủ đề business (C.5) — KHÔNG dùng section markers cũ HAPPY-PATH/NEGATIVE-CASE/EDGE-CASE
-# - [ ] /review-context score ≥90 (project gate)
+# BR mapping (mỗi bullet PHẢI có ≥1 SC — C.2):
+#   {TICKET-ID}-UC{N}-BR1 (...) → SC1, SC2
+#   {TICKET-ID}-UC{N}-BR2 (...) → SC3
+# Wireframe mapping (mỗi component/action ≥1 SC — C.1):
+#   Screen "<screen name>":
+#     [x] <action 1>  → SC1
+#     [x] <action 2>  → SC2
+#     [ ] <action 3>  → MISSING ← BLOCK MERGE
+# Design Spec coverage (chỉ FE/App — C.1 mở rộng; bỏ khối này nếu không nạp design-spec):
+#   Screen "<screen>": loading → SC?, error → SC?, empty → SC?
+#   AC-UI behavioral: AC-UI3 (lỗi+khôi phục) → SC?, AC-UI4 (empty CTA) → SC?
+#     (bỏ AC-UI visual thuần: AC-UI1 khớp Figma, AC-UI5 WCAG — Designer/QA review riêng)
+
+# === PRE-MERGE CHECKLIST ===
+# - [ ] Mỗi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
+# - [ ] Coverage Matrix: 0 dòng MISSING (C.1)
+# - [ ] FE/App: mỗi Screen State (≠default) + AC-UI behavioral của design-spec có ≥1 SC (C.1 mở rộng)
+# - [ ] Mỗi AC/BR map tới ≥1 SC (C.2)
+# - [ ] 0 banned term (C.4) — grep file trước khi merge
+# - [ ] Feature ≥3 SC có NHÓM grouping theo business theme (C.5)
+# - [ ] Nếu popup/modal: khai báo Popup/Modal Lifecycle trong BUSINESS DEFINITION
+# - [ ] Nếu display logic ≥2 chiều: Display Logic Matrix trong BUSINESS DEFINITION

package/core/templates/prd.template.md

@@ -69,6 +69,8 @@
 
 ## b. Phạm vi
 
+> **Scope = ranh giới, KHÔNG phải đặc tả.** Mỗi mục một dòng ngắn "làm gì / không làm gì". Đừng nhét **cơ chế** (retry/timeout/nhánh lỗi → BR/BL) hay **định nghĩa thuật ngữ** (vd "điểm khởi tạo = …" → Business Definition / business-dictionary) vào đây.
+
 **In Scope**
 - {hạng mục trong phạm vi 1}
 - {hạng mục trong phạm vi 2}
@@ -87,10 +89,14 @@
 # 2. Acceptance Criteria
 
 > Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
+>
+> **1 AC = 1 tiêu chí NGHIỆM THU (outcome quan sát/kiểm được) + ref BR.** KHÔNG viết cơ chế trong AC (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết) — cái đó thuộc **BR/BL** ở §3, AC chỉ trỏ tới. Nếu tiêu chí có **nhiều nhánh** → tách **bullet con** (mỗi ý một dòng), đừng dồn thành câu dài. Khi `/refine-prd` làm rõ thêm: chi tiết cơ chế → đẩy sang BR/BL; ở tầng AC thì tách bullet/AC mới — KHÔNG nối mệnh đề vào câu cũ (tránh AC thành "đoạn văn" và trùng BR).
 
 **AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
-**AC2:** {…} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+**AC2:** {Tiêu chí có nhiều nhánh — tách bullet:} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+  - {nhánh/điều kiện 1 → kết quả kỳ vọng}
+  - {nhánh/điều kiện 2 → kết quả kỳ vọng}
 
 ---
 
@@ -197,11 +203,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)*
+
+<!-- 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. -->
 
-| Mục | Thay đổi |
-|-----|----------|
-| — | Bản đầu — sinh từ product-definition. |
+| 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

@@ -35,7 +35,7 @@ paths:
   # prd-slug is derived from the PRD folder path — not a separate config variable.
   specs_dir: "specs"
   templates_dir: "specs/templates"
-  feature_template: "specs/templates/feature.template"
+  feature_template: ".agent/templates/feature.template"   # SoT skeleton .feature (dùng bởi /generate-bdd qua {{include}})
   bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
   trace_report: "specs/.trace/trace-report.md"
 

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

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

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

@@ -45,16 +45,17 @@ Discovery → PRD → BDD → Tech Design → Code → Dev self-check:
     → specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
 /refine-prd specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md         # AI suggestions → Review Board
 /refine-prd --resume specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  # apply + bump version
-/review-context specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md      # quality gate (P1–P4)
+/review-context specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md      # quality gate (P0–P5)
 /review-context --resume specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-    → ✅ APPROVED → tiếp Phase 3
+    → ✅ 0 critical → PO đặt | **Status** | approved | trong Metadata → tiếp Phase 3
 
 # PHASE 3 — SPEC & DESIGN
 # (FE/App only) /generate-design-spec specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md → designer + PO sign-off
 /generate-bdd specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
     → specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
 /review-context specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-/review-context --resume specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature   # apply + bump bdd_version
+/review-context --resume specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature   # apply + bump bdd_version + reset @trace.status draft
+    → ✅ 0 critical → đặt # @trace.status: approved trong .feature → tiếp Tech Design
 /generate-tech-docs specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
     → specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md
 /review-tech-docs specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md

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

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

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

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

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

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

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

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