@educa-corp/sdd-framework 0.1.0

package/commands/generate-bdd.tmpl

@@ -0,0 +1,499 @@
+# /generate-bdd — Sinh BDD Feature Files
+
+## Gate
+{{include:steps/gate.md}}
+
+## Context
+{{include:steps/context-loader.md}}
+
+> **Proposal của tester (input tuỳ chọn):** trước khi sinh, quét `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm `{UC-ID}-*.md`. Với mỗi proposal:
+> - `Status: accepted` (PO/Dev đã duyệt) → chèn scenario vào `.feature` của UC (giữ `@trace`), rồi **lưu trữ**: chuyển file sang `{paths.bdd_proposals_dir}/archived/` + đặt `Status: incorporated`, và **commit + push** spec repo để gỡ khỏi feedback chung.
+> - `Status: proposed`/`rejected` (hoặc thiếu `Status`) → **bỏ qua**, để nguyên cho PO/Dev xử lý (KHÔNG tự đoán, KHÔNG tự đưa vào).
+> Bỏ qua sạch nếu folder rỗng.
+
+---
+
+## Sub-Agent Mode — dùng state từ payload *(nếu `_agent_mode`)*
+
+*Chỉ khi Gate Step 0 phát hiện `_agent_mode: true` (đang chạy như sub-agent do orchestration spawn).* Orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec **một lần**; sub-agent KHÔNG lặp lại:
+- `active_platform` = `payload.active_platform` → **bỏ qua** Platform Selection / Service Detection.
+- `design_coverage` = `payload.design_coverage` → **bỏ qua** "Design Spec — Gate & Load"; nếu rỗng thì chỉ phủ Wireframe PRD.
+- **Bỏ qua** Guard "PRD đã duyệt" + Guard Design-Spec bên dưới (orchestrator đã kiểm).
+- Đi thẳng tới UC Decomposition + Generate cho `payload.uc_id`, dùng `design_coverage` để phủ Screen States + AC-UI.
+
+---
+
+## Guard — PRD đã duyệt chưa
+
+Đọc `| **Status** |` từ bảng Metadata của PRD nguồn:
+- `Status: approved` → tiếp tục bình thường.
+- `Status: draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép prototype):
+  ```
+  ⚠️  PRD đang ở Status: {status} (chưa duyệt). BDD sinh từ PRD chưa chốt có thể phải làm lại.
+     Khuyến nghị: PO review xong đặt `| **Status** | approved |` rồi mới sinh BDD.
+     Vẫn sinh BDD bây giờ? (Y/N)
+  ```
+  Chỉ tiếp tục khi người dùng chọn Y.
+
+---
+
+## Phát hiện Repo Mode
+
+Sau khi nạp context, xác định chế độ hoạt động:
+
+- **Spec repo mode**: `project-context.yaml` KHÔNG có section `services` HOẶC `setup.mode: spec`
+- **Umbrella mode**: `project-context.yaml` CÓ section `services` VÀ `setup.mode: umbrella`
+
+→ Spec repo mode → tới **Platform Selection** bên dưới (bỏ qua Service Detection)
+→ Umbrella mode → tới **Service Detection** bên dưới (bỏ qua Platform Selection)
+
+---
+
+## Platform Selection (chỉ Spec Repo Mode)
+
+*Bỏ qua section này nếu đang chạy umbrella mode.*
+
+Hỏi người dùng chọn platform target:
+
+```
+BDD này dành cho platform nào?
+  1. web    — FE/Web (React, Next.js, Angular, Vue, Nuxt)
+  2. app    — Mobile (Flutter, React Native, iOS, Android)
+  3. system — System/BE BDD (tổng hợp từ web + app BDD có sẵn)
+```
+
+Chờ người dùng chọn. Set `active_platform` = giá trị đã chọn.
+
+**Output path (spec repo mode):**
+`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature`
+
+**Từ vựng theo platform:**
+
+| Platform | "user action" | "type/input" | "observe" | "navigate" |
+|---|---|---|---|---|
+| web | "clicks" | "types into" / "enters" | "sees" / "the page shows" | "navigates to" / "goes to" |
+| app | "taps" | "enters" / "inputs" | "sees" / "the screen shows" | "navigates to" / "opens" |
+| system | N/A — dùng business event | — | "the system returns" / "receives response" | — |
+
+---
+
+## System BDD Synthesis (active_platform = system)
+
+*Chỉ áp dụng khi platform = system. Bỏ qua với web và app.*
+
+### Step S0 — Brownfield Check
+
+Kiểm tra bảng Metadata của PRD nguồn tìm `| **API Source** | existing |`.
+
+**Nếu `API Source: existing`:**
+- API contract đã được PO ghi trong phần "Existing API Contract" của PRD.
+- **Skip Steps S1–S3** — không cần scan FE/App BDD, không cần conflict resolution.
+- Dùng bảng "Existing API Contract" trong PRD làm contract input cho Step S4.
+- Set `# @trace.api_source: existing` trong header của file system BDD được gen.
+
+**Nếu `API Source` không có hoặc không phải `existing`:**
+- Tiếp tục Steps S1–S3 (normal synthesis flow).
+
+---
+
+### Step S1 — Scan các BDD FE/App có sẵn
+
+Tìm các BDD có sẵn cho TICKET-ID này:
+- Web BDD: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/web/{TICKET-ID}-*.feature`
+- App BDD: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/app/{TICKET-ID}-*.feature`
+
+Phân loại feature:
+
+| Điều kiện | Mode |
+|---|---|
+| Tìm thấy cả web + app BDD | **Multi-platform** — tổng hợp từ cả hai |
+| Chỉ tìm thấy web BDD | **Web-only** — tổng hợp từ web |
+| Chỉ tìm thấy app BDD | **App-only** — tổng hợp từ app |
+| Không tìm thấy FE/App BDD | **Backend-only** — gen trực tiếp từ PRD |
+
+---
+
+### Step S2 — Trích contract kỳ vọng theo từng platform
+
+Với mỗi file BDD tìm thấy, trích:
+- **Triggers**: hành động người dùng nào gọi backend? (map sang event "request" logic)
+- **Expected response data**: mỗi mệnh đề `Then` cần field/shape gì từ hệ thống?
+- **Error signals**: backend phải báo hiệu các trạng thái lỗi nào?
+- **Business rules**: mỗi platform giả định hệ thống thực thi các invariant nào?
+
+---
+
+### Step S3 — Cross-Platform Conflict Check (chỉ multi-platform mode)
+
+*Bỏ qua nếu web-only, app-only, hoặc backend-only.*
+
+So sánh các contract đã trích giữa các platform. Gắn cờ conflict nếu bất kỳ cái nào khác nhau:
+
+| Loại conflict | Ví dụ |
+|---|---|
+| **Response shape mismatch** | Web mong `{ token, redirect_url }`, App mong `{ token, user_profile }` |
+| **Error semantics mismatch** | Web mong HTTP 423 cho lock, App mong custom error code `ACC_LOCKED` |
+| **Business rule contradiction** | Web BDD nói "lock sau 5 lần", App BDD nói "lock sau 3 lần" |
+| **Data field conflict** | Web mong `expires_in: seconds`, App mong `expires_at: ISO timestamp` |
+
+**Nếu phát hiện conflict → CHECKPOINT (bắt buộc, không bỏ qua được):**
+
+```
+⚠️  CROSS-PLATFORM CONTRACT CONFLICT
+──────────────────────────────────────────────────────────────────
+Feature : {TICKET-ID} — {UC name}
+
+Conflict 1: Response shape mismatch
+  Web BDD (Then): user sees dashboard → implies { token, redirect_url }
+  App BDD (Then): app navigates to HomeScreen → implies { token, user_profile }
+
+Resolution options:
+  A — Union response
+      BE trả về tất cả field: { token, redirect_url, user_profile }
+      Client bỏ qua field không dùng. Đơn giản, hơi over-fetch.
+  B — Platform hint trong request
+      Client gửi X-Platform: web|app trong header, BE tuỳ biến response.
+      Response gọn hơn, nhiều BE logic hơn.
+  C — Endpoint riêng
+      POST /auth/login/web  và  POST /auth/login/app
+      Linh hoạt tối đa, nhiều endpoint phải bảo trì hơn.
+  D — Custom: mô tả cách của bạn
+──────────────────────────────────────────────────────────────────
+Chọn resolution cho mỗi conflict (A/B/C/D):
+```
+
+Chờ PO giải quyết từng conflict. Ghi mỗi quyết định thành annotation `# @system.resolution:` trong file system BDD được gen.
+
+**Nếu không có conflict → tới Step S4 trực tiếp.**
+
+---
+
+### Step S4 — Sinh các scenario System BDD
+
+Sinh scenario dựa trên mode và các conflict đã giải quyết:
+
+- **Multi-platform**: tổng hợp từ cả contract web + app, áp dụng các resolution đã chọn
+- **Web-only / App-only**: suy ra từ contract của một platform
+- **Backend-only**: suy ra trực tiếp từ AC/BR của PRD dùng ngôn ngữ business event (không phải HTTP)
+
+Từ vựng step của System BDD (luôn dùng — bất kể từ vựng FE/App):
+- Triggers: "the system receives {event}" / "a {actor} submits {action}"
+- Assertions: "the system returns {data}" / "the system signals {error}" / "the system stores {state}"
+- KHÔNG dùng từ UI (click, tap, see, navigate) trong system BDD
+
+**Nếu multi-platform với resolution A (union):**
+- System BDD thể hiện contract response đầy đủ: tất cả field từ mọi platform
+- Thêm comment: `# @system.resolution: union — clients receive all fields`
+
+**Nếu resolution B (platform hint):**
+- Viết `Scenario Outline` riêng dùng Examples table cho biến thể response `web` vs `app`
+- Thêm comment: `# @system.resolution: platform-hint — X-Platform header determines response shape`
+
+**Nếu resolution C (endpoint riêng):**
+- Viết Scenario riêng cho mỗi endpoint
+- Ghi rõ việc tách endpoint trong phần SCOPE
+
+---
+
+## Service Detection (chỉ Umbrella Mode)
+
+*Bỏ qua section này nếu đang chạy spec repo mode.*
+
+Routing service là **domain-keyed** và **context-loader (Bước 1.5) đã phân giải sẵn** từ `@trace.domain`/Domain của PRD — KHÔNG re-resolve ở đây, chỉ dùng lại các biến đã set:
+- `active_service` = `services.{domain}.path` (path submodule, vd `user-service/`) — hoặc `"unresolved"` nếu domain không khớp entry nào, hoặc bỏ trống ở single-service.
+- `active_module` = module của service (`services.{domain}.module`, đã override `tech_stack.module` ở Bước 1.5) — dùng cho từ vựng bên dưới.
+
+Chỉ cần kiểm tra trạng thái đã phân giải:
+
+| Trạng thái (từ context-loader) | Hành động |
+|---|---|
+| `active_service` đã phân giải thành path service | Tiếp tục với `active_module` đã set. |
+| `active_service = "unresolved"` (có section `services` nhưng domain PRD không khớp entry nào) | **DỪNG**, báo: "Domain `{domain}` của PRD không khớp service nào trong `services:` của project-context.yaml — bổ sung mapping rồi chạy lại." (Không đoán/hỏi tay — domain là khoá định danh, lệch là lỗi cấu hình cần sửa ở SoT.) |
+| Single-service (không có section `services`) | `active_module = tech_stack.module` (đã set ở Bước 6.5). Tiếp tục. |
+
+**Output path (umbrella mode):** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature`
+
+*(Không thêm subfolder theo service: feature-package đã domain-scoped sẵn ở `{domain}/`, mà service route 1-1 theo domain — nên thêm subfolder service sẽ chỉ lặp lại domain. `active_service` chỉ dùng cho `service_root`/từ vựng, KHÔNG vào path spec.)*
+
+**Từ vựng theo platform** — điều chỉnh cách viết step BDD theo `active_module`:
+
+| Platform type | Modules | "click" | "type" | "see" | "navigate" |
+|---|---|---|---|---|---|
+| Web | react, nextjs, vue, nuxt, angular | "clicks" | "types into" / "enters" | "sees" / "the page shows" | "navigates to" / "goes to" |
+| Mobile | flutter, react-native, ios-swiftui, android-compose | "taps" | "enters" / "inputs" | "sees" / "the screen shows" | "navigates to" / "opens" |
+| Backend / API | java-spring, golang, dotnet, php-laravel | *(không có UI step — dùng)* "submits a request" / "calls the API" | — | "receives response" / "the system returns" | — |
+
+Áp dụng từ vựng này âm thầm khi viết step Gherkin. KHÔNG trộn từ web và mobile trong cùng một file feature.
+
+---
+
+## Design Spec — Gate & Load (chỉ FE/App)
+
+*Chỉ chạy khi target platform là FE/App — spec mode: `active_platform ∈ {web, app, app-ios, app-android}`; umbrella mode: `active_module` là module FE/App (react/nextjs/vue/nuxt/angular/flutter/react-native/ios-swiftui/android-compose). Bỏ qua HOÀN TOÀN với `system` và backend/brownfield.*
+
+**1. Định vị design-spec của platform:**
+`{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
+- `app-ios`/`app-android` không có bản riêng → fallback bản `-app-`.
+
+**2. Guard — sign-off & độ tươi (cảnh báo MỀM, đồng bộ Guard PRD — không chặn cứng):**
+Đọc `| **Status** |` và `| **Built from PRD** |` từ Metadata design-spec.
+- Không tìm thấy file, HOẶC `Status ≠ approved`, HOẶC design-spec còn màn ❌ Missing, HOẶC `Built from PRD` ≠ `| **Version** |` của PRD hiện tại (design-spec **lỗi thời** so với PRD) → CHECKPOINT:
+  ```
+  ⚠️  Design Spec cho {active_platform} chưa sẵn sàng (Status: {status} / không có / còn màn thiếu Figma / lỗi thời: dựng từ PRD v{old}, PRD giờ v{new}).
+     BDD FE/App nên sinh từ design-spec đã approved & cập nhật để phủ đúng Screen States + AC-UI.
+     Khuyến nghị: hoàn tất / cập nhật design-spec (chạy lại /generate-design-spec nếu PRD đã đổi) rồi mới sinh BDD.
+     Vẫn sinh BDD bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y. Nếu Y mà KHÔNG có design-spec → bỏ qua bước 3 (chỉ phủ Wireframe PRD §4b).
+- `Status: approved` VÀ `Built from PRD` khớp PRD hiện tại → nạp design-spec, sang bước 2.5.
+
+**2.5. Sanity-scan nội dung design-spec** (lớp soi độc lập — D1; soi nhanh ngay tại chỗ đã mở file, trước khi dùng):
+Quét tìm cờ đỏ; nếu có → **cảnh báo mềm** (liệt kê + hỏi "Vẫn dùng design-spec này? (Y/N)"):
+- Màn nào thiếu state `loading`/`error`/`empty`.
+- AC-UI nào mơ hồ, không testable ("looks good" / "đẹp" / không pass-fail rõ).
+- Component còn `[NEW]` / `[TODO]` (chưa chốt với designer).
+- Còn `❌ Missing` frame (lẽ ra Status đã `draft` — approved mà vẫn Missing là bất thường).
+Bắt lỗi design-spec **ngay trước khi nó lan xuống BDD**. Chọn N → quay lại hoàn thiện design-spec; chọn Y → sang bước 3.
+
+**3. Trích coverage từ design-spec** (lưu thành `design_coverage`, dùng ở UC Decomposition + Coverage Matrix):
+- **Screen States** ≠ `default` cho mỗi màn: `loading`, `error`, `empty`, `success` (cái nào có).
+- **AC-UI behavioral**: giữ AC-UI mà cột `Verified by` là **PO/QA** và mô tả outcome quan sát được (lỗi + đường khôi phục, empty state + CTA, gesture điều hướng, có loading state). **LOẠI AC-UI visual thuần** (khớp Figma trong dung sai, tương phản WCAG, màu/pixel/animation — thường `Verified by: Designer`): Designer/QA review riêng, KHÔNG đưa vào Gherkin (giữ R3/R5/R6).
+- **Dedup**: nếu một Screen State / AC-UI đã trùng một AC nghiệp vụ của PRD → không tạo SC mới, chỉ ghi nhận đã phủ.
+
+---
+
+## Orchestration Check
+
+*Bỏ qua section này nếu đã ở sub-agent mode (Step 0 của Gate đã kích hoạt).*
+
+Sau khi nạp context, kiểm tra PRD target có đủ lớn để cần sub-agent không:
+
+1. Đếm các heading `#### {TICKET-ID}-UC` trong PRD → **UC count**.
+2. Đếm tổng số dòng trong PRD → **line count**.
+3. Nếu **UC count > 3** HOẶC **line count > 300**:
+   - Chuyển sang orchestration mode — theo `steps/spawn-agent.md`.
+   - Session chính trở thành orchestrator: spawn 1 sub-agent cho mỗi UC.
+   - Mỗi sub-agent chạy `/generate-bdd` với payload `_agent_mode: true`.
+   - Thu thập kết quả và hiện report đã merge.
+   - **KHÔNG tiếp tục các bước bên dưới.**
+4. Nếu UC count ≤ 3 VÀ line count ≤ 300 → tiếp tục Version Check bên dưới (single-session mode).
+
+---
+
+## Sub-Agent Return Format
+
+*Section này áp dụng khi chạy như sub-agent (Gate Step 0 phát hiện `_agent_mode: true`).*
+
+Sau khi sinh tất cả file `.feature` và `.tsv` cho UC được giao, trả về JSON kết quả có cấu trúc (theo `steps/spawn-agent.md` Step E):
+
+```json
+{ "uc_id": "{TICKET-ID}-UC{N}", "files_created": ["path/to/file1", "path/to/file2"], "status": "success | error", "errors": [] }
+```
+
+---
+
+## Version Check
+
+Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
+
+1. Phân giải search path theo mode:
+   - **Spec repo mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC*.feature`
+   - **Umbrella mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC*.feature`
+2. Đọc `| **Version** |` hiện tại của PRD từ metadata (vd: `1.2`).
+
+**Nếu không có file feature nào** → gen mới, tiếp tục bình thường. Dùng version PRD làm `@trace.prd_version`.
+
+**Nếu tìm thấy file feature có sẵn**:
+- Đọc `# @trace.prd_version:` từ header file feature có sẵn.
+- So với version PRD hiện tại.
+- Nếu **giống** → hỏi: "BDD đã sinh từ PRD v{version}. Gen lại? (Y/N)"
+- Nếu **khác** (PRD đã cập nhật):
+  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có. **Nếu `@trace.prd_version` của BDD CŨ HƠN row cũ nhất còn trong bảng** (lịch sử đã bị cắt sang `changelog/`) → không thấy đủ diff → **khuyến nghị F** (gen lại toàn bộ), đừng tin Y một phần.
+  2. Hiện CHECKPOINT:
+     ```
+     ⚠️  Phát hiện PRD version drift
+     BDD được sinh từ PRD v{old}
+     PRD giờ ở v{new}
+
+     Thay đổi kể từ v{old}:
+       {changelog rows}
+
+     Options:
+       Y — chỉ cập nhật các scenario bị ảnh hưởng
+       F — gen lại toàn bộ scenario
+       N — huỷ
+     ```
+  3. Tiếp tục theo lựa chọn của người dùng. **Nếu changelog row không nêu rõ UC/AC/BR bị đổi (mơ hồ) → khuyến nghị F** (gen lại toàn bộ) thay vì Y, để khỏi sót scenario bị ảnh hưởng (lưới an toàn — không chắc đổi ở đâu thì quét rộng).
+
+---
+
+## BDD Writing Rules (R1-R10 — enforce nghiêm)
+
+| Rule | Name | Yêu cầu |
+|------|------|-------------|
+| R1 | Given/When/Then Semantics | Given=state, When=action, Then=outcome. Mỗi SC cần đủ G/W/T. |
+| R2 | One Behavior Per Scenario | 1 SC = 1 behavior. KHÔNG chain When→Then→When→Then. |
+| R3 | Ubiquitous Language | KHÔNG dùng UI selector / tên API / tech term trong step. |
+| R4 | Outside-in Naming | Tên SC mô tả business outcome. Không "click" / "(Case X)" / tên component. |
+| R5 | Declarative over Imperative | Mô tả WHAT (ý định nghiệp vụ), KHÔNG phải HOW (cơ chế UI). |
+| R6 | Observable Outcomes Only | Then khẳng định outcome quan sát được. Không phải trạng thái UI trung gian / internal state. |
+| R7 | Key Examples / Concrete | Dùng giá trị cụ thể. Không "valid data" mơ hồ. |
+| R8 | Independence | SC chạy độc lập. Không phụ thuộc state từ SC khác. |
+| R9 | Test Data Completeness | Data table có đủ field để suy ra Then kỳ vọng. |
+| R10 | Scope Boundary Explicit | Cross-UC reference dùng cách diễn đạt navigation + comment Note. |
+
+## Project Compliance (fail review nếu thiếu — C.1-C.5)
+
+| Check | Rule |
+|-------|------|
+| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe (PRD §4b) có ≥1 SC. **FE/App: mỗi Screen State (≠default) và mỗi AC-UI behavioral của design-spec (`design_coverage`) cũng phải có ≥1 SC** — dedup với AC nghiệp vụ PRD; bỏ AC-UI visual thuần. |
+| C.2 PRD Traceability | Mỗi AC và mỗi BR (gồm từng bullet logic) map tới ≥1 SC. |
+| C.3 Business Dictionary | Dùng đúng canonical term từ business-dictionary.md. |
+| C.4 Banned Terms | 0 banned term trong file — grep trước khi gen. |
+| C.5 NHÓM Grouping | Feature ≥3 SC → PHẢI có NHÓM grouping theo business theme. |
+
+---
+
+## NHÓM Grouping Convention (C.5 — bắt buộc cho ≥3 scenario)
+
+Gom theo business theme, KHÔNG theo happy/negative/edge.
+
+Format header (thụt 2 space, cùng cấp với Background):
+```
+  # ==========================================================
+  # NHÓM N: <Business theme> (<BR refs nếu áp dụng>)
+  # ==========================================================
+```
+
+Rules:
+- Đánh số tuần tự NHÓM 1 → N. SC ID tuần tự xuyên suốt lifecycle (không reset theo từng NHÓM).
+- Mỗi NHÓM có thể chứa @happy + @edge + @negative cùng theme.
+- SC trong NHÓM không cần theo thứ tự ID (NHÓM 2 có thể chứa SC4, SC8, SC11 nếu cùng theme).
+
+Pattern gợi ý (điều chỉnh theo UC):
+- `Init / Save success — valid data combinations`
+- `Validation / Block when invalid`
+- `Error handling — API fail / system error`
+- `Cancel changes / Close modal without saving`
+- `Cross-system / Downstream effects`
+- `Idempotency & Concurrency`
+
+---
+
+## UC Decomposition
+
+Với mỗi UC trong PRD, trình bày outline SC **trước khi sinh**:
+```
+{TICKET-ID}-UC1: {Use Case Name}
+  NHÓM 1: {Theme} (BR1, BR2)
+    SC1 [@happy]:              {business outcome}
+    SC2 [@happy @alternative]: {variant outcome}
+  NHÓM 2: {Theme} (BR2, BR3)
+    SC3 [@edge]:               {edge case}
+    SC4 [@negative]:           {error handling}
+  ACs covered: AC1, AC2
+  BRs covered: {TICKET-ID}-UC1-BR1, BR2, BR3
+```
+
+*(FE/App: nếu đã nạp design-spec (xem "Design Spec — Gate & Load"), đưa Screen State ≠default (loading/error/empty) + AC-UI behavioral của `design_coverage` vào outline — dedup với AC nghiệp vụ, đừng tạo SC trùng.)*
+
+CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào không?" → **Chờ confirm trước khi sinh.**
+
+---
+
+## Generate
+
+**Output path theo mode:**
+- **Spec repo mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature`
+- **Umbrella mode**: `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC{N}-{slug}.feature` *(service route 1-1 theo domain → không thêm subfolder service)*
+
+Với mỗi UC, ghi vào path đã phân giải ở trên. Dùng từ vựng cho active platform (từ Platform Selection hoặc Service Detection).
+
+```gherkin
+{{include:templates/feature.template}}
+```
+
+*(Template `.feature` là **single-source** ở `templates/feature.template` — sửa file đó để đổi cấu trúc mọi `.feature` sinh ra. Coverage Matrix + Pre-merge Checklist nằm ở **cuối** template, thêm vào cuối mỗi file.)*
+
+---
+
+## Write Trace State
+
+Sau khi sinh tất cả file `.feature`, tạo hoặc cập nhật **sổ trace theo platform** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv` cho mỗi UC — một sổ riêng cho `system` / `web` / `app`. Vì `sc_id` = `{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) (mỗi platform tự đánh số SC từ 1), **mỗi platform một file** để scenario platform này không đè/xoá platform khác. Lệnh luôn biết `active_platform` (từ Platform Selection / Service Detection) nên chỉ ghi đúng sổ của platform đang gen.
+
+> **Umbrella + `spec_source`:** cả file `.feature` **và** trace `.tsv` đều ghi vào **spec repo** (`{spec_source}/specs/{domain}/{prd-slug}/bdd/…` và `{spec_source}/.trace/{domain}/{prd-slug}/…`, do context-loader phân giải) — một thao tác ghi **single-repo**, commit/push vào spec submodule. (Trace được gộp trong spec repo để PM quản lý mọi status ở một chỗ; các lệnh phía code cập nhật liên-repo sau.)
+
+**Cột TSV (tab-separated, một header row + một data row cho mỗi scenario):**
+```
+sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tdev_selftest\tdev_selftest_at\tqc_status\tqc_run_at\tqc_owner\tqc_blocked_by\tprd_version\tbdd_version\ttech_doc_revision\tfe_tech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
+```
+
+**Rules:**
+- Nếu file chưa tồn tại → tạo với header row + tất cả scenario row.
+- Nếu file tồn tại (gen lại) → với mỗi SC trong `.feature` mới:
+  - SC đã có trong `.tsv` VÀ `spec_ver` không đổi → chỉ cập nhật: `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Giữ nguyên các cột khác.
+  - SC đã có trong `.tsv` VÀ `spec_ver` đổi (scenario bị sửa) → cập nhật: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` VÀ set `status = DRIFT` ngay (để TSV phản ánh drift mà không cần đợi `/validate-traces`). Giữ nguyên `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision`, `fe_tech_doc_revision`.
+  - SC mới (thêm trong lần gen lại này) → append row mới với `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`, `tech_doc_revision`, `fe_tech_doc_revision` đều set `—`.
+  - SC không còn trong `.feature` (bị xoá) → xoá row của nó. *(An toàn: sổ này chỉ chứa scenario của `{active_platform}`, so với `.feature` của chính platform đó — không bao giờ đụng scenario platform khác.)*
+
+**Giá trị ghi cho mỗi scenario:**
+
+| Cột | Giá trị |
+|--------|-------|
+| `sc_id` | `{UC-ID}-SC{N}` |
+| `sc_title` | text title của scenario |
+| `spec_ver` | `@trace.sc_version` của scenario này |
+| `gen_ver` | `—` (chưa gen) |
+| `implemented_by` | `—` |
+| `test_count` | `—` |
+| `test_classes` | `—` |
+| `dev_selftest` | `—` (chưa chạy test) |
+| `dev_selftest_at` | `—` |
+| `qc_status` | `—` (kết quả QC automation chính thức — set bởi `/qc-run-test`) |
+| `qc_run_at` | `—` |
+| `qc_owner` | `—` (SC chưa pass đang chờ ai: `dev` / `po` — set bởi `/qc-run-test` + `/report-bug`) |
+| `qc_blocked_by` | `—` (`BUG-{id}` / `GAP-{id}` liên kết — set bởi `/qc-run-test` + `/report-bug`) |
+| `prd_version` | `@trace.prd_version` từ header `.feature` |
+| `bdd_version` | `@trace.bdd_version` từ header `.feature` |
+| `tech_doc_revision` | `—` (revision tech-doc gộp `{TICKET-ID}-tech-design.md` — set bởi `/generate-code` + `/review-tech-docs`) |
+| `fe_tech_doc_revision` | `—` (revision cùng tech-doc gộp, ghi khi FE `--phase=integration` wire theo §4.5.4 — set bởi `/generate-code`) |
+| `prd_status` | đọc `\| **Status** \|` từ metadata PRD |
+| `uc_status` | `draft` cho UC mới; giữ giá trị hiện có khi gen lại |
+| `fe_phase` | `—` (set bởi `/generate-code --phase` khi FE implement) |
+| `status` | `UNTRACKED` |
+| `last_updated` | hôm nay `YYYY-MM-DD` |
+
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-bdd Hoàn tất
+
+[Spec repo mode — platform: {active_platform}]
+Files:
+  {paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC1-{slug}.feature ({N} scenarios)
+  {paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{TICKET-ID}-UC2-{slug}.feature ({N} scenarios)
+Trace:
+  {paths.trace_dir}/{domain}/{prd-slug}/{TICKET-ID}-UC1-{active_platform}.tsv ({N} rows)
+  {paths.trace_dir}/{domain}/{prd-slug}/{TICKET-ID}-UC2-{active_platform}.tsv ({N} rows)
+Next (spec repo):
+  → Chạy /generate-bdd lại cho các platform khác (web → app → system)
+  → Sau khi gen hết platform: commit + push + báo team dev
+  → Team dev đọc BDD từ spec submodule — không chạy /generate-bdd ở phía họ
+
+[Umbrella mode — service: {active_service}]
+Files:
+  {paths.specs_dir}/{domain}/{prd-slug}/bdd/{TICKET-ID}-UC1-{slug}.feature ({N} scenarios)
+Trace:
+  {paths.trace_dir}/{domain}/{prd-slug}/{TICKET-ID}-UC1-{active_platform}.tsv ({N} rows)
+Next (umbrella):
+  → /review-context {feature-file} để kiểm tra coverage
+  → /generate-tech-docs {feature-file}
+  → /generate-code {feature-file}
+
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
+```